12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970197119721973197419751976197719781979198019811982198319841985198619871988198919901991199219931994199519961997199819992000200120022003200420052006200720082009201020112012201320142015201620172018201920202021202220232024202520262027202820292030203120322033203420352036203720382039204020412042204320442045204620472048204920502051205220532054205520562057205820592060206120622063206420652066206720682069207020712072207320742075207620772078207920802081208220832084208520862087208820892090209120922093209420952096209720982099210021012102210321042105210621072108210921102111211221132114211521162117211821192120212121222123212421252126212721282129213021312132213321342135213621372138213921402141214221432144214521462147214821492150215121522153215421552156215721582159216021612162216321642165216621672168216921702171217221732174217521762177217821792180218121822183218421852186218721882189219021912192219321942195219621972198219922002201220222032204220522062207220822092210221122122213221422152216221722182219222022212222222322242225222622272228222922302231223222332234223522362237223822392240224122422243224422452246224722482249225022512252225322542255225622572258225922602261226222632264226522662267226822692270227122722273227422752276227722782279228022812282228322842285228622872288228922902291229222932294229522962297229822992300230123022303230423052306230723082309231023112312231323142315231623172318231923202321232223232324232523262327232823292330233123322333233423352336233723382339234023412342234323442345234623472348234923502351235223532354235523562357235823592360236123622363236423652366236723682369237023712372237323742375237623772378237923802381238223832384238523862387238823892390239123922393239423952396239723982399240024012402240324042405240624072408240924102411241224132414241524162417241824192420242124222423242424252426242724282429243024312432243324342435243624372438243924402441244224432444244524462447244824492450245124522453245424552456245724582459246024612462246324642465246624672468246924702471247224732474247524762477247824792480248124822483248424852486248724882489249024912492249324942495249624972498249925002501250225032504250525062507250825092510251125122513251425152516251725182519252025212522252325242525252625272528252925302531253225332534253525362537253825392540254125422543254425452546254725482549255025512552255325542555255625572558255925602561256225632564256525662567256825692570257125722573257425752576257725782579258025812582258325842585258625872588258925902591259225932594259525962597259825992600260126022603260426052606260726082609261026112612261326142615261626172618261926202621262226232624262526262627262826292630263126322633263426352636263726382639264026412642264326442645264626472648264926502651265226532654265526562657265826592660266126622663266426652666266726682669267026712672267326742675267626772678267926802681268226832684268526862687268826892690269126922693269426952696269726982699270027012702270327042705270627072708270927102711271227132714271527162717271827192720272127222723272427252726272727282729273027312732273327342735273627372738273927402741274227432744274527462747274827492750275127522753275427552756275727582759276027612762276327642765276627672768276927702771277227732774277527762777277827792780278127822783278427852786278727882789279027912792279327942795279627972798279928002801280228032804280528062807280828092810281128122813281428152816281728182819282028212822282328242825282628272828282928302831283228332834283528362837283828392840284128422843284428452846284728482849285028512852285328542855285628572858285928602861286228632864286528662867286828692870287128722873287428752876287728782879288028812882288328842885288628872888288928902891289228932894289528962897289828992900290129022903290429052906290729082909291029112912291329142915291629172918291929202921292229232924292529262927292829292930293129322933293429352936293729382939294029412942294329442945294629472948294929502951295229532954295529562957295829592960296129622963296429652966296729682969297029712972297329742975297629772978297929802981298229832984298529862987298829892990299129922993299429952996299729982999300030013002300330043005300630073008300930103011301230133014301530163017301830193020302130223023302430253026302730283029303030313032303330343035303630373038303930403041304230433044304530463047304830493050305130523053305430553056305730583059306030613062306330643065306630673068306930703071307230733074307530763077307830793080308130823083308430853086308730883089309030913092309330943095309630973098309931003101310231033104310531063107310831093110311131123113311431153116311731183119312031213122312331243125312631273128312931303131313231333134313531363137313831393140314131423143314431453146314731483149315031513152315331543155315631573158315931603161316231633164316531663167316831693170317131723173317431753176317731783179318031813182318331843185318631873188318931903191319231933194319531963197319831993200320132023203320432053206320732083209321032113212321332143215321632173218321932203221322232233224322532263227322832293230323132323233323432353236323732383239324032413242324332443245324632473248324932503251325232533254325532563257325832593260326132623263326432653266326732683269327032713272327332743275327632773278327932803281328232833284328532863287328832893290329132923293329432953296329732983299330033013302330333043305330633073308330933103311331233133314331533163317331833193320332133223323332433253326332733283329333033313332333333343335333633373338333933403341334233433344334533463347334833493350335133523353335433553356335733583359336033613362336333643365336633673368336933703371337233733374337533763377337833793380338133823383338433853386338733883389339033913392339333943395339633973398339934003401340234033404340534063407340834093410341134123413341434153416341734183419342034213422342334243425342634273428342934303431343234333434343534363437343834393440344134423443344434453446344734483449345034513452345334543455345634573458345934603461346234633464346534663467346834693470347134723473347434753476347734783479348034813482348334843485348634873488348934903491349234933494349534963497349834993500350135023503350435053506350735083509351035113512351335143515351635173518351935203521352235233524352535263527352835293530353135323533353435353536353735383539354035413542354335443545354635473548354935503551355235533554355535563557355835593560356135623563356435653566356735683569357035713572357335743575357635773578357935803581358235833584358535863587358835893590359135923593359435953596359735983599360036013602360336043605360636073608360936103611361236133614361536163617361836193620362136223623362436253626362736283629363036313632363336343635363636373638363936403641364236433644364536463647364836493650365136523653365436553656365736583659366036613662366336643665366636673668366936703671367236733674367536763677367836793680368136823683368436853686368736883689369036913692369336943695369636973698369937003701370237033704370537063707370837093710371137123713371437153716371737183719372037213722372337243725372637273728372937303731373237333734373537363737373837393740374137423743374437453746374737483749375037513752375337543755375637573758375937603761376237633764376537663767376837693770377137723773377437753776377737783779378037813782378337843785378637873788378937903791379237933794379537963797379837993800380138023803380438053806380738083809381038113812381338143815381638173818381938203821382238233824382538263827382838293830383138323833383438353836383738383839384038413842384338443845384638473848384938503851385238533854385538563857385838593860386138623863386438653866386738683869387038713872387338743875387638773878387938803881388238833884388538863887388838893890389138923893389438953896389738983899390039013902390339043905390639073908390939103911391239133914391539163917391839193920392139223923392439253926392739283929393039313932393339343935393639373938393939403941394239433944394539463947394839493950395139523953395439553956395739583959396039613962396339643965396639673968396939703971397239733974397539763977397839793980398139823983398439853986398739883989399039913992399339943995399639973998399940004001400240034004400540064007400840094010401140124013401440154016401740184019402040214022402340244025402640274028402940304031403240334034403540364037403840394040404140424043404440454046404740484049405040514052405340544055405640574058405940604061406240634064406540664067406840694070407140724073407440754076407740784079408040814082408340844085408640874088408940904091409240934094409540964097409840994100410141024103410441054106410741084109411041114112411341144115411641174118411941204121412241234124412541264127412841294130413141324133413441354136413741384139414041414142414341444145414641474148414941504151415241534154415541564157415841594160416141624163416441654166416741684169417041714172417341744175417641774178417941804181418241834184418541864187418841894190419141924193419441954196419741984199420042014202420342044205420642074208420942104211421242134214421542164217421842194220422142224223422442254226422742284229423042314232423342344235423642374238423942404241424242434244424542464247424842494250425142524253425442554256425742584259426042614262426342644265426642674268426942704271427242734274427542764277427842794280428142824283428442854286428742884289429042914292429342944295429642974298429943004301430243034304430543064307430843094310431143124313431443154316431743184319432043214322432343244325432643274328432943304331433243334334433543364337433843394340434143424343434443454346434743484349435043514352435343544355435643574358435943604361436243634364436543664367436843694370437143724373437443754376437743784379438043814382438343844385438643874388438943904391439243934394439543964397439843994400440144024403440444054406440744084409441044114412441344144415441644174418441944204421442244234424442544264427442844294430443144324433443444354436443744384439444044414442444344444445444644474448444944504451445244534454445544564457445844594460446144624463446444654466446744684469447044714472447344744475447644774478447944804481448244834484448544864487448844894490449144924493449444954496449744984499450045014502450345044505450645074508450945104511451245134514451545164517451845194520452145224523452445254526452745284529453045314532453345344535453645374538453945404541454245434544454545464547454845494550455145524553455445554556455745584559456045614562456345644565456645674568456945704571457245734574457545764577457845794580458145824583458445854586458745884589459045914592459345944595459645974598459946004601460246034604460546064607460846094610461146124613461446154616461746184619462046214622462346244625462646274628462946304631463246334634463546364637463846394640464146424643464446454646464746484649465046514652465346544655465646574658465946604661466246634664466546664667466846694670467146724673467446754676467746784679468046814682468346844685468646874688468946904691469246934694469546964697469846994700470147024703470447054706470747084709471047114712471347144715471647174718471947204721472247234724472547264727472847294730473147324733473447354736473747384739474047414742474347444745474647474748474947504751475247534754475547564757475847594760476147624763476447654766476747684769477047714772477347744775477647774778477947804781478247834784478547864787478847894790479147924793479447954796479747984799480048014802480348044805480648074808480948104811481248134814481548164817481848194820482148224823482448254826482748284829483048314832483348344835483648374838483948404841484248434844484548464847484848494850485148524853485448554856485748584859486048614862486348644865486648674868486948704871487248734874487548764877487848794880488148824883488448854886488748884889489048914892489348944895489648974898489949004901490249034904490549064907490849094910491149124913491449154916491749184919492049214922492349244925492649274928492949304931493249334934493549364937493849394940494149424943494449454946494749484949495049514952495349544955495649574958495949604961496249634964496549664967496849694970497149724973497449754976497749784979498049814982498349844985498649874988498949904991499249934994499549964997499849995000500150025003500450055006500750085009501050115012501350145015501650175018501950205021502250235024502550265027502850295030503150325033503450355036503750385039504050415042504350445045504650475048504950505051505250535054505550565057505850595060506150625063506450655066506750685069507050715072507350745075507650775078507950805081508250835084508550865087508850895090509150925093509450955096509750985099510051015102510351045105510651075108510951105111511251135114511551165117511851195120512151225123512451255126512751285129513051315132513351345135513651375138513951405141514251435144514551465147514851495150515151525153515451555156515751585159516051615162516351645165516651675168516951705171517251735174517551765177517851795180518151825183518451855186518751885189519051915192519351945195519651975198519952005201520252035204520552065207520852095210521152125213521452155216521752185219522052215222522352245225522652275228522952305231523252335234523552365237523852395240524152425243524452455246524752485249525052515252525352545255525652575258525952605261526252635264526552665267526852695270527152725273527452755276527752785279528052815282528352845285528652875288528952905291529252935294529552965297529852995300530153025303530453055306530753085309531053115312531353145315531653175318531953205321532253235324532553265327532853295330533153325333533453355336533753385339534053415342534353445345534653475348534953505351535253535354535553565357535853595360536153625363536453655366536753685369537053715372537353745375537653775378537953805381538253835384538553865387538853895390539153925393539453955396539753985399540054015402540354045405540654075408540954105411541254135414541554165417541854195420542154225423542454255426542754285429543054315432543354345435543654375438543954405441544254435444544554465447544854495450545154525453545454555456545754585459546054615462546354645465546654675468546954705471547254735474547554765477547854795480548154825483548454855486548754885489549054915492549354945495549654975498549955005501550255035504550555065507550855095510551155125513551455155516551755185519552055215522552355245525552655275528552955305531553255335534553555365537553855395540554155425543554455455546554755485549555055515552555355545555555655575558555955605561556255635564556555665567556855695570557155725573557455755576557755785579558055815582558355845585558655875588558955905591559255935594559555965597559855995600560156025603560456055606560756085609561056115612561356145615561656175618561956205621562256235624562556265627562856295630563156325633563456355636563756385639564056415642564356445645564656475648564956505651565256535654565556565657565856595660566156625663566456655666566756685669567056715672567356745675567656775678567956805681568256835684568556865687568856895690569156925693569456955696569756985699570057015702570357045705570657075708570957105711571257135714571557165717571857195720572157225723572457255726572757285729573057315732573357345735573657375738573957405741574257435744574557465747574857495750575157525753575457555756575757585759576057615762576357645765576657675768576957705771577257735774577557765777577857795780578157825783578457855786578757885789579057915792579357945795579657975798579958005801580258035804580558065807580858095810581158125813581458155816581758185819582058215822582358245825582658275828582958305831583258335834583558365837583858395840584158425843584458455846584758485849585058515852585358545855585658575858585958605861586258635864586558665867586858695870587158725873587458755876587758785879588058815882588358845885588658875888588958905891589258935894589558965897589858995900590159025903590459055906590759085909591059115912591359145915591659175918591959205921592259235924592559265927592859295930593159325933593459355936593759385939594059415942594359445945594659475948594959505951595259535954595559565957595859595960596159625963596459655966596759685969597059715972597359745975597659775978597959805981598259835984598559865987598859895990599159925993599459955996599759985999600060016002600360046005600660076008600960106011601260136014601560166017601860196020602160226023602460256026602760286029603060316032603360346035603660376038603960406041604260436044604560466047604860496050605160526053605460556056605760586059606060616062606360646065606660676068606960706071607260736074607560766077607860796080608160826083608460856086608760886089609060916092609360946095609660976098609961006101610261036104610561066107610861096110611161126113611461156116611761186119612061216122612361246125612661276128612961306131613261336134613561366137613861396140614161426143614461456146614761486149615061516152615361546155615661576158615961606161616261636164616561666167616861696170617161726173617461756176617761786179618061816182618361846185618661876188618961906191619261936194619561966197619861996200620162026203620462056206620762086209621062116212621362146215621662176218621962206221622262236224622562266227622862296230623162326233623462356236623762386239624062416242624362446245624662476248624962506251625262536254625562566257625862596260626162626263626462656266626762686269627062716272627362746275627662776278627962806281628262836284628562866287628862896290629162926293629462956296629762986299630063016302630363046305630663076308630963106311631263136314631563166317631863196320632163226323632463256326632763286329633063316332633363346335633663376338633963406341634263436344634563466347634863496350635163526353635463556356635763586359636063616362636363646365636663676368636963706371637263736374637563766377637863796380638163826383638463856386638763886389639063916392639363946395639663976398639964006401640264036404640564066407640864096410641164126413641464156416641764186419642064216422642364246425642664276428642964306431643264336434643564366437643864396440644164426443644464456446644764486449645064516452645364546455645664576458645964606461646264636464646564666467646864696470647164726473647464756476647764786479648064816482648364846485648664876488648964906491649264936494649564966497649864996500650165026503650465056506650765086509651065116512651365146515651665176518651965206521652265236524652565266527652865296530653165326533653465356536653765386539654065416542654365446545654665476548654965506551655265536554655565566557655865596560656165626563656465656566656765686569657065716572657365746575657665776578657965806581658265836584658565866587658865896590659165926593659465956596659765986599660066016602660366046605660666076608660966106611661266136614661566166617661866196620662166226623662466256626662766286629663066316632663366346635663666376638663966406641664266436644664566466647664866496650665166526653665466556656665766586659666066616662666366646665666666676668666966706671667266736674667566766677667866796680668166826683668466856686668766886689669066916692669366946695669666976698669967006701670267036704670567066707670867096710671167126713671467156716671767186719672067216722672367246725672667276728672967306731673267336734673567366737673867396740674167426743674467456746674767486749675067516752675367546755675667576758675967606761676267636764676567666767676867696770677167726773677467756776677767786779678067816782678367846785678667876788678967906791679267936794679567966797679867996800680168026803680468056806680768086809681068116812681368146815681668176818681968206821682268236824682568266827682868296830683168326833683468356836683768386839684068416842684368446845684668476848684968506851685268536854685568566857685868596860686168626863686468656866686768686869687068716872687368746875687668776878687968806881688268836884688568866887688868896890689168926893689468956896689768986899690069016902690369046905690669076908690969106911691269136914691569166917691869196920692169226923692469256926692769286929693069316932693369346935693669376938693969406941694269436944694569466947694869496950695169526953695469556956695769586959696069616962696369646965696669676968696969706971697269736974697569766977697869796980698169826983698469856986698769886989699069916992699369946995699669976998699970007001700270037004700570067007700870097010701170127013701470157016701770187019702070217022702370247025702670277028702970307031703270337034703570367037703870397040704170427043704470457046704770487049705070517052705370547055705670577058705970607061706270637064706570667067706870697070707170727073707470757076707770787079708070817082708370847085708670877088708970907091709270937094709570967097709870997100710171027103710471057106710771087109711071117112711371147115711671177118711971207121712271237124712571267127712871297130713171327133713471357136713771387139714071417142714371447145714671477148714971507151715271537154715571567157715871597160716171627163716471657166716771687169717071717172717371747175717671777178717971807181718271837184718571867187718871897190719171927193719471957196719771987199720072017202720372047205720672077208720972107211721272137214721572167217721872197220722172227223722472257226722772287229723072317232723372347235723672377238723972407241724272437244724572467247724872497250725172527253725472557256725772587259726072617262726372647265726672677268726972707271727272737274727572767277727872797280728172827283728472857286728772887289729072917292729372947295729672977298729973007301730273037304730573067307730873097310731173127313731473157316731773187319732073217322732373247325732673277328732973307331733273337334733573367337733873397340734173427343734473457346734773487349735073517352735373547355735673577358735973607361736273637364736573667367736873697370737173727373737473757376737773787379738073817382738373847385738673877388738973907391739273937394739573967397739873997400740174027403740474057406740774087409741074117412741374147415741674177418741974207421742274237424742574267427742874297430743174327433743474357436743774387439744074417442744374447445744674477448744974507451745274537454745574567457745874597460746174627463746474657466746774687469747074717472747374747475747674777478747974807481748274837484748574867487748874897490749174927493749474957496749774987499750075017502750375047505750675077508750975107511751275137514751575167517751875197520752175227523752475257526752775287529753075317532753375347535753675377538753975407541754275437544754575467547754875497550755175527553755475557556755775587559756075617562756375647565756675677568756975707571757275737574757575767577757875797580758175827583758475857586758775887589759075917592759375947595759675977598759976007601760276037604760576067607760876097610761176127613761476157616761776187619762076217622762376247625762676277628762976307631763276337634763576367637763876397640764176427643764476457646764776487649765076517652765376547655765676577658765976607661766276637664766576667667766876697670767176727673767476757676767776787679768076817682768376847685768676877688768976907691769276937694769576967697769876997700770177027703770477057706770777087709771077117712771377147715771677177718771977207721772277237724772577267727772877297730773177327733773477357736773777387739774077417742774377447745774677477748774977507751775277537754775577567757775877597760776177627763776477657766776777687769777077717772777377747775777677777778777977807781778277837784778577867787778877897790779177927793779477957796779777987799780078017802780378047805780678077808780978107811781278137814781578167817781878197820782178227823782478257826782778287829783078317832783378347835783678377838783978407841784278437844784578467847784878497850785178527853785478557856785778587859786078617862786378647865786678677868786978707871787278737874787578767877787878797880788178827883788478857886788778887889789078917892789378947895789678977898789979007901790279037904790579067907790879097910791179127913791479157916791779187919792079217922792379247925792679277928792979307931793279337934793579367937793879397940794179427943794479457946794779487949795079517952795379547955795679577958795979607961796279637964796579667967796879697970797179727973797479757976797779787979798079817982798379847985798679877988798979907991799279937994799579967997799879998000800180028003800480058006800780088009801080118012801380148015801680178018801980208021802280238024802580268027802880298030803180328033803480358036803780388039804080418042804380448045804680478048804980508051805280538054805580568057805880598060806180628063806480658066806780688069807080718072807380748075807680778078807980808081808280838084808580868087808880898090809180928093809480958096809780988099810081018102810381048105810681078108810981108111811281138114811581168117811881198120812181228123812481258126812781288129813081318132813381348135813681378138813981408141814281438144814581468147814881498150815181528153815481558156815781588159816081618162816381648165816681678168816981708171817281738174817581768177817881798180818181828183818481858186818781888189819081918192819381948195819681978198819982008201820282038204820582068207820882098210821182128213821482158216821782188219822082218222822382248225822682278228822982308231823282338234823582368237823882398240824182428243824482458246824782488249825082518252825382548255825682578258825982608261826282638264826582668267826882698270827182728273827482758276827782788279828082818282828382848285828682878288828982908291829282938294829582968297829882998300830183028303830483058306830783088309831083118312831383148315831683178318831983208321832283238324832583268327832883298330833183328333833483358336833783388339834083418342834383448345834683478348834983508351835283538354835583568357835883598360836183628363836483658366836783688369837083718372837383748375837683778378837983808381838283838384838583868387838883898390839183928393839483958396839783988399840084018402840384048405840684078408840984108411841284138414841584168417841884198420842184228423842484258426842784288429843084318432843384348435843684378438843984408441844284438444844584468447844884498450845184528453845484558456845784588459846084618462846384648465846684678468846984708471847284738474847584768477847884798480848184828483848484858486848784888489849084918492849384948495849684978498849985008501850285038504850585068507850885098510851185128513851485158516851785188519852085218522852385248525852685278528852985308531853285338534853585368537853885398540854185428543854485458546854785488549855085518552855385548555855685578558855985608561856285638564856585668567856885698570857185728573857485758576857785788579858085818582858385848585858685878588858985908591859285938594859585968597859885998600860186028603860486058606860786088609861086118612861386148615861686178618861986208621862286238624862586268627862886298630863186328633863486358636863786388639864086418642864386448645864686478648864986508651865286538654865586568657865886598660866186628663866486658666866786688669867086718672867386748675867686778678867986808681868286838684868586868687868886898690869186928693869486958696869786988699870087018702870387048705870687078708870987108711871287138714871587168717871887198720872187228723872487258726872787288729873087318732873387348735873687378738873987408741874287438744874587468747874887498750875187528753875487558756875787588759876087618762876387648765876687678768876987708771877287738774877587768777877887798780878187828783878487858786878787888789879087918792879387948795879687978798879988008801880288038804880588068807880888098810881188128813881488158816881788188819882088218822882388248825882688278828 |
- <!--{
- "Title": "The Go Programming Language Specification",
- "Subtitle": "Language version go1.23 (June 13, 2024)",
- "Path": "/ref/spec"
- }-->
- <h2 id="Introduction">Introduction</h2>
- <p>
- This is the reference manual for the Go programming language.
- The pre-Go1.18 version, without generics, can be found
- <a href="/doc/go1.17_spec.html">here</a>.
- For more information and other documents, see <a href="/">go.dev</a>.
- </p>
- <p>
- Go is a general-purpose language designed with systems programming
- in mind. It is strongly typed and garbage-collected and has explicit
- support for concurrent programming. Programs are constructed from
- <i>packages</i>, whose properties allow efficient management of
- dependencies.
- </p>
- <p>
- The syntax is compact and simple to parse, allowing for easy analysis
- by automatic tools such as integrated development environments.
- </p>
- <h2 id="Notation">Notation</h2>
- <p>
- The syntax is specified using a
- <a href="https://en.wikipedia.org/wiki/Wirth_syntax_notation">variant</a>
- of Extended Backus-Naur Form (EBNF):
- </p>
- <pre class="grammar">
- Syntax = { Production } .
- Production = production_name "=" [ Expression ] "." .
- Expression = Term { "|" Term } .
- Term = Factor { Factor } .
- Factor = production_name | token [ "…" token ] | Group | Option | Repetition .
- Group = "(" Expression ")" .
- Option = "[" Expression "]" .
- Repetition = "{" Expression "}" .
- </pre>
- <p>
- Productions are expressions constructed from terms and the following
- operators, in increasing precedence:
- </p>
- <pre class="grammar">
- | alternation
- () grouping
- [] option (0 or 1 times)
- {} repetition (0 to n times)
- </pre>
- <p>
- Lowercase production names are used to identify lexical (terminal) tokens.
- Non-terminals are in CamelCase. Lexical tokens are enclosed in
- double quotes <code>""</code> or back quotes <code>``</code>.
- </p>
- <p>
- The form <code>a … b</code> represents the set of characters from
- <code>a</code> through <code>b</code> as alternatives. The horizontal
- ellipsis <code>…</code> is also used elsewhere in the spec to informally denote various
- enumerations or code snippets that are not further specified. The character <code>…</code>
- (as opposed to the three characters <code>...</code>) is not a token of the Go
- language.
- </p>
- <p>
- A link of the form [<a href="#Language_versions">Go 1.xx</a>] indicates that a described
- language feature (or some aspect of it) was changed or added with language version 1.xx and
- thus requires at minimum that language version to build.
- For details, see the <a href="#Language_versions">linked section</a>
- in the <a href="#Appendix">appendix</a>.
- </p>
- <h2 id="Source_code_representation">Source code representation</h2>
- <p>
- Source code is Unicode text encoded in
- <a href="https://en.wikipedia.org/wiki/UTF-8">UTF-8</a>. The text is not
- canonicalized, so a single accented code point is distinct from the
- same character constructed from combining an accent and a letter;
- those are treated as two code points. For simplicity, this document
- will use the unqualified term <i>character</i> to refer to a Unicode code point
- in the source text.
- </p>
- <p>
- Each code point is distinct; for instance, uppercase and lowercase letters
- are different characters.
- </p>
- <p>
- Implementation restriction: For compatibility with other tools, a
- compiler may disallow the NUL character (U+0000) in the source text.
- </p>
- <p>
- Implementation restriction: For compatibility with other tools, a
- compiler may ignore a UTF-8-encoded byte order mark
- (U+FEFF) if it is the first Unicode code point in the source text.
- A byte order mark may be disallowed anywhere else in the source.
- </p>
- <h3 id="Characters">Characters</h3>
- <p>
- The following terms are used to denote specific Unicode character categories:
- </p>
- <pre class="ebnf">
- newline = /* the Unicode code point U+000A */ .
- unicode_char = /* an arbitrary Unicode code point except newline */ .
- unicode_letter = /* a Unicode code point categorized as "Letter" */ .
- unicode_digit = /* a Unicode code point categorized as "Number, decimal digit" */ .
- </pre>
- <p>
- In <a href="https://www.unicode.org/versions/Unicode8.0.0/">The Unicode Standard 8.0</a>,
- Section 4.5 "General Category" defines a set of character categories.
- Go treats all characters in any of the Letter categories Lu, Ll, Lt, Lm, or Lo
- as Unicode letters, and those in the Number category Nd as Unicode digits.
- </p>
- <h3 id="Letters_and_digits">Letters and digits</h3>
- <p>
- The underscore character <code>_</code> (U+005F) is considered a lowercase letter.
- </p>
- <pre class="ebnf">
- letter = unicode_letter | "_" .
- decimal_digit = "0" … "9" .
- binary_digit = "0" | "1" .
- octal_digit = "0" … "7" .
- hex_digit = "0" … "9" | "A" … "F" | "a" … "f" .
- </pre>
- <h2 id="Lexical_elements">Lexical elements</h2>
- <h3 id="Comments">Comments</h3>
- <p>
- Comments serve as program documentation. There are two forms:
- </p>
- <ol>
- <li>
- <i>Line comments</i> start with the character sequence <code>//</code>
- and stop at the end of the line.
- </li>
- <li>
- <i>General comments</i> start with the character sequence <code>/*</code>
- and stop with the first subsequent character sequence <code>*/</code>.
- </li>
- </ol>
- <p>
- A comment cannot start inside a <a href="#Rune_literals">rune</a> or
- <a href="#String_literals">string literal</a>, or inside a comment.
- A general comment containing no newlines acts like a space.
- Any other comment acts like a newline.
- </p>
- <h3 id="Tokens">Tokens</h3>
- <p>
- Tokens form the vocabulary of the Go language.
- There are four classes: <i>identifiers</i>, <i>keywords</i>, <i>operators
- and punctuation</i>, and <i>literals</i>. <i>White space</i>, formed from
- spaces (U+0020), horizontal tabs (U+0009),
- carriage returns (U+000D), and newlines (U+000A),
- is ignored except as it separates tokens
- that would otherwise combine into a single token. Also, a newline or end of file
- may trigger the insertion of a <a href="#Semicolons">semicolon</a>.
- While breaking the input into tokens,
- the next token is the longest sequence of characters that form a
- valid token.
- </p>
- <h3 id="Semicolons">Semicolons</h3>
- <p>
- The formal syntax uses semicolons <code>";"</code> as terminators in
- a number of productions. Go programs may omit most of these semicolons
- using the following two rules:
- </p>
- <ol>
- <li>
- When the input is broken into tokens, a semicolon is automatically inserted
- into the token stream immediately after a line's final token if that token is
- <ul>
- <li>an
- <a href="#Identifiers">identifier</a>
- </li>
- <li>an
- <a href="#Integer_literals">integer</a>,
- <a href="#Floating-point_literals">floating-point</a>,
- <a href="#Imaginary_literals">imaginary</a>,
- <a href="#Rune_literals">rune</a>, or
- <a href="#String_literals">string</a> literal
- </li>
- <li>one of the <a href="#Keywords">keywords</a>
- <code>break</code>,
- <code>continue</code>,
- <code>fallthrough</code>, or
- <code>return</code>
- </li>
- <li>one of the <a href="#Operators_and_punctuation">operators and punctuation</a>
- <code>++</code>,
- <code>--</code>,
- <code>)</code>,
- <code>]</code>, or
- <code>}</code>
- </li>
- </ul>
- </li>
- <li>
- To allow complex statements to occupy a single line, a semicolon
- may be omitted before a closing <code>")"</code> or <code>"}"</code>.
- </li>
- </ol>
- <p>
- To reflect idiomatic use, code examples in this document elide semicolons
- using these rules.
- </p>
- <h3 id="Identifiers">Identifiers</h3>
- <p>
- Identifiers name program entities such as variables and types.
- An identifier is a sequence of one or more letters and digits.
- The first character in an identifier must be a letter.
- </p>
- <pre class="ebnf">
- identifier = letter { letter | unicode_digit } .
- </pre>
- <pre>
- a
- _x9
- ThisVariableIsExported
- αβ
- </pre>
- <p>
- Some identifiers are <a href="#Predeclared_identifiers">predeclared</a>.
- </p>
- <h3 id="Keywords">Keywords</h3>
- <p>
- The following keywords are reserved and may not be used as identifiers.
- </p>
- <pre class="grammar">
- break default func interface select
- case defer go map struct
- chan else goto package switch
- const fallthrough if range type
- continue for import return var
- </pre>
- <h3 id="Operators_and_punctuation">Operators and punctuation</h3>
- <p>
- The following character sequences represent <a href="#Operators">operators</a>
- (including <a href="#Assignment_statements">assignment operators</a>) and punctuation
- [<a href="#Go_1.18">Go 1.18</a>]:
- </p>
- <pre class="grammar">
- + & += &= && == != ( )
- - | -= |= || < <= [ ]
- * ^ *= ^= <- > >= { }
- / << /= <<= ++ = := , ;
- % >> %= >>= -- ! ... . :
- &^ &^= ~
- </pre>
- <h3 id="Integer_literals">Integer literals</h3>
- <p>
- An integer literal is a sequence of digits representing an
- <a href="#Constants">integer constant</a>.
- An optional prefix sets a non-decimal base: <code>0b</code> or <code>0B</code>
- for binary, <code>0</code>, <code>0o</code>, or <code>0O</code> for octal,
- and <code>0x</code> or <code>0X</code> for hexadecimal
- [<a href="#Go_1.13">Go 1.13</a>].
- A single <code>0</code> is considered a decimal zero.
- In hexadecimal literals, letters <code>a</code> through <code>f</code>
- and <code>A</code> through <code>F</code> represent values 10 through 15.
- </p>
- <p>
- For readability, an underscore character <code>_</code> may appear after
- a base prefix or between successive digits; such underscores do not change
- the literal's value.
- </p>
- <pre class="ebnf">
- int_lit = decimal_lit | binary_lit | octal_lit | hex_lit .
- decimal_lit = "0" | ( "1" … "9" ) [ [ "_" ] decimal_digits ] .
- binary_lit = "0" ( "b" | "B" ) [ "_" ] binary_digits .
- octal_lit = "0" [ "o" | "O" ] [ "_" ] octal_digits .
- hex_lit = "0" ( "x" | "X" ) [ "_" ] hex_digits .
- decimal_digits = decimal_digit { [ "_" ] decimal_digit } .
- binary_digits = binary_digit { [ "_" ] binary_digit } .
- octal_digits = octal_digit { [ "_" ] octal_digit } .
- hex_digits = hex_digit { [ "_" ] hex_digit } .
- </pre>
- <pre>
- 42
- 4_2
- 0600
- 0_600
- 0o600
- 0O600 // second character is capital letter 'O'
- 0xBadFace
- 0xBad_Face
- 0x_67_7a_2f_cc_40_c6
- 170141183460469231731687303715884105727
- 170_141183_460469_231731_687303_715884_105727
- _42 // an identifier, not an integer literal
- 42_ // invalid: _ must separate successive digits
- 4__2 // invalid: only one _ at a time
- 0_xBadFace // invalid: _ must separate successive digits
- </pre>
- <h3 id="Floating-point_literals">Floating-point literals</h3>
- <p>
- A floating-point literal is a decimal or hexadecimal representation of a
- <a href="#Constants">floating-point constant</a>.
- </p>
- <p>
- A decimal floating-point literal consists of an integer part (decimal digits),
- a decimal point, a fractional part (decimal digits), and an exponent part
- (<code>e</code> or <code>E</code> followed by an optional sign and decimal digits).
- One of the integer part or the fractional part may be elided; one of the decimal point
- or the exponent part may be elided.
- An exponent value exp scales the mantissa (integer and fractional part) by 10<sup>exp</sup>.
- </p>
- <p>
- A hexadecimal floating-point literal consists of a <code>0x</code> or <code>0X</code>
- prefix, an integer part (hexadecimal digits), a radix point, a fractional part (hexadecimal digits),
- and an exponent part (<code>p</code> or <code>P</code> followed by an optional sign and decimal digits).
- One of the integer part or the fractional part may be elided; the radix point may be elided as well,
- but the exponent part is required. (This syntax matches the one given in IEEE 754-2008 §5.12.3.)
- An exponent value exp scales the mantissa (integer and fractional part) by 2<sup>exp</sup>
- [<a href="#Go_1.13">Go 1.13</a>].
- </p>
- <p>
- For readability, an underscore character <code>_</code> may appear after
- a base prefix or between successive digits; such underscores do not change
- the literal value.
- </p>
- <pre class="ebnf">
- float_lit = decimal_float_lit | hex_float_lit .
- decimal_float_lit = decimal_digits "." [ decimal_digits ] [ decimal_exponent ] |
- decimal_digits decimal_exponent |
- "." decimal_digits [ decimal_exponent ] .
- decimal_exponent = ( "e" | "E" ) [ "+" | "-" ] decimal_digits .
- hex_float_lit = "0" ( "x" | "X" ) hex_mantissa hex_exponent .
- hex_mantissa = [ "_" ] hex_digits "." [ hex_digits ] |
- [ "_" ] hex_digits |
- "." hex_digits .
- hex_exponent = ( "p" | "P" ) [ "+" | "-" ] decimal_digits .
- </pre>
- <pre>
- 0.
- 72.40
- 072.40 // == 72.40
- 2.71828
- 1.e+0
- 6.67428e-11
- 1E6
- .25
- .12345E+5
- 1_5. // == 15.0
- 0.15e+0_2 // == 15.0
- 0x1p-2 // == 0.25
- 0x2.p10 // == 2048.0
- 0x1.Fp+0 // == 1.9375
- 0X.8p-0 // == 0.5
- 0X_1FFFP-16 // == 0.1249847412109375
- 0x15e-2 // == 0x15e - 2 (integer subtraction)
- 0x.p1 // invalid: mantissa has no digits
- 1p-2 // invalid: p exponent requires hexadecimal mantissa
- 0x1.5e-2 // invalid: hexadecimal mantissa requires p exponent
- 1_.5 // invalid: _ must separate successive digits
- 1._5 // invalid: _ must separate successive digits
- 1.5_e1 // invalid: _ must separate successive digits
- 1.5e_1 // invalid: _ must separate successive digits
- 1.5e1_ // invalid: _ must separate successive digits
- </pre>
- <h3 id="Imaginary_literals">Imaginary literals</h3>
- <p>
- An imaginary literal represents the imaginary part of a
- <a href="#Constants">complex constant</a>.
- It consists of an <a href="#Integer_literals">integer</a> or
- <a href="#Floating-point_literals">floating-point</a> literal
- followed by the lowercase letter <code>i</code>.
- The value of an imaginary literal is the value of the respective
- integer or floating-point literal multiplied by the imaginary unit <i>i</i>
- [<a href="#Go_1.13">Go 1.13</a>]
- </p>
- <pre class="ebnf">
- imaginary_lit = (decimal_digits | int_lit | float_lit) "i" .
- </pre>
- <p>
- For backward compatibility, an imaginary literal's integer part consisting
- entirely of decimal digits (and possibly underscores) is considered a decimal
- integer, even if it starts with a leading <code>0</code>.
- </p>
- <pre>
- 0i
- 0123i // == 123i for backward-compatibility
- 0o123i // == 0o123 * 1i == 83i
- 0xabci // == 0xabc * 1i == 2748i
- 0.i
- 2.71828i
- 1.e+0i
- 6.67428e-11i
- 1E6i
- .25i
- .12345E+5i
- 0x1p-2i // == 0x1p-2 * 1i == 0.25i
- </pre>
- <h3 id="Rune_literals">Rune literals</h3>
- <p>
- A rune literal represents a <a href="#Constants">rune constant</a>,
- an integer value identifying a Unicode code point.
- A rune literal is expressed as one or more characters enclosed in single quotes,
- as in <code>'x'</code> or <code>'\n'</code>.
- Within the quotes, any character may appear except newline and unescaped single
- quote. A single quoted character represents the Unicode value
- of the character itself,
- while multi-character sequences beginning with a backslash encode
- values in various formats.
- </p>
- <p>
- The simplest form represents the single character within the quotes;
- since Go source text is Unicode characters encoded in UTF-8, multiple
- UTF-8-encoded bytes may represent a single integer value. For
- instance, the literal <code>'a'</code> holds a single byte representing
- a literal <code>a</code>, Unicode U+0061, value <code>0x61</code>, while
- <code>'ä'</code> holds two bytes (<code>0xc3</code> <code>0xa4</code>) representing
- a literal <code>a</code>-dieresis, U+00E4, value <code>0xe4</code>.
- </p>
- <p>
- Several backslash escapes allow arbitrary values to be encoded as
- ASCII text. There are four ways to represent the integer value
- as a numeric constant: <code>\x</code> followed by exactly two hexadecimal
- digits; <code>\u</code> followed by exactly four hexadecimal digits;
- <code>\U</code> followed by exactly eight hexadecimal digits, and a
- plain backslash <code>\</code> followed by exactly three octal digits.
- In each case the value of the literal is the value represented by
- the digits in the corresponding base.
- </p>
- <p>
- Although these representations all result in an integer, they have
- different valid ranges. Octal escapes must represent a value between
- 0 and 255 inclusive. Hexadecimal escapes satisfy this condition
- by construction. The escapes <code>\u</code> and <code>\U</code>
- represent Unicode code points so within them some values are illegal,
- in particular those above <code>0x10FFFF</code> and surrogate halves.
- </p>
- <p>
- After a backslash, certain single-character escapes represent special values:
- </p>
- <pre class="grammar">
- \a U+0007 alert or bell
- \b U+0008 backspace
- \f U+000C form feed
- \n U+000A line feed or newline
- \r U+000D carriage return
- \t U+0009 horizontal tab
- \v U+000B vertical tab
- \\ U+005C backslash
- \' U+0027 single quote (valid escape only within rune literals)
- \" U+0022 double quote (valid escape only within string literals)
- </pre>
- <p>
- An unrecognized character following a backslash in a rune literal is illegal.
- </p>
- <pre class="ebnf">
- rune_lit = "'" ( unicode_value | byte_value ) "'" .
- unicode_value = unicode_char | little_u_value | big_u_value | escaped_char .
- byte_value = octal_byte_value | hex_byte_value .
- octal_byte_value = `\` octal_digit octal_digit octal_digit .
- hex_byte_value = `\` "x" hex_digit hex_digit .
- little_u_value = `\` "u" hex_digit hex_digit hex_digit hex_digit .
- big_u_value = `\` "U" hex_digit hex_digit hex_digit hex_digit
- hex_digit hex_digit hex_digit hex_digit .
- escaped_char = `\` ( "a" | "b" | "f" | "n" | "r" | "t" | "v" | `\` | "'" | `"` ) .
- </pre>
- <pre>
- 'a'
- 'ä'
- '本'
- '\t'
- '\000'
- '\007'
- '\377'
- '\x07'
- '\xff'
- '\u12e4'
- '\U00101234'
- '\'' // rune literal containing single quote character
- 'aa' // illegal: too many characters
- '\k' // illegal: k is not recognized after a backslash
- '\xa' // illegal: too few hexadecimal digits
- '\0' // illegal: too few octal digits
- '\400' // illegal: octal value over 255
- '\uDFFF' // illegal: surrogate half
- '\U00110000' // illegal: invalid Unicode code point
- </pre>
- <h3 id="String_literals">String literals</h3>
- <p>
- A string literal represents a <a href="#Constants">string constant</a>
- obtained from concatenating a sequence of characters. There are two forms:
- raw string literals and interpreted string literals.
- </p>
- <p>
- Raw string literals are character sequences between back quotes, as in
- <code>`foo`</code>. Within the quotes, any character may appear except
- back quote. The value of a raw string literal is the
- string composed of the uninterpreted (implicitly UTF-8-encoded) characters
- between the quotes;
- in particular, backslashes have no special meaning and the string may
- contain newlines.
- Carriage return characters ('\r') inside raw string literals
- are discarded from the raw string value.
- </p>
- <p>
- Interpreted string literals are character sequences between double
- quotes, as in <code>"bar"</code>.
- Within the quotes, any character may appear except newline and unescaped double quote.
- The text between the quotes forms the
- value of the literal, with backslash escapes interpreted as they
- are in <a href="#Rune_literals">rune literals</a> (except that <code>\'</code> is illegal and
- <code>\"</code> is legal), with the same restrictions.
- The three-digit octal (<code>\</code><i>nnn</i>)
- and two-digit hexadecimal (<code>\x</code><i>nn</i>) escapes represent individual
- <i>bytes</i> of the resulting string; all other escapes represent
- the (possibly multi-byte) UTF-8 encoding of individual <i>characters</i>.
- Thus inside a string literal <code>\377</code> and <code>\xFF</code> represent
- a single byte of value <code>0xFF</code>=255, while <code>ÿ</code>,
- <code>\u00FF</code>, <code>\U000000FF</code> and <code>\xc3\xbf</code> represent
- the two bytes <code>0xc3</code> <code>0xbf</code> of the UTF-8 encoding of character
- U+00FF.
- </p>
- <pre class="ebnf">
- string_lit = raw_string_lit | interpreted_string_lit .
- raw_string_lit = "`" { unicode_char | newline } "`" .
- interpreted_string_lit = `"` { unicode_value | byte_value } `"` .
- </pre>
- <pre>
- `abc` // same as "abc"
- `\n
- \n` // same as "\\n\n\\n"
- "\n"
- "\"" // same as `"`
- "Hello, world!\n"
- "日本語"
- "\u65e5本\U00008a9e"
- "\xff\u00FF"
- "\uD800" // illegal: surrogate half
- "\U00110000" // illegal: invalid Unicode code point
- </pre>
- <p>
- These examples all represent the same string:
- </p>
- <pre>
- "日本語" // UTF-8 input text
- `日本語` // UTF-8 input text as a raw literal
- "\u65e5\u672c\u8a9e" // the explicit Unicode code points
- "\U000065e5\U0000672c\U00008a9e" // the explicit Unicode code points
- "\xe6\x97\xa5\xe6\x9c\xac\xe8\xaa\x9e" // the explicit UTF-8 bytes
- </pre>
- <p>
- If the source code represents a character as two code points, such as
- a combining form involving an accent and a letter, the result will be
- an error if placed in a rune literal (it is not a single code
- point), and will appear as two code points if placed in a string
- literal.
- </p>
- <h2 id="Constants">Constants</h2>
- <p>There are <i>boolean constants</i>,
- <i>rune constants</i>,
- <i>integer constants</i>,
- <i>floating-point constants</i>, <i>complex constants</i>,
- and <i>string constants</i>. Rune, integer, floating-point,
- and complex constants are
- collectively called <i>numeric constants</i>.
- </p>
- <p>
- A constant value is represented by a
- <a href="#Rune_literals">rune</a>,
- <a href="#Integer_literals">integer</a>,
- <a href="#Floating-point_literals">floating-point</a>,
- <a href="#Imaginary_literals">imaginary</a>,
- or
- <a href="#String_literals">string</a> literal,
- an identifier denoting a constant,
- a <a href="#Constant_expressions">constant expression</a>,
- a <a href="#Conversions">conversion</a> with a result that is a constant, or
- the result value of some built-in functions such as
- <code>min</code> or <code>max</code> applied to constant arguments,
- <code>unsafe.Sizeof</code> applied to <a href="#Package_unsafe">certain values</a>,
- <code>cap</code> or <code>len</code> applied to
- <a href="#Length_and_capacity">some expressions</a>,
- <code>real</code> and <code>imag</code> applied to a complex constant
- and <code>complex</code> applied to numeric constants.
- The boolean truth values are represented by the predeclared constants
- <code>true</code> and <code>false</code>. The predeclared identifier
- <a href="#Iota">iota</a> denotes an integer constant.
- </p>
- <p>
- In general, complex constants are a form of
- <a href="#Constant_expressions">constant expression</a>
- and are discussed in that section.
- </p>
- <p>
- Numeric constants represent exact values of arbitrary precision and do not overflow.
- Consequently, there are no constants denoting the IEEE 754 negative zero, infinity,
- and not-a-number values.
- </p>
- <p>
- Constants may be <a href="#Types">typed</a> or <i>untyped</i>.
- Literal constants, <code>true</code>, <code>false</code>, <code>iota</code>,
- and certain <a href="#Constant_expressions">constant expressions</a>
- containing only untyped constant operands are untyped.
- </p>
- <p>
- A constant may be given a type explicitly by a <a href="#Constant_declarations">constant declaration</a>
- or <a href="#Conversions">conversion</a>, or implicitly when used in a
- <a href="#Variable_declarations">variable declaration</a> or an
- <a href="#Assignment_statements">assignment statement</a> or as an
- operand in an <a href="#Expressions">expression</a>.
- It is an error if the constant value
- cannot be <a href="#Representability">represented</a> as a value of the respective type.
- If the type is a type parameter, the constant is converted into a non-constant
- value of the type parameter.
- </p>
- <p>
- An untyped constant has a <i>default type</i> which is the type to which the
- constant is implicitly converted in contexts where a typed value is required,
- for instance, in a <a href="#Short_variable_declarations">short variable declaration</a>
- such as <code>i := 0</code> where there is no explicit type.
- The default type of an untyped constant is <code>bool</code>, <code>rune</code>,
- <code>int</code>, <code>float64</code>, <code>complex128</code>, or <code>string</code>
- respectively, depending on whether it is a boolean, rune, integer, floating-point,
- complex, or string constant.
- </p>
- <p>
- Implementation restriction: Although numeric constants have arbitrary
- precision in the language, a compiler may implement them using an
- internal representation with limited precision. That said, every
- implementation must:
- </p>
- <ul>
- <li>Represent integer constants with at least 256 bits.</li>
- <li>Represent floating-point constants, including the parts of
- a complex constant, with a mantissa of at least 256 bits
- and a signed binary exponent of at least 16 bits.</li>
- <li>Give an error if unable to represent an integer constant
- precisely.</li>
- <li>Give an error if unable to represent a floating-point or
- complex constant due to overflow.</li>
- <li>Round to the nearest representable constant if unable to
- represent a floating-point or complex constant due to limits
- on precision.</li>
- </ul>
- <p>
- These requirements apply both to literal constants and to the result
- of evaluating <a href="#Constant_expressions">constant
- expressions</a>.
- </p>
- <h2 id="Variables">Variables</h2>
- <p>
- A variable is a storage location for holding a <i>value</i>.
- The set of permissible values is determined by the
- variable's <i><a href="#Types">type</a></i>.
- </p>
- <p>
- A <a href="#Variable_declarations">variable declaration</a>
- or, for function parameters and results, the signature
- of a <a href="#Function_declarations">function declaration</a>
- or <a href="#Function_literals">function literal</a> reserves
- storage for a named variable.
- Calling the built-in function <a href="#Allocation"><code>new</code></a>
- or taking the address of a <a href="#Composite_literals">composite literal</a>
- allocates storage for a variable at run time.
- Such an anonymous variable is referred to via a (possibly implicit)
- <a href="#Address_operators">pointer indirection</a>.
- </p>
- <p>
- <i>Structured</i> variables of <a href="#Array_types">array</a>, <a href="#Slice_types">slice</a>,
- and <a href="#Struct_types">struct</a> types have elements and fields that may
- be <a href="#Address_operators">addressed</a> individually. Each such element
- acts like a variable.
- </p>
- <p>
- The <i>static type</i> (or just <i>type</i>) of a variable is the
- type given in its declaration, the type provided in the
- <code>new</code> call or composite literal, or the type of
- an element of a structured variable.
- Variables of interface type also have a distinct <i>dynamic type</i>,
- which is the (non-interface) type of the value assigned to the variable at run time
- (unless the value is the predeclared identifier <code>nil</code>,
- which has no type).
- The dynamic type may vary during execution but values stored in interface
- variables are always <a href="#Assignability">assignable</a>
- to the static type of the variable.
- </p>
- <pre>
- var x interface{} // x is nil and has static type interface{}
- var v *T // v has value nil, static type *T
- x = 42 // x has value 42 and dynamic type int
- x = v // x has value (*T)(nil) and dynamic type *T
- </pre>
- <p>
- A variable's value is retrieved by referring to the variable in an
- <a href="#Expressions">expression</a>; it is the most recent value
- <a href="#Assignment_statements">assigned</a> to the variable.
- If a variable has not yet been assigned a value, its value is the
- <a href="#The_zero_value">zero value</a> for its type.
- </p>
- <h2 id="Types">Types</h2>
- <p>
- A type determines a set of values together with operations and methods specific
- to those values. A type may be denoted by a <i>type name</i>, if it has one, which must be
- followed by <a href="#Instantiations">type arguments</a> if the type is generic.
- A type may also be specified using a <i>type literal</i>, which composes a type
- from existing types.
- </p>
- <pre class="ebnf">
- Type = TypeName [ TypeArgs ] | TypeLit | "(" Type ")" .
- TypeName = identifier | QualifiedIdent .
- TypeArgs = "[" TypeList [ "," ] "]" .
- TypeList = Type { "," Type } .
- TypeLit = ArrayType | StructType | PointerType | FunctionType | InterfaceType |
- SliceType | MapType | ChannelType .
- </pre>
- <p>
- The language <a href="#Predeclared_identifiers">predeclares</a> certain type names.
- Others are introduced with <a href="#Type_declarations">type declarations</a>
- or <a href="#Type_parameter_declarations">type parameter lists</a>.
- <i>Composite types</i>—array, struct, pointer, function,
- interface, slice, map, and channel types—may be constructed using
- type literals.
- </p>
- <p>
- Predeclared types, defined types, and type parameters are called <i>named types</i>.
- An alias denotes a named type if the type given in the alias declaration is a named type.
- </p>
- <h3 id="Boolean_types">Boolean types</h3>
- <p>
- A <i>boolean type</i> represents the set of Boolean truth values
- denoted by the predeclared constants <code>true</code>
- and <code>false</code>. The predeclared boolean type is <code>bool</code>;
- it is a <a href="#Type_definitions">defined type</a>.
- </p>
- <h3 id="Numeric_types">Numeric types</h3>
- <p>
- An <i>integer</i>, <i>floating-point</i>, or <i>complex</i> type
- represents the set of integer, floating-point, or complex values, respectively.
- They are collectively called <i>numeric types</i>.
- The predeclared architecture-independent numeric types are:
- </p>
- <pre class="grammar">
- uint8 the set of all unsigned 8-bit integers (0 to 255)
- uint16 the set of all unsigned 16-bit integers (0 to 65535)
- uint32 the set of all unsigned 32-bit integers (0 to 4294967295)
- uint64 the set of all unsigned 64-bit integers (0 to 18446744073709551615)
- int8 the set of all signed 8-bit integers (-128 to 127)
- int16 the set of all signed 16-bit integers (-32768 to 32767)
- int32 the set of all signed 32-bit integers (-2147483648 to 2147483647)
- int64 the set of all signed 64-bit integers (-9223372036854775808 to 9223372036854775807)
- float32 the set of all IEEE 754 32-bit floating-point numbers
- float64 the set of all IEEE 754 64-bit floating-point numbers
- complex64 the set of all complex numbers with float32 real and imaginary parts
- complex128 the set of all complex numbers with float64 real and imaginary parts
- byte alias for uint8
- rune alias for int32
- </pre>
- <p>
- The value of an <i>n</i>-bit integer is <i>n</i> bits wide and represented using
- <a href="https://en.wikipedia.org/wiki/Two's_complement">two's complement arithmetic</a>.
- </p>
- <p>
- There is also a set of predeclared integer types with implementation-specific sizes:
- </p>
- <pre class="grammar">
- uint either 32 or 64 bits
- int same size as uint
- uintptr an unsigned integer large enough to store the uninterpreted bits of a pointer value
- </pre>
- <p>
- To avoid portability issues all numeric types are <a href="#Type_definitions">defined
- types</a> and thus distinct except
- <code>byte</code>, which is an <a href="#Alias_declarations">alias</a> for <code>uint8</code>, and
- <code>rune</code>, which is an alias for <code>int32</code>.
- Explicit conversions
- are required when different numeric types are mixed in an expression
- or assignment. For instance, <code>int32</code> and <code>int</code>
- are not the same type even though they may have the same size on a
- particular architecture.
- </p>
- <h3 id="String_types">String types</h3>
- <p>
- A <i>string type</i> represents the set of string values.
- A string value is a (possibly empty) sequence of bytes.
- The number of bytes is called the length of the string and is never negative.
- Strings are immutable: once created,
- it is impossible to change the contents of a string.
- The predeclared string type is <code>string</code>;
- it is a <a href="#Type_definitions">defined type</a>.
- </p>
- <p>
- The length of a string <code>s</code> can be discovered using
- the built-in function <a href="#Length_and_capacity"><code>len</code></a>.
- The length is a compile-time constant if the string is a constant.
- A string's bytes can be accessed by integer <a href="#Index_expressions">indices</a>
- 0 through <code>len(s)-1</code>.
- It is illegal to take the address of such an element; if
- <code>s[i]</code> is the <code>i</code>'th byte of a
- string, <code>&s[i]</code> is invalid.
- </p>
- <h3 id="Array_types">Array types</h3>
- <p>
- An array is a numbered sequence of elements of a single
- type, called the element type.
- The number of elements is called the length of the array and is never negative.
- </p>
- <pre class="ebnf">
- ArrayType = "[" ArrayLength "]" ElementType .
- ArrayLength = Expression .
- ElementType = Type .
- </pre>
- <p>
- The length is part of the array's type; it must evaluate to a
- non-negative <a href="#Constants">constant</a>
- <a href="#Representability">representable</a> by a value
- of type <code>int</code>.
- The length of array <code>a</code> can be discovered
- using the built-in function <a href="#Length_and_capacity"><code>len</code></a>.
- The elements can be addressed by integer <a href="#Index_expressions">indices</a>
- 0 through <code>len(a)-1</code>.
- Array types are always one-dimensional but may be composed to form
- multi-dimensional types.
- </p>
- <pre>
- [32]byte
- [2*N] struct { x, y int32 }
- [1000]*float64
- [3][5]int
- [2][2][2]float64 // same as [2]([2]([2]float64))
- </pre>
- <p>
- An array type <code>T</code> may not have an element of type <code>T</code>,
- or of a type containing <code>T</code> as a component, directly or indirectly,
- if those containing types are only array or struct types.
- </p>
- <pre>
- // invalid array types
- type (
- T1 [10]T1 // element type of T1 is T1
- T2 [10]struct{ f T2 } // T2 contains T2 as component of a struct
- T3 [10]T4 // T3 contains T3 as component of a struct in T4
- T4 struct{ f T3 } // T4 contains T4 as component of array T3 in a struct
- )
- // valid array types
- type (
- T5 [10]*T5 // T5 contains T5 as component of a pointer
- T6 [10]func() T6 // T6 contains T6 as component of a function type
- T7 [10]struct{ f []T7 } // T7 contains T7 as component of a slice in a struct
- )
- </pre>
- <h3 id="Slice_types">Slice types</h3>
- <p>
- A slice is a descriptor for a contiguous segment of an <i>underlying array</i> and
- provides access to a numbered sequence of elements from that array.
- A slice type denotes the set of all slices of arrays of its element type.
- The number of elements is called the length of the slice and is never negative.
- The value of an uninitialized slice is <code>nil</code>.
- </p>
- <pre class="ebnf">
- SliceType = "[" "]" ElementType .
- </pre>
- <p>
- The length of a slice <code>s</code> can be discovered by the built-in function
- <a href="#Length_and_capacity"><code>len</code></a>; unlike with arrays it may change during
- execution. The elements can be addressed by integer <a href="#Index_expressions">indices</a>
- 0 through <code>len(s)-1</code>. The slice index of a
- given element may be less than the index of the same element in the
- underlying array.
- </p>
- <p>
- A slice, once initialized, is always associated with an underlying
- array that holds its elements. A slice therefore shares storage
- with its array and with other slices of the same array; by contrast,
- distinct arrays always represent distinct storage.
- </p>
- <p>
- The array underlying a slice may extend past the end of the slice.
- The <i>capacity</i> is a measure of that extent: it is the sum of
- the length of the slice and the length of the array beyond the slice;
- a slice of length up to that capacity can be created by
- <a href="#Slice_expressions"><i>slicing</i></a> a new one from the original slice.
- The capacity of a slice <code>a</code> can be discovered using the
- built-in function <a href="#Length_and_capacity"><code>cap(a)</code></a>.
- </p>
- <p>
- A new, initialized slice value for a given element type <code>T</code> may be
- made using the built-in function
- <a href="#Making_slices_maps_and_channels"><code>make</code></a>,
- which takes a slice type
- and parameters specifying the length and optionally the capacity.
- A slice created with <code>make</code> always allocates a new, hidden array
- to which the returned slice value refers. That is, executing
- </p>
- <pre>
- make([]T, length, capacity)
- </pre>
- <p>
- produces the same slice as allocating an array and <a href="#Slice_expressions">slicing</a>
- it, so these two expressions are equivalent:
- </p>
- <pre>
- make([]int, 50, 100)
- new([100]int)[0:50]
- </pre>
- <p>
- Like arrays, slices are always one-dimensional but may be composed to construct
- higher-dimensional objects.
- With arrays of arrays, the inner arrays are, by construction, always the same length;
- however with slices of slices (or arrays of slices), the inner lengths may vary dynamically.
- Moreover, the inner slices must be initialized individually.
- </p>
- <h3 id="Struct_types">Struct types</h3>
- <p>
- A struct is a sequence of named elements, called fields, each of which has a
- name and a type. Field names may be specified explicitly (IdentifierList) or
- implicitly (EmbeddedField).
- Within a struct, non-<a href="#Blank_identifier">blank</a> field names must
- be <a href="#Uniqueness_of_identifiers">unique</a>.
- </p>
- <pre class="ebnf">
- StructType = "struct" "{" { FieldDecl ";" } "}" .
- FieldDecl = (IdentifierList Type | EmbeddedField) [ Tag ] .
- EmbeddedField = [ "*" ] TypeName [ TypeArgs ] .
- Tag = string_lit .
- </pre>
- <pre>
- // An empty struct.
- struct {}
- // A struct with 6 fields.
- struct {
- x, y int
- u float32
- _ float32 // padding
- A *[]int
- F func()
- }
- </pre>
- <p>
- A field declared with a type but no explicit field name is called an <i>embedded field</i>.
- An embedded field must be specified as
- a type name <code>T</code> or as a pointer to a non-interface type name <code>*T</code>,
- and <code>T</code> itself may not be
- a pointer type. The unqualified type name acts as the field name.
- </p>
- <pre>
- // A struct with four embedded fields of types T1, *T2, P.T3 and *P.T4
- struct {
- T1 // field name is T1
- *T2 // field name is T2
- P.T3 // field name is T3
- *P.T4 // field name is T4
- x, y int // field names are x and y
- }
- </pre>
- <p>
- The following declaration is illegal because field names must be unique
- in a struct type:
- </p>
- <pre>
- struct {
- T // conflicts with embedded field *T and *P.T
- *T // conflicts with embedded field T and *P.T
- *P.T // conflicts with embedded field T and *T
- }
- </pre>
- <p>
- A field or <a href="#Method_declarations">method</a> <code>f</code> of an
- embedded field in a struct <code>x</code> is called <i>promoted</i> if
- <code>x.f</code> is a legal <a href="#Selectors">selector</a> that denotes
- that field or method <code>f</code>.
- </p>
- <p>
- Promoted fields act like ordinary fields
- of a struct except that they cannot be used as field names in
- <a href="#Composite_literals">composite literals</a> of the struct.
- </p>
- <p>
- Given a struct type <code>S</code> and a <a href="#Types">named type</a>
- <code>T</code>, promoted methods are included in the method set of the struct as follows:
- </p>
- <ul>
- <li>
- If <code>S</code> contains an embedded field <code>T</code>,
- the <a href="#Method_sets">method sets</a> of <code>S</code>
- and <code>*S</code> both include promoted methods with receiver
- <code>T</code>. The method set of <code>*S</code> also
- includes promoted methods with receiver <code>*T</code>.
- </li>
- <li>
- If <code>S</code> contains an embedded field <code>*T</code>,
- the method sets of <code>S</code> and <code>*S</code> both
- include promoted methods with receiver <code>T</code> or
- <code>*T</code>.
- </li>
- </ul>
- <p>
- A field declaration may be followed by an optional string literal <i>tag</i>,
- which becomes an attribute for all the fields in the corresponding
- field declaration. An empty tag string is equivalent to an absent tag.
- The tags are made visible through a <a href="/pkg/reflect/#StructTag">reflection interface</a>
- and take part in <a href="#Type_identity">type identity</a> for structs
- but are otherwise ignored.
- </p>
- <pre>
- struct {
- x, y float64 "" // an empty tag string is like an absent tag
- name string "any string is permitted as a tag"
- _ [4]byte "ceci n'est pas un champ de structure"
- }
- // A struct corresponding to a TimeStamp protocol buffer.
- // The tag strings define the protocol buffer field numbers;
- // they follow the convention outlined by the reflect package.
- struct {
- microsec uint64 `protobuf:"1"`
- serverIP6 uint64 `protobuf:"2"`
- }
- </pre>
- <p>
- A struct type <code>T</code> may not contain a field of type <code>T</code>,
- or of a type containing <code>T</code> as a component, directly or indirectly,
- if those containing types are only array or struct types.
- </p>
- <pre>
- // invalid struct types
- type (
- T1 struct{ T1 } // T1 contains a field of T1
- T2 struct{ f [10]T2 } // T2 contains T2 as component of an array
- T3 struct{ T4 } // T3 contains T3 as component of an array in struct T4
- T4 struct{ f [10]T3 } // T4 contains T4 as component of struct T3 in an array
- )
- // valid struct types
- type (
- T5 struct{ f *T5 } // T5 contains T5 as component of a pointer
- T6 struct{ f func() T6 } // T6 contains T6 as component of a function type
- T7 struct{ f [10][]T7 } // T7 contains T7 as component of a slice in an array
- )
- </pre>
- <h3 id="Pointer_types">Pointer types</h3>
- <p>
- A pointer type denotes the set of all pointers to <a href="#Variables">variables</a> of a given
- type, called the <i>base type</i> of the pointer.
- The value of an uninitialized pointer is <code>nil</code>.
- </p>
- <pre class="ebnf">
- PointerType = "*" BaseType .
- BaseType = Type .
- </pre>
- <pre>
- *Point
- *[4]int
- </pre>
- <h3 id="Function_types">Function types</h3>
- <p>
- A function type denotes the set of all functions with the same parameter
- and result types. The value of an uninitialized variable of function type
- is <code>nil</code>.
- </p>
- <pre class="ebnf">
- FunctionType = "func" Signature .
- Signature = Parameters [ Result ] .
- Result = Parameters | Type .
- Parameters = "(" [ ParameterList [ "," ] ] ")" .
- ParameterList = ParameterDecl { "," ParameterDecl } .
- ParameterDecl = [ IdentifierList ] [ "..." ] Type .
- </pre>
- <p>
- Within a list of parameters or results, the names (IdentifierList)
- must either all be present or all be absent. If present, each name
- stands for one item (parameter or result) of the specified type and
- all non-<a href="#Blank_identifier">blank</a> names in the signature
- must be <a href="#Uniqueness_of_identifiers">unique</a>.
- If absent, each type stands for one item of that type.
- Parameter and result
- lists are always parenthesized except that if there is exactly
- one unnamed result it may be written as an unparenthesized type.
- </p>
- <p>
- The final incoming parameter in a function signature may have
- a type prefixed with <code>...</code>.
- A function with such a parameter is called <i>variadic</i> and
- may be invoked with zero or more arguments for that parameter.
- </p>
- <pre>
- func()
- func(x int) int
- func(a, _ int, z float32) bool
- func(a, b int, z float32) (bool)
- func(prefix string, values ...int)
- func(a, b int, z float64, opt ...interface{}) (success bool)
- func(int, int, float64) (float64, *[]int)
- func(n int) func(p *T)
- </pre>
- <h3 id="Interface_types">Interface types</h3>
- <p>
- An interface type defines a <i>type set</i>.
- A variable of interface type can store a value of any type that is in the type
- set of the interface. Such a type is said to
- <a href="#Implementing_an_interface">implement the interface</a>.
- The value of an uninitialized variable of interface type is <code>nil</code>.
- </p>
- <pre class="ebnf">
- InterfaceType = "interface" "{" { InterfaceElem ";" } "}" .
- InterfaceElem = MethodElem | TypeElem .
- MethodElem = MethodName Signature .
- MethodName = identifier .
- TypeElem = TypeTerm { "|" TypeTerm } .
- TypeTerm = Type | UnderlyingType .
- UnderlyingType = "~" Type .
- </pre>
- <p>
- An interface type is specified by a list of <i>interface elements</i>.
- An interface element is either a <i>method</i> or a <i>type element</i>,
- where a type element is a union of one or more <i>type terms</i>.
- A type term is either a single type or a single underlying type.
- </p>
- <h4 id="Basic_interfaces">Basic interfaces</h4>
- <p>
- In its most basic form an interface specifies a (possibly empty) list of methods.
- The type set defined by such an interface is the set of types which implement all of
- those methods, and the corresponding <a href="#Method_sets">method set</a> consists
- exactly of the methods specified by the interface.
- Interfaces whose type sets can be defined entirely by a list of methods are called
- <i>basic interfaces.</i>
- </p>
- <pre>
- // A simple File interface.
- interface {
- Read([]byte) (int, error)
- Write([]byte) (int, error)
- Close() error
- }
- </pre>
- <p>
- The name of each explicitly specified method must be <a href="#Uniqueness_of_identifiers">unique</a>
- and not <a href="#Blank_identifier">blank</a>.
- </p>
- <pre>
- interface {
- String() string
- String() string // illegal: String not unique
- _(x int) // illegal: method must have non-blank name
- }
- </pre>
- <p>
- More than one type may implement an interface.
- For instance, if two types <code>S1</code> and <code>S2</code>
- have the method set
- </p>
- <pre>
- func (p T) Read(p []byte) (n int, err error)
- func (p T) Write(p []byte) (n int, err error)
- func (p T) Close() error
- </pre>
- <p>
- (where <code>T</code> stands for either <code>S1</code> or <code>S2</code>)
- then the <code>File</code> interface is implemented by both <code>S1</code> and
- <code>S2</code>, regardless of what other methods
- <code>S1</code> and <code>S2</code> may have or share.
- </p>
- <p>
- Every type that is a member of the type set of an interface implements that interface.
- Any given type may implement several distinct interfaces.
- For instance, all types implement the <i>empty interface</i> which stands for the set
- of all (non-interface) types:
- </p>
- <pre>
- interface{}
- </pre>
- <p>
- For convenience, the predeclared type <code>any</code> is an alias for the empty interface.
- [<a href="#Go_1.18">Go 1.18</a>]
- </p>
- <p>
- Similarly, consider this interface specification,
- which appears within a <a href="#Type_declarations">type declaration</a>
- to define an interface called <code>Locker</code>:
- </p>
- <pre>
- type Locker interface {
- Lock()
- Unlock()
- }
- </pre>
- <p>
- If <code>S1</code> and <code>S2</code> also implement
- </p>
- <pre>
- func (p T) Lock() { … }
- func (p T) Unlock() { … }
- </pre>
- <p>
- they implement the <code>Locker</code> interface as well
- as the <code>File</code> interface.
- </p>
- <h4 id="Embedded_interfaces">Embedded interfaces</h4>
- <p>
- In a slightly more general form
- an interface <code>T</code> may use a (possibly qualified) interface type
- name <code>E</code> as an interface element. This is called
- <i>embedding</i> interface <code>E</code> in <code>T</code>
- [<a href="#Go_1.14">Go 1.14</a>].
- The type set of <code>T</code> is the <i>intersection</i> of the type sets
- defined by <code>T</code>'s explicitly declared methods and the type sets
- of <code>T</code>’s embedded interfaces.
- In other words, the type set of <code>T</code> is the set of all types that implement all the
- explicitly declared methods of <code>T</code> and also all the methods of
- <code>E</code>
- [<a href="#Go_1.18">Go 1.18</a>].
- </p>
- <pre>
- type Reader interface {
- Read(p []byte) (n int, err error)
- Close() error
- }
- type Writer interface {
- Write(p []byte) (n int, err error)
- Close() error
- }
- // ReadWriter's methods are Read, Write, and Close.
- type ReadWriter interface {
- Reader // includes methods of Reader in ReadWriter's method set
- Writer // includes methods of Writer in ReadWriter's method set
- }
- </pre>
- <p>
- When embedding interfaces, methods with the
- <a href="#Uniqueness_of_identifiers">same</a> names must
- have <a href="#Type_identity">identical</a> signatures.
- </p>
- <pre>
- type ReadCloser interface {
- Reader // includes methods of Reader in ReadCloser's method set
- Close() // illegal: signatures of Reader.Close and Close are different
- }
- </pre>
- <h4 id="General_interfaces">General interfaces</h4>
- <p>
- In their most general form, an interface element may also be an arbitrary type term
- <code>T</code>, or a term of the form <code>~T</code> specifying the underlying type <code>T</code>,
- or a union of terms <code>t<sub>1</sub>|t<sub>2</sub>|…|t<sub>n</sub></code>
- [<a href="#Go_1.18">Go 1.18</a>].
- Together with method specifications, these elements enable the precise
- definition of an interface's type set as follows:
- </p>
- <ul>
- <li>The type set of the empty interface is the set of all non-interface types.
- </li>
- <li>The type set of a non-empty interface is the intersection of the type sets
- of its interface elements.
- </li>
- <li>The type set of a method specification is the set of all non-interface types
- whose method sets include that method.
- </li>
- <li>The type set of a non-interface type term is the set consisting
- of just that type.
- </li>
- <li>The type set of a term of the form <code>~T</code>
- is the set of all types whose underlying type is <code>T</code>.
- </li>
- <li>The type set of a <i>union</i> of terms
- <code>t<sub>1</sub>|t<sub>2</sub>|…|t<sub>n</sub></code>
- is the union of the type sets of the terms.
- </li>
- </ul>
- <p>
- The quantification "the set of all non-interface types" refers not just to all (non-interface)
- types declared in the program at hand, but all possible types in all possible programs, and
- hence is infinite.
- Similarly, given the set of all non-interface types that implement a particular method, the
- intersection of the method sets of those types will contain exactly that method, even if all
- types in the program at hand always pair that method with another method.
- </p>
- <p>
- By construction, an interface's type set never contains an interface type.
- </p>
- <pre>
- // An interface representing only the type int.
- interface {
- int
- }
- // An interface representing all types with underlying type int.
- interface {
- ~int
- }
- // An interface representing all types with underlying type int that implement the String method.
- interface {
- ~int
- String() string
- }
- // An interface representing an empty type set: there is no type that is both an int and a string.
- interface {
- int
- string
- }
- </pre>
- <p>
- In a term of the form <code>~T</code>, the underlying type of <code>T</code>
- must be itself, and <code>T</code> cannot be an interface.
- </p>
- <pre>
- type MyInt int
- interface {
- ~[]byte // the underlying type of []byte is itself
- ~MyInt // illegal: the underlying type of MyInt is not MyInt
- ~error // illegal: error is an interface
- }
- </pre>
- <p>
- Union elements denote unions of type sets:
- </p>
- <pre>
- // The Float interface represents all floating-point types
- // (including any named types whose underlying types are
- // either float32 or float64).
- type Float interface {
- ~float32 | ~float64
- }
- </pre>
- <p>
- The type <code>T</code> in a term of the form <code>T</code> or <code>~T</code> cannot
- be a <a href="#Type_parameter_declarations">type parameter</a>, and the type sets of all
- non-interface terms must be pairwise disjoint (the pairwise intersection of the type sets must be empty).
- Given a type parameter <code>P</code>:
- </p>
- <pre>
- interface {
- P // illegal: P is a type parameter
- int | ~P // illegal: P is a type parameter
- ~int | MyInt // illegal: the type sets for ~int and MyInt are not disjoint (~int includes MyInt)
- float32 | Float // overlapping type sets but Float is an interface
- }
- </pre>
- <p>
- Implementation restriction:
- A union (with more than one term) cannot contain the
- <a href="#Predeclared_identifiers">predeclared identifier</a> <code>comparable</code>
- or interfaces that specify methods, or embed <code>comparable</code> or interfaces
- that specify methods.
- </p>
- <p>
- Interfaces that are not <a href="#Basic_interfaces">basic</a> may only be used as type
- constraints, or as elements of other interfaces used as constraints.
- They cannot be the types of values or variables, or components of other,
- non-interface types.
- </p>
- <pre>
- var x Float // illegal: Float is not a basic interface
- var x interface{} = Float(nil) // illegal
- type Floatish struct {
- f Float // illegal
- }
- </pre>
- <p>
- An interface type <code>T</code> may not embed a type element
- that is, contains, or embeds <code>T</code>, directly or indirectly.
- </p>
- <pre>
- // illegal: Bad may not embed itself
- type Bad interface {
- Bad
- }
- // illegal: Bad1 may not embed itself using Bad2
- type Bad1 interface {
- Bad2
- }
- type Bad2 interface {
- Bad1
- }
- // illegal: Bad3 may not embed a union containing Bad3
- type Bad3 interface {
- ~int | ~string | Bad3
- }
- // illegal: Bad4 may not embed an array containing Bad4 as element type
- type Bad4 interface {
- [10]Bad4
- }
- </pre>
- <h4 id="Implementing_an_interface">Implementing an interface</h4>
- <p>
- A type <code>T</code> implements an interface <code>I</code> if
- </p>
- <ul>
- <li>
- <code>T</code> is not an interface and is an element of the type set of <code>I</code>; or
- </li>
- <li>
- <code>T</code> is an interface and the type set of <code>T</code> is a subset of the
- type set of <code>I</code>.
- </li>
- </ul>
- <p>
- A value of type <code>T</code> implements an interface if <code>T</code>
- implements the interface.
- </p>
- <h3 id="Map_types">Map types</h3>
- <p>
- A map is an unordered group of elements of one type, called the
- element type, indexed by a set of unique <i>keys</i> of another type,
- called the key type.
- The value of an uninitialized map is <code>nil</code>.
- </p>
- <pre class="ebnf">
- MapType = "map" "[" KeyType "]" ElementType .
- KeyType = Type .
- </pre>
- <p>
- The <a href="#Comparison_operators">comparison operators</a>
- <code>==</code> and <code>!=</code> must be fully defined
- for operands of the key type; thus the key type must not be a function, map, or
- slice.
- If the key type is an interface type, these
- comparison operators must be defined for the dynamic key values;
- failure will cause a <a href="#Run_time_panics">run-time panic</a>.
- </p>
- <pre>
- map[string]int
- map[*T]struct{ x, y float64 }
- map[string]interface{}
- </pre>
- <p>
- The number of map elements is called its length.
- For a map <code>m</code>, it can be discovered using the
- built-in function <a href="#Length_and_capacity"><code>len</code></a>
- and may change during execution. Elements may be added during execution
- using <a href="#Assignment_statements">assignments</a> and retrieved with
- <a href="#Index_expressions">index expressions</a>; they may be removed with the
- <a href="#Deletion_of_map_elements"><code>delete</code></a> and
- <a href="#Clear"><code>clear</code></a> built-in function.
- </p>
- <p>
- A new, empty map value is made using the built-in
- function <a href="#Making_slices_maps_and_channels"><code>make</code></a>,
- which takes the map type and an optional capacity hint as arguments:
- </p>
- <pre>
- make(map[string]int)
- make(map[string]int, 100)
- </pre>
- <p>
- The initial capacity does not bound its size:
- maps grow to accommodate the number of items
- stored in them, with the exception of <code>nil</code> maps.
- A <code>nil</code> map is equivalent to an empty map except that no elements
- may be added.
- </p>
- <h3 id="Channel_types">Channel types</h3>
- <p>
- A channel provides a mechanism for
- <a href="#Go_statements">concurrently executing functions</a>
- to communicate by
- <a href="#Send_statements">sending</a> and
- <a href="#Receive_operator">receiving</a>
- values of a specified element type.
- The value of an uninitialized channel is <code>nil</code>.
- </p>
- <pre class="ebnf">
- ChannelType = ( "chan" | "chan" "<-" | "<-" "chan" ) ElementType .
- </pre>
- <p>
- The optional <code><-</code> operator specifies the channel <i>direction</i>,
- <i>send</i> or <i>receive</i>. If a direction is given, the channel is <i>directional</i>,
- otherwise it is <i>bidirectional</i>.
- A channel may be constrained only to send or only to receive by
- <a href="#Assignment_statements">assignment</a> or
- explicit <a href="#Conversions">conversion</a>.
- </p>
- <pre>
- chan T // can be used to send and receive values of type T
- chan<- float64 // can only be used to send float64s
- <-chan int // can only be used to receive ints
- </pre>
- <p>
- The <code><-</code> operator associates with the leftmost <code>chan</code>
- possible:
- </p>
- <pre>
- chan<- chan int // same as chan<- (chan int)
- chan<- <-chan int // same as chan<- (<-chan int)
- <-chan <-chan int // same as <-chan (<-chan int)
- chan (<-chan int)
- </pre>
- <p>
- A new, initialized channel
- value can be made using the built-in function
- <a href="#Making_slices_maps_and_channels"><code>make</code></a>,
- which takes the channel type and an optional <i>capacity</i> as arguments:
- </p>
- <pre>
- make(chan int, 100)
- </pre>
- <p>
- The capacity, in number of elements, sets the size of the buffer in the channel.
- If the capacity is zero or absent, the channel is unbuffered and communication
- succeeds only when both a sender and receiver are ready. Otherwise, the channel
- is buffered and communication succeeds without blocking if the buffer
- is not full (sends) or not empty (receives).
- A <code>nil</code> channel is never ready for communication.
- </p>
- <p>
- A channel may be closed with the built-in function
- <a href="#Close"><code>close</code></a>.
- The multi-valued assignment form of the
- <a href="#Receive_operator">receive operator</a>
- reports whether a received value was sent before
- the channel was closed.
- </p>
- <p>
- A single channel may be used in
- <a href="#Send_statements">send statements</a>,
- <a href="#Receive_operator">receive operations</a>,
- and calls to the built-in functions
- <a href="#Length_and_capacity"><code>cap</code></a> and
- <a href="#Length_and_capacity"><code>len</code></a>
- by any number of goroutines without further synchronization.
- Channels act as first-in-first-out queues.
- For example, if one goroutine sends values on a channel
- and a second goroutine receives them, the values are
- received in the order sent.
- </p>
- <h2 id="Properties_of_types_and_values">Properties of types and values</h2>
- <h3 id="Underlying_types">Underlying types</h3>
- <p>
- Each type <code>T</code> has an <i>underlying type</i>: If <code>T</code>
- is one of the predeclared boolean, numeric, or string types, or a type literal,
- the corresponding underlying type is <code>T</code> itself.
- Otherwise, <code>T</code>'s underlying type is the underlying type of the
- type to which <code>T</code> refers in its declaration.
- For a type parameter that is the underlying type of its
- <a href="#Type_constraints">type constraint</a>, which is always an interface.
- </p>
- <pre>
- type (
- A1 = string
- A2 = A1
- )
- type (
- B1 string
- B2 B1
- B3 []B1
- B4 B3
- )
- func f[P any](x P) { … }
- </pre>
- <p>
- The underlying type of <code>string</code>, <code>A1</code>, <code>A2</code>, <code>B1</code>,
- and <code>B2</code> is <code>string</code>.
- The underlying type of <code>[]B1</code>, <code>B3</code>, and <code>B4</code> is <code>[]B1</code>.
- The underlying type of <code>P</code> is <code>interface{}</code>.
- </p>
- <h3 id="Core_types">Core types</h3>
- <p>
- Each non-interface type <code>T</code> has a <i>core type</i>, which is the same as the
- <a href="#Underlying_types">underlying type</a> of <code>T</code>.
- </p>
- <p>
- An interface <code>T</code> has a core type if one of the following
- conditions is satisfied:
- </p>
- <ol>
- <li>
- There is a single type <code>U</code> which is the <a href="#Underlying_types">underlying type</a>
- of all types in the <a href="#Interface_types">type set</a> of <code>T</code>; or
- </li>
- <li>
- the type set of <code>T</code> contains only <a href="#Channel_types">channel types</a>
- with identical element type <code>E</code>, and all directional channels have the same
- direction.
- </li>
- </ol>
- <p>
- No other interfaces have a core type.
- </p>
- <p>
- The core type of an interface is, depending on the condition that is satisfied, either:
- </p>
- <ol>
- <li>
- the type <code>U</code>; or
- </li>
- <li>
- the type <code>chan E</code> if <code>T</code> contains only bidirectional
- channels, or the type <code>chan<- E</code> or <code><-chan E</code>
- depending on the direction of the directional channels present.
- </li>
- </ol>
- <p>
- By definition, a core type is never a <a href="#Type_definitions">defined type</a>,
- <a href="#Type_parameter_declarations">type parameter</a>, or
- <a href="#Interface_types">interface type</a>.
- </p>
- <p>
- Examples of interfaces with core types:
- </p>
- <pre>
- type Celsius float32
- type Kelvin float32
- interface{ int } // int
- interface{ Celsius|Kelvin } // float32
- interface{ ~chan int } // chan int
- interface{ ~chan int|~chan<- int } // chan<- int
- interface{ ~[]*data; String() string } // []*data
- </pre>
- <p>
- Examples of interfaces without core types:
- </p>
- <pre>
- interface{} // no single underlying type
- interface{ Celsius|float64 } // no single underlying type
- interface{ chan int | chan<- string } // channels have different element types
- interface{ <-chan int | chan<- int } // directional channels have different directions
- </pre>
- <p>
- Some operations (<a href="#Slice_expressions">slice expressions</a>,
- <a href="#Appending_and_copying_slices"><code>append</code> and <code>copy</code></a>)
- rely on a slightly more loose form of core types which accept byte slices and strings.
- Specifically, if there are exactly two types, <code>[]byte</code> and <code>string</code>,
- which are the underlying types of all types in the type set of interface <code>T</code>,
- the core type of <code>T</code> is called <code>bytestring</code>.
- </p>
- <p>
- Examples of interfaces with <code>bytestring</code> core types:
- </p>
- <pre>
- interface{ int } // int (same as ordinary core type)
- interface{ []byte | string } // bytestring
- interface{ ~[]byte | myString } // bytestring
- </pre>
- <p>
- Note that <code>bytestring</code> is not a real type; it cannot be used to declare
- variables or compose other types. It exists solely to describe the behavior of some
- operations that read from a sequence of bytes, which may be a byte slice or a string.
- </p>
- <h3 id="Type_identity">Type identity</h3>
- <p>
- Two types are either <i>identical</i> or <i>different</i>.
- </p>
- <p>
- A <a href="#Types">named type</a> is always different from any other type.
- Otherwise, two types are identical if their <a href="#Types">underlying</a> type literals are
- structurally equivalent; that is, they have the same literal structure and corresponding
- components have identical types. In detail:
- </p>
- <ul>
- <li>Two array types are identical if they have identical element types and
- the same array length.</li>
- <li>Two slice types are identical if they have identical element types.</li>
- <li>Two struct types are identical if they have the same sequence of fields,
- and if corresponding fields have the same names, and identical types,
- and identical tags.
- <a href="#Exported_identifiers">Non-exported</a> field names from different
- packages are always different.</li>
- <li>Two pointer types are identical if they have identical base types.</li>
- <li>Two function types are identical if they have the same number of parameters
- and result values, corresponding parameter and result types are
- identical, and either both functions are variadic or neither is.
- Parameter and result names are not required to match.</li>
- <li>Two interface types are identical if they define the same type set.
- </li>
- <li>Two map types are identical if they have identical key and element types.</li>
- <li>Two channel types are identical if they have identical element types and
- the same direction.</li>
- <li>Two <a href="#Instantiations">instantiated</a> types are identical if
- their defined types and all type arguments are identical.
- </li>
- </ul>
- <p>
- Given the declarations
- </p>
- <pre>
- type (
- A0 = []string
- A1 = A0
- A2 = struct{ a, b int }
- A3 = int
- A4 = func(A3, float64) *A0
- A5 = func(x int, _ float64) *[]string
- B0 A0
- B1 []string
- B2 struct{ a, b int }
- B3 struct{ a, c int }
- B4 func(int, float64) *B0
- B5 func(x int, y float64) *A1
- C0 = B0
- D0[P1, P2 any] struct{ x P1; y P2 }
- E0 = D0[int, string]
- )
- </pre>
- <p>
- these types are identical:
- </p>
- <pre>
- A0, A1, and []string
- A2 and struct{ a, b int }
- A3 and int
- A4, func(int, float64) *[]string, and A5
- B0 and C0
- D0[int, string] and E0
- []int and []int
- struct{ a, b *B5 } and struct{ a, b *B5 }
- func(x int, y float64) *[]string, func(int, float64) (result *[]string), and A5
- </pre>
- <p>
- <code>B0</code> and <code>B1</code> are different because they are new types
- created by distinct <a href="#Type_definitions">type definitions</a>;
- <code>func(int, float64) *B0</code> and <code>func(x int, y float64) *[]string</code>
- are different because <code>B0</code> is different from <code>[]string</code>;
- and <code>P1</code> and <code>P2</code> are different because they are different
- type parameters.
- <code>D0[int, string]</code> and <code>struct{ x int; y string }</code> are
- different because the former is an <a href="#Instantiations">instantiated</a>
- defined type while the latter is a type literal
- (but they are still <a href="#Assignability">assignable</a>).
- </p>
- <h3 id="Assignability">Assignability</h3>
- <p>
- A value <code>x</code> of type <code>V</code> is <i>assignable</i> to a <a href="#Variables">variable</a> of type <code>T</code>
- ("<code>x</code> is assignable to <code>T</code>") if one of the following conditions applies:
- </p>
- <ul>
- <li>
- <code>V</code> and <code>T</code> are identical.
- </li>
- <li>
- <code>V</code> and <code>T</code> have identical
- <a href="#Underlying_types">underlying types</a>
- but are not type parameters and at least one of <code>V</code>
- or <code>T</code> is not a <a href="#Types">named type</a>.
- </li>
- <li>
- <code>V</code> and <code>T</code> are channel types with
- identical element types, <code>V</code> is a bidirectional channel,
- and at least one of <code>V</code> or <code>T</code> is not a <a href="#Types">named type</a>.
- </li>
- <li>
- <code>T</code> is an interface type, but not a type parameter, and
- <code>x</code> <a href="#Implementing_an_interface">implements</a> <code>T</code>.
- </li>
- <li>
- <code>x</code> is the predeclared identifier <code>nil</code> and <code>T</code>
- is a pointer, function, slice, map, channel, or interface type,
- but not a type parameter.
- </li>
- <li>
- <code>x</code> is an untyped <a href="#Constants">constant</a>
- <a href="#Representability">representable</a>
- by a value of type <code>T</code>.
- </li>
- </ul>
- <p>
- Additionally, if <code>x</code>'s type <code>V</code> or <code>T</code> are type parameters, <code>x</code>
- is assignable to a variable of type <code>T</code> if one of the following conditions applies:
- </p>
- <ul>
- <li>
- <code>x</code> is the predeclared identifier <code>nil</code>, <code>T</code> is
- a type parameter, and <code>x</code> is assignable to each type in
- <code>T</code>'s type set.
- </li>
- <li>
- <code>V</code> is not a <a href="#Types">named type</a>, <code>T</code> is
- a type parameter, and <code>x</code> is assignable to each type in
- <code>T</code>'s type set.
- </li>
- <li>
- <code>V</code> is a type parameter and <code>T</code> is not a named type,
- and values of each type in <code>V</code>'s type set are assignable
- to <code>T</code>.
- </li>
- </ul>
- <h3 id="Representability">Representability</h3>
- <p>
- A <a href="#Constants">constant</a> <code>x</code> is <i>representable</i>
- by a value of type <code>T</code>,
- where <code>T</code> is not a <a href="#Type_parameter_declarations">type parameter</a>,
- if one of the following conditions applies:
- </p>
- <ul>
- <li>
- <code>x</code> is in the set of values <a href="#Types">determined</a> by <code>T</code>.
- </li>
- <li>
- <code>T</code> is a <a href="#Numeric_types">floating-point type</a> and <code>x</code> can be rounded to <code>T</code>'s
- precision without overflow. Rounding uses IEEE 754 round-to-even rules but with an IEEE
- negative zero further simplified to an unsigned zero. Note that constant values never result
- in an IEEE negative zero, NaN, or infinity.
- </li>
- <li>
- <code>T</code> is a complex type, and <code>x</code>'s
- <a href="#Complex_numbers">components</a> <code>real(x)</code> and <code>imag(x)</code>
- are representable by values of <code>T</code>'s component type (<code>float32</code> or
- <code>float64</code>).
- </li>
- </ul>
- <p>
- If <code>T</code> is a type parameter,
- <code>x</code> is representable by a value of type <code>T</code> if <code>x</code> is representable
- by a value of each type in <code>T</code>'s type set.
- </p>
- <pre>
- x T x is representable by a value of T because
- 'a' byte 97 is in the set of byte values
- 97 rune rune is an alias for int32, and 97 is in the set of 32-bit integers
- "foo" string "foo" is in the set of string values
- 1024 int16 1024 is in the set of 16-bit integers
- 42.0 byte 42 is in the set of unsigned 8-bit integers
- 1e10 uint64 10000000000 is in the set of unsigned 64-bit integers
- 2.718281828459045 float32 2.718281828459045 rounds to 2.7182817 which is in the set of float32 values
- -1e-1000 float64 -1e-1000 rounds to IEEE -0.0 which is further simplified to 0.0
- 0i int 0 is an integer value
- (42 + 0i) float32 42.0 (with zero imaginary part) is in the set of float32 values
- </pre>
- <pre>
- x T x is not representable by a value of T because
- 0 bool 0 is not in the set of boolean values
- 'a' string 'a' is a rune, it is not in the set of string values
- 1024 byte 1024 is not in the set of unsigned 8-bit integers
- -1 uint16 -1 is not in the set of unsigned 16-bit integers
- 1.1 int 1.1 is not an integer value
- 42i float32 (0 + 42i) is not in the set of float32 values
- 1e1000 float64 1e1000 overflows to IEEE +Inf after rounding
- </pre>
- <h3 id="Method_sets">Method sets</h3>
- <p>
- The <i>method set</i> of a type determines the methods that can be
- <a href="#Calls">called</a> on an <a href="#Operands">operand</a> of that type.
- Every type has a (possibly empty) method set associated with it:
- </p>
- <ul>
- <li>The method set of a <a href="#Type_definitions">defined type</a> <code>T</code> consists of all
- <a href="#Method_declarations">methods</a> declared with receiver type <code>T</code>.
- </li>
- <li>
- The method set of a pointer to a defined type <code>T</code>
- (where <code>T</code> is neither a pointer nor an interface)
- is the set of all methods declared with receiver <code>*T</code> or <code>T</code>.
- </li>
- <li>The method set of an <a href="#Interface_types">interface type</a> is the intersection
- of the method sets of each type in the interface's <a href="#Interface_types">type set</a>
- (the resulting method set is usually just the set of declared methods in the interface).
- </li>
- </ul>
- <p>
- Further rules apply to structs (and pointer to structs) containing embedded fields,
- as described in the section on <a href="#Struct_types">struct types</a>.
- Any other type has an empty method set.
- </p>
- <p>
- In a method set, each method must have a
- <a href="#Uniqueness_of_identifiers">unique</a>
- non-<a href="#Blank_identifier">blank</a> <a href="#MethodName">method name</a>.
- </p>
- <h2 id="Blocks">Blocks</h2>
- <p>
- A <i>block</i> is a possibly empty sequence of declarations and statements
- within matching brace brackets.
- </p>
- <pre class="ebnf">
- Block = "{" StatementList "}" .
- StatementList = { Statement ";" } .
- </pre>
- <p>
- In addition to explicit blocks in the source code, there are implicit blocks:
- </p>
- <ol>
- <li>The <i>universe block</i> encompasses all Go source text.</li>
- <li>Each <a href="#Packages">package</a> has a <i>package block</i> containing all
- Go source text for that package.</li>
- <li>Each file has a <i>file block</i> containing all Go source text
- in that file.</li>
- <li>Each <a href="#If_statements">"if"</a>,
- <a href="#For_statements">"for"</a>, and
- <a href="#Switch_statements">"switch"</a>
- statement is considered to be in its own implicit block.</li>
- <li>Each clause in a <a href="#Switch_statements">"switch"</a>
- or <a href="#Select_statements">"select"</a> statement
- acts as an implicit block.</li>
- </ol>
- <p>
- Blocks nest and influence <a href="#Declarations_and_scope">scoping</a>.
- </p>
- <h2 id="Declarations_and_scope">Declarations and scope</h2>
- <p>
- A <i>declaration</i> binds a non-<a href="#Blank_identifier">blank</a> identifier to a
- <a href="#Constant_declarations">constant</a>,
- <a href="#Type_declarations">type</a>,
- <a href="#Type_parameter_declarations">type parameter</a>,
- <a href="#Variable_declarations">variable</a>,
- <a href="#Function_declarations">function</a>,
- <a href="#Labeled_statements">label</a>, or
- <a href="#Import_declarations">package</a>.
- Every identifier in a program must be declared.
- No identifier may be declared twice in the same block, and
- no identifier may be declared in both the file and package block.
- </p>
- <p>
- The <a href="#Blank_identifier">blank identifier</a> may be used like any other identifier
- in a declaration, but it does not introduce a binding and thus is not declared.
- In the package block, the identifier <code>init</code> may only be used for
- <a href="#Package_initialization"><code>init</code> function</a> declarations,
- and like the blank identifier it does not introduce a new binding.
- </p>
- <pre class="ebnf">
- Declaration = ConstDecl | TypeDecl | VarDecl .
- TopLevelDecl = Declaration | FunctionDecl | MethodDecl .
- </pre>
- <p>
- The <i>scope</i> of a declared identifier is the extent of source text in which
- the identifier denotes the specified constant, type, variable, function, label, or package.
- </p>
- <p>
- Go is lexically scoped using <a href="#Blocks">blocks</a>:
- </p>
- <ol>
- <li>The scope of a <a href="#Predeclared_identifiers">predeclared identifier</a> is the universe block.</li>
- <li>The scope of an identifier denoting a constant, type, variable,
- or function (but not method) declared at top level (outside any
- function) is the package block.</li>
- <li>The scope of the package name of an imported package is the file block
- of the file containing the import declaration.</li>
- <li>The scope of an identifier denoting a method receiver, function parameter,
- or result variable is the function body.</li>
- <li>The scope of an identifier denoting a type parameter of a function
- or declared by a method receiver begins after the name of the function
- and ends at the end of the function body.</li>
- <li>The scope of an identifier denoting a type parameter of a type
- begins after the name of the type and ends at the end
- of the TypeSpec.</li>
- <li>The scope of a constant or variable identifier declared
- inside a function begins at the end of the ConstSpec or VarSpec
- (ShortVarDecl for short variable declarations)
- and ends at the end of the innermost containing block.</li>
- <li>The scope of a type identifier declared inside a function
- begins at the identifier in the TypeSpec
- and ends at the end of the innermost containing block.</li>
- </ol>
- <p>
- An identifier declared in a block may be redeclared in an inner block.
- While the identifier of the inner declaration is in scope, it denotes
- the entity declared by the inner declaration.
- </p>
- <p>
- The <a href="#Package_clause">package clause</a> is not a declaration; the package name
- does not appear in any scope. Its purpose is to identify the files belonging
- to the same <a href="#Packages">package</a> and to specify the default package name for import
- declarations.
- </p>
- <h3 id="Label_scopes">Label scopes</h3>
- <p>
- Labels are declared by <a href="#Labeled_statements">labeled statements</a> and are
- used in the <a href="#Break_statements">"break"</a>,
- <a href="#Continue_statements">"continue"</a>, and
- <a href="#Goto_statements">"goto"</a> statements.
- It is illegal to define a label that is never used.
- In contrast to other identifiers, labels are not block scoped and do
- not conflict with identifiers that are not labels. The scope of a label
- is the body of the function in which it is declared and excludes
- the body of any nested function.
- </p>
- <h3 id="Blank_identifier">Blank identifier</h3>
- <p>
- The <i>blank identifier</i> is represented by the underscore character <code>_</code>.
- It serves as an anonymous placeholder instead of a regular (non-blank)
- identifier and has special meaning in <a href="#Declarations_and_scope">declarations</a>,
- as an <a href="#Operands">operand</a>, and in <a href="#Assignment_statements">assignment statements</a>.
- </p>
- <h3 id="Predeclared_identifiers">Predeclared identifiers</h3>
- <p>
- The following identifiers are implicitly declared in the
- <a href="#Blocks">universe block</a>
- [<a href="#Go_1.18">Go 1.18</a>]
- [<a href="#Go_1.21">Go 1.21</a>]:
- </p>
- <pre class="grammar">
- Types:
- any bool byte comparable
- complex64 complex128 error float32 float64
- int int8 int16 int32 int64 rune string
- uint uint8 uint16 uint32 uint64 uintptr
- Constants:
- true false iota
- Zero value:
- nil
- Functions:
- append cap clear close complex copy delete imag len
- make max min new panic print println real recover
- </pre>
- <h3 id="Exported_identifiers">Exported identifiers</h3>
- <p>
- An identifier may be <i>exported</i> to permit access to it from another package.
- An identifier is exported if both:
- </p>
- <ol>
- <li>the first character of the identifier's name is a Unicode uppercase
- letter (Unicode character category Lu); and</li>
- <li>the identifier is declared in the <a href="#Blocks">package block</a>
- or it is a <a href="#Struct_types">field name</a> or
- <a href="#MethodName">method name</a>.</li>
- </ol>
- <p>
- All other identifiers are not exported.
- </p>
- <h3 id="Uniqueness_of_identifiers">Uniqueness of identifiers</h3>
- <p>
- Given a set of identifiers, an identifier is called <i>unique</i> if it is
- <i>different</i> from every other in the set.
- Two identifiers are different if they are spelled differently, or if they
- appear in different <a href="#Packages">packages</a> and are not
- <a href="#Exported_identifiers">exported</a>. Otherwise, they are the same.
- </p>
- <h3 id="Constant_declarations">Constant declarations</h3>
- <p>
- A constant declaration binds a list of identifiers (the names of
- the constants) to the values of a list of <a href="#Constant_expressions">constant expressions</a>.
- The number of identifiers must be equal
- to the number of expressions, and the <i>n</i>th identifier on
- the left is bound to the value of the <i>n</i>th expression on the
- right.
- </p>
- <pre class="ebnf">
- ConstDecl = "const" ( ConstSpec | "(" { ConstSpec ";" } ")" ) .
- ConstSpec = IdentifierList [ [ Type ] "=" ExpressionList ] .
- IdentifierList = identifier { "," identifier } .
- ExpressionList = Expression { "," Expression } .
- </pre>
- <p>
- If the type is present, all constants take the type specified, and
- the expressions must be <a href="#Assignability">assignable</a> to that type,
- which must not be a type parameter.
- If the type is omitted, the constants take the
- individual types of the corresponding expressions.
- If the expression values are untyped <a href="#Constants">constants</a>,
- the declared constants remain untyped and the constant identifiers
- denote the constant values. For instance, if the expression is a
- floating-point literal, the constant identifier denotes a floating-point
- constant, even if the literal's fractional part is zero.
- </p>
- <pre>
- const Pi float64 = 3.14159265358979323846
- const zero = 0.0 // untyped floating-point constant
- const (
- size int64 = 1024
- eof = -1 // untyped integer constant
- )
- const a, b, c = 3, 4, "foo" // a = 3, b = 4, c = "foo", untyped integer and string constants
- const u, v float32 = 0, 3 // u = 0.0, v = 3.0
- </pre>
- <p>
- Within a parenthesized <code>const</code> declaration list the
- expression list may be omitted from any but the first ConstSpec.
- Such an empty list is equivalent to the textual substitution of the
- first preceding non-empty expression list and its type if any.
- Omitting the list of expressions is therefore equivalent to
- repeating the previous list. The number of identifiers must be equal
- to the number of expressions in the previous list.
- Together with the <a href="#Iota"><code>iota</code> constant generator</a>
- this mechanism permits light-weight declaration of sequential values:
- </p>
- <pre>
- const (
- Sunday = iota
- Monday
- Tuesday
- Wednesday
- Thursday
- Friday
- Partyday
- numberOfDays // this constant is not exported
- )
- </pre>
- <h3 id="Iota">Iota</h3>
- <p>
- Within a <a href="#Constant_declarations">constant declaration</a>, the predeclared identifier
- <code>iota</code> represents successive untyped integer <a href="#Constants">
- constants</a>. Its value is the index of the respective <a href="#ConstSpec">ConstSpec</a>
- in that constant declaration, starting at zero.
- It can be used to construct a set of related constants:
- </p>
- <pre>
- const (
- c0 = iota // c0 == 0
- c1 = iota // c1 == 1
- c2 = iota // c2 == 2
- )
- const (
- a = 1 << iota // a == 1 (iota == 0)
- b = 1 << iota // b == 2 (iota == 1)
- c = 3 // c == 3 (iota == 2, unused)
- d = 1 << iota // d == 8 (iota == 3)
- )
- const (
- u = iota * 42 // u == 0 (untyped integer constant)
- v float64 = iota * 42 // v == 42.0 (float64 constant)
- w = iota * 42 // w == 84 (untyped integer constant)
- )
- const x = iota // x == 0
- const y = iota // y == 0
- </pre>
- <p>
- By definition, multiple uses of <code>iota</code> in the same ConstSpec all have the same value:
- </p>
- <pre>
- const (
- bit0, mask0 = 1 << iota, 1<<iota - 1 // bit0 == 1, mask0 == 0 (iota == 0)
- bit1, mask1 // bit1 == 2, mask1 == 1 (iota == 1)
- _, _ // (iota == 2, unused)
- bit3, mask3 // bit3 == 8, mask3 == 7 (iota == 3)
- )
- </pre>
- <p>
- This last example exploits the <a href="#Constant_declarations">implicit repetition</a>
- of the last non-empty expression list.
- </p>
- <h3 id="Type_declarations">Type declarations</h3>
- <p>
- A type declaration binds an identifier, the <i>type name</i>, to a <a href="#Types">type</a>.
- Type declarations come in two forms: alias declarations and type definitions.
- </p>
- <pre class="ebnf">
- TypeDecl = "type" ( TypeSpec | "(" { TypeSpec ";" } ")" ) .
- TypeSpec = AliasDecl | TypeDef .
- </pre>
- <h4 id="Alias_declarations">Alias declarations</h4>
- <p>
- An alias declaration binds an identifier to the given type
- [<a href="#Go_1.9">Go 1.9</a>].
- </p>
- <pre class="ebnf">
- AliasDecl = identifier "=" Type .
- </pre>
- <p>
- Within the <a href="#Declarations_and_scope">scope</a> of
- the identifier, it serves as an <i>alias</i> for the type.
- </p>
- <pre>
- type (
- nodeList = []*Node // nodeList and []*Node are identical types
- Polar = polar // Polar and polar denote identical types
- )
- </pre>
- <h4 id="Type_definitions">Type definitions</h4>
- <p>
- A type definition creates a new, distinct type with the same
- <a href="#Underlying_types">underlying type</a> and operations as the given type
- and binds an identifier, the <i>type name</i>, to it.
- </p>
- <pre class="ebnf">
- TypeDef = identifier [ TypeParameters ] Type .
- </pre>
- <p>
- The new type is called a <i>defined type</i>.
- It is <a href="#Type_identity">different</a> from any other type,
- including the type it is created from.
- </p>
- <pre>
- type (
- Point struct{ x, y float64 } // Point and struct{ x, y float64 } are different types
- polar Point // polar and Point denote different types
- )
- type TreeNode struct {
- left, right *TreeNode
- value any
- }
- type Block interface {
- BlockSize() int
- Encrypt(src, dst []byte)
- Decrypt(src, dst []byte)
- }
- </pre>
- <p>
- A defined type may have <a href="#Method_declarations">methods</a> associated with it.
- It does not inherit any methods bound to the given type,
- but the <a href="#Method_sets">method set</a>
- of an interface type or of elements of a composite type remains unchanged:
- </p>
- <pre>
- // A Mutex is a data type with two methods, Lock and Unlock.
- type Mutex struct { /* Mutex fields */ }
- func (m *Mutex) Lock() { /* Lock implementation */ }
- func (m *Mutex) Unlock() { /* Unlock implementation */ }
- // NewMutex has the same composition as Mutex but its method set is empty.
- type NewMutex Mutex
- // The method set of PtrMutex's underlying type *Mutex remains unchanged,
- // but the method set of PtrMutex is empty.
- type PtrMutex *Mutex
- // The method set of *PrintableMutex contains the methods
- // Lock and Unlock bound to its embedded field Mutex.
- type PrintableMutex struct {
- Mutex
- }
- // MyBlock is an interface type that has the same method set as Block.
- type MyBlock Block
- </pre>
- <p>
- Type definitions may be used to define different boolean, numeric,
- or string types and associate methods with them:
- </p>
- <pre>
- type TimeZone int
- const (
- EST TimeZone = -(5 + iota)
- CST
- MST
- PST
- )
- func (tz TimeZone) String() string {
- return fmt.Sprintf("GMT%+dh", tz)
- }
- </pre>
- <p>
- If the type definition specifies <a href="#Type_parameter_declarations">type parameters</a>,
- the type name denotes a <i>generic type</i>.
- Generic types must be <a href="#Instantiations">instantiated</a> when they
- are used.
- </p>
- <pre>
- type List[T any] struct {
- next *List[T]
- value T
- }
- </pre>
- <p>
- In a type definition the given type cannot be a type parameter.
- </p>
- <pre>
- type T[P any] P // illegal: P is a type parameter
- func f[T any]() {
- type L T // illegal: T is a type parameter declared by the enclosing function
- }
- </pre>
- <p>
- A generic type may also have <a href="#Method_declarations">methods</a> associated with it.
- In this case, the method receivers must declare the same number of type parameters as
- present in the generic type definition.
- </p>
- <pre>
- // The method Len returns the number of elements in the linked list l.
- func (l *List[T]) Len() int { … }
- </pre>
- <h3 id="Type_parameter_declarations">Type parameter declarations</h3>
- <p>
- A type parameter list declares the <i>type parameters</i> of a generic function or type declaration.
- The type parameter list looks like an ordinary <a href="#Function_types">function parameter list</a>
- except that the type parameter names must all be present and the list is enclosed
- in square brackets rather than parentheses
- [<a href="#Go_1.18">Go 1.18</a>].
- </p>
- <pre class="ebnf">
- TypeParameters = "[" TypeParamList [ "," ] "]" .
- TypeParamList = TypeParamDecl { "," TypeParamDecl } .
- TypeParamDecl = IdentifierList TypeConstraint .
- </pre>
- <p>
- All non-blank names in the list must be unique.
- Each name declares a type parameter, which is a new and different <a href="#Types">named type</a>
- that acts as a placeholder for an (as of yet) unknown type in the declaration.
- The type parameter is replaced with a <i>type argument</i> upon
- <a href="#Instantiations">instantiation</a> of the generic function or type.
- </p>
- <pre>
- [P any]
- [S interface{ ~[]byte|string }]
- [S ~[]E, E any]
- [P Constraint[int]]
- [_ any]
- </pre>
- <p>
- Just as each ordinary function parameter has a parameter type, each type parameter
- has a corresponding (meta-)type which is called its
- <a href="#Type_constraints"><i>type constraint</i></a>.
- </p>
- <p>
- A parsing ambiguity arises when the type parameter list for a generic type
- declares a single type parameter <code>P</code> with a constraint <code>C</code>
- such that the text <code>P C</code> forms a valid expression:
- </p>
- <pre>
- type T[P *C] …
- type T[P (C)] …
- type T[P *C|Q] …
- …
- </pre>
- <p>
- In these rare cases, the type parameter list is indistinguishable from an
- expression and the type declaration is parsed as an array type declaration.
- To resolve the ambiguity, embed the constraint in an
- <a href="#Interface_types">interface</a> or use a trailing comma:
- </p>
- <pre>
- type T[P interface{*C}] …
- type T[P *C,] …
- </pre>
- <p>
- Type parameters may also be declared by the receiver specification
- of a <a href="#Method_declarations">method declaration</a> associated
- with a generic type.
- </p>
- <p>
- Within a type parameter list of a generic type <code>T</code>, a type constraint
- may not (directly, or indirectly through the type parameter list of another
- generic type) refer to <code>T</code>.
- </p>
- <pre>
- type T1[P T1[P]] … // illegal: T1 refers to itself
- type T2[P interface{ T2[int] }] … // illegal: T2 refers to itself
- type T3[P interface{ m(T3[int])}] … // illegal: T3 refers to itself
- type T4[P T5[P]] … // illegal: T4 refers to T5 and
- type T5[P T4[P]] … // T5 refers to T4
- type T6[P int] struct{ f *T6[P] } // ok: reference to T6 is not in type parameter list
- </pre>
- <h4 id="Type_constraints">Type constraints</h4>
- <p>
- A <i>type constraint</i> is an <a href="#Interface_types">interface</a> that defines the
- set of permissible type arguments for the respective type parameter and controls the
- operations supported by values of that type parameter
- [<a href="#Go_1.18">Go 1.18</a>].
- </p>
- <pre class="ebnf">
- TypeConstraint = TypeElem .
- </pre>
- <p>
- If the constraint is an interface literal of the form <code>interface{E}</code> where
- <code>E</code> is an embedded <a href="#Interface_types">type element</a> (not a method), in a type parameter list
- the enclosing <code>interface{ … }</code> may be omitted for convenience:
- </p>
- <pre>
- [T []P] // = [T interface{[]P}]
- [T ~int] // = [T interface{~int}]
- [T int|string] // = [T interface{int|string}]
- type Constraint ~int // illegal: ~int is not in a type parameter list
- </pre>
- <!--
- We should be able to simplify the rules for comparable or delegate some of them
- elsewhere since we have a section that clearly defines how interfaces implement
- other interfaces based on their type sets. But this should get us going for now.
- -->
- <p>
- The <a href="#Predeclared_identifiers">predeclared</a>
- <a href="#Interface_types">interface type</a> <code>comparable</code>
- denotes the set of all non-interface types that are
- <a href="#Comparison_operators">strictly comparable</a>
- [<a href="#Go_1.18">Go 1.18</a>].
- </p>
- <p>
- Even though interfaces that are not type parameters are <a href="#Comparison_operators">comparable</a>,
- they are not strictly comparable and therefore they do not implement <code>comparable</code>.
- However, they <a href="#Satisfying_a_type_constraint">satisfy</a> <code>comparable</code>.
- </p>
- <pre>
- int // implements comparable (int is strictly comparable)
- []byte // does not implement comparable (slices cannot be compared)
- interface{} // does not implement comparable (see above)
- interface{ ~int | ~string } // type parameter only: implements comparable (int, string types are strictly comparable)
- interface{ comparable } // type parameter only: implements comparable (comparable implements itself)
- interface{ ~int | ~[]byte } // type parameter only: does not implement comparable (slices are not comparable)
- interface{ ~struct{ any } } // type parameter only: does not implement comparable (field any is not strictly comparable)
- </pre>
- <p>
- The <code>comparable</code> interface and interfaces that (directly or indirectly) embed
- <code>comparable</code> may only be used as type constraints. They cannot be the types of
- values or variables, or components of other, non-interface types.
- </p>
- <h4 id="Satisfying_a_type_constraint">Satisfying a type constraint</h4>
- <p>
- A type argument <code>T</code><i> satisfies</i> a type constraint <code>C</code>
- if <code>T</code> is an element of the type set defined by <code>C</code>; i.e.,
- if <code>T</code> <a href="#Implementing_an_interface">implements</a> <code>C</code>.
- As an exception, a <a href="#Comparison_operators">strictly comparable</a>
- type constraint may also be satisfied by a <a href="#Comparison_operators">comparable</a>
- (not necessarily strictly comparable) type argument
- [<a href="#Go_1.20">Go 1.20</a>].
- More precisely:
- </p>
- <p>
- A type T <i>satisfies</i> a constraint <code>C</code> if
- </p>
- <ul>
- <li>
- <code>T</code> <a href="#Implementing_an_interface">implements</a> <code>C</code>; or
- </li>
- <li>
- <code>C</code> can be written in the form <code>interface{ comparable; E }</code>,
- where <code>E</code> is a <a href="#Basic_interfaces">basic interface</a> and
- <code>T</code> is <a href="#Comparison_operators">comparable</a> and implements <code>E</code>.
- </li>
- </ul>
- <pre>
- type argument type constraint // constraint satisfaction
- int interface{ ~int } // satisfied: int implements interface{ ~int }
- string comparable // satisfied: string implements comparable (string is strictly comparable)
- []byte comparable // not satisfied: slices are not comparable
- any interface{ comparable; int } // not satisfied: any does not implement interface{ int }
- any comparable // satisfied: any is comparable and implements the basic interface any
- struct{f any} comparable // satisfied: struct{f any} is comparable and implements the basic interface any
- any interface{ comparable; m() } // not satisfied: any does not implement the basic interface interface{ m() }
- interface{ m() } interface{ comparable; m() } // satisfied: interface{ m() } is comparable and implements the basic interface interface{ m() }
- </pre>
- <p>
- Because of the exception in the constraint satisfaction rule, comparing operands of type parameter type
- may panic at run-time (even though comparable type parameters are always strictly comparable).
- </p>
- <h3 id="Variable_declarations">Variable declarations</h3>
- <p>
- A variable declaration creates one or more <a href="#Variables">variables</a>,
- binds corresponding identifiers to them, and gives each a type and an initial value.
- </p>
- <pre class="ebnf">
- VarDecl = "var" ( VarSpec | "(" { VarSpec ";" } ")" ) .
- VarSpec = IdentifierList ( Type [ "=" ExpressionList ] | "=" ExpressionList ) .
- </pre>
- <pre>
- var i int
- var U, V, W float64
- var k = 0
- var x, y float32 = -1, -2
- var (
- i int
- u, v, s = 2.0, 3.0, "bar"
- )
- var re, im = complexSqrt(-1)
- var _, found = entries[name] // map lookup; only interested in "found"
- </pre>
- <p>
- If a list of expressions is given, the variables are initialized
- with the expressions following the rules for <a href="#Assignment_statements">assignment statements</a>.
- Otherwise, each variable is initialized to its <a href="#The_zero_value">zero value</a>.
- </p>
- <p>
- If a type is present, each variable is given that type.
- Otherwise, each variable is given the type of the corresponding
- initialization value in the assignment.
- If that value is an untyped constant, it is first implicitly
- <a href="#Conversions">converted</a> to its <a href="#Constants">default type</a>;
- if it is an untyped boolean value, it is first implicitly converted to type <code>bool</code>.
- The predeclared value <code>nil</code> cannot be used to initialize a variable
- with no explicit type.
- </p>
- <pre>
- var d = math.Sin(0.5) // d is float64
- var i = 42 // i is int
- var t, ok = x.(T) // t is T, ok is bool
- var n = nil // illegal
- </pre>
- <p>
- Implementation restriction: A compiler may make it illegal to declare a variable
- inside a <a href="#Function_declarations">function body</a> if the variable is
- never used.
- </p>
- <h3 id="Short_variable_declarations">Short variable declarations</h3>
- <p>
- A <i>short variable declaration</i> uses the syntax:
- </p>
- <pre class="ebnf">
- ShortVarDecl = IdentifierList ":=" ExpressionList .
- </pre>
- <p>
- It is shorthand for a regular <a href="#Variable_declarations">variable declaration</a>
- with initializer expressions but no types:
- </p>
- <pre class="grammar">
- "var" IdentifierList "=" ExpressionList .
- </pre>
- <pre>
- i, j := 0, 10
- f := func() int { return 7 }
- ch := make(chan int)
- r, w, _ := os.Pipe() // os.Pipe() returns a connected pair of Files and an error, if any
- _, y, _ := coord(p) // coord() returns three values; only interested in y coordinate
- </pre>
- <p>
- Unlike regular variable declarations, a short variable declaration may <i>redeclare</i>
- variables provided they were originally declared earlier in the same block
- (or the parameter lists if the block is the function body) with the same type,
- and at least one of the non-<a href="#Blank_identifier">blank</a> variables is new.
- As a consequence, redeclaration can only appear in a multi-variable short declaration.
- Redeclaration does not introduce a new variable; it just assigns a new value to the original.
- The non-blank variable names on the left side of <code>:=</code>
- must be <a href="#Uniqueness_of_identifiers">unique</a>.
- </p>
- <pre>
- field1, offset := nextField(str, 0)
- field2, offset := nextField(str, offset) // redeclares offset
- x, y, x := 1, 2, 3 // illegal: x repeated on left side of :=
- </pre>
- <p>
- Short variable declarations may appear only inside functions.
- In some contexts such as the initializers for
- <a href="#If_statements">"if"</a>,
- <a href="#For_statements">"for"</a>, or
- <a href="#Switch_statements">"switch"</a> statements,
- they can be used to declare local temporary variables.
- </p>
- <h3 id="Function_declarations">Function declarations</h3>
- <!--
- Given the importance of functions, this section has always
- been woefully underdeveloped. Would be nice to expand this
- a bit.
- -->
- <p>
- A function declaration binds an identifier, the <i>function name</i>,
- to a function.
- </p>
- <pre class="ebnf">
- FunctionDecl = "func" FunctionName [ TypeParameters ] Signature [ FunctionBody ] .
- FunctionName = identifier .
- FunctionBody = Block .
- </pre>
- <p>
- If the function's <a href="#Function_types">signature</a> declares
- result parameters, the function body's statement list must end in
- a <a href="#Terminating_statements">terminating statement</a>.
- </p>
- <pre>
- func IndexRune(s string, r rune) int {
- for i, c := range s {
- if c == r {
- return i
- }
- }
- // invalid: missing return statement
- }
- </pre>
- <p>
- If the function declaration specifies <a href="#Type_parameter_declarations">type parameters</a>,
- the function name denotes a <i>generic function</i>.
- A generic function must be <a href="#Instantiations">instantiated</a> before it can be
- called or used as a value.
- </p>
- <pre>
- func min[T ~int|~float64](x, y T) T {
- if x < y {
- return x
- }
- return y
- }
- </pre>
- <p>
- A function declaration without type parameters may omit the body.
- Such a declaration provides the signature for a function implemented outside Go,
- such as an assembly routine.
- </p>
- <pre>
- func flushICache(begin, end uintptr) // implemented externally
- </pre>
- <h3 id="Method_declarations">Method declarations</h3>
- <p>
- A method is a <a href="#Function_declarations">function</a> with a <i>receiver</i>.
- A method declaration binds an identifier, the <i>method name</i>, to a method,
- and associates the method with the receiver's <i>base type</i>.
- </p>
- <pre class="ebnf">
- MethodDecl = "func" Receiver MethodName Signature [ FunctionBody ] .
- Receiver = Parameters .
- </pre>
- <p>
- The receiver is specified via an extra parameter section preceding the method
- name. That parameter section must declare a single non-variadic parameter, the receiver.
- Its type must be a <a href="#Type_definitions">defined</a> type <code>T</code> or a
- pointer to a defined type <code>T</code>, possibly followed by a list of type parameter
- names <code>[P1, P2, …]</code> enclosed in square brackets.
- <code>T</code> is called the receiver <i>base type</i>. A receiver base type cannot be
- a pointer or interface type and it must be defined in the same package as the method.
- The method is said to be <i>bound</i> to its receiver base type and the method name
- is visible only within <a href="#Selectors">selectors</a> for type <code>T</code>
- or <code>*T</code>.
- </p>
- <p>
- A non-<a href="#Blank_identifier">blank</a> receiver identifier must be
- <a href="#Uniqueness_of_identifiers">unique</a> in the method signature.
- If the receiver's value is not referenced inside the body of the method,
- its identifier may be omitted in the declaration. The same applies in
- general to parameters of functions and methods.
- </p>
- <p>
- For a base type, the non-blank names of methods bound to it must be unique.
- If the base type is a <a href="#Struct_types">struct type</a>,
- the non-blank method and field names must be distinct.
- </p>
- <p>
- Given defined type <code>Point</code> the declarations
- </p>
- <pre>
- func (p *Point) Length() float64 {
- return math.Sqrt(p.x * p.x + p.y * p.y)
- }
- func (p *Point) Scale(factor float64) {
- p.x *= factor
- p.y *= factor
- }
- </pre>
- <p>
- bind the methods <code>Length</code> and <code>Scale</code>,
- with receiver type <code>*Point</code>,
- to the base type <code>Point</code>.
- </p>
- <p>
- If the receiver base type is a <a href="#Type_declarations">generic type</a>, the
- receiver specification must declare corresponding type parameters for the method
- to use. This makes the receiver type parameters available to the method.
- Syntactically, this type parameter declaration looks like an
- <a href="#Instantiations">instantiation</a> of the receiver base type: the type
- arguments must be identifiers denoting the type parameters being declared, one
- for each type parameter of the receiver base type.
- The type parameter names do not need to match their corresponding parameter names in the
- receiver base type definition, and all non-blank parameter names must be unique in the
- receiver parameter section and the method signature.
- The receiver type parameter constraints are implied by the receiver base type definition:
- corresponding type parameters have corresponding constraints.
- </p>
- <pre>
- type Pair[A, B any] struct {
- a A
- b B
- }
- func (p Pair[A, B]) Swap() Pair[B, A] { … } // receiver declares A, B
- func (p Pair[First, _]) First() First { … } // receiver declares First, corresponds to A in Pair
- </pre>
- <h2 id="Expressions">Expressions</h2>
- <p>
- An expression specifies the computation of a value by applying
- operators and functions to operands.
- </p>
- <h3 id="Operands">Operands</h3>
- <p>
- Operands denote the elementary values in an expression. An operand may be a
- literal, a (possibly <a href="#Qualified_identifiers">qualified</a>)
- non-<a href="#Blank_identifier">blank</a> identifier denoting a
- <a href="#Constant_declarations">constant</a>,
- <a href="#Variable_declarations">variable</a>, or
- <a href="#Function_declarations">function</a>,
- or a parenthesized expression.
- </p>
- <pre class="ebnf">
- Operand = Literal | OperandName [ TypeArgs ] | "(" Expression ")" .
- Literal = BasicLit | CompositeLit | FunctionLit .
- BasicLit = int_lit | float_lit | imaginary_lit | rune_lit | string_lit .
- OperandName = identifier | QualifiedIdent .
- </pre>
- <p>
- An operand name denoting a <a href="#Function_declarations">generic function</a>
- may be followed by a list of <a href="#Instantiations">type arguments</a>; the
- resulting operand is an <a href="#Instantiations">instantiated</a> function.
- </p>
- <p>
- The <a href="#Blank_identifier">blank identifier</a> may appear as an
- operand only on the left-hand side of an <a href="#Assignment_statements">assignment statement</a>.
- </p>
- <p>
- Implementation restriction: A compiler need not report an error if an operand's
- type is a <a href="#Type_parameter_declarations">type parameter</a> with an empty
- <a href="#Interface_types">type set</a>. Functions with such type parameters
- cannot be <a href="#Instantiations">instantiated</a>; any attempt will lead
- to an error at the instantiation site.
- </p>
- <h3 id="Qualified_identifiers">Qualified identifiers</h3>
- <p>
- A <i>qualified identifier</i> is an identifier qualified with a package name prefix.
- Both the package name and the identifier must not be
- <a href="#Blank_identifier">blank</a>.
- </p>
- <pre class="ebnf">
- QualifiedIdent = PackageName "." identifier .
- </pre>
- <p>
- A qualified identifier accesses an identifier in a different package, which
- must be <a href="#Import_declarations">imported</a>.
- The identifier must be <a href="#Exported_identifiers">exported</a> and
- declared in the <a href="#Blocks">package block</a> of that package.
- </p>
- <pre>
- math.Sin // denotes the Sin function in package math
- </pre>
- <h3 id="Composite_literals">Composite literals</h3>
- <p>
- Composite literals construct new composite values each time they are evaluated.
- They consist of the type of the literal followed by a brace-bound list of elements.
- Each element may optionally be preceded by a corresponding key.
- </p>
- <pre class="ebnf">
- CompositeLit = LiteralType LiteralValue .
- LiteralType = StructType | ArrayType | "[" "..." "]" ElementType |
- SliceType | MapType | TypeName [ TypeArgs ] .
- LiteralValue = "{" [ ElementList [ "," ] ] "}" .
- ElementList = KeyedElement { "," KeyedElement } .
- KeyedElement = [ Key ":" ] Element .
- Key = FieldName | Expression | LiteralValue .
- FieldName = identifier .
- Element = Expression | LiteralValue .
- </pre>
- <p>
- The LiteralType's <a href="#Core_types">core type</a> <code>T</code>
- must be a struct, array, slice, or map type
- (the syntax enforces this constraint except when the type is given
- as a TypeName).
- The types of the elements and keys must be <a href="#Assignability">assignable</a>
- to the respective field, element, and key types of type <code>T</code>;
- there is no additional conversion.
- The key is interpreted as a field name for struct literals,
- an index for array and slice literals, and a key for map literals.
- For map literals, all elements must have a key. It is an error
- to specify multiple elements with the same field name or
- constant key value. For non-constant map keys, see the section on
- <a href="#Order_of_evaluation">evaluation order</a>.
- </p>
- <p>
- For struct literals the following rules apply:
- </p>
- <ul>
- <li>A key must be a field name declared in the struct type.
- </li>
- <li>An element list that does not contain any keys must
- list an element for each struct field in the
- order in which the fields are declared.
- </li>
- <li>If any element has a key, every element must have a key.
- </li>
- <li>An element list that contains keys does not need to
- have an element for each struct field. Omitted fields
- get the zero value for that field.
- </li>
- <li>A literal may omit the element list; such a literal evaluates
- to the zero value for its type.
- </li>
- <li>It is an error to specify an element for a non-exported
- field of a struct belonging to a different package.
- </li>
- </ul>
- <p>
- Given the declarations
- </p>
- <pre>
- type Point3D struct { x, y, z float64 }
- type Line struct { p, q Point3D }
- </pre>
- <p>
- one may write
- </p>
- <pre>
- origin := Point3D{} // zero value for Point3D
- line := Line{origin, Point3D{y: -4, z: 12.3}} // zero value for line.q.x
- </pre>
- <p>
- For array and slice literals the following rules apply:
- </p>
- <ul>
- <li>Each element has an associated integer index marking
- its position in the array.
- </li>
- <li>An element with a key uses the key as its index. The
- key must be a non-negative constant
- <a href="#Representability">representable</a> by
- a value of type <code>int</code>; and if it is typed
- it must be of <a href="#Numeric_types">integer type</a>.
- </li>
- <li>An element without a key uses the previous element's index plus one.
- If the first element has no key, its index is zero.
- </li>
- </ul>
- <p>
- <a href="#Address_operators">Taking the address</a> of a composite literal
- generates a pointer to a unique <a href="#Variables">variable</a> initialized
- with the literal's value.
- </p>
- <pre>
- var pointer *Point3D = &Point3D{y: 1000}
- </pre>
- <p>
- Note that the <a href="#The_zero_value">zero value</a> for a slice or map
- type is not the same as an initialized but empty value of the same type.
- Consequently, taking the address of an empty slice or map composite literal
- does not have the same effect as allocating a new slice or map value with
- <a href="#Allocation">new</a>.
- </p>
- <pre>
- p1 := &[]int{} // p1 points to an initialized, empty slice with value []int{} and length 0
- p2 := new([]int) // p2 points to an uninitialized slice with value nil and length 0
- </pre>
- <p>
- The length of an array literal is the length specified in the literal type.
- If fewer elements than the length are provided in the literal, the missing
- elements are set to the zero value for the array element type.
- It is an error to provide elements with index values outside the index range
- of the array. The notation <code>...</code> specifies an array length equal
- to the maximum element index plus one.
- </p>
- <pre>
- buffer := [10]string{} // len(buffer) == 10
- intSet := [6]int{1, 2, 3, 5} // len(intSet) == 6
- days := [...]string{"Sat", "Sun"} // len(days) == 2
- </pre>
- <p>
- A slice literal describes the entire underlying array literal.
- Thus the length and capacity of a slice literal are the maximum
- element index plus one. A slice literal has the form
- </p>
- <pre>
- []T{x1, x2, … xn}
- </pre>
- <p>
- and is shorthand for a slice operation applied to an array:
- </p>
- <pre>
- tmp := [n]T{x1, x2, … xn}
- tmp[0 : n]
- </pre>
- <p>
- Within a composite literal of array, slice, or map type <code>T</code>,
- elements or map keys that are themselves composite literals may elide the respective
- literal type if it is identical to the element or key type of <code>T</code>.
- Similarly, elements or keys that are addresses of composite literals may elide
- the <code>&T</code> when the element or key type is <code>*T</code>.
- </p>
- <pre>
- [...]Point{{1.5, -3.5}, {0, 0}} // same as [...]Point{Point{1.5, -3.5}, Point{0, 0}}
- [][]int{{1, 2, 3}, {4, 5}} // same as [][]int{[]int{1, 2, 3}, []int{4, 5}}
- [][]Point{{{0, 1}, {1, 2}}} // same as [][]Point{[]Point{Point{0, 1}, Point{1, 2}}}
- map[string]Point{"orig": {0, 0}} // same as map[string]Point{"orig": Point{0, 0}}
- map[Point]string{{0, 0}: "orig"} // same as map[Point]string{Point{0, 0}: "orig"}
- type PPoint *Point
- [2]*Point{{1.5, -3.5}, {}} // same as [2]*Point{&Point{1.5, -3.5}, &Point{}}
- [2]PPoint{{1.5, -3.5}, {}} // same as [2]PPoint{PPoint(&Point{1.5, -3.5}), PPoint(&Point{})}
- </pre>
- <p>
- A parsing ambiguity arises when a composite literal using the
- TypeName form of the LiteralType appears as an operand between the
- <a href="#Keywords">keyword</a> and the opening brace of the block
- of an "if", "for", or "switch" statement, and the composite literal
- is not enclosed in parentheses, square brackets, or curly braces.
- In this rare case, the opening brace of the literal is erroneously parsed
- as the one introducing the block of statements. To resolve the ambiguity,
- the composite literal must appear within parentheses.
- </p>
- <pre>
- if x == (T{a,b,c}[i]) { … }
- if (x == T{a,b,c}[i]) { … }
- </pre>
- <p>
- Examples of valid array, slice, and map literals:
- </p>
- <pre>
- // list of prime numbers
- primes := []int{2, 3, 5, 7, 9, 2147483647}
- // vowels[ch] is true if ch is a vowel
- vowels := [128]bool{'a': true, 'e': true, 'i': true, 'o': true, 'u': true, 'y': true}
- // the array [10]float32{-1, 0, 0, 0, -0.1, -0.1, 0, 0, 0, -1}
- filter := [10]float32{-1, 4: -0.1, -0.1, 9: -1}
- // frequencies in Hz for equal-tempered scale (A4 = 440Hz)
- noteFrequency := map[string]float32{
- "C0": 16.35, "D0": 18.35, "E0": 20.60, "F0": 21.83,
- "G0": 24.50, "A0": 27.50, "B0": 30.87,
- }
- </pre>
- <h3 id="Function_literals">Function literals</h3>
- <p>
- A function literal represents an anonymous <a href="#Function_declarations">function</a>.
- Function literals cannot declare type parameters.
- </p>
- <pre class="ebnf">
- FunctionLit = "func" Signature FunctionBody .
- </pre>
- <pre>
- func(a, b int, z float64) bool { return a*b < int(z) }
- </pre>
- <p>
- A function literal can be assigned to a variable or invoked directly.
- </p>
- <pre>
- f := func(x, y int) int { return x + y }
- func(ch chan int) { ch <- ACK }(replyChan)
- </pre>
- <p>
- Function literals are <i>closures</i>: they may refer to variables
- defined in a surrounding function. Those variables are then shared between
- the surrounding function and the function literal, and they survive as long
- as they are accessible.
- </p>
- <h3 id="Primary_expressions">Primary expressions</h3>
- <p>
- Primary expressions are the operands for unary and binary expressions.
- </p>
- <pre class="ebnf">
- PrimaryExpr =
- Operand |
- Conversion |
- MethodExpr |
- PrimaryExpr Selector |
- PrimaryExpr Index |
- PrimaryExpr Slice |
- PrimaryExpr TypeAssertion |
- PrimaryExpr Arguments .
- Selector = "." identifier .
- Index = "[" Expression [ "," ] "]" .
- Slice = "[" [ Expression ] ":" [ Expression ] "]" |
- "[" [ Expression ] ":" Expression ":" Expression "]" .
- TypeAssertion = "." "(" Type ")" .
- Arguments = "(" [ ( ExpressionList | Type [ "," ExpressionList ] ) [ "..." ] [ "," ] ] ")" .
- </pre>
- <pre>
- x
- 2
- (s + ".txt")
- f(3.1415, true)
- Point{1, 2}
- m["foo"]
- s[i : j + 1]
- obj.color
- f.p[i].x()
- </pre>
- <h3 id="Selectors">Selectors</h3>
- <p>
- For a <a href="#Primary_expressions">primary expression</a> <code>x</code>
- that is not a <a href="#Package_clause">package name</a>, the
- <i>selector expression</i>
- </p>
- <pre>
- x.f
- </pre>
- <p>
- denotes the field or method <code>f</code> of the value <code>x</code>
- (or sometimes <code>*x</code>; see below).
- The identifier <code>f</code> is called the (field or method) <i>selector</i>;
- it must not be the <a href="#Blank_identifier">blank identifier</a>.
- The type of the selector expression is the type of <code>f</code>.
- If <code>x</code> is a package name, see the section on
- <a href="#Qualified_identifiers">qualified identifiers</a>.
- </p>
- <p>
- A selector <code>f</code> may denote a field or method <code>f</code> of
- a type <code>T</code>, or it may refer
- to a field or method <code>f</code> of a nested
- <a href="#Struct_types">embedded field</a> of <code>T</code>.
- The number of embedded fields traversed
- to reach <code>f</code> is called its <i>depth</i> in <code>T</code>.
- The depth of a field or method <code>f</code>
- declared in <code>T</code> is zero.
- The depth of a field or method <code>f</code> declared in
- an embedded field <code>A</code> in <code>T</code> is the
- depth of <code>f</code> in <code>A</code> plus one.
- </p>
- <p>
- The following rules apply to selectors:
- </p>
- <ol>
- <li>
- For a value <code>x</code> of type <code>T</code> or <code>*T</code>
- where <code>T</code> is not a pointer or interface type,
- <code>x.f</code> denotes the field or method at the shallowest depth
- in <code>T</code> where there is such an <code>f</code>.
- If there is not exactly <a href="#Uniqueness_of_identifiers">one <code>f</code></a>
- with shallowest depth, the selector expression is illegal.
- </li>
- <li>
- For a value <code>x</code> of type <code>I</code> where <code>I</code>
- is an interface type, <code>x.f</code> denotes the actual method with name
- <code>f</code> of the dynamic value of <code>x</code>.
- If there is no method with name <code>f</code> in the
- <a href="#Method_sets">method set</a> of <code>I</code>, the selector
- expression is illegal.
- </li>
- <li>
- As an exception, if the type of <code>x</code> is a <a href="#Type_definitions">defined</a>
- pointer type and <code>(*x).f</code> is a valid selector expression denoting a field
- (but not a method), <code>x.f</code> is shorthand for <code>(*x).f</code>.
- </li>
- <li>
- In all other cases, <code>x.f</code> is illegal.
- </li>
- <li>
- If <code>x</code> is of pointer type and has the value
- <code>nil</code> and <code>x.f</code> denotes a struct field,
- assigning to or evaluating <code>x.f</code>
- causes a <a href="#Run_time_panics">run-time panic</a>.
- </li>
- <li>
- If <code>x</code> is of interface type and has the value
- <code>nil</code>, <a href="#Calls">calling</a> or
- <a href="#Method_values">evaluating</a> the method <code>x.f</code>
- causes a <a href="#Run_time_panics">run-time panic</a>.
- </li>
- </ol>
- <p>
- For example, given the declarations:
- </p>
- <pre>
- type T0 struct {
- x int
- }
- func (*T0) M0()
- type T1 struct {
- y int
- }
- func (T1) M1()
- type T2 struct {
- z int
- T1
- *T0
- }
- func (*T2) M2()
- type Q *T2
- var t T2 // with t.T0 != nil
- var p *T2 // with p != nil and (*p).T0 != nil
- var q Q = p
- </pre>
- <p>
- one may write:
- </p>
- <pre>
- t.z // t.z
- t.y // t.T1.y
- t.x // (*t.T0).x
- p.z // (*p).z
- p.y // (*p).T1.y
- p.x // (*(*p).T0).x
- q.x // (*(*q).T0).x (*q).x is a valid field selector
- p.M0() // ((*p).T0).M0() M0 expects *T0 receiver
- p.M1() // ((*p).T1).M1() M1 expects T1 receiver
- p.M2() // p.M2() M2 expects *T2 receiver
- t.M2() // (&t).M2() M2 expects *T2 receiver, see section on Calls
- </pre>
- <p>
- but the following is invalid:
- </p>
- <pre>
- q.M0() // (*q).M0 is valid but not a field selector
- </pre>
- <h3 id="Method_expressions">Method expressions</h3>
- <p>
- If <code>M</code> is in the <a href="#Method_sets">method set</a> of type <code>T</code>,
- <code>T.M</code> is a function that is callable as a regular function
- with the same arguments as <code>M</code> prefixed by an additional
- argument that is the receiver of the method.
- </p>
- <pre class="ebnf">
- MethodExpr = ReceiverType "." MethodName .
- ReceiverType = Type .
- </pre>
- <p>
- Consider a struct type <code>T</code> with two methods,
- <code>Mv</code>, whose receiver is of type <code>T</code>, and
- <code>Mp</code>, whose receiver is of type <code>*T</code>.
- </p>
- <pre>
- type T struct {
- a int
- }
- func (tv T) Mv(a int) int { return 0 } // value receiver
- func (tp *T) Mp(f float32) float32 { return 1 } // pointer receiver
- var t T
- </pre>
- <p>
- The expression
- </p>
- <pre>
- T.Mv
- </pre>
- <p>
- yields a function equivalent to <code>Mv</code> but
- with an explicit receiver as its first argument; it has signature
- </p>
- <pre>
- func(tv T, a int) int
- </pre>
- <p>
- That function may be called normally with an explicit receiver, so
- these five invocations are equivalent:
- </p>
- <pre>
- t.Mv(7)
- T.Mv(t, 7)
- (T).Mv(t, 7)
- f1 := T.Mv; f1(t, 7)
- f2 := (T).Mv; f2(t, 7)
- </pre>
- <p>
- Similarly, the expression
- </p>
- <pre>
- (*T).Mp
- </pre>
- <p>
- yields a function value representing <code>Mp</code> with signature
- </p>
- <pre>
- func(tp *T, f float32) float32
- </pre>
- <p>
- For a method with a value receiver, one can derive a function
- with an explicit pointer receiver, so
- </p>
- <pre>
- (*T).Mv
- </pre>
- <p>
- yields a function value representing <code>Mv</code> with signature
- </p>
- <pre>
- func(tv *T, a int) int
- </pre>
- <p>
- Such a function indirects through the receiver to create a value
- to pass as the receiver to the underlying method;
- the method does not overwrite the value whose address is passed in
- the function call.
- </p>
- <p>
- The final case, a value-receiver function for a pointer-receiver method,
- is illegal because pointer-receiver methods are not in the method set
- of the value type.
- </p>
- <p>
- Function values derived from methods are called with function call syntax;
- the receiver is provided as the first argument to the call.
- That is, given <code>f := T.Mv</code>, <code>f</code> is invoked
- as <code>f(t, 7)</code> not <code>t.f(7)</code>.
- To construct a function that binds the receiver, use a
- <a href="#Function_literals">function literal</a> or
- <a href="#Method_values">method value</a>.
- </p>
- <p>
- It is legal to derive a function value from a method of an interface type.
- The resulting function takes an explicit receiver of that interface type.
- </p>
- <h3 id="Method_values">Method values</h3>
- <p>
- If the expression <code>x</code> has static type <code>T</code> and
- <code>M</code> is in the <a href="#Method_sets">method set</a> of type <code>T</code>,
- <code>x.M</code> is called a <i>method value</i>.
- The method value <code>x.M</code> is a function value that is callable
- with the same arguments as a method call of <code>x.M</code>.
- The expression <code>x</code> is evaluated and saved during the evaluation of the
- method value; the saved copy is then used as the receiver in any calls,
- which may be executed later.
- </p>
- <pre>
- type S struct { *T }
- type T int
- func (t T) M() { print(t) }
- t := new(T)
- s := S{T: t}
- f := t.M // receiver *t is evaluated and stored in f
- g := s.M // receiver *(s.T) is evaluated and stored in g
- *t = 42 // does not affect stored receivers in f and g
- </pre>
- <p>
- The type <code>T</code> may be an interface or non-interface type.
- </p>
- <p>
- As in the discussion of <a href="#Method_expressions">method expressions</a> above,
- consider a struct type <code>T</code> with two methods,
- <code>Mv</code>, whose receiver is of type <code>T</code>, and
- <code>Mp</code>, whose receiver is of type <code>*T</code>.
- </p>
- <pre>
- type T struct {
- a int
- }
- func (tv T) Mv(a int) int { return 0 } // value receiver
- func (tp *T) Mp(f float32) float32 { return 1 } // pointer receiver
- var t T
- var pt *T
- func makeT() T
- </pre>
- <p>
- The expression
- </p>
- <pre>
- t.Mv
- </pre>
- <p>
- yields a function value of type
- </p>
- <pre>
- func(int) int
- </pre>
- <p>
- These two invocations are equivalent:
- </p>
- <pre>
- t.Mv(7)
- f := t.Mv; f(7)
- </pre>
- <p>
- Similarly, the expression
- </p>
- <pre>
- pt.Mp
- </pre>
- <p>
- yields a function value of type
- </p>
- <pre>
- func(float32) float32
- </pre>
- <p>
- As with <a href="#Selectors">selectors</a>, a reference to a non-interface method with a value receiver
- using a pointer will automatically dereference that pointer: <code>pt.Mv</code> is equivalent to <code>(*pt).Mv</code>.
- </p>
- <p>
- As with <a href="#Calls">method calls</a>, a reference to a non-interface method with a pointer receiver
- using an addressable value will automatically take the address of that value: <code>t.Mp</code> is equivalent to <code>(&t).Mp</code>.
- </p>
- <pre>
- f := t.Mv; f(7) // like t.Mv(7)
- f := pt.Mp; f(7) // like pt.Mp(7)
- f := pt.Mv; f(7) // like (*pt).Mv(7)
- f := t.Mp; f(7) // like (&t).Mp(7)
- f := makeT().Mp // invalid: result of makeT() is not addressable
- </pre>
- <p>
- Although the examples above use non-interface types, it is also legal to create a method value
- from a value of interface type.
- </p>
- <pre>
- var i interface { M(int) } = myVal
- f := i.M; f(7) // like i.M(7)
- </pre>
- <h3 id="Index_expressions">Index expressions</h3>
- <p>
- A primary expression of the form
- </p>
- <pre>
- a[x]
- </pre>
- <p>
- denotes the element of the array, pointer to array, slice, string or map <code>a</code> indexed by <code>x</code>.
- The value <code>x</code> is called the <i>index</i> or <i>map key</i>, respectively.
- The following rules apply:
- </p>
- <p>
- If <code>a</code> is neither a map nor a type parameter:
- </p>
- <ul>
- <li>the index <code>x</code> must be an untyped constant or its
- <a href="#Core_types">core type</a> must be an <a href="#Numeric_types">integer</a></li>
- <li>a constant index must be non-negative and
- <a href="#Representability">representable</a> by a value of type <code>int</code></li>
- <li>a constant index that is untyped is given type <code>int</code></li>
- <li>the index <code>x</code> is <i>in range</i> if <code>0 <= x < len(a)</code>,
- otherwise it is <i>out of range</i></li>
- </ul>
- <p>
- For <code>a</code> of <a href="#Array_types">array type</a> <code>A</code>:
- </p>
- <ul>
- <li>a <a href="#Constants">constant</a> index must be in range</li>
- <li>if <code>x</code> is out of range at run time,
- a <a href="#Run_time_panics">run-time panic</a> occurs</li>
- <li><code>a[x]</code> is the array element at index <code>x</code> and the type of
- <code>a[x]</code> is the element type of <code>A</code></li>
- </ul>
- <p>
- For <code>a</code> of <a href="#Pointer_types">pointer</a> to array type:
- </p>
- <ul>
- <li><code>a[x]</code> is shorthand for <code>(*a)[x]</code></li>
- </ul>
- <p>
- For <code>a</code> of <a href="#Slice_types">slice type</a> <code>S</code>:
- </p>
- <ul>
- <li>if <code>x</code> is out of range at run time,
- a <a href="#Run_time_panics">run-time panic</a> occurs</li>
- <li><code>a[x]</code> is the slice element at index <code>x</code> and the type of
- <code>a[x]</code> is the element type of <code>S</code></li>
- </ul>
- <p>
- For <code>a</code> of <a href="#String_types">string type</a>:
- </p>
- <ul>
- <li>a <a href="#Constants">constant</a> index must be in range
- if the string <code>a</code> is also constant</li>
- <li>if <code>x</code> is out of range at run time,
- a <a href="#Run_time_panics">run-time panic</a> occurs</li>
- <li><code>a[x]</code> is the non-constant byte value at index <code>x</code> and the type of
- <code>a[x]</code> is <code>byte</code></li>
- <li><code>a[x]</code> may not be assigned to</li>
- </ul>
- <p>
- For <code>a</code> of <a href="#Map_types">map type</a> <code>M</code>:
- </p>
- <ul>
- <li><code>x</code>'s type must be
- <a href="#Assignability">assignable</a>
- to the key type of <code>M</code></li>
- <li>if the map contains an entry with key <code>x</code>,
- <code>a[x]</code> is the map element with key <code>x</code>
- and the type of <code>a[x]</code> is the element type of <code>M</code></li>
- <li>if the map is <code>nil</code> or does not contain such an entry,
- <code>a[x]</code> is the <a href="#The_zero_value">zero value</a>
- for the element type of <code>M</code></li>
- </ul>
- <p>
- For <code>a</code> of <a href="#Type_parameter_declarations">type parameter type</a> <code>P</code>:
- </p>
- <ul>
- <li>The index expression <code>a[x]</code> must be valid for values
- of all types in <code>P</code>'s type set.</li>
- <li>The element types of all types in <code>P</code>'s type set must be identical.
- In this context, the element type of a string type is <code>byte</code>.</li>
- <li>If there is a map type in the type set of <code>P</code>,
- all types in that type set must be map types, and the respective key types
- must be all identical.</li>
- <li><code>a[x]</code> is the array, slice, or string element at index <code>x</code>,
- or the map element with key <code>x</code> of the type argument
- that <code>P</code> is instantiated with, and the type of <code>a[x]</code> is
- the type of the (identical) element types.</li>
- <li><code>a[x]</code> may not be assigned to if <code>P</code>'s type set
- includes string types.</li>
- </ul>
- <p>
- Otherwise <code>a[x]</code> is illegal.
- </p>
- <p>
- An index expression on a map <code>a</code> of type <code>map[K]V</code>
- used in an <a href="#Assignment_statements">assignment statement</a> or initialization of the special form
- </p>
- <pre>
- v, ok = a[x]
- v, ok := a[x]
- var v, ok = a[x]
- </pre>
- <p>
- yields an additional untyped boolean value. The value of <code>ok</code> is
- <code>true</code> if the key <code>x</code> is present in the map, and
- <code>false</code> otherwise.
- </p>
- <p>
- Assigning to an element of a <code>nil</code> map causes a
- <a href="#Run_time_panics">run-time panic</a>.
- </p>
- <h3 id="Slice_expressions">Slice expressions</h3>
- <p>
- Slice expressions construct a substring or slice from a string, array, pointer
- to array, or slice. There are two variants: a simple form that specifies a low
- and high bound, and a full form that also specifies a bound on the capacity.
- </p>
- <h4>Simple slice expressions</h4>
- <p>
- The primary expression
- </p>
- <pre>
- a[low : high]
- </pre>
- <p>
- constructs a substring or slice. The <a href="#Core_types">core type</a> of
- <code>a</code> must be a string, array, pointer to array, slice, or a
- <a href="#Core_types"><code>bytestring</code></a>.
- The <i>indices</i> <code>low</code> and
- <code>high</code> select which elements of operand <code>a</code> appear
- in the result. The result has indices starting at 0 and length equal to
- <code>high</code> - <code>low</code>.
- After slicing the array <code>a</code>
- </p>
- <pre>
- a := [5]int{1, 2, 3, 4, 5}
- s := a[1:4]
- </pre>
- <p>
- the slice <code>s</code> has type <code>[]int</code>, length 3, capacity 4, and elements
- </p>
- <pre>
- s[0] == 2
- s[1] == 3
- s[2] == 4
- </pre>
- <p>
- For convenience, any of the indices may be omitted. A missing <code>low</code>
- index defaults to zero; a missing <code>high</code> index defaults to the length of the
- sliced operand:
- </p>
- <pre>
- a[2:] // same as a[2 : len(a)]
- a[:3] // same as a[0 : 3]
- a[:] // same as a[0 : len(a)]
- </pre>
- <p>
- If <code>a</code> is a pointer to an array, <code>a[low : high]</code> is shorthand for
- <code>(*a)[low : high]</code>.
- </p>
- <p>
- For arrays or strings, the indices are <i>in range</i> if
- <code>0</code> <= <code>low</code> <= <code>high</code> <= <code>len(a)</code>,
- otherwise they are <i>out of range</i>.
- For slices, the upper index bound is the slice capacity <code>cap(a)</code> rather than the length.
- A <a href="#Constants">constant</a> index must be non-negative and
- <a href="#Representability">representable</a> by a value of type
- <code>int</code>; for arrays or constant strings, constant indices must also be in range.
- If both indices are constant, they must satisfy <code>low <= high</code>.
- If the indices are out of range at run time, a <a href="#Run_time_panics">run-time panic</a> occurs.
- </p>
- <p>
- Except for <a href="#Constants">untyped strings</a>, if the sliced operand is a string or slice,
- the result of the slice operation is a non-constant value of the same type as the operand.
- For untyped string operands the result is a non-constant value of type <code>string</code>.
- If the sliced operand is an array, it must be <a href="#Address_operators">addressable</a>
- and the result of the slice operation is a slice with the same element type as the array.
- </p>
- <p>
- If the sliced operand of a valid slice expression is a <code>nil</code> slice, the result
- is a <code>nil</code> slice. Otherwise, if the result is a slice, it shares its underlying
- array with the operand.
- </p>
- <pre>
- var a [10]int
- s1 := a[3:7] // underlying array of s1 is array a; &s1[2] == &a[5]
- s2 := s1[1:4] // underlying array of s2 is underlying array of s1 which is array a; &s2[1] == &a[5]
- s2[1] = 42 // s2[1] == s1[2] == a[5] == 42; they all refer to the same underlying array element
- var s []int
- s3 := s[:0] // s3 == nil
- </pre>
- <h4>Full slice expressions</h4>
- <p>
- The primary expression
- </p>
- <pre>
- a[low : high : max]
- </pre>
- <p>
- constructs a slice of the same type, and with the same length and elements as the simple slice
- expression <code>a[low : high]</code>. Additionally, it controls the resulting slice's capacity
- by setting it to <code>max - low</code>. Only the first index may be omitted; it defaults to 0.
- The <a href="#Core_types">core type</a> of <code>a</code> must be an array, pointer to array,
- or slice (but not a string).
- After slicing the array <code>a</code>
- </p>
- <pre>
- a := [5]int{1, 2, 3, 4, 5}
- t := a[1:3:5]
- </pre>
- <p>
- the slice <code>t</code> has type <code>[]int</code>, length 2, capacity 4, and elements
- </p>
- <pre>
- t[0] == 2
- t[1] == 3
- </pre>
- <p>
- As for simple slice expressions, if <code>a</code> is a pointer to an array,
- <code>a[low : high : max]</code> is shorthand for <code>(*a)[low : high : max]</code>.
- If the sliced operand is an array, it must be <a href="#Address_operators">addressable</a>.
- </p>
- <p>
- The indices are <i>in range</i> if <code>0 <= low <= high <= max <= cap(a)</code>,
- otherwise they are <i>out of range</i>.
- A <a href="#Constants">constant</a> index must be non-negative and
- <a href="#Representability">representable</a> by a value of type
- <code>int</code>; for arrays, constant indices must also be in range.
- If multiple indices are constant, the constants that are present must be in range relative to each
- other.
- If the indices are out of range at run time, a <a href="#Run_time_panics">run-time panic</a> occurs.
- </p>
- <h3 id="Type_assertions">Type assertions</h3>
- <p>
- For an expression <code>x</code> of <a href="#Interface_types">interface type</a>,
- but not a <a href="#Type_parameter_declarations">type parameter</a>, and a type <code>T</code>,
- the primary expression
- </p>
- <pre>
- x.(T)
- </pre>
- <p>
- asserts that <code>x</code> is not <code>nil</code>
- and that the value stored in <code>x</code> is of type <code>T</code>.
- The notation <code>x.(T)</code> is called a <i>type assertion</i>.
- </p>
- <p>
- More precisely, if <code>T</code> is not an interface type, <code>x.(T)</code> asserts
- that the dynamic type of <code>x</code> is <a href="#Type_identity">identical</a>
- to the type <code>T</code>.
- In this case, <code>T</code> must <a href="#Method_sets">implement</a> the (interface) type of <code>x</code>;
- otherwise the type assertion is invalid since it is not possible for <code>x</code>
- to store a value of type <code>T</code>.
- If <code>T</code> is an interface type, <code>x.(T)</code> asserts that the dynamic type
- of <code>x</code> <a href="#Implementing_an_interface">implements</a> the interface <code>T</code>.
- </p>
- <p>
- If the type assertion holds, the value of the expression is the value
- stored in <code>x</code> and its type is <code>T</code>. If the type assertion is false,
- a <a href="#Run_time_panics">run-time panic</a> occurs.
- In other words, even though the dynamic type of <code>x</code>
- is known only at run time, the type of <code>x.(T)</code> is
- known to be <code>T</code> in a correct program.
- </p>
- <pre>
- var x interface{} = 7 // x has dynamic type int and value 7
- i := x.(int) // i has type int and value 7
- type I interface { m() }
- func f(y I) {
- s := y.(string) // illegal: string does not implement I (missing method m)
- r := y.(io.Reader) // r has type io.Reader and the dynamic type of y must implement both I and io.Reader
- …
- }
- </pre>
- <p>
- A type assertion used in an <a href="#Assignment_statements">assignment statement</a> or initialization of the special form
- </p>
- <pre>
- v, ok = x.(T)
- v, ok := x.(T)
- var v, ok = x.(T)
- var v, ok interface{} = x.(T) // dynamic types of v and ok are T and bool
- </pre>
- <p>
- yields an additional untyped boolean value. The value of <code>ok</code> is <code>true</code>
- if the assertion holds. Otherwise it is <code>false</code> and the value of <code>v</code> is
- the <a href="#The_zero_value">zero value</a> for type <code>T</code>.
- No <a href="#Run_time_panics">run-time panic</a> occurs in this case.
- </p>
- <h3 id="Calls">Calls</h3>
- <p>
- Given an expression <code>f</code> with a <a href="#Core_types">core type</a>
- <code>F</code> of <a href="#Function_types">function type</a>,
- </p>
- <pre>
- f(a1, a2, … an)
- </pre>
- <p>
- calls <code>f</code> with arguments <code>a1, a2, … an</code>.
- Except for one special case, arguments must be single-valued expressions
- <a href="#Assignability">assignable</a> to the parameter types of
- <code>F</code> and are evaluated before the function is called.
- The type of the expression is the result type
- of <code>F</code>.
- A method invocation is similar but the method itself
- is specified as a selector upon a value of the receiver type for
- the method.
- </p>
- <pre>
- math.Atan2(x, y) // function call
- var pt *Point
- pt.Scale(3.5) // method call with receiver pt
- </pre>
- <p>
- If <code>f</code> denotes a generic function, it must be
- <a href="#Instantiations">instantiated</a> before it can be called
- or used as a function value.
- </p>
- <p>
- In a function call, the function value and arguments are evaluated in
- <a href="#Order_of_evaluation">the usual order</a>.
- After they are evaluated, the parameters of the call are passed by value to the function
- and the called function begins execution.
- The return parameters of the function are passed by value
- back to the caller when the function returns.
- </p>
- <p>
- Calling a <code>nil</code> function value
- causes a <a href="#Run_time_panics">run-time panic</a>.
- </p>
- <p>
- As a special case, if the return values of a function or method
- <code>g</code> are equal in number and individually
- assignable to the parameters of another function or method
- <code>f</code>, then the call <code>f(g(<i>parameters_of_g</i>))</code>
- will invoke <code>f</code> after binding the return values of
- <code>g</code> to the parameters of <code>f</code> in order. The call
- of <code>f</code> must contain no parameters other than the call of <code>g</code>,
- and <code>g</code> must have at least one return value.
- If <code>f</code> has a final <code>...</code> parameter, it is
- assigned the return values of <code>g</code> that remain after
- assignment of regular parameters.
- </p>
- <pre>
- func Split(s string, pos int) (string, string) {
- return s[0:pos], s[pos:]
- }
- func Join(s, t string) string {
- return s + t
- }
- if Join(Split(value, len(value)/2)) != value {
- log.Panic("test fails")
- }
- </pre>
- <p>
- A method call <code>x.m()</code> is valid if the <a href="#Method_sets">method set</a>
- of (the type of) <code>x</code> contains <code>m</code> and the
- argument list can be assigned to the parameter list of <code>m</code>.
- If <code>x</code> is <a href="#Address_operators">addressable</a> and <code>&x</code>'s method
- set contains <code>m</code>, <code>x.m()</code> is shorthand
- for <code>(&x).m()</code>:
- </p>
- <pre>
- var p Point
- p.Scale(3.5)
- </pre>
- <p>
- There is no distinct method type and there are no method literals.
- </p>
- <h3 id="Passing_arguments_to_..._parameters">Passing arguments to <code>...</code> parameters</h3>
- <p>
- If <code>f</code> is <a href="#Function_types">variadic</a> with a final
- parameter <code>p</code> of type <code>...T</code>, then within <code>f</code>
- the type of <code>p</code> is equivalent to type <code>[]T</code>.
- If <code>f</code> is invoked with no actual arguments for <code>p</code>,
- the value passed to <code>p</code> is <code>nil</code>.
- Otherwise, the value passed is a new slice
- of type <code>[]T</code> with a new underlying array whose successive elements
- are the actual arguments, which all must be <a href="#Assignability">assignable</a>
- to <code>T</code>. The length and capacity of the slice is therefore
- the number of arguments bound to <code>p</code> and may differ for each
- call site.
- </p>
- <p>
- Given the function and calls
- </p>
- <pre>
- func Greeting(prefix string, who ...string)
- Greeting("nobody")
- Greeting("hello:", "Joe", "Anna", "Eileen")
- </pre>
- <p>
- within <code>Greeting</code>, <code>who</code> will have the value
- <code>nil</code> in the first call, and
- <code>[]string{"Joe", "Anna", "Eileen"}</code> in the second.
- </p>
- <p>
- If the final argument is assignable to a slice type <code>[]T</code> and
- is followed by <code>...</code>, it is passed unchanged as the value
- for a <code>...T</code> parameter. In this case no new slice is created.
- </p>
- <p>
- Given the slice <code>s</code> and call
- </p>
- <pre>
- s := []string{"James", "Jasmine"}
- Greeting("goodbye:", s...)
- </pre>
- <p>
- within <code>Greeting</code>, <code>who</code> will have the same value as <code>s</code>
- with the same underlying array.
- </p>
- <h3 id="Instantiations">Instantiations</h3>
- <p>
- A generic function or type is <i>instantiated</i> by substituting <i>type arguments</i>
- for the type parameters [<a href="#Go_1.18">Go 1.18</a>].
- Instantiation proceeds in two steps:
- </p>
- <ol>
- <li>
- Each type argument is substituted for its corresponding type parameter in the generic
- declaration.
- This substitution happens across the entire function or type declaration,
- including the type parameter list itself and any types in that list.
- </li>
- <li>
- After substitution, each type argument must <a href="#Satisfying_a_type_constraint">satisfy</a>
- the <a href="#Type_parameter_declarations">constraint</a> (instantiated, if necessary)
- of the corresponding type parameter. Otherwise instantiation fails.
- </li>
- </ol>
- <p>
- Instantiating a type results in a new non-generic <a href="#Types">named type</a>;
- instantiating a function produces a new non-generic function.
- </p>
- <pre>
- type parameter list type arguments after substitution
- [P any] int int satisfies any
- [S ~[]E, E any] []int, int []int satisfies ~[]int, int satisfies any
- [P io.Writer] string illegal: string doesn't satisfy io.Writer
- [P comparable] any any satisfies (but does not implement) comparable
- </pre>
- <p>
- When using a generic function, type arguments may be provided explicitly,
- or they may be partially or completely <a href="#Type_inference">inferred</a>
- from the context in which the function is used.
- Provided that they can be inferred, type argument lists may be omitted entirely if the function is:
- </p>
- <ul>
- <li>
- <a href="#Calls">called</a> with ordinary arguments,
- </li>
- <li>
- <a href="#Assignment_statements">assigned</a> to a variable with a known type
- </li>
- <li>
- <a href="#Calls">passed as an argument</a> to another function, or
- </li>
- <li>
- <a href="#Return_statements">returned as a result</a>.
- </li>
- </ul>
- <p>
- In all other cases, a (possibly partial) type argument list must be present.
- If a type argument list is absent or partial, all missing type arguments
- must be inferrable from the context in which the function is used.
- </p>
- <pre>
- // sum returns the sum (concatenation, for strings) of its arguments.
- func sum[T ~int | ~float64 | ~string](x... T) T { … }
- x := sum // illegal: the type of x is unknown
- intSum := sum[int] // intSum has type func(x... int) int
- a := intSum(2, 3) // a has value 5 of type int
- b := sum[float64](2.0, 3) // b has value 5.0 of type float64
- c := sum(b, -1) // c has value 4.0 of type float64
- type sumFunc func(x... string) string
- var f sumFunc = sum // same as var f sumFunc = sum[string]
- f = sum // same as f = sum[string]
- </pre>
- <p>
- A partial type argument list cannot be empty; at least the first argument must be present.
- The list is a prefix of the full list of type arguments, leaving the remaining arguments
- to be inferred. Loosely speaking, type arguments may be omitted from "right to left".
- </p>
- <pre>
- func apply[S ~[]E, E any](s S, f func(E) E) S { … }
- f0 := apply[] // illegal: type argument list cannot be empty
- f1 := apply[[]int] // type argument for S explicitly provided, type argument for E inferred
- f2 := apply[[]string, string] // both type arguments explicitly provided
- var bytes []byte
- r := apply(bytes, func(byte) byte { … }) // both type arguments inferred from the function arguments
- </pre>
- <p>
- For a generic type, all type arguments must always be provided explicitly.
- </p>
- <h3 id="Type_inference">Type inference</h3>
- <p>
- A use of a generic function may omit some or all type arguments if they can be
- <i>inferred</i> from the context within which the function is used, including
- the constraints of the function's type parameters.
- Type inference succeeds if it can infer the missing type arguments
- and <a href="#Instantiations">instantiation</a> succeeds with the
- inferred type arguments.
- Otherwise, type inference fails and the program is invalid.
- </p>
- <p>
- Type inference uses the type relationships between pairs of types for inference:
- For instance, a function argument must be <a href="#Assignability">assignable</a>
- to its respective function parameter; this establishes a relationship between the
- type of the argument and the type of the parameter.
- If either of these two types contains type parameters, type inference looks for the
- type arguments to substitute the type parameters with such that the assignability
- relationship is satisfied.
- Similarly, type inference uses the fact that a type argument must
- <a href="#Satisfying_a_type_constraint">satisfy</a> the constraint of its respective
- type parameter.
- </p>
- <p>
- Each such pair of matched types corresponds to a <i>type equation</i> containing
- one or multiple type parameters, from one or possibly multiple generic functions.
- Inferring the missing type arguments means solving the resulting set of type
- equations for the respective type parameters.
- </p>
- <p>
- For example, given
- </p>
- <pre>
- // dedup returns a copy of the argument slice with any duplicate entries removed.
- func dedup[S ~[]E, E comparable](S) S { … }
- type Slice []int
- var s Slice
- s = dedup(s) // same as s = dedup[Slice, int](s)
- </pre>
- <p>
- the variable <code>s</code> of type <code>Slice</code> must be assignable to
- the function parameter type <code>S</code> for the program to be valid.
- To reduce complexity, type inference ignores the directionality of assignments,
- so the type relationship between <code>Slice</code> and <code>S</code> can be
- expressed via the (symmetric) type equation <code>Slice ≡<sub>A</sub> S</code>
- (or <code>S ≡<sub>A</sub> Slice</code> for that matter),
- where the <code><sub>A</sub></code> in <code>≡<sub>A</sub></code>
- indicates that the LHS and RHS types must match per assignability rules
- (see the section on <a href="#Type_unification">type unification</a> for
- details).
- Similarly, the type parameter <code>S</code> must satisfy its constraint
- <code>~[]E</code>. This can be expressed as <code>S ≡<sub>C</sub> ~[]E</code>
- where <code>X ≡<sub>C</sub> Y</code> stands for
- "<code>X</code> satisfies constraint <code>Y</code>".
- These observations lead to a set of two equations
- </p>
- <pre>
- Slice ≡<sub>A</sub> S (1)
- S ≡<sub>C</sub> ~[]E (2)
- </pre>
- <p>
- which now can be solved for the type parameters <code>S</code> and <code>E</code>.
- From (1) a compiler can infer that the type argument for <code>S</code> is <code>Slice</code>.
- Similarly, because the underlying type of <code>Slice</code> is <code>[]int</code>
- and <code>[]int</code> must match <code>[]E</code> of the constraint,
- a compiler can infer that <code>E</code> must be <code>int</code>.
- Thus, for these two equations, type inference infers
- </p>
- <pre>
- S ➞ Slice
- E ➞ int
- </pre>
- <p>
- Given a set of type equations, the type parameters to solve for are
- the type parameters of the functions that need to be instantiated
- and for which no explicit type arguments is provided.
- These type parameters are called <i>bound</i> type parameters.
- For instance, in the <code>dedup</code> example above, the type parameters
- <code>S</code> and <code>E</code> are bound to <code>dedup</code>.
- An argument to a generic function call may be a generic function itself.
- The type parameters of that function are included in the set of bound
- type parameters.
- The types of function arguments may contain type parameters from other
- functions (such as a generic function enclosing a function call).
- Those type parameters may also appear in type equations but they are
- not bound in that context.
- Type equations are always solved for the bound type parameters only.
- </p>
- <p>
- Type inference supports calls of generic functions and assignments
- of generic functions to (explicitly function-typed) variables.
- This includes passing generic functions as arguments to other
- (possibly also generic) functions, and returning generic functions
- as results.
- Type inference operates on a set of equations specific to each of
- these cases.
- The equations are as follows (type argument lists are omitted for clarity):
- </p>
- <ul>
- <li>
- <p>
- For a function call <code>f(a<sub>0</sub>, a<sub>1</sub>, …)</code> where
- <code>f</code> or a function argument <code>a<sub>i</sub></code> is
- a generic function:
- <br>
- Each pair <code>(a<sub>i</sub>, p<sub>i</sub>)</code> of corresponding
- function arguments and parameters where <code>a<sub>i</sub></code> is not an
- <a href="#Constants">untyped constant</a> yields an equation
- <code>typeof(p<sub>i</sub>) ≡<sub>A</sub> typeof(a<sub>i</sub>)</code>.
- <br>
- If <code>a<sub>i</sub></code> is an untyped constant <code>c<sub>j</sub></code>,
- and <code>typeof(p<sub>i</sub>)</code> is a bound type parameter <code>P<sub>k</sub></code>,
- the pair <code>(c<sub>j</sub>, P<sub>k</sub>)</code> is collected separately from
- the type equations.
- </p>
- </li>
- <li>
- <p>
- For an assignment <code>v = f</code> of a generic function <code>f</code> to a
- (non-generic) variable <code>v</code> of function type:
- <br>
- <code>typeof(v) ≡<sub>A</sub> typeof(f)</code>.
- </p>
- </li>
- <li>
- <p>
- For a return statement <code>return …, f, … </code> where <code>f</code> is a
- generic function returned as a result to a (non-generic) result variable
- <code>r</code> of function type:
- <br>
- <code>typeof(r) ≡<sub>A</sub> typeof(f)</code>.
- </p>
- </li>
- </ul>
- <p>
- Additionally, each type parameter <code>P<sub>k</sub></code> and corresponding type constraint
- <code>C<sub>k</sub></code> yields the type equation
- <code>P<sub>k</sub> ≡<sub>C</sub> C<sub>k</sub></code>.
- </p>
- <p>
- Type inference gives precedence to type information obtained from typed operands
- before considering untyped constants.
- Therefore, inference proceeds in two phases:
- </p>
- <ol>
- <li>
- <p>
- The type equations are solved for the bound
- type parameters using <a href="#Type_unification">type unification</a>.
- If unification fails, type inference fails.
- </p>
- </li>
- <li>
- <p>
- For each bound type parameter <code>P<sub>k</sub></code> for which no type argument
- has been inferred yet and for which one or more pairs
- <code>(c<sub>j</sub>, P<sub>k</sub>)</code> with that same type parameter
- were collected, determine the <a href="#Constant_expressions">constant kind</a>
- of the constants <code>c<sub>j</sub></code> in all those pairs the same way as for
- <a href="#Constant_expressions">constant expressions</a>.
- The type argument for <code>P<sub>k</sub></code> is the
- <a href="#Constants">default type</a> for the determined constant kind.
- If a constant kind cannot be determined due to conflicting constant kinds,
- type inference fails.
- </p>
- </li>
- </ol>
- <p>
- If not all type arguments have been found after these two phases, type inference fails.
- </p>
- <p>
- If the two phases are successful, type inference determined a type argument for each
- bound type parameter:
- </p>
- <pre>
- P<sub>k</sub> ➞ A<sub>k</sub>
- </pre>
- <p>
- A type argument <code>A<sub>k</sub></code> may be a composite type,
- containing other bound type parameters <code>P<sub>k</sub></code> as element types
- (or even be just another bound type parameter).
- In a process of repeated simplification, the bound type parameters in each type
- argument are substituted with the respective type arguments for those type
- parameters until each type argument is free of bound type parameters.
- </p>
- <p>
- If type arguments contain cyclic references to themselves
- through bound type parameters, simplification and thus type
- inference fails.
- Otherwise, type inference succeeds.
- </p>
- <h4 id="Type_unification">Type unification</h4>
- <p>
- Type inference solves type equations through <i>type unification</i>.
- Type unification recursively compares the LHS and RHS types of an
- equation, where either or both types may be or contain bound type parameters,
- and looks for type arguments for those type parameters such that the LHS
- and RHS match (become identical or assignment-compatible, depending on
- context).
- To that effect, type inference maintains a map of bound type parameters
- to inferred type arguments; this map is consulted and updated during type unification.
- Initially, the bound type parameters are known but the map is empty.
- During type unification, if a new type argument <code>A</code> is inferred,
- the respective mapping <code>P ➞ A</code> from type parameter to argument
- is added to the map.
- Conversely, when comparing types, a known type argument
- (a type argument for which a map entry already exists)
- takes the place of its corresponding type parameter.
- As type inference progresses, the map is populated more and more
- until all equations have been considered, or until unification fails.
- Type inference succeeds if no unification step fails and the map has
- an entry for each type parameter.
- </p>
- <p>
- For example, given the type equation with the bound type parameter
- <code>P</code>
- </p>
- <pre>
- [10]struct{ elem P, list []P } ≡<sub>A</sub> [10]struct{ elem string; list []string }
- </pre>
- <p>
- type inference starts with an empty map.
- Unification first compares the top-level structure of the LHS and RHS
- types.
- Both are arrays of the same length; they unify if the element types unify.
- Both element types are structs; they unify if they have
- the same number of fields with the same names and if the
- field types unify.
- The type argument for <code>P</code> is not known yet (there is no map entry),
- so unifying <code>P</code> with <code>string</code> adds
- the mapping <code>P ➞ string</code> to the map.
- Unifying the types of the <code>list</code> field requires
- unifying <code>[]P</code> and <code>[]string</code> and
- thus <code>P</code> and <code>string</code>.
- Since the type argument for <code>P</code> is known at this point
- (there is a map entry for <code>P</code>), its type argument
- <code>string</code> takes the place of <code>P</code>.
- And since <code>string</code> is identical to <code>string</code>,
- this unification step succeeds as well.
- Unification of the LHS and RHS of the equation is now finished.
- Type inference succeeds because there is only one type equation,
- no unification step failed, and the map is fully populated.
- </p>
- <p>
- Unification uses a combination of <i>exact</i> and <i>loose</i>
- unification depending on whether two types have to be
- <a href="#Type_identity">identical</a>,
- <a href="#Assignability">assignment-compatible</a>, or
- only structurally equal.
- The respective <a href="#Type_unification_rules">type unification rules</a>
- are spelled out in detail in the <a href="#Appendix">Appendix</a>.
- </p>
- <p>
- For an equation of the form <code>X ≡<sub>A</sub> Y</code>,
- where <code>X</code> and <code>Y</code> are types involved
- in an assignment (including parameter passing and return statements),
- the top-level type structures may unify loosely but element types
- must unify exactly, matching the rules for assignments.
- </p>
- <p>
- For an equation of the form <code>P ≡<sub>C</sub> C</code>,
- where <code>P</code> is a type parameter and <code>C</code>
- its corresponding constraint, the unification rules are bit
- more complicated:
- </p>
- <ul>
- <li>
- If <code>C</code> has a <a href="#Core_types">core type</a>
- <code>core(C)</code>
- and <code>P</code> has a known type argument <code>A</code>,
- <code>core(C)</code> and <code>A</code> must unify loosely.
- If <code>P</code> does not have a known type argument
- and <code>C</code> contains exactly one type term <code>T</code>
- that is not an underlying (tilde) type, unification adds the
- mapping <code>P ➞ T</code> to the map.
- </li>
- <li>
- If <code>C</code> does not have a core type
- and <code>P</code> has a known type argument <code>A</code>,
- <code>A</code> must have all methods of <code>C</code>, if any,
- and corresponding method types must unify exactly.
- </li>
- </ul>
- <p>
- When solving type equations from type constraints,
- solving one equation may infer additional type arguments,
- which in turn may enable solving other equations that depend
- on those type arguments.
- Type inference repeats type unification as long as new type
- arguments are inferred.
- </p>
- <h3 id="Operators">Operators</h3>
- <p>
- Operators combine operands into expressions.
- </p>
- <pre class="ebnf">
- Expression = UnaryExpr | Expression binary_op Expression .
- UnaryExpr = PrimaryExpr | unary_op UnaryExpr .
- binary_op = "||" | "&&" | rel_op | add_op | mul_op .
- rel_op = "==" | "!=" | "<" | "<=" | ">" | ">=" .
- add_op = "+" | "-" | "|" | "^" .
- mul_op = "*" | "/" | "%" | "<<" | ">>" | "&" | "&^" .
- unary_op = "+" | "-" | "!" | "^" | "*" | "&" | "<-" .
- </pre>
- <p>
- Comparisons are discussed <a href="#Comparison_operators">elsewhere</a>.
- For other binary operators, the operand types must be <a href="#Type_identity">identical</a>
- unless the operation involves shifts or untyped <a href="#Constants">constants</a>.
- For operations involving constants only, see the section on
- <a href="#Constant_expressions">constant expressions</a>.
- </p>
- <p>
- Except for shift operations, if one operand is an untyped <a href="#Constants">constant</a>
- and the other operand is not, the constant is implicitly <a href="#Conversions">converted</a>
- to the type of the other operand.
- </p>
- <p>
- The right operand in a shift expression must have <a href="#Numeric_types">integer type</a>
- [<a href="#Go_1.13">Go 1.13</a>]
- or be an untyped constant <a href="#Representability">representable</a> by a
- value of type <code>uint</code>.
- If the left operand of a non-constant shift expression is an untyped constant,
- it is first implicitly converted to the type it would assume if the shift expression were
- replaced by its left operand alone.
- </p>
- <pre>
- var a [1024]byte
- var s uint = 33
- // The results of the following examples are given for 64-bit ints.
- var i = 1<<s // 1 has type int
- var j int32 = 1<<s // 1 has type int32; j == 0
- var k = uint64(1<<s) // 1 has type uint64; k == 1<<33
- var m int = 1.0<<s // 1.0 has type int; m == 1<<33
- var n = 1.0<<s == j // 1.0 has type int32; n == true
- var o = 1<<s == 2<<s // 1 and 2 have type int; o == false
- var p = 1<<s == 1<<33 // 1 has type int; p == true
- var u = 1.0<<s // illegal: 1.0 has type float64, cannot shift
- var u1 = 1.0<<s != 0 // illegal: 1.0 has type float64, cannot shift
- var u2 = 1<<s != 1.0 // illegal: 1 has type float64, cannot shift
- var v1 float32 = 1<<s // illegal: 1 has type float32, cannot shift
- var v2 = string(1<<s) // illegal: 1 is converted to a string, cannot shift
- var w int64 = 1.0<<33 // 1.0<<33 is a constant shift expression; w == 1<<33
- var x = a[1.0<<s] // panics: 1.0 has type int, but 1<<33 overflows array bounds
- var b = make([]byte, 1.0<<s) // 1.0 has type int; len(b) == 1<<33
- // The results of the following examples are given for 32-bit ints,
- // which means the shifts will overflow.
- var mm int = 1.0<<s // 1.0 has type int; mm == 0
- var oo = 1<<s == 2<<s // 1 and 2 have type int; oo == true
- var pp = 1<<s == 1<<33 // illegal: 1 has type int, but 1<<33 overflows int
- var xx = a[1.0<<s] // 1.0 has type int; xx == a[0]
- var bb = make([]byte, 1.0<<s) // 1.0 has type int; len(bb) == 0
- </pre>
- <h4 id="Operator_precedence">Operator precedence</h4>
- <p>
- Unary operators have the highest precedence.
- As the <code>++</code> and <code>--</code> operators form
- statements, not expressions, they fall
- outside the operator hierarchy.
- As a consequence, statement <code>*p++</code> is the same as <code>(*p)++</code>.
- </p>
- <p>
- There are five precedence levels for binary operators.
- Multiplication operators bind strongest, followed by addition
- operators, comparison operators, <code>&&</code> (logical AND),
- and finally <code>||</code> (logical OR):
- </p>
- <pre class="grammar">
- Precedence Operator
- 5 * / % << >> & &^
- 4 + - | ^
- 3 == != < <= > >=
- 2 &&
- 1 ||
- </pre>
- <p>
- Binary operators of the same precedence associate from left to right.
- For instance, <code>x / y * z</code> is the same as <code>(x / y) * z</code>.
- </p>
- <pre>
- +x // x
- 42 + a - b // (42 + a) - b
- 23 + 3*x[i] // 23 + (3 * x[i])
- x <= f() // x <= f()
- ^a >> b // (^a) >> b
- f() || g() // f() || g()
- x == y+1 && <-chanInt > 0 // (x == (y+1)) && ((<-chanInt) > 0)
- </pre>
- <h3 id="Arithmetic_operators">Arithmetic operators</h3>
- <p>
- Arithmetic operators apply to numeric values and yield a result of the same
- type as the first operand. The four standard arithmetic operators (<code>+</code>,
- <code>-</code>, <code>*</code>, <code>/</code>) apply to
- <a href="#Numeric_types">integer</a>, <a href="#Numeric_types">floating-point</a>, and
- <a href="#Numeric_types">complex</a> types; <code>+</code> also applies to <a href="#String_types">strings</a>.
- The bitwise logical and shift operators apply to integers only.
- </p>
- <pre class="grammar">
- + sum integers, floats, complex values, strings
- - difference integers, floats, complex values
- * product integers, floats, complex values
- / quotient integers, floats, complex values
- % remainder integers
- & bitwise AND integers
- | bitwise OR integers
- ^ bitwise XOR integers
- &^ bit clear (AND NOT) integers
- << left shift integer << integer >= 0
- >> right shift integer >> integer >= 0
- </pre>
- <p>
- If the operand type is a <a href="#Type_parameter_declarations">type parameter</a>,
- the operator must apply to each type in that type set.
- The operands are represented as values of the type argument that the type parameter
- is <a href="#Instantiations">instantiated</a> with, and the operation is computed
- with the precision of that type argument. For example, given the function:
- </p>
- <pre>
- func dotProduct[F ~float32|~float64](v1, v2 []F) F {
- var s F
- for i, x := range v1 {
- y := v2[i]
- s += x * y
- }
- return s
- }
- </pre>
- <p>
- the product <code>x * y</code> and the addition <code>s += x * y</code>
- are computed with <code>float32</code> or <code>float64</code> precision,
- respectively, depending on the type argument for <code>F</code>.
- </p>
- <h4 id="Integer_operators">Integer operators</h4>
- <p>
- For two integer values <code>x</code> and <code>y</code>, the integer quotient
- <code>q = x / y</code> and remainder <code>r = x % y</code> satisfy the following
- relationships:
- </p>
- <pre>
- x = q*y + r and |r| < |y|
- </pre>
- <p>
- with <code>x / y</code> truncated towards zero
- (<a href="https://en.wikipedia.org/wiki/Modulo_operation">"truncated division"</a>).
- </p>
- <pre>
- x y x / y x % y
- 5 3 1 2
- -5 3 -1 -2
- 5 -3 -1 2
- -5 -3 1 -2
- </pre>
- <p>
- The one exception to this rule is that if the dividend <code>x</code> is
- the most negative value for the int type of <code>x</code>, the quotient
- <code>q = x / -1</code> is equal to <code>x</code> (and <code>r = 0</code>)
- due to two's-complement <a href="#Integer_overflow">integer overflow</a>:
- </p>
- <pre>
- x, q
- int8 -128
- int16 -32768
- int32 -2147483648
- int64 -9223372036854775808
- </pre>
- <p>
- If the divisor is a <a href="#Constants">constant</a>, it must not be zero.
- If the divisor is zero at run time, a <a href="#Run_time_panics">run-time panic</a> occurs.
- If the dividend is non-negative and the divisor is a constant power of 2,
- the division may be replaced by a right shift, and computing the remainder may
- be replaced by a bitwise AND operation:
- </p>
- <pre>
- x x / 4 x % 4 x >> 2 x & 3
- 11 2 3 2 3
- -11 -2 -3 -3 1
- </pre>
- <p>
- The shift operators shift the left operand by the shift count specified by the
- right operand, which must be non-negative. If the shift count is negative at run time,
- a <a href="#Run_time_panics">run-time panic</a> occurs.
- The shift operators implement arithmetic shifts if the left operand is a signed
- integer and logical shifts if it is an unsigned integer.
- There is no upper limit on the shift count. Shifts behave
- as if the left operand is shifted <code>n</code> times by 1 for a shift
- count of <code>n</code>.
- As a result, <code>x << 1</code> is the same as <code>x*2</code>
- and <code>x >> 1</code> is the same as
- <code>x/2</code> but truncated towards negative infinity.
- </p>
- <p>
- For integer operands, the unary operators
- <code>+</code>, <code>-</code>, and <code>^</code> are defined as
- follows:
- </p>
- <pre class="grammar">
- +x is 0 + x
- -x negation is 0 - x
- ^x bitwise complement is m ^ x with m = "all bits set to 1" for unsigned x
- and m = -1 for signed x
- </pre>
- <h4 id="Integer_overflow">Integer overflow</h4>
- <p>
- For <a href="#Numeric_types">unsigned integer</a> values, the operations <code>+</code>,
- <code>-</code>, <code>*</code>, and <code><<</code> are
- computed modulo 2<sup><i>n</i></sup>, where <i>n</i> is the bit width of
- the unsigned integer's type.
- Loosely speaking, these unsigned integer operations
- discard high bits upon overflow, and programs may rely on "wrap around".
- </p>
- <p>
- For signed integers, the operations <code>+</code>,
- <code>-</code>, <code>*</code>, <code>/</code>, and <code><<</code> may legally
- overflow and the resulting value exists and is deterministically defined
- by the signed integer representation, the operation, and its operands.
- Overflow does not cause a <a href="#Run_time_panics">run-time panic</a>.
- A compiler may not optimize code under the assumption that overflow does
- not occur. For instance, it may not assume that <code>x < x + 1</code> is always true.
- </p>
- <h4 id="Floating_point_operators">Floating-point operators</h4>
- <p>
- For floating-point and complex numbers,
- <code>+x</code> is the same as <code>x</code>,
- while <code>-x</code> is the negation of <code>x</code>.
- The result of a floating-point or complex division by zero is not specified beyond the
- IEEE 754 standard; whether a <a href="#Run_time_panics">run-time panic</a>
- occurs is implementation-specific.
- </p>
- <p>
- An implementation may combine multiple floating-point operations into a single
- fused operation, possibly across statements, and produce a result that differs
- from the value obtained by executing and rounding the instructions individually.
- An explicit <a href="#Numeric_types">floating-point type</a> <a href="#Conversions">conversion</a> rounds to
- the precision of the target type, preventing fusion that would discard that rounding.
- </p>
- <p>
- For instance, some architectures provide a "fused multiply and add" (FMA) instruction
- that computes <code>x*y + z</code> without rounding the intermediate result <code>x*y</code>.
- These examples show when a Go implementation can use that instruction:
- </p>
- <pre>
- // FMA allowed for computing r, because x*y is not explicitly rounded:
- r = x*y + z
- r = z; r += x*y
- t = x*y; r = t + z
- *p = x*y; r = *p + z
- r = x*y + float64(z)
- // FMA disallowed for computing r, because it would omit rounding of x*y:
- r = float64(x*y) + z
- r = z; r += float64(x*y)
- t = float64(x*y); r = t + z
- </pre>
- <h4 id="String_concatenation">String concatenation</h4>
- <p>
- Strings can be concatenated using the <code>+</code> operator
- or the <code>+=</code> assignment operator:
- </p>
- <pre>
- s := "hi" + string(c)
- s += " and good bye"
- </pre>
- <p>
- String addition creates a new string by concatenating the operands.
- </p>
- <h3 id="Comparison_operators">Comparison operators</h3>
- <p>
- Comparison operators compare two operands and yield an untyped boolean value.
- </p>
- <pre class="grammar">
- == equal
- != not equal
- < less
- <= less or equal
- > greater
- >= greater or equal
- </pre>
- <p>
- In any comparison, the first operand
- must be <a href="#Assignability">assignable</a>
- to the type of the second operand, or vice versa.
- </p>
- <p>
- The equality operators <code>==</code> and <code>!=</code> apply
- to operands of <i>comparable</i> types.
- The ordering operators <code><</code>, <code><=</code>, <code>></code>, and <code>>=</code>
- apply to operands of <i>ordered</i> types.
- These terms and the result of the comparisons are defined as follows:
- </p>
- <ul>
- <li>
- Boolean types are comparable.
- Two boolean values are equal if they are either both
- <code>true</code> or both <code>false</code>.
- </li>
- <li>
- Integer types are comparable and ordered.
- Two integer values are compared in the usual way.
- </li>
- <li>
- Floating-point types are comparable and ordered.
- Two floating-point values are compared as defined by the IEEE 754 standard.
- </li>
- <li>
- Complex types are comparable.
- Two complex values <code>u</code> and <code>v</code> are
- equal if both <code>real(u) == real(v)</code> and
- <code>imag(u) == imag(v)</code>.
- </li>
- <li>
- String types are comparable and ordered.
- Two string values are compared lexically byte-wise.
- </li>
- <li>
- Pointer types are comparable.
- Two pointer values are equal if they point to the same variable or if both have value <code>nil</code>.
- Pointers to distinct <a href="#Size_and_alignment_guarantees">zero-size</a> variables may or may not be equal.
- </li>
- <li>
- Channel types are comparable.
- Two channel values are equal if they were created by the same call to
- <a href="#Making_slices_maps_and_channels"><code>make</code></a>
- or if both have value <code>nil</code>.
- </li>
- <li>
- Interface types that are not type parameters are comparable.
- Two interface values are equal if they have <a href="#Type_identity">identical</a> dynamic types
- and equal dynamic values or if both have value <code>nil</code>.
- </li>
- <li>
- A value <code>x</code> of non-interface type <code>X</code> and
- a value <code>t</code> of interface type <code>T</code> can be compared
- if type <code>X</code> is comparable and
- <code>X</code> <a href="#Implementing_an_interface">implements</a> <code>T</code>.
- They are equal if <code>t</code>'s dynamic type is identical to <code>X</code>
- and <code>t</code>'s dynamic value is equal to <code>x</code>.
- </li>
- <li>
- Struct types are comparable if all their field types are comparable.
- Two struct values are equal if their corresponding
- non-<a href="#Blank_identifier">blank</a> field values are equal.
- The fields are compared in source order, and comparison stops as
- soon as two field values differ (or all fields have been compared).
- </li>
- <li>
- Array types are comparable if their array element types are comparable.
- Two array values are equal if their corresponding element values are equal.
- The elements are compared in ascending index order, and comparison stops
- as soon as two element values differ (or all elements have been compared).
- </li>
- <li>
- Type parameters are comparable if they are strictly comparable (see below).
- </li>
- </ul>
- <p>
- A comparison of two interface values with identical dynamic types
- causes a <a href="#Run_time_panics">run-time panic</a> if that type
- is not comparable. This behavior applies not only to direct interface
- value comparisons but also when comparing arrays of interface values
- or structs with interface-valued fields.
- </p>
- <p>
- Slice, map, and function types are not comparable.
- However, as a special case, a slice, map, or function value may
- be compared to the predeclared identifier <code>nil</code>.
- Comparison of pointer, channel, and interface values to <code>nil</code>
- is also allowed and follows from the general rules above.
- </p>
- <pre>
- const c = 3 < 4 // c is the untyped boolean constant true
- type MyBool bool
- var x, y int
- var (
- // The result of a comparison is an untyped boolean.
- // The usual assignment rules apply.
- b3 = x == y // b3 has type bool
- b4 bool = x == y // b4 has type bool
- b5 MyBool = x == y // b5 has type MyBool
- )
- </pre>
- <p>
- A type is <i>strictly comparable</i> if it is comparable and not an interface
- type nor composed of interface types.
- Specifically:
- </p>
- <ul>
- <li>
- Boolean, numeric, string, pointer, and channel types are strictly comparable.
- </li>
- <li>
- Struct types are strictly comparable if all their field types are strictly comparable.
- </li>
- <li>
- Array types are strictly comparable if their array element types are strictly comparable.
- </li>
- <li>
- Type parameters are strictly comparable if all types in their type set are strictly comparable.
- </li>
- </ul>
- <h3 id="Logical_operators">Logical operators</h3>
- <p>
- Logical operators apply to <a href="#Boolean_types">boolean</a> values
- and yield a result of the same type as the operands.
- The left operand is evaluated, and then the right if the condition requires it.
- </p>
- <pre class="grammar">
- && conditional AND p && q is "if p then q else false"
- || conditional OR p || q is "if p then true else q"
- ! NOT !p is "not p"
- </pre>
- <h3 id="Address_operators">Address operators</h3>
- <p>
- For an operand <code>x</code> of type <code>T</code>, the address operation
- <code>&x</code> generates a pointer of type <code>*T</code> to <code>x</code>.
- The operand must be <i>addressable</i>,
- that is, either a variable, pointer indirection, or slice indexing
- operation; or a field selector of an addressable struct operand;
- or an array indexing operation of an addressable array.
- As an exception to the addressability requirement, <code>x</code> may also be a
- (possibly parenthesized)
- <a href="#Composite_literals">composite literal</a>.
- If the evaluation of <code>x</code> would cause a <a href="#Run_time_panics">run-time panic</a>,
- then the evaluation of <code>&x</code> does too.
- </p>
- <p>
- For an operand <code>x</code> of pointer type <code>*T</code>, the pointer
- indirection <code>*x</code> denotes the <a href="#Variables">variable</a> of type <code>T</code> pointed
- to by <code>x</code>.
- If <code>x</code> is <code>nil</code>, an attempt to evaluate <code>*x</code>
- will cause a <a href="#Run_time_panics">run-time panic</a>.
- </p>
- <pre>
- &x
- &a[f(2)]
- &Point{2, 3}
- *p
- *pf(x)
- var x *int = nil
- *x // causes a run-time panic
- &*x // causes a run-time panic
- </pre>
- <h3 id="Receive_operator">Receive operator</h3>
- <p>
- For an operand <code>ch</code> whose <a href="#Core_types">core type</a> is a
- <a href="#Channel_types">channel</a>,
- the value of the receive operation <code><-ch</code> is the value received
- from the channel <code>ch</code>. The channel direction must permit receive operations,
- and the type of the receive operation is the element type of the channel.
- The expression blocks until a value is available.
- Receiving from a <code>nil</code> channel blocks forever.
- A receive operation on a <a href="#Close">closed</a> channel can always proceed
- immediately, yielding the element type's <a href="#The_zero_value">zero value</a>
- after any previously sent values have been received.
- </p>
- <pre>
- v1 := <-ch
- v2 = <-ch
- f(<-ch)
- <-strobe // wait until clock pulse and discard received value
- </pre>
- <p>
- A receive expression used in an <a href="#Assignment_statements">assignment statement</a> or initialization of the special form
- </p>
- <pre>
- x, ok = <-ch
- x, ok := <-ch
- var x, ok = <-ch
- var x, ok T = <-ch
- </pre>
- <p>
- yields an additional untyped boolean result reporting whether the
- communication succeeded. The value of <code>ok</code> is <code>true</code>
- if the value received was delivered by a successful send operation to the
- channel, or <code>false</code> if it is a zero value generated because the
- channel is closed and empty.
- </p>
- <h3 id="Conversions">Conversions</h3>
- <p>
- A conversion changes the <a href="#Types">type</a> of an expression
- to the type specified by the conversion.
- A conversion may appear literally in the source, or it may be <i>implied</i>
- by the context in which an expression appears.
- </p>
- <p>
- An <i>explicit</i> conversion is an expression of the form <code>T(x)</code>
- where <code>T</code> is a type and <code>x</code> is an expression
- that can be converted to type <code>T</code>.
- </p>
- <pre class="ebnf">
- Conversion = Type "(" Expression [ "," ] ")" .
- </pre>
- <p>
- If the type starts with the operator <code>*</code> or <code><-</code>,
- or if the type starts with the keyword <code>func</code>
- and has no result list, it must be parenthesized when
- necessary to avoid ambiguity:
- </p>
- <pre>
- *Point(p) // same as *(Point(p))
- (*Point)(p) // p is converted to *Point
- <-chan int(c) // same as <-(chan int(c))
- (<-chan int)(c) // c is converted to <-chan int
- func()(x) // function signature func() x
- (func())(x) // x is converted to func()
- (func() int)(x) // x is converted to func() int
- func() int(x) // x is converted to func() int (unambiguous)
- </pre>
- <p>
- A <a href="#Constants">constant</a> value <code>x</code> can be converted to
- type <code>T</code> if <code>x</code> is <a href="#Representability">representable</a>
- by a value of <code>T</code>.
- As a special case, an integer constant <code>x</code> can be explicitly converted to a
- <a href="#String_types">string type</a> using the
- <a href="#Conversions_to_and_from_a_string_type">same rule</a>
- as for non-constant <code>x</code>.
- </p>
- <p>
- Converting a constant to a type that is not a <a href="#Type_parameter_declarations">type parameter</a>
- yields a typed constant.
- </p>
- <pre>
- uint(iota) // iota value of type uint
- float32(2.718281828) // 2.718281828 of type float32
- complex128(1) // 1.0 + 0.0i of type complex128
- float32(0.49999999) // 0.5 of type float32
- float64(-1e-1000) // 0.0 of type float64
- string('x') // "x" of type string
- string(0x266c) // "♬" of type string
- myString("foo" + "bar") // "foobar" of type myString
- string([]byte{'a'}) // not a constant: []byte{'a'} is not a constant
- (*int)(nil) // not a constant: nil is not a constant, *int is not a boolean, numeric, or string type
- int(1.2) // illegal: 1.2 cannot be represented as an int
- string(65.0) // illegal: 65.0 is not an integer constant
- </pre>
- <p>
- Converting a constant to a type parameter yields a <i>non-constant</i> value of that type,
- with the value represented as a value of the type argument that the type parameter
- is <a href="#Instantiations">instantiated</a> with.
- For example, given the function:
- </p>
- <pre>
- func f[P ~float32|~float64]() {
- … P(1.1) …
- }
- </pre>
- <p>
- the conversion <code>P(1.1)</code> results in a non-constant value of type <code>P</code>
- and the value <code>1.1</code> is represented as a <code>float32</code> or a <code>float64</code>
- depending on the type argument for <code>f</code>.
- Accordingly, if <code>f</code> is instantiated with a <code>float32</code> type,
- the numeric value of the expression <code>P(1.1) + 1.2</code> will be computed
- with the same precision as the corresponding non-constant <code>float32</code>
- addition.
- </p>
- <p>
- A non-constant value <code>x</code> can be converted to type <code>T</code>
- in any of these cases:
- </p>
- <ul>
- <li>
- <code>x</code> is <a href="#Assignability">assignable</a>
- to <code>T</code>.
- </li>
- <li>
- ignoring struct tags (see below),
- <code>x</code>'s type and <code>T</code> are not
- <a href="#Type_parameter_declarations">type parameters</a> but have
- <a href="#Type_identity">identical</a> <a href="#Underlying_types">underlying types</a>.
- </li>
- <li>
- ignoring struct tags (see below),
- <code>x</code>'s type and <code>T</code> are pointer types
- that are not <a href="#Types">named types</a>,
- and their pointer base types are not type parameters but
- have identical underlying types.
- </li>
- <li>
- <code>x</code>'s type and <code>T</code> are both integer or floating
- point types.
- </li>
- <li>
- <code>x</code>'s type and <code>T</code> are both complex types.
- </li>
- <li>
- <code>x</code> is an integer or a slice of bytes or runes
- and <code>T</code> is a string type.
- </li>
- <li>
- <code>x</code> is a string and <code>T</code> is a slice of bytes or runes.
- </li>
- <li>
- <code>x</code> is a slice, <code>T</code> is an array [<a href="#Go_1.20">Go 1.20</a>]
- or a pointer to an array [<a href="#Go_1.17">Go 1.17</a>],
- and the slice and array types have <a href="#Type_identity">identical</a> element types.
- </li>
- </ul>
- <p>
- Additionally, if <code>T</code> or <code>x</code>'s type <code>V</code> are type
- parameters, <code>x</code>
- can also be converted to type <code>T</code> if one of the following conditions applies:
- </p>
- <ul>
- <li>
- Both <code>V</code> and <code>T</code> are type parameters and a value of each
- type in <code>V</code>'s type set can be converted to each type in <code>T</code>'s
- type set.
- </li>
- <li>
- Only <code>V</code> is a type parameter and a value of each
- type in <code>V</code>'s type set can be converted to <code>T</code>.
- </li>
- <li>
- Only <code>T</code> is a type parameter and <code>x</code> can be converted to each
- type in <code>T</code>'s type set.
- </li>
- </ul>
- <p>
- <a href="#Struct_types">Struct tags</a> are ignored when comparing struct types
- for identity for the purpose of conversion:
- </p>
- <pre>
- type Person struct {
- Name string
- Address *struct {
- Street string
- City string
- }
- }
- var data *struct {
- Name string `json:"name"`
- Address *struct {
- Street string `json:"street"`
- City string `json:"city"`
- } `json:"address"`
- }
- var person = (*Person)(data) // ignoring tags, the underlying types are identical
- </pre>
- <p>
- Specific rules apply to (non-constant) conversions between numeric types or
- to and from a string type.
- These conversions may change the representation of <code>x</code>
- and incur a run-time cost.
- All other conversions only change the type but not the representation
- of <code>x</code>.
- </p>
- <p>
- There is no linguistic mechanism to convert between pointers and integers.
- The package <a href="#Package_unsafe"><code>unsafe</code></a>
- implements this functionality under restricted circumstances.
- </p>
- <h4>Conversions between numeric types</h4>
- <p>
- For the conversion of non-constant numeric values, the following rules apply:
- </p>
- <ol>
- <li>
- When converting between <a href="#Numeric_types">integer types</a>, if the value is a signed integer, it is
- sign extended to implicit infinite precision; otherwise it is zero extended.
- It is then truncated to fit in the result type's size.
- For example, if <code>v := uint16(0x10F0)</code>, then <code>uint32(int8(v)) == 0xFFFFFFF0</code>.
- The conversion always yields a valid value; there is no indication of overflow.
- </li>
- <li>
- When converting a <a href="#Numeric_types">floating-point number</a> to an integer, the fraction is discarded
- (truncation towards zero).
- </li>
- <li>
- When converting an integer or floating-point number to a floating-point type,
- or a <a href="#Numeric_types">complex number</a> to another complex type, the result value is rounded
- to the precision specified by the destination type.
- For instance, the value of a variable <code>x</code> of type <code>float32</code>
- may be stored using additional precision beyond that of an IEEE 754 32-bit number,
- but float32(x) represents the result of rounding <code>x</code>'s value to
- 32-bit precision. Similarly, <code>x + 0.1</code> may use more than 32 bits
- of precision, but <code>float32(x + 0.1)</code> does not.
- </li>
- </ol>
- <p>
- In all non-constant conversions involving floating-point or complex values,
- if the result type cannot represent the value the conversion
- succeeds but the result value is implementation-dependent.
- </p>
- <h4 id="Conversions_to_and_from_a_string_type">Conversions to and from a string type</h4>
- <ol>
- <li>
- Converting a slice of bytes to a string type yields
- a string whose successive bytes are the elements of the slice.
- <pre>
- string([]byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'}) // "hellø"
- string([]byte{}) // ""
- string([]byte(nil)) // ""
- type bytes []byte
- string(bytes{'h', 'e', 'l', 'l', '\xc3', '\xb8'}) // "hellø"
- type myByte byte
- string([]myByte{'w', 'o', 'r', 'l', 'd', '!'}) // "world!"
- myString([]myByte{'\xf0', '\x9f', '\x8c', '\x8d'}) // "🌍"
- </pre>
- </li>
- <li>
- Converting a slice of runes to a string type yields
- a string that is the concatenation of the individual rune values
- converted to strings.
- <pre>
- string([]rune{0x767d, 0x9d6c, 0x7fd4}) // "\u767d\u9d6c\u7fd4" == "白鵬翔"
- string([]rune{}) // ""
- string([]rune(nil)) // ""
- type runes []rune
- string(runes{0x767d, 0x9d6c, 0x7fd4}) // "\u767d\u9d6c\u7fd4" == "白鵬翔"
- type myRune rune
- string([]myRune{0x266b, 0x266c}) // "\u266b\u266c" == "♫♬"
- myString([]myRune{0x1f30e}) // "\U0001f30e" == "🌎"
- </pre>
- </li>
- <li>
- Converting a value of a string type to a slice of bytes type
- yields a non-nil slice whose successive elements are the bytes of the string.
- <pre>
- []byte("hellø") // []byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'}
- []byte("") // []byte{}
- bytes("hellø") // []byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'}
- []myByte("world!") // []myByte{'w', 'o', 'r', 'l', 'd', '!'}
- []myByte(myString("🌏")) // []myByte{'\xf0', '\x9f', '\x8c', '\x8f'}
- </pre>
- </li>
- <li>
- Converting a value of a string type to a slice of runes type
- yields a slice containing the individual Unicode code points of the string.
- <pre>
- []rune(myString("白鵬翔")) // []rune{0x767d, 0x9d6c, 0x7fd4}
- []rune("") // []rune{}
- runes("白鵬翔") // []rune{0x767d, 0x9d6c, 0x7fd4}
- []myRune("♫♬") // []myRune{0x266b, 0x266c}
- []myRune(myString("🌐")) // []myRune{0x1f310}
- </pre>
- </li>
- <li>
- Finally, for historical reasons, an integer value may be converted to a string type.
- This form of conversion yields a string containing the (possibly multi-byte) UTF-8
- representation of the Unicode code point with the given integer value.
- Values outside the range of valid Unicode code points are converted to <code>"\uFFFD"</code>.
- <pre>
- string('a') // "a"
- string(65) // "A"
- string('\xf8') // "\u00f8" == "ø" == "\xc3\xb8"
- string(-1) // "\ufffd" == "\xef\xbf\xbd"
- type myString string
- myString('\u65e5') // "\u65e5" == "日" == "\xe6\x97\xa5"
- </pre>
- Note: This form of conversion may eventually be removed from the language.
- The <a href="/pkg/cmd/vet"><code>go vet</code></a> tool flags certain
- integer-to-string conversions as potential errors.
- Library functions such as
- <a href="/pkg/unicode/utf8#AppendRune"><code>utf8.AppendRune</code></a> or
- <a href="/pkg/unicode/utf8#EncodeRune"><code>utf8.EncodeRune</code></a>
- should be used instead.
- </li>
- </ol>
- <h4 id="Conversions_from_slice_to_array_or_array_pointer">Conversions from slice to array or array pointer</h4>
- <p>
- Converting a slice to an array yields an array containing the elements of the underlying array of the slice.
- Similarly, converting a slice to an array pointer yields a pointer to the underlying array of the slice.
- In both cases, if the <a href="#Length_and_capacity">length</a> of the slice is less than the length of the array,
- a <a href="#Run_time_panics">run-time panic</a> occurs.
- </p>
- <pre>
- s := make([]byte, 2, 4)
- a0 := [0]byte(s)
- a1 := [1]byte(s[1:]) // a1[0] == s[1]
- a2 := [2]byte(s) // a2[0] == s[0]
- a4 := [4]byte(s) // panics: len([4]byte) > len(s)
- s0 := (*[0]byte)(s) // s0 != nil
- s1 := (*[1]byte)(s[1:]) // &s1[0] == &s[1]
- s2 := (*[2]byte)(s) // &s2[0] == &s[0]
- s4 := (*[4]byte)(s) // panics: len([4]byte) > len(s)
- var t []string
- t0 := [0]string(t) // ok for nil slice t
- t1 := (*[0]string)(t) // t1 == nil
- t2 := (*[1]string)(t) // panics: len([1]string) > len(t)
- u := make([]byte, 0)
- u0 := (*[0]byte)(u) // u0 != nil
- </pre>
- <h3 id="Constant_expressions">Constant expressions</h3>
- <p>
- Constant expressions may contain only <a href="#Constants">constant</a>
- operands and are evaluated at compile time.
- </p>
- <p>
- Untyped boolean, numeric, and string constants may be used as operands
- wherever it is legal to use an operand of boolean, numeric, or string type,
- respectively.
- </p>
- <p>
- A constant <a href="#Comparison_operators">comparison</a> always yields
- an untyped boolean constant. If the left operand of a constant
- <a href="#Operators">shift expression</a> is an untyped constant, the
- result is an integer constant; otherwise it is a constant of the same
- type as the left operand, which must be of
- <a href="#Numeric_types">integer type</a>.
- </p>
- <p>
- Any other operation on untyped constants results in an untyped constant of the
- same kind; that is, a boolean, integer, floating-point, complex, or string
- constant.
- If the untyped operands of a binary operation (other than a shift) are of
- different kinds, the result is of the operand's kind that appears later in this
- list: integer, rune, floating-point, complex.
- For example, an untyped integer constant divided by an
- untyped complex constant yields an untyped complex constant.
- </p>
- <pre>
- const a = 2 + 3.0 // a == 5.0 (untyped floating-point constant)
- const b = 15 / 4 // b == 3 (untyped integer constant)
- const c = 15 / 4.0 // c == 3.75 (untyped floating-point constant)
- const Θ float64 = 3/2 // Θ == 1.0 (type float64, 3/2 is integer division)
- const Π float64 = 3/2. // Π == 1.5 (type float64, 3/2. is float division)
- const d = 1 << 3.0 // d == 8 (untyped integer constant)
- const e = 1.0 << 3 // e == 8 (untyped integer constant)
- const f = int32(1) << 33 // illegal (constant 8589934592 overflows int32)
- const g = float64(2) >> 1 // illegal (float64(2) is a typed floating-point constant)
- const h = "foo" > "bar" // h == true (untyped boolean constant)
- const j = true // j == true (untyped boolean constant)
- const k = 'w' + 1 // k == 'x' (untyped rune constant)
- const l = "hi" // l == "hi" (untyped string constant)
- const m = string(k) // m == "x" (type string)
- const Σ = 1 - 0.707i // (untyped complex constant)
- const Δ = Σ + 2.0e-4 // (untyped complex constant)
- const Φ = iota*1i - 1/1i // (untyped complex constant)
- </pre>
- <p>
- Applying the built-in function <code>complex</code> to untyped
- integer, rune, or floating-point constants yields
- an untyped complex constant.
- </p>
- <pre>
- const ic = complex(0, c) // ic == 3.75i (untyped complex constant)
- const iΘ = complex(0, Θ) // iΘ == 1i (type complex128)
- </pre>
- <p>
- Constant expressions are always evaluated exactly; intermediate values and the
- constants themselves may require precision significantly larger than supported
- by any predeclared type in the language. The following are legal declarations:
- </p>
- <pre>
- const Huge = 1 << 100 // Huge == 1267650600228229401496703205376 (untyped integer constant)
- const Four int8 = Huge >> 98 // Four == 4 (type int8)
- </pre>
- <p>
- The divisor of a constant division or remainder operation must not be zero:
- </p>
- <pre>
- 3.14 / 0.0 // illegal: division by zero
- </pre>
- <p>
- The values of <i>typed</i> constants must always be accurately
- <a href="#Representability">representable</a> by values
- of the constant type. The following constant expressions are illegal:
- </p>
- <pre>
- uint(-1) // -1 cannot be represented as a uint
- int(3.14) // 3.14 cannot be represented as an int
- int64(Huge) // 1267650600228229401496703205376 cannot be represented as an int64
- Four * 300 // operand 300 cannot be represented as an int8 (type of Four)
- Four * 100 // product 400 cannot be represented as an int8 (type of Four)
- </pre>
- <p>
- The mask used by the unary bitwise complement operator <code>^</code> matches
- the rule for non-constants: the mask is all 1s for unsigned constants
- and -1 for signed and untyped constants.
- </p>
- <pre>
- ^1 // untyped integer constant, equal to -2
- uint8(^1) // illegal: same as uint8(-2), -2 cannot be represented as a uint8
- ^uint8(1) // typed uint8 constant, same as 0xFF ^ uint8(1) = uint8(0xFE)
- int8(^1) // same as int8(-2)
- ^int8(1) // same as -1 ^ int8(1) = -2
- </pre>
- <p>
- Implementation restriction: A compiler may use rounding while
- computing untyped floating-point or complex constant expressions; see
- the implementation restriction in the section
- on <a href="#Constants">constants</a>. This rounding may cause a
- floating-point constant expression to be invalid in an integer
- context, even if it would be integral when calculated using infinite
- precision, and vice versa.
- </p>
- <h3 id="Order_of_evaluation">Order of evaluation</h3>
- <p>
- At package level, <a href="#Package_initialization">initialization dependencies</a>
- determine the evaluation order of individual initialization expressions in
- <a href="#Variable_declarations">variable declarations</a>.
- Otherwise, when evaluating the <a href="#Operands">operands</a> of an
- expression, assignment, or
- <a href="#Return_statements">return statement</a>,
- all function calls, method calls,
- <a href="#Receive operator">receive operations</a>,
- and <a href="#Logical_operators">binary logical operations</a>
- are evaluated in lexical left-to-right order.
- </p>
- <p>
- For example, in the (function-local) assignment
- </p>
- <pre>
- y[f()], ok = g(z || h(), i()+x[j()], <-c), k()
- </pre>
- <p>
- the function calls and communication happen in the order
- <code>f()</code>, <code>h()</code> (if <code>z</code>
- evaluates to false), <code>i()</code>, <code>j()</code>,
- <code><-c</code>, <code>g()</code>, and <code>k()</code>.
- However, the order of those events compared to the evaluation
- and indexing of <code>x</code> and the evaluation
- of <code>y</code> and <code>z</code> is not specified,
- except as required lexically. For instance, <code>g</code>
- cannot be called before its arguments are evaluated.
- </p>
- <pre>
- a := 1
- f := func() int { a++; return a }
- x := []int{a, f()} // x may be [1, 2] or [2, 2]: evaluation order between a and f() is not specified
- m := map[int]int{a: 1, a: 2} // m may be {2: 1} or {2: 2}: evaluation order between the two map assignments is not specified
- n := map[int]int{a: f()} // n may be {2: 3} or {3: 3}: evaluation order between the key and the value is not specified
- </pre>
- <p>
- At package level, initialization dependencies override the left-to-right rule
- for individual initialization expressions, but not for operands within each
- expression:
- </p>
- <pre>
- var a, b, c = f() + v(), g(), sqr(u()) + v()
- func f() int { return c }
- func g() int { return a }
- func sqr(x int) int { return x*x }
- // functions u and v are independent of all other variables and functions
- </pre>
- <p>
- The function calls happen in the order
- <code>u()</code>, <code>sqr()</code>, <code>v()</code>,
- <code>f()</code>, <code>v()</code>, and <code>g()</code>.
- </p>
- <p>
- Floating-point operations within a single expression are evaluated according to
- the associativity of the operators. Explicit parentheses affect the evaluation
- by overriding the default associativity.
- In the expression <code>x + (y + z)</code> the addition <code>y + z</code>
- is performed before adding <code>x</code>.
- </p>
- <h2 id="Statements">Statements</h2>
- <p>
- Statements control execution.
- </p>
- <pre class="ebnf">
- Statement =
- Declaration | LabeledStmt | SimpleStmt |
- GoStmt | ReturnStmt | BreakStmt | ContinueStmt | GotoStmt |
- FallthroughStmt | Block | IfStmt | SwitchStmt | SelectStmt | ForStmt |
- DeferStmt .
- SimpleStmt = EmptyStmt | ExpressionStmt | SendStmt | IncDecStmt | Assignment | ShortVarDecl .
- </pre>
- <h3 id="Terminating_statements">Terminating statements</h3>
- <p>
- A <i>terminating statement</i> interrupts the regular flow of control in
- a <a href="#Blocks">block</a>. The following statements are terminating:
- </p>
- <ol>
- <li>
- A <a href="#Return_statements">"return"</a> or
- <a href="#Goto_statements">"goto"</a> statement.
- <!-- ul below only for regular layout -->
- <ul> </ul>
- </li>
- <li>
- A call to the built-in function
- <a href="#Handling_panics"><code>panic</code></a>.
- <!-- ul below only for regular layout -->
- <ul> </ul>
- </li>
- <li>
- A <a href="#Blocks">block</a> in which the statement list ends in a terminating statement.
- <!-- ul below only for regular layout -->
- <ul> </ul>
- </li>
- <li>
- An <a href="#If_statements">"if" statement</a> in which:
- <ul>
- <li>the "else" branch is present, and</li>
- <li>both branches are terminating statements.</li>
- </ul>
- </li>
- <li>
- A <a href="#For_statements">"for" statement</a> in which:
- <ul>
- <li>there are no "break" statements referring to the "for" statement, and</li>
- <li>the loop condition is absent, and</li>
- <li>the "for" statement does not use a range clause.</li>
- </ul>
- </li>
- <li>
- A <a href="#Switch_statements">"switch" statement</a> in which:
- <ul>
- <li>there are no "break" statements referring to the "switch" statement,</li>
- <li>there is a default case, and</li>
- <li>the statement lists in each case, including the default, end in a terminating
- statement, or a possibly labeled <a href="#Fallthrough_statements">"fallthrough"
- statement</a>.</li>
- </ul>
- </li>
- <li>
- A <a href="#Select_statements">"select" statement</a> in which:
- <ul>
- <li>there are no "break" statements referring to the "select" statement, and</li>
- <li>the statement lists in each case, including the default if present,
- end in a terminating statement.</li>
- </ul>
- </li>
- <li>
- A <a href="#Labeled_statements">labeled statement</a> labeling
- a terminating statement.
- </li>
- </ol>
- <p>
- All other statements are not terminating.
- </p>
- <p>
- A <a href="#Blocks">statement list</a> ends in a terminating statement if the list
- is not empty and its final non-empty statement is terminating.
- </p>
- <h3 id="Empty_statements">Empty statements</h3>
- <p>
- The empty statement does nothing.
- </p>
- <pre class="ebnf">
- EmptyStmt = .
- </pre>
- <h3 id="Labeled_statements">Labeled statements</h3>
- <p>
- A labeled statement may be the target of a <code>goto</code>,
- <code>break</code> or <code>continue</code> statement.
- </p>
- <pre class="ebnf">
- LabeledStmt = Label ":" Statement .
- Label = identifier .
- </pre>
- <pre>
- Error: log.Panic("error encountered")
- </pre>
- <h3 id="Expression_statements">Expression statements</h3>
- <p>
- With the exception of specific built-in functions,
- function and method <a href="#Calls">calls</a> and
- <a href="#Receive_operator">receive operations</a>
- can appear in statement context. Such statements may be parenthesized.
- </p>
- <pre class="ebnf">
- ExpressionStmt = Expression .
- </pre>
- <p>
- The following built-in functions are not permitted in statement context:
- </p>
- <pre>
- append cap complex imag len make new real
- unsafe.Add unsafe.Alignof unsafe.Offsetof unsafe.Sizeof unsafe.Slice unsafe.SliceData unsafe.String unsafe.StringData
- </pre>
- <pre>
- h(x+y)
- f.Close()
- <-ch
- (<-ch)
- len("foo") // illegal if len is the built-in function
- </pre>
- <h3 id="Send_statements">Send statements</h3>
- <p>
- A send statement sends a value on a channel.
- The channel expression's <a href="#Core_types">core type</a>
- must be a <a href="#Channel_types">channel</a>,
- the channel direction must permit send operations,
- and the type of the value to be sent must be <a href="#Assignability">assignable</a>
- to the channel's element type.
- </p>
- <pre class="ebnf">
- SendStmt = Channel "<-" Expression .
- Channel = Expression .
- </pre>
- <p>
- Both the channel and the value expression are evaluated before communication
- begins. Communication blocks until the send can proceed.
- A send on an unbuffered channel can proceed if a receiver is ready.
- A send on a buffered channel can proceed if there is room in the buffer.
- A send on a closed channel proceeds by causing a <a href="#Run_time_panics">run-time panic</a>.
- A send on a <code>nil</code> channel blocks forever.
- </p>
- <pre>
- ch <- 3 // send value 3 to channel ch
- </pre>
- <h3 id="IncDec_statements">IncDec statements</h3>
- <p>
- The "++" and "--" statements increment or decrement their operands
- by the untyped <a href="#Constants">constant</a> <code>1</code>.
- As with an assignment, the operand must be <a href="#Address_operators">addressable</a>
- or a map index expression.
- </p>
- <pre class="ebnf">
- IncDecStmt = Expression ( "++" | "--" ) .
- </pre>
- <p>
- The following <a href="#Assignment_statements">assignment statements</a> are semantically
- equivalent:
- </p>
- <pre class="grammar">
- IncDec statement Assignment
- x++ x += 1
- x-- x -= 1
- </pre>
- <h3 id="Assignment_statements">Assignment statements</h3>
- <p>
- An <i>assignment</i> replaces the current value stored in a <a href="#Variables">variable</a>
- with a new value specified by an <a href="#Expressions">expression</a>.
- An assignment statement may assign a single value to a single variable, or multiple values to a
- matching number of variables.
- </p>
- <pre class="ebnf">
- Assignment = ExpressionList assign_op ExpressionList .
- assign_op = [ add_op | mul_op ] "=" .
- </pre>
- <p>
- Each left-hand side operand must be <a href="#Address_operators">addressable</a>,
- a map index expression, or (for <code>=</code> assignments only) the
- <a href="#Blank_identifier">blank identifier</a>.
- Operands may be parenthesized.
- </p>
- <pre>
- x = 1
- *p = f()
- a[i] = 23
- (k) = <-ch // same as: k = <-ch
- </pre>
- <p>
- An <i>assignment operation</i> <code>x</code> <i>op</i><code>=</code>
- <code>y</code> where <i>op</i> is a binary <a href="#Arithmetic_operators">arithmetic operator</a>
- is equivalent to <code>x</code> <code>=</code> <code>x</code> <i>op</i>
- <code>(y)</code> but evaluates <code>x</code>
- only once. The <i>op</i><code>=</code> construct is a single token.
- In assignment operations, both the left- and right-hand expression lists
- must contain exactly one single-valued expression, and the left-hand
- expression must not be the blank identifier.
- </p>
- <pre>
- a[i] <<= 2
- i &^= 1<<n
- </pre>
- <p>
- A tuple assignment assigns the individual elements of a multi-valued
- operation to a list of variables. There are two forms. In the
- first, the right hand operand is a single multi-valued expression
- such as a function call, a <a href="#Channel_types">channel</a> or
- <a href="#Map_types">map</a> operation, or a <a href="#Type_assertions">type assertion</a>.
- The number of operands on the left
- hand side must match the number of values. For instance, if
- <code>f</code> is a function returning two values,
- </p>
- <pre>
- x, y = f()
- </pre>
- <p>
- assigns the first value to <code>x</code> and the second to <code>y</code>.
- In the second form, the number of operands on the left must equal the number
- of expressions on the right, each of which must be single-valued, and the
- <i>n</i>th expression on the right is assigned to the <i>n</i>th
- operand on the left:
- </p>
- <pre>
- one, two, three = '一', '二', '三'
- </pre>
- <p>
- The <a href="#Blank_identifier">blank identifier</a> provides a way to
- ignore right-hand side values in an assignment:
- </p>
- <pre>
- _ = x // evaluate x but ignore it
- x, _ = f() // evaluate f() but ignore second result value
- </pre>
- <p>
- The assignment proceeds in two phases.
- First, the operands of <a href="#Index_expressions">index expressions</a>
- and <a href="#Address_operators">pointer indirections</a>
- (including implicit pointer indirections in <a href="#Selectors">selectors</a>)
- on the left and the expressions on the right are all
- <a href="#Order_of_evaluation">evaluated in the usual order</a>.
- Second, the assignments are carried out in left-to-right order.
- </p>
- <pre>
- a, b = b, a // exchange a and b
- x := []int{1, 2, 3}
- i := 0
- i, x[i] = 1, 2 // set i = 1, x[0] = 2
- i = 0
- x[i], i = 2, 1 // set x[0] = 2, i = 1
- x[0], x[0] = 1, 2 // set x[0] = 1, then x[0] = 2 (so x[0] == 2 at end)
- x[1], x[3] = 4, 5 // set x[1] = 4, then panic setting x[3] = 5.
- type Point struct { x, y int }
- var p *Point
- x[2], p.x = 6, 7 // set x[2] = 6, then panic setting p.x = 7
- i = 2
- x = []int{3, 5, 7}
- for i, x[i] = range x { // set i, x[2] = 0, x[0]
- break
- }
- // after this loop, i == 0 and x is []int{3, 5, 3}
- </pre>
- <p>
- In assignments, each value must be <a href="#Assignability">assignable</a>
- to the type of the operand to which it is assigned, with the following special cases:
- </p>
- <ol>
- <li>
- Any typed value may be assigned to the blank identifier.
- </li>
- <li>
- If an untyped constant
- is assigned to a variable of interface type or the blank identifier,
- the constant is first implicitly <a href="#Conversions">converted</a> to its
- <a href="#Constants">default type</a>.
- </li>
- <li>
- If an untyped boolean value is assigned to a variable of interface type or
- the blank identifier, it is first implicitly converted to type <code>bool</code>.
- </li>
- </ol>
- <h3 id="If_statements">If statements</h3>
- <p>
- "If" statements specify the conditional execution of two branches
- according to the value of a boolean expression. If the expression
- evaluates to true, the "if" branch is executed, otherwise, if
- present, the "else" branch is executed.
- </p>
- <pre class="ebnf">
- IfStmt = "if" [ SimpleStmt ";" ] Expression Block [ "else" ( IfStmt | Block ) ] .
- </pre>
- <pre>
- if x > max {
- x = max
- }
- </pre>
- <p>
- The expression may be preceded by a simple statement, which
- executes before the expression is evaluated.
- </p>
- <pre>
- if x := f(); x < y {
- return x
- } else if x > z {
- return z
- } else {
- return y
- }
- </pre>
- <h3 id="Switch_statements">Switch statements</h3>
- <p>
- "Switch" statements provide multi-way execution.
- An expression or type is compared to the "cases"
- inside the "switch" to determine which branch
- to execute.
- </p>
- <pre class="ebnf">
- SwitchStmt = ExprSwitchStmt | TypeSwitchStmt .
- </pre>
- <p>
- There are two forms: expression switches and type switches.
- In an expression switch, the cases contain expressions that are compared
- against the value of the switch expression.
- In a type switch, the cases contain types that are compared against the
- type of a specially annotated switch expression.
- The switch expression is evaluated exactly once in a switch statement.
- </p>
- <h4 id="Expression_switches">Expression switches</h4>
- <p>
- In an expression switch,
- the switch expression is evaluated and
- the case expressions, which need not be constants,
- are evaluated left-to-right and top-to-bottom; the first one that equals the
- switch expression
- triggers execution of the statements of the associated case;
- the other cases are skipped.
- If no case matches and there is a "default" case,
- its statements are executed.
- There can be at most one default case and it may appear anywhere in the
- "switch" statement.
- A missing switch expression is equivalent to the boolean value
- <code>true</code>.
- </p>
- <pre class="ebnf">
- ExprSwitchStmt = "switch" [ SimpleStmt ";" ] [ Expression ] "{" { ExprCaseClause } "}" .
- ExprCaseClause = ExprSwitchCase ":" StatementList .
- ExprSwitchCase = "case" ExpressionList | "default" .
- </pre>
- <p>
- If the switch expression evaluates to an untyped constant, it is first implicitly
- <a href="#Conversions">converted</a> to its <a href="#Constants">default type</a>.
- The predeclared untyped value <code>nil</code> cannot be used as a switch expression.
- The switch expression type must be <a href="#Comparison_operators">comparable</a>.
- </p>
- <p>
- If a case expression is untyped, it is first implicitly <a href="#Conversions">converted</a>
- to the type of the switch expression.
- For each (possibly converted) case expression <code>x</code> and the value <code>t</code>
- of the switch expression, <code>x == t</code> must be a valid <a href="#Comparison_operators">comparison</a>.
- </p>
- <p>
- In other words, the switch expression is treated as if it were used to declare and
- initialize a temporary variable <code>t</code> without explicit type; it is that
- value of <code>t</code> against which each case expression <code>x</code> is tested
- for equality.
- </p>
- <p>
- In a case or default clause, the last non-empty statement
- may be a (possibly <a href="#Labeled_statements">labeled</a>)
- <a href="#Fallthrough_statements">"fallthrough" statement</a> to
- indicate that control should flow from the end of this clause to
- the first statement of the next clause.
- Otherwise control flows to the end of the "switch" statement.
- A "fallthrough" statement may appear as the last statement of all
- but the last clause of an expression switch.
- </p>
- <p>
- The switch expression may be preceded by a simple statement, which
- executes before the expression is evaluated.
- </p>
- <pre>
- switch tag {
- default: s3()
- case 0, 1, 2, 3: s1()
- case 4, 5, 6, 7: s2()
- }
- switch x := f(); { // missing switch expression means "true"
- case x < 0: return -x
- default: return x
- }
- switch {
- case x < y: f1()
- case x < z: f2()
- case x == 4: f3()
- }
- </pre>
- <p>
- Implementation restriction: A compiler may disallow multiple case
- expressions evaluating to the same constant.
- For instance, the current compilers disallow duplicate integer,
- floating point, or string constants in case expressions.
- </p>
- <h4 id="Type_switches">Type switches</h4>
- <p>
- A type switch compares types rather than values. It is otherwise similar
- to an expression switch. It is marked by a special switch expression that
- has the form of a <a href="#Type_assertions">type assertion</a>
- using the keyword <code>type</code> rather than an actual type:
- </p>
- <pre>
- switch x.(type) {
- // cases
- }
- </pre>
- <p>
- Cases then match actual types <code>T</code> against the dynamic type of the
- expression <code>x</code>. As with type assertions, <code>x</code> must be of
- <a href="#Interface_types">interface type</a>, but not a
- <a href="#Type_parameter_declarations">type parameter</a>, and each non-interface type
- <code>T</code> listed in a case must implement the type of <code>x</code>.
- The types listed in the cases of a type switch must all be
- <a href="#Type_identity">different</a>.
- </p>
- <pre class="ebnf">
- TypeSwitchStmt = "switch" [ SimpleStmt ";" ] TypeSwitchGuard "{" { TypeCaseClause } "}" .
- TypeSwitchGuard = [ identifier ":=" ] PrimaryExpr "." "(" "type" ")" .
- TypeCaseClause = TypeSwitchCase ":" StatementList .
- TypeSwitchCase = "case" TypeList | "default" .
- </pre>
- <p>
- The TypeSwitchGuard may include a
- <a href="#Short_variable_declarations">short variable declaration</a>.
- When that form is used, the variable is declared at the end of the
- TypeSwitchCase in the <a href="#Blocks">implicit block</a> of each clause.
- In clauses with a case listing exactly one type, the variable
- has that type; otherwise, the variable has the type of the expression
- in the TypeSwitchGuard.
- </p>
- <p>
- Instead of a type, a case may use the predeclared identifier
- <a href="#Predeclared_identifiers"><code>nil</code></a>;
- that case is selected when the expression in the TypeSwitchGuard
- is a <code>nil</code> interface value.
- There may be at most one <code>nil</code> case.
- </p>
- <p>
- Given an expression <code>x</code> of type <code>interface{}</code>,
- the following type switch:
- </p>
- <pre>
- switch i := x.(type) {
- case nil:
- printString("x is nil") // type of i is type of x (interface{})
- case int:
- printInt(i) // type of i is int
- case float64:
- printFloat64(i) // type of i is float64
- case func(int) float64:
- printFunction(i) // type of i is func(int) float64
- case bool, string:
- printString("type is bool or string") // type of i is type of x (interface{})
- default:
- printString("don't know the type") // type of i is type of x (interface{})
- }
- </pre>
- <p>
- could be rewritten:
- </p>
- <pre>
- v := x // x is evaluated exactly once
- if v == nil {
- i := v // type of i is type of x (interface{})
- printString("x is nil")
- } else if i, isInt := v.(int); isInt {
- printInt(i) // type of i is int
- } else if i, isFloat64 := v.(float64); isFloat64 {
- printFloat64(i) // type of i is float64
- } else if i, isFunc := v.(func(int) float64); isFunc {
- printFunction(i) // type of i is func(int) float64
- } else {
- _, isBool := v.(bool)
- _, isString := v.(string)
- if isBool || isString {
- i := v // type of i is type of x (interface{})
- printString("type is bool or string")
- } else {
- i := v // type of i is type of x (interface{})
- printString("don't know the type")
- }
- }
- </pre>
- <p>
- A <a href="#Type_parameter_declarations">type parameter</a> or a <a href="#Type_declarations">generic type</a>
- may be used as a type in a case. If upon <a href="#Instantiations">instantiation</a> that type turns
- out to duplicate another entry in the switch, the first matching case is chosen.
- </p>
- <pre>
- func f[P any](x any) int {
- switch x.(type) {
- case P:
- return 0
- case string:
- return 1
- case []P:
- return 2
- case []byte:
- return 3
- default:
- return 4
- }
- }
- var v1 = f[string]("foo") // v1 == 0
- var v2 = f[byte]([]byte{}) // v2 == 2
- </pre>
- <p>
- The type switch guard may be preceded by a simple statement, which
- executes before the guard is evaluated.
- </p>
- <p>
- The "fallthrough" statement is not permitted in a type switch.
- </p>
- <h3 id="For_statements">For statements</h3>
- <p>
- A "for" statement specifies repeated execution of a block. There are three forms:
- The iteration may be controlled by a single condition, a "for" clause, or a "range" clause.
- </p>
- <pre class="ebnf">
- ForStmt = "for" [ Condition | ForClause | RangeClause ] Block .
- Condition = Expression .
- </pre>
- <h4 id="For_condition">For statements with single condition</h4>
- <p>
- In its simplest form, a "for" statement specifies the repeated execution of
- a block as long as a boolean condition evaluates to true.
- The condition is evaluated before each iteration.
- If the condition is absent, it is equivalent to the boolean value
- <code>true</code>.
- </p>
- <pre>
- for a < b {
- a *= 2
- }
- </pre>
- <h4 id="For_clause">For statements with <code>for</code> clause</h4>
- <p>
- A "for" statement with a ForClause is also controlled by its condition, but
- additionally it may specify an <i>init</i>
- and a <i>post</i> statement, such as an assignment,
- an increment or decrement statement. The init statement may be a
- <a href="#Short_variable_declarations">short variable declaration</a>, but the post statement must not.
- </p>
- <pre class="ebnf">
- ForClause = [ InitStmt ] ";" [ Condition ] ";" [ PostStmt ] .
- InitStmt = SimpleStmt .
- PostStmt = SimpleStmt .
- </pre>
- <pre>
- for i := 0; i < 10; i++ {
- f(i)
- }
- </pre>
- <p>
- If non-empty, the init statement is executed once before evaluating the
- condition for the first iteration;
- the post statement is executed after each execution of the block (and
- only if the block was executed).
- Any element of the ForClause may be empty but the
- <a href="#Semicolons">semicolons</a> are
- required unless there is only a condition.
- If the condition is absent, it is equivalent to the boolean value
- <code>true</code>.
- </p>
- <pre>
- for cond { S() } is the same as for ; cond ; { S() }
- for { S() } is the same as for true { S() }
- </pre>
- <p>
- Each iteration has its own separate declared variable (or variables)
- [<a href="#Go_1.22">Go 1.22</a>].
- The variable used by the first iteration is declared by the init statement.
- The variable used by each subsequent iteration is declared implicitly before
- executing the post statement and initialized to the value of the previous
- iteration's variable at that moment.
- </p>
- <pre>
- var prints []func()
- for i := 0; i < 5; i++ {
- prints = append(prints, func() { println(i) })
- i++
- }
- for _, p := range prints {
- p()
- }
- </pre>
- <p>
- prints
- </p>
- <pre>
- 1
- 3
- 5
- </pre>
- <p>
- Prior to [<a href="#Go_1.22">Go 1.22</a>], iterations share one set of variables
- instead of having their own separate variables.
- In that case, the example above prints
- </p>
- <pre>
- 6
- 6
- 6
- </pre>
- <h4 id="For_range">For statements with <code>range</code> clause</h4>
- <p>
- A "for" statement with a "range" clause
- iterates through all entries of an array, slice, string or map, values received on
- a channel, integer values from zero to an upper limit [<a href="#Go_1.22">Go 1.22</a>],
- or values passed to an iterator function's yield function [<a href="#Go_1.23">Go 1.23</a>].
- For each entry it assigns <i>iteration values</i>
- to corresponding <i>iteration variables</i> if present and then executes the block.
- </p>
- <pre class="ebnf">
- RangeClause = [ ExpressionList "=" | IdentifierList ":=" ] "range" Expression .
- </pre>
- <p>
- The expression on the right in the "range" clause is called the <i>range expression</i>,
- its <a href="#Core_types">core type</a> must be
- an array, pointer to an array, slice, string, map, channel permitting
- <a href="#Receive_operator">receive operations</a>, an integer, or
- a function with specific signature (see below).
- As with an assignment, if present the operands on the left must be
- <a href="#Address_operators">addressable</a> or map index expressions; they
- denote the iteration variables.
- If the range expression is a function, the maximum number of iteration variables depends on
- the function signature.
- If the range expression is a channel or integer, at most one iteration variable is permitted;
- otherwise there may be up to two.
- If the last iteration variable is the <a href="#Blank_identifier">blank identifier</a>,
- the range clause is equivalent to the same clause without that identifier.
- </p>
- <p>
- The range expression <code>x</code> is evaluated before beginning the loop,
- with one exception: if at most one iteration variable is present and <code>x</code> or
- <a href="#Length_and_capacity"><code>len(x)</code></a> is <a href="#Constants">constant</a>,
- the range expression is not evaluated.
- </p>
- <p>
- Function calls on the left are evaluated once per iteration.
- For each iteration, iteration values are produced as follows
- if the respective iteration variables are present:
- </p>
- <pre class="grammar">
- Range expression 1st value 2nd value
- array or slice a [n]E, *[n]E, or []E index i int a[i] E
- string s string type index i int see below rune
- map m map[K]V key k K m[k] V
- channel c chan E, <-chan E element e E
- integer value n integer type, or untyped int value i see below
- function, 0 values f func(func() bool)
- function, 1 value f func(func(V) bool) value v V
- function, 2 values f func(func(K, V) bool) key k K v V
- </pre>
- <ol>
- <li>
- For an array, pointer to array, or slice value <code>a</code>, the index iteration
- values are produced in increasing order, starting at element index 0.
- If at most one iteration variable is present, the range loop produces
- iteration values from 0 up to <code>len(a)-1</code> and does not index into the array
- or slice itself. For a <code>nil</code> slice, the number of iterations is 0.
- </li>
- <li>
- For a string value, the "range" clause iterates over the Unicode code points
- in the string starting at byte index 0. On successive iterations, the index value will be the
- index of the first byte of successive UTF-8-encoded code points in the string,
- and the second value, of type <code>rune</code>, will be the value of
- the corresponding code point. If the iteration encounters an invalid
- UTF-8 sequence, the second value will be <code>0xFFFD</code>,
- the Unicode replacement character, and the next iteration will advance
- a single byte in the string.
- </li>
- <li>
- The iteration order over maps is not specified
- and is not guaranteed to be the same from one iteration to the next.
- If a map entry that has not yet been reached is removed during iteration,
- the corresponding iteration value will not be produced. If a map entry is
- created during iteration, that entry may be produced during the iteration or
- may be skipped. The choice may vary for each entry created and from one
- iteration to the next.
- If the map is <code>nil</code>, the number of iterations is 0.
- </li>
- <li>
- For channels, the iteration values produced are the successive values sent on
- the channel until the channel is <a href="#Close">closed</a>. If the channel
- is <code>nil</code>, the range expression blocks forever.
- </li>
- <li>
- For an integer value <code>n</code>, where <code>n</code> is of <a href="#Numeric_types">integer type</a>
- or an untyped <a href="#Constants">integer constant</a>, the iteration values 0 through <code>n-1</code>
- are produced in increasing order.
- If <code>n</code> is of integer type, the iteration values have that same type.
- Otherwise, the type of <code>n</code> is determined as if it were assigned to the
- iteration variable.
- Specifically:
- if the iteration variable is preexisting, the type of the iteration values is the type of the iteration
- variable, which must be of integer type.
- Otherwise, if the iteration variable is declared by the "range" clause or is absent,
- the type of the iteration values is the <a href="#Constants">default type</a> for <code>n</code>.
- If <code>n</code> <= 0, the loop does not run any iterations.
- </li>
- <li>
- For a function <code>f</code>, the iteration proceeds by calling <code>f</code>
- with a new, synthesized <code>yield</code> function as its argument.
- If <code>yield</code> is called before <code>f</code> returns,
- the arguments to <code>yield</code> become the iteration values
- for executing the loop body once.
- After each successive loop iteration, <code>yield</code> returns true
- and may be called again to continue the loop.
- As long as the loop body does not terminate, the "range" clause will continue
- to generate iteration values this way for each <code>yield</code> call until
- <code>f</code> returns.
- If the loop body terminates (such as by a <code>break</code> statement),
- <code>yield</code> returns false and must not be called again.
- </li>
- </ol>
- <p>
- The iteration variables may be declared by the "range" clause using a form of
- <a href="#Short_variable_declarations">short variable declaration</a>
- (<code>:=</code>).
- In this case their <a href="#Declarations_and_scope">scope</a> is the block of the "for" statement
- and each iteration has its own new variables [<a href="#Go_1.22">Go 1.22</a>]
- (see also <a href="#For_clause">"for" statements with a ForClause</a>).
- The variables have the types of their respective iteration values.
- </p>
- <p>
- If the iteration variables are not explicitly declared by the "range" clause,
- they must be preexisting.
- In this case, the iteration values are assigned to the respective variables
- as in an <a href="#Assignment_statements">assignment statement</a>.
- </p>
- <pre>
- var testdata *struct {
- a *[7]int
- }
- for i, _ := range testdata.a {
- // testdata.a is never evaluated; len(testdata.a) is constant
- // i ranges from 0 to 6
- f(i)
- }
- var a [10]string
- for i, s := range a {
- // type of i is int
- // type of s is string
- // s == a[i]
- g(i, s)
- }
- var key string
- var val interface{} // element type of m is assignable to val
- m := map[string]int{"mon":0, "tue":1, "wed":2, "thu":3, "fri":4, "sat":5, "sun":6}
- for key, val = range m {
- h(key, val)
- }
- // key == last map key encountered in iteration
- // val == map[key]
- var ch chan Work = producer()
- for w := range ch {
- doWork(w)
- }
- // empty a channel
- for range ch {}
- // call f(0), f(1), ... f(9)
- for i := range 10 {
- // type of i is int (default type for untyped constant 10)
- f(i)
- }
- // invalid: 256 cannot be assigned to uint8
- var u uint8
- for u = range 256 {
- }
- // invalid: 1e3 is a floating-point constant
- for range 1e3 {
- }
- // fibo generates the Fibonacci sequence
- fibo := func(yield func(x int) bool) {
- f0, f1 := 0, 1
- for yield(f0) {
- f0, f1 = f1, f0+f1
- }
- }
- // print the Fibonacci numbers below 1000:
- for x := range fibo {
- if x >= 1000 {
- break
- }
- fmt.Printf("%d ", x)
- }
- // output: 0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987
- // iteration support for a recursive tree data structure
- type Tree[K cmp.Ordered, V any] struct {
- left, right *Tree[K, V]
- key K
- value V
- }
- func (t *Tree[K, V]) walk(yield func(key K, val V) bool) bool {
- return t == nil || t.left.walk(yield) && yield(t.key, t.value) && t.right.walk(yield)
- }
- func (t *Tree[K, V]) Walk(yield func(key K, val V) bool) {
- t.walk(yield)
- }
- // walk tree t in-order
- var t Tree[string, int]
- for k, v := range t.Walk {
- // process k, v
- }
- </pre>
- <h3 id="Go_statements">Go statements</h3>
- <p>
- A "go" statement starts the execution of a function call
- as an independent concurrent thread of control, or <i>goroutine</i>,
- within the same address space.
- </p>
- <pre class="ebnf">
- GoStmt = "go" Expression .
- </pre>
- <p>
- The expression must be a function or method call; it cannot be parenthesized.
- Calls of built-in functions are restricted as for
- <a href="#Expression_statements">expression statements</a>.
- </p>
- <p>
- The function value and parameters are
- <a href="#Calls">evaluated as usual</a>
- in the calling goroutine, but
- unlike with a regular call, program execution does not wait
- for the invoked function to complete.
- Instead, the function begins executing independently
- in a new goroutine.
- When the function terminates, its goroutine also terminates.
- If the function has any return values, they are discarded when the
- function completes.
- </p>
- <pre>
- go Server()
- go func(ch chan<- bool) { for { sleep(10); ch <- true }} (c)
- </pre>
- <h3 id="Select_statements">Select statements</h3>
- <p>
- A "select" statement chooses which of a set of possible
- <a href="#Send_statements">send</a> or
- <a href="#Receive_operator">receive</a>
- operations will proceed.
- It looks similar to a
- <a href="#Switch_statements">"switch"</a> statement but with the
- cases all referring to communication operations.
- </p>
- <pre class="ebnf">
- SelectStmt = "select" "{" { CommClause } "}" .
- CommClause = CommCase ":" StatementList .
- CommCase = "case" ( SendStmt | RecvStmt ) | "default" .
- RecvStmt = [ ExpressionList "=" | IdentifierList ":=" ] RecvExpr .
- RecvExpr = Expression .
- </pre>
- <p>
- A case with a RecvStmt may assign the result of a RecvExpr to one or
- two variables, which may be declared using a
- <a href="#Short_variable_declarations">short variable declaration</a>.
- The RecvExpr must be a (possibly parenthesized) receive operation.
- There can be at most one default case and it may appear anywhere
- in the list of cases.
- </p>
- <p>
- Execution of a "select" statement proceeds in several steps:
- </p>
- <ol>
- <li>
- For all the cases in the statement, the channel operands of receive operations
- and the channel and right-hand-side expressions of send statements are
- evaluated exactly once, in source order, upon entering the "select" statement.
- The result is a set of channels to receive from or send to,
- and the corresponding values to send.
- Any side effects in that evaluation will occur irrespective of which (if any)
- communication operation is selected to proceed.
- Expressions on the left-hand side of a RecvStmt with a short variable declaration
- or assignment are not yet evaluated.
- </li>
- <li>
- If one or more of the communications can proceed,
- a single one that can proceed is chosen via a uniform pseudo-random selection.
- Otherwise, if there is a default case, that case is chosen.
- If there is no default case, the "select" statement blocks until
- at least one of the communications can proceed.
- </li>
- <li>
- Unless the selected case is the default case, the respective communication
- operation is executed.
- </li>
- <li>
- If the selected case is a RecvStmt with a short variable declaration or
- an assignment, the left-hand side expressions are evaluated and the
- received value (or values) are assigned.
- </li>
- <li>
- The statement list of the selected case is executed.
- </li>
- </ol>
- <p>
- Since communication on <code>nil</code> channels can never proceed,
- a select with only <code>nil</code> channels and no default case blocks forever.
- </p>
- <pre>
- var a []int
- var c, c1, c2, c3, c4 chan int
- var i1, i2 int
- select {
- case i1 = <-c1:
- print("received ", i1, " from c1\n")
- case c2 <- i2:
- print("sent ", i2, " to c2\n")
- case i3, ok := (<-c3): // same as: i3, ok := <-c3
- if ok {
- print("received ", i3, " from c3\n")
- } else {
- print("c3 is closed\n")
- }
- case a[f()] = <-c4:
- // same as:
- // case t := <-c4
- // a[f()] = t
- default:
- print("no communication\n")
- }
- for { // send random sequence of bits to c
- select {
- case c <- 0: // note: no statement, no fallthrough, no folding of cases
- case c <- 1:
- }
- }
- select {} // block forever
- </pre>
- <h3 id="Return_statements">Return statements</h3>
- <p>
- A "return" statement in a function <code>F</code> terminates the execution
- of <code>F</code>, and optionally provides one or more result values.
- Any functions <a href="#Defer_statements">deferred</a> by <code>F</code>
- are executed before <code>F</code> returns to its caller.
- </p>
- <pre class="ebnf">
- ReturnStmt = "return" [ ExpressionList ] .
- </pre>
- <p>
- In a function without a result type, a "return" statement must not
- specify any result values.
- </p>
- <pre>
- func noResult() {
- return
- }
- </pre>
- <p>
- There are three ways to return values from a function with a result
- type:
- </p>
- <ol>
- <li>The return value or values may be explicitly listed
- in the "return" statement. Each expression must be single-valued
- and <a href="#Assignability">assignable</a>
- to the corresponding element of the function's result type.
- <pre>
- func simpleF() int {
- return 2
- }
- func complexF1() (re float64, im float64) {
- return -7.0, -4.0
- }
- </pre>
- </li>
- <li>The expression list in the "return" statement may be a single
- call to a multi-valued function. The effect is as if each value
- returned from that function were assigned to a temporary
- variable with the type of the respective value, followed by a
- "return" statement listing these variables, at which point the
- rules of the previous case apply.
- <pre>
- func complexF2() (re float64, im float64) {
- return complexF1()
- }
- </pre>
- </li>
- <li>The expression list may be empty if the function's result
- type specifies names for its <a href="#Function_types">result parameters</a>.
- The result parameters act as ordinary local variables
- and the function may assign values to them as necessary.
- The "return" statement returns the values of these variables.
- <pre>
- func complexF3() (re float64, im float64) {
- re = 7.0
- im = 4.0
- return
- }
- func (devnull) Write(p []byte) (n int, _ error) {
- n = len(p)
- return
- }
- </pre>
- </li>
- </ol>
- <p>
- Regardless of how they are declared, all the result values are initialized to
- the <a href="#The_zero_value">zero values</a> for their type upon entry to the
- function. A "return" statement that specifies results sets the result parameters before
- any deferred functions are executed.
- </p>
- <p>
- Implementation restriction: A compiler may disallow an empty expression list
- in a "return" statement if a different entity (constant, type, or variable)
- with the same name as a result parameter is in
- <a href="#Declarations_and_scope">scope</a> at the place of the return.
- </p>
- <pre>
- func f(n int) (res int, err error) {
- if _, err := f(n-1); err != nil {
- return // invalid return statement: err is shadowed
- }
- return
- }
- </pre>
- <h3 id="Break_statements">Break statements</h3>
- <p>
- A "break" statement terminates execution of the innermost
- <a href="#For_statements">"for"</a>,
- <a href="#Switch_statements">"switch"</a>, or
- <a href="#Select_statements">"select"</a> statement
- within the same function.
- </p>
- <pre class="ebnf">
- BreakStmt = "break" [ Label ] .
- </pre>
- <p>
- If there is a label, it must be that of an enclosing
- "for", "switch", or "select" statement,
- and that is the one whose execution terminates.
- </p>
- <pre>
- OuterLoop:
- for i = 0; i < n; i++ {
- for j = 0; j < m; j++ {
- switch a[i][j] {
- case nil:
- state = Error
- break OuterLoop
- case item:
- state = Found
- break OuterLoop
- }
- }
- }
- </pre>
- <h3 id="Continue_statements">Continue statements</h3>
- <p>
- A "continue" statement begins the next iteration of the
- innermost enclosing <a href="#For_statements">"for" loop</a>
- by advancing control to the end of the loop block.
- The "for" loop must be within the same function.
- </p>
- <pre class="ebnf">
- ContinueStmt = "continue" [ Label ] .
- </pre>
- <p>
- If there is a label, it must be that of an enclosing
- "for" statement, and that is the one whose execution
- advances.
- </p>
- <pre>
- RowLoop:
- for y, row := range rows {
- for x, data := range row {
- if data == endOfRow {
- continue RowLoop
- }
- row[x] = data + bias(x, y)
- }
- }
- </pre>
- <h3 id="Goto_statements">Goto statements</h3>
- <p>
- A "goto" statement transfers control to the statement with the corresponding label
- within the same function.
- </p>
- <pre class="ebnf">
- GotoStmt = "goto" Label .
- </pre>
- <pre>
- goto Error
- </pre>
- <p>
- Executing the "goto" statement must not cause any variables to come into
- <a href="#Declarations_and_scope">scope</a> that were not already in scope at the point of the goto.
- For instance, this example:
- </p>
- <pre>
- goto L // BAD
- v := 3
- L:
- </pre>
- <p>
- is erroneous because the jump to label <code>L</code> skips
- the creation of <code>v</code>.
- </p>
- <p>
- A "goto" statement outside a <a href="#Blocks">block</a> cannot jump to a label inside that block.
- For instance, this example:
- </p>
- <pre>
- if n%2 == 1 {
- goto L1
- }
- for n > 0 {
- f()
- n--
- L1:
- f()
- n--
- }
- </pre>
- <p>
- is erroneous because the label <code>L1</code> is inside
- the "for" statement's block but the <code>goto</code> is not.
- </p>
- <h3 id="Fallthrough_statements">Fallthrough statements</h3>
- <p>
- A "fallthrough" statement transfers control to the first statement of the
- next case clause in an <a href="#Expression_switches">expression "switch" statement</a>.
- It may be used only as the final non-empty statement in such a clause.
- </p>
- <pre class="ebnf">
- FallthroughStmt = "fallthrough" .
- </pre>
- <h3 id="Defer_statements">Defer statements</h3>
- <p>
- A "defer" statement invokes a function whose execution is deferred
- to the moment the surrounding function returns, either because the
- surrounding function executed a <a href="#Return_statements">return statement</a>,
- reached the end of its <a href="#Function_declarations">function body</a>,
- or because the corresponding goroutine is <a href="#Handling_panics">panicking</a>.
- </p>
- <pre class="ebnf">
- DeferStmt = "defer" Expression .
- </pre>
- <p>
- The expression must be a function or method call; it cannot be parenthesized.
- Calls of built-in functions are restricted as for
- <a href="#Expression_statements">expression statements</a>.
- </p>
- <p>
- Each time a "defer" statement
- executes, the function value and parameters to the call are
- <a href="#Calls">evaluated as usual</a>
- and saved anew but the actual function is not invoked.
- Instead, deferred functions are invoked immediately before
- the surrounding function returns, in the reverse order
- they were deferred. That is, if the surrounding function
- returns through an explicit <a href="#Return_statements">return statement</a>,
- deferred functions are executed <i>after</i> any result parameters are set
- by that return statement but <i>before</i> the function returns to its caller.
- If a deferred function value evaluates
- to <code>nil</code>, execution <a href="#Handling_panics">panics</a>
- when the function is invoked, not when the "defer" statement is executed.
- </p>
- <p>
- For instance, if the deferred function is
- a <a href="#Function_literals">function literal</a> and the surrounding
- function has <a href="#Function_types">named result parameters</a> that
- are in scope within the literal, the deferred function may access and modify
- the result parameters before they are returned.
- If the deferred function has any return values, they are discarded when
- the function completes.
- (See also the section on <a href="#Handling_panics">handling panics</a>.)
- </p>
- <pre>
- lock(l)
- defer unlock(l) // unlocking happens before surrounding function returns
- // prints 3 2 1 0 before surrounding function returns
- for i := 0; i <= 3; i++ {
- defer fmt.Print(i)
- }
- // f returns 42
- func f() (result int) {
- defer func() {
- // result is accessed after it was set to 6 by the return statement
- result *= 7
- }()
- return 6
- }
- </pre>
- <h2 id="Built-in_functions">Built-in functions</h2>
- <p>
- Built-in functions are
- <a href="#Predeclared_identifiers">predeclared</a>.
- They are called like any other function but some of them
- accept a type instead of an expression as the first argument.
- </p>
- <p>
- The built-in functions do not have standard Go types,
- so they can only appear in <a href="#Calls">call expressions</a>;
- they cannot be used as function values.
- </p>
- <h3 id="Appending_and_copying_slices">Appending to and copying slices</h3>
- <p>
- The built-in functions <code>append</code> and <code>copy</code> assist in
- common slice operations.
- For both functions, the result is independent of whether the memory referenced
- by the arguments overlaps.
- </p>
- <p>
- The <a href="#Function_types">variadic</a> function <code>append</code>
- appends zero or more values <code>x</code> to a slice <code>s</code>
- and returns the resulting slice of the same type as <code>s</code>.
- The <a href="#Core_types">core type</a> of <code>s</code> must be a slice
- of type <code>[]E</code>.
- The values <code>x</code> are passed to a parameter of type <code>...E</code>
- and the respective <a href="#Passing_arguments_to_..._parameters">parameter
- passing rules</a> apply.
- As a special case, if the core type of <code>s</code> is <code>[]byte</code>,
- <code>append</code> also accepts a second argument with core type
- <a href="#Core_types"><code>bytestring</code></a> followed by <code>...</code>.
- This form appends the bytes of the byte slice or string.
- </p>
- <pre class="grammar">
- append(s S, x ...E) S // core type of S is []E
- </pre>
- <p>
- If the capacity of <code>s</code> is not large enough to fit the additional
- values, <code>append</code> <a href="#Allocation">allocates</a> a new, sufficiently large underlying
- array that fits both the existing slice elements and the additional values.
- Otherwise, <code>append</code> re-uses the underlying array.
- </p>
- <pre>
- s0 := []int{0, 0}
- s1 := append(s0, 2) // append a single element s1 is []int{0, 0, 2}
- s2 := append(s1, 3, 5, 7) // append multiple elements s2 is []int{0, 0, 2, 3, 5, 7}
- s3 := append(s2, s0...) // append a slice s3 is []int{0, 0, 2, 3, 5, 7, 0, 0}
- s4 := append(s3[3:6], s3[2:]...) // append overlapping slice s4 is []int{3, 5, 7, 2, 3, 5, 7, 0, 0}
- var t []interface{}
- t = append(t, 42, 3.1415, "foo") // t is []interface{}{42, 3.1415, "foo"}
- var b []byte
- b = append(b, "bar"...) // append string contents b is []byte{'b', 'a', 'r' }
- </pre>
- <p>
- The function <code>copy</code> copies slice elements from
- a source <code>src</code> to a destination <code>dst</code> and returns the
- number of elements copied.
- The <a href="#Core_types">core types</a> of both arguments must be slices
- with <a href="#Type_identity">identical</a> element type.
- The number of elements copied is the minimum of
- <code>len(src)</code> and <code>len(dst)</code>.
- As a special case, if the destination's core type is <code>[]byte</code>,
- <code>copy</code> also accepts a source argument with core type
- <a href="#Core_types"><code>bytestring</code></a>.
- This form copies the bytes from the byte slice or string into the byte slice.
- </p>
- <pre class="grammar">
- copy(dst, src []T) int
- copy(dst []byte, src string) int
- </pre>
- <p>
- Examples:
- </p>
- <pre>
- var a = [...]int{0, 1, 2, 3, 4, 5, 6, 7}
- var s = make([]int, 6)
- var b = make([]byte, 5)
- n1 := copy(s, a[0:]) // n1 == 6, s is []int{0, 1, 2, 3, 4, 5}
- n2 := copy(s, s[2:]) // n2 == 4, s is []int{2, 3, 4, 5, 4, 5}
- n3 := copy(b, "Hello, World!") // n3 == 5, b is []byte("Hello")
- </pre>
- <h3 id="Clear">Clear</h3>
- <p>
- The built-in function <code>clear</code> takes an argument of <a href="#Map_types">map</a>,
- <a href="#Slice_types">slice</a>, or <a href="#Type_parameter_declarations">type parameter</a> type,
- and deletes or zeroes out all elements
- [<a href="#Go_1.21">Go 1.21</a>].
- </p>
- <pre class="grammar">
- Call Argument type Result
- clear(m) map[K]T deletes all entries, resulting in an
- empty map (len(m) == 0)
- clear(s) []T sets all elements up to the length of
- <code>s</code> to the zero value of T
- clear(t) type parameter see below
- </pre>
- <p>
- If the type of the argument to <code>clear</code> is a
- <a href="#Type_parameter_declarations">type parameter</a>,
- all types in its type set must be maps or slices, and <code>clear</code>
- performs the operation corresponding to the actual type argument.
- </p>
- <p>
- If the map or slice is <code>nil</code>, <code>clear</code> is a no-op.
- </p>
- <h3 id="Close">Close</h3>
- <p>
- For an argument <code>ch</code> with a <a href="#Core_types">core type</a>
- that is a <a href="#Channel_types">channel</a>, the built-in function <code>close</code>
- records that no more values will be sent on the channel.
- It is an error if <code>ch</code> is a receive-only channel.
- Sending to or closing a closed channel causes a <a href="#Run_time_panics">run-time panic</a>.
- Closing the nil channel also causes a <a href="#Run_time_panics">run-time panic</a>.
- After calling <code>close</code>, and after any previously
- sent values have been received, receive operations will return
- the zero value for the channel's type without blocking.
- The multi-valued <a href="#Receive_operator">receive operation</a>
- returns a received value along with an indication of whether the channel is closed.
- </p>
- <h3 id="Complex_numbers">Manipulating complex numbers</h3>
- <p>
- Three functions assemble and disassemble complex numbers.
- The built-in function <code>complex</code> constructs a complex
- value from a floating-point real and imaginary part, while
- <code>real</code> and <code>imag</code>
- extract the real and imaginary parts of a complex value.
- </p>
- <pre class="grammar">
- complex(realPart, imaginaryPart floatT) complexT
- real(complexT) floatT
- imag(complexT) floatT
- </pre>
- <p>
- The type of the arguments and return value correspond.
- For <code>complex</code>, the two arguments must be of the same
- <a href="#Numeric_types">floating-point type</a> and the return type is the
- <a href="#Numeric_types">complex type</a>
- with the corresponding floating-point constituents:
- <code>complex64</code> for <code>float32</code> arguments, and
- <code>complex128</code> for <code>float64</code> arguments.
- If one of the arguments evaluates to an untyped constant, it is first implicitly
- <a href="#Conversions">converted</a> to the type of the other argument.
- If both arguments evaluate to untyped constants, they must be non-complex
- numbers or their imaginary parts must be zero, and the return value of
- the function is an untyped complex constant.
- </p>
- <p>
- For <code>real</code> and <code>imag</code>, the argument must be
- of complex type, and the return type is the corresponding floating-point
- type: <code>float32</code> for a <code>complex64</code> argument, and
- <code>float64</code> for a <code>complex128</code> argument.
- If the argument evaluates to an untyped constant, it must be a number,
- and the return value of the function is an untyped floating-point constant.
- </p>
- <p>
- The <code>real</code> and <code>imag</code> functions together form the inverse of
- <code>complex</code>, so for a value <code>z</code> of a complex type <code>Z</code>,
- <code>z == Z(complex(real(z), imag(z)))</code>.
- </p>
- <p>
- If the operands of these functions are all constants, the return
- value is a constant.
- </p>
- <pre>
- var a = complex(2, -2) // complex128
- const b = complex(1.0, -1.4) // untyped complex constant 1 - 1.4i
- x := float32(math.Cos(math.Pi/2)) // float32
- var c64 = complex(5, -x) // complex64
- var s int = complex(1, 0) // untyped complex constant 1 + 0i can be converted to int
- _ = complex(1, 2<<s) // illegal: 2 assumes floating-point type, cannot shift
- var rl = real(c64) // float32
- var im = imag(a) // float64
- const c = imag(b) // untyped constant -1.4
- _ = imag(3 << s) // illegal: 3 assumes complex type, cannot shift
- </pre>
- <p>
- Arguments of type parameter type are not permitted.
- </p>
- <h3 id="Deletion_of_map_elements">Deletion of map elements</h3>
- <p>
- The built-in function <code>delete</code> removes the element with key
- <code>k</code> from a <a href="#Map_types">map</a> <code>m</code>. The
- value <code>k</code> must be <a href="#Assignability">assignable</a>
- to the key type of <code>m</code>.
- </p>
- <pre class="grammar">
- delete(m, k) // remove element m[k] from map m
- </pre>
- <p>
- If the type of <code>m</code> is a <a href="#Type_parameter_declarations">type parameter</a>,
- all types in that type set must be maps, and they must all have identical key types.
- </p>
- <p>
- If the map <code>m</code> is <code>nil</code> or the element <code>m[k]</code>
- does not exist, <code>delete</code> is a no-op.
- </p>
- <h3 id="Length_and_capacity">Length and capacity</h3>
- <p>
- The built-in functions <code>len</code> and <code>cap</code> take arguments
- of various types and return a result of type <code>int</code>.
- The implementation guarantees that the result always fits into an <code>int</code>.
- </p>
- <pre class="grammar">
- Call Argument type Result
- len(s) string type string length in bytes
- [n]T, *[n]T array length (== n)
- []T slice length
- map[K]T map length (number of defined keys)
- chan T number of elements queued in channel buffer
- type parameter see below
- cap(s) [n]T, *[n]T array length (== n)
- []T slice capacity
- chan T channel buffer capacity
- type parameter see below
- </pre>
- <p>
- If the argument type is a <a href="#Type_parameter_declarations">type parameter</a> <code>P</code>,
- the call <code>len(e)</code> (or <code>cap(e)</code> respectively) must be valid for
- each type in <code>P</code>'s type set.
- The result is the length (or capacity, respectively) of the argument whose type
- corresponds to the type argument with which <code>P</code> was
- <a href="#Instantiations">instantiated</a>.
- </p>
- <p>
- The capacity of a slice is the number of elements for which there is
- space allocated in the underlying array.
- At any time the following relationship holds:
- </p>
- <pre>
- 0 <= len(s) <= cap(s)
- </pre>
- <p>
- The length of a <code>nil</code> slice, map or channel is 0.
- The capacity of a <code>nil</code> slice or channel is 0.
- </p>
- <p>
- The expression <code>len(s)</code> is <a href="#Constants">constant</a> if
- <code>s</code> is a string constant. The expressions <code>len(s)</code> and
- <code>cap(s)</code> are constants if the type of <code>s</code> is an array
- or pointer to an array and the expression <code>s</code> does not contain
- <a href="#Receive_operator">channel receives</a> or (non-constant)
- <a href="#Calls">function calls</a>; in this case <code>s</code> is not evaluated.
- Otherwise, invocations of <code>len</code> and <code>cap</code> are not
- constant and <code>s</code> is evaluated.
- </p>
- <pre>
- const (
- c1 = imag(2i) // imag(2i) = 2.0 is a constant
- c2 = len([10]float64{2}) // [10]float64{2} contains no function calls
- c3 = len([10]float64{c1}) // [10]float64{c1} contains no function calls
- c4 = len([10]float64{imag(2i)}) // imag(2i) is a constant and no function call is issued
- c5 = len([10]float64{imag(z)}) // invalid: imag(z) is a (non-constant) function call
- )
- var z complex128
- </pre>
- <h3 id="Making_slices_maps_and_channels">Making slices, maps and channels</h3>
- <p>
- The built-in function <code>make</code> takes a type <code>T</code>,
- optionally followed by a type-specific list of expressions.
- The <a href="#Core_types">core type</a> of <code>T</code> must
- be a slice, map or channel.
- It returns a value of type <code>T</code> (not <code>*T</code>).
- The memory is initialized as described in the section on
- <a href="#The_zero_value">initial values</a>.
- </p>
- <pre class="grammar">
- Call Core type Result
- make(T, n) slice slice of type T with length n and capacity n
- make(T, n, m) slice slice of type T with length n and capacity m
- make(T) map map of type T
- make(T, n) map map of type T with initial space for approximately n elements
- make(T) channel unbuffered channel of type T
- make(T, n) channel buffered channel of type T, buffer size n
- </pre>
- <p>
- Each of the size arguments <code>n</code> and <code>m</code> must be of <a href="#Numeric_types">integer type</a>,
- have a <a href="#Interface_types">type set</a> containing only integer types,
- or be an untyped <a href="#Constants">constant</a>.
- A constant size argument must be non-negative and <a href="#Representability">representable</a>
- by a value of type <code>int</code>; if it is an untyped constant it is given type <code>int</code>.
- If both <code>n</code> and <code>m</code> are provided and are constant, then
- <code>n</code> must be no larger than <code>m</code>.
- For slices and channels, if <code>n</code> is negative or larger than <code>m</code> at run time,
- a <a href="#Run_time_panics">run-time panic</a> occurs.
- </p>
- <pre>
- s := make([]int, 10, 100) // slice with len(s) == 10, cap(s) == 100
- s := make([]int, 1e3) // slice with len(s) == cap(s) == 1000
- s := make([]int, 1<<63) // illegal: len(s) is not representable by a value of type int
- s := make([]int, 10, 0) // illegal: len(s) > cap(s)
- c := make(chan int, 10) // channel with a buffer size of 10
- m := make(map[string]int, 100) // map with initial space for approximately 100 elements
- </pre>
- <p>
- Calling <code>make</code> with a map type and size hint <code>n</code> will
- create a map with initial space to hold <code>n</code> map elements.
- The precise behavior is implementation-dependent.
- </p>
- <h3 id="Min_and_max">Min and max</h3>
- <p>
- The built-in functions <code>min</code> and <code>max</code> compute the
- smallest—or largest, respectively—value of a fixed number of
- arguments of <a href="#Comparison_operators">ordered types</a>.
- There must be at least one argument
- [<a href="#Go_1.21">Go 1.21</a>].
- </p>
- <p>
- The same type rules as for <a href="#Operators">operators</a> apply:
- for <a href="#Comparison_operators">ordered</a> arguments <code>x</code> and
- <code>y</code>, <code>min(x, y)</code> is valid if <code>x + y</code> is valid,
- and the type of <code>min(x, y)</code> is the type of <code>x + y</code>
- (and similarly for <code>max</code>).
- If all arguments are constant, the result is constant.
- </p>
- <pre>
- var x, y int
- m := min(x) // m == x
- m := min(x, y) // m is the smaller of x and y
- m := max(x, y, 10) // m is the larger of x and y but at least 10
- c := max(1, 2.0, 10) // c == 10.0 (floating-point kind)
- f := max(0, float32(x)) // type of f is float32
- var s []string
- _ = min(s...) // invalid: slice arguments are not permitted
- t := max("", "foo", "bar") // t == "foo" (string kind)
- </pre>
- <p>
- For numeric arguments, assuming all NaNs are equal, <code>min</code> and <code>max</code> are
- commutative and associative:
- </p>
- <pre>
- min(x, y) == min(y, x)
- min(x, y, z) == min(min(x, y), z) == min(x, min(y, z))
- </pre>
- <p>
- For floating-point arguments negative zero, NaN, and infinity the following rules apply:
- </p>
- <pre>
- x y min(x, y) max(x, y)
- -0.0 0.0 -0.0 0.0 // negative zero is smaller than (non-negative) zero
- -Inf y -Inf y // negative infinity is smaller than any other number
- +Inf y y +Inf // positive infinity is larger than any other number
- NaN y NaN NaN // if any argument is a NaN, the result is a NaN
- </pre>
- <p>
- For string arguments the result for <code>min</code> is the first argument
- with the smallest (or for <code>max</code>, largest) value,
- compared lexically byte-wise:
- </p>
- <pre>
- min(x, y) == if x <= y then x else y
- min(x, y, z) == min(min(x, y), z)
- </pre>
- <h3 id="Allocation">Allocation</h3>
- <p>
- The built-in function <code>new</code> takes a type <code>T</code>,
- allocates storage for a <a href="#Variables">variable</a> of that type
- at run time, and returns a value of type <code>*T</code>
- <a href="#Pointer_types">pointing</a> to it.
- The variable is initialized as described in the section on
- <a href="#The_zero_value">initial values</a>.
- </p>
- <pre class="grammar">
- new(T)
- </pre>
- <p>
- For instance
- </p>
- <pre>
- type S struct { a int; b float64 }
- new(S)
- </pre>
- <p>
- allocates storage for a variable of type <code>S</code>,
- initializes it (<code>a=0</code>, <code>b=0.0</code>),
- and returns a value of type <code>*S</code> containing the address
- of the location.
- </p>
- <h3 id="Handling_panics">Handling panics</h3>
- <p> Two built-in functions, <code>panic</code> and <code>recover</code>,
- assist in reporting and handling <a href="#Run_time_panics">run-time panics</a>
- and program-defined error conditions.
- </p>
- <pre class="grammar">
- func panic(interface{})
- func recover() interface{}
- </pre>
- <p>
- While executing a function <code>F</code>,
- an explicit call to <code>panic</code> or a <a href="#Run_time_panics">run-time panic</a>
- terminates the execution of <code>F</code>.
- Any functions <a href="#Defer_statements">deferred</a> by <code>F</code>
- are then executed as usual.
- Next, any deferred functions run by <code>F</code>'s caller are run,
- and so on up to any deferred by the top-level function in the executing goroutine.
- At that point, the program is terminated and the error
- condition is reported, including the value of the argument to <code>panic</code>.
- This termination sequence is called <i>panicking</i>.
- </p>
- <pre>
- panic(42)
- panic("unreachable")
- panic(Error("cannot parse"))
- </pre>
- <p>
- The <code>recover</code> function allows a program to manage behavior
- of a panicking goroutine.
- Suppose a function <code>G</code> defers a function <code>D</code> that calls
- <code>recover</code> and a panic occurs in a function on the same goroutine in which <code>G</code>
- is executing.
- When the running of deferred functions reaches <code>D</code>,
- the return value of <code>D</code>'s call to <code>recover</code> will be the value passed to the call of <code>panic</code>.
- If <code>D</code> returns normally, without starting a new
- <code>panic</code>, the panicking sequence stops. In that case,
- the state of functions called between <code>G</code> and the call to <code>panic</code>
- is discarded, and normal execution resumes.
- Any functions deferred by <code>G</code> before <code>D</code> are then run and <code>G</code>'s
- execution terminates by returning to its caller.
- </p>
- <p>
- The return value of <code>recover</code> is <code>nil</code> when the
- goroutine is not panicking or <code>recover</code> was not called directly by a deferred function.
- Conversely, if a goroutine is panicking and <code>recover</code> was called directly by a deferred function,
- the return value of <code>recover</code> is guaranteed not to be <code>nil</code>.
- To ensure this, calling <code>panic</code> with a <code>nil</code> interface value (or an untyped <code>nil</code>)
- causes a <a href="#Run_time_panics">run-time panic</a>.
- </p>
- <p>
- The <code>protect</code> function in the example below invokes
- the function argument <code>g</code> and protects callers from
- run-time panics raised by <code>g</code>.
- </p>
- <pre>
- func protect(g func()) {
- defer func() {
- log.Println("done") // Println executes normally even if there is a panic
- if x := recover(); x != nil {
- log.Printf("run time panic: %v", x)
- }
- }()
- log.Println("start")
- g()
- }
- </pre>
- <h3 id="Bootstrapping">Bootstrapping</h3>
- <p>
- Current implementations provide several built-in functions useful during
- bootstrapping. These functions are documented for completeness but are not
- guaranteed to stay in the language. They do not return a result.
- </p>
- <pre class="grammar">
- Function Behavior
- print prints all arguments; formatting of arguments is implementation-specific
- println like print but prints spaces between arguments and a newline at the end
- </pre>
- <p>
- Implementation restriction: <code>print</code> and <code>println</code> need not
- accept arbitrary argument types, but printing of boolean, numeric, and string
- <a href="#Types">types</a> must be supported.
- </p>
- <h2 id="Packages">Packages</h2>
- <p>
- Go programs are constructed by linking together <i>packages</i>.
- A package in turn is constructed from one or more source files
- that together declare constants, types, variables and functions
- belonging to the package and which are accessible in all files
- of the same package. Those elements may be
- <a href="#Exported_identifiers">exported</a> and used in another package.
- </p>
- <h3 id="Source_file_organization">Source file organization</h3>
- <p>
- Each source file consists of a package clause defining the package
- to which it belongs, followed by a possibly empty set of import
- declarations that declare packages whose contents it wishes to use,
- followed by a possibly empty set of declarations of functions,
- types, variables, and constants.
- </p>
- <pre class="ebnf">
- SourceFile = PackageClause ";" { ImportDecl ";" } { TopLevelDecl ";" } .
- </pre>
- <h3 id="Package_clause">Package clause</h3>
- <p>
- A package clause begins each source file and defines the package
- to which the file belongs.
- </p>
- <pre class="ebnf">
- PackageClause = "package" PackageName .
- PackageName = identifier .
- </pre>
- <p>
- The PackageName must not be the <a href="#Blank_identifier">blank identifier</a>.
- </p>
- <pre>
- package math
- </pre>
- <p>
- A set of files sharing the same PackageName form the implementation of a package.
- An implementation may require that all source files for a package inhabit the same directory.
- </p>
- <h3 id="Import_declarations">Import declarations</h3>
- <p>
- An import declaration states that the source file containing the declaration
- depends on functionality of the <i>imported</i> package
- (<a href="#Program_initialization_and_execution">§Program initialization and execution</a>)
- and enables access to <a href="#Exported_identifiers">exported</a> identifiers
- of that package.
- The import names an identifier (PackageName) to be used for access and an ImportPath
- that specifies the package to be imported.
- </p>
- <pre class="ebnf">
- ImportDecl = "import" ( ImportSpec | "(" { ImportSpec ";" } ")" ) .
- ImportSpec = [ "." | PackageName ] ImportPath .
- ImportPath = string_lit .
- </pre>
- <p>
- The PackageName is used in <a href="#Qualified_identifiers">qualified identifiers</a>
- to access exported identifiers of the package within the importing source file.
- It is declared in the <a href="#Blocks">file block</a>.
- If the PackageName is omitted, it defaults to the identifier specified in the
- <a href="#Package_clause">package clause</a> of the imported package.
- If an explicit period (<code>.</code>) appears instead of a name, all the
- package's exported identifiers declared in that package's
- <a href="#Blocks">package block</a> will be declared in the importing source
- file's file block and must be accessed without a qualifier.
- </p>
- <p>
- The interpretation of the ImportPath is implementation-dependent but
- it is typically a substring of the full file name of the compiled
- package and may be relative to a repository of installed packages.
- </p>
- <p>
- Implementation restriction: A compiler may restrict ImportPaths to
- non-empty strings using only characters belonging to
- <a href="https://www.unicode.org/versions/Unicode6.3.0/">Unicode's</a>
- L, M, N, P, and S general categories (the Graphic characters without
- spaces) and may also exclude the characters
- <code>!"#$%&'()*,:;<=>?[\]^`{|}</code>
- and the Unicode replacement character U+FFFD.
- </p>
- <p>
- Consider a compiled a package containing the package clause
- <code>package math</code>, which exports function <code>Sin</code>, and
- installed the compiled package in the file identified by
- <code>"lib/math"</code>.
- This table illustrates how <code>Sin</code> is accessed in files
- that import the package after the
- various types of import declaration.
- </p>
- <pre class="grammar">
- Import declaration Local name of Sin
- import "lib/math" math.Sin
- import m "lib/math" m.Sin
- import . "lib/math" Sin
- </pre>
- <p>
- An import declaration declares a dependency relation between
- the importing and imported package.
- It is illegal for a package to import itself, directly or indirectly,
- or to directly import a package without
- referring to any of its exported identifiers. To import a package solely for
- its side-effects (initialization), use the <a href="#Blank_identifier">blank</a>
- identifier as explicit package name:
- </p>
- <pre>
- import _ "lib/math"
- </pre>
- <h3 id="An_example_package">An example package</h3>
- <p>
- Here is a complete Go package that implements a concurrent prime sieve.
- </p>
- <pre>
- package main
- import "fmt"
- // Send the sequence 2, 3, 4, … to channel 'ch'.
- func generate(ch chan<- int) {
- for i := 2; ; i++ {
- ch <- i // Send 'i' to channel 'ch'.
- }
- }
- // Copy the values from channel 'src' to channel 'dst',
- // removing those divisible by 'prime'.
- func filter(src <-chan int, dst chan<- int, prime int) {
- for i := range src { // Loop over values received from 'src'.
- if i%prime != 0 {
- dst <- i // Send 'i' to channel 'dst'.
- }
- }
- }
- // The prime sieve: Daisy-chain filter processes together.
- func sieve() {
- ch := make(chan int) // Create a new channel.
- go generate(ch) // Start generate() as a subprocess.
- for {
- prime := <-ch
- fmt.Print(prime, "\n")
- ch1 := make(chan int)
- go filter(ch, ch1, prime)
- ch = ch1
- }
- }
- func main() {
- sieve()
- }
- </pre>
- <h2 id="Program_initialization_and_execution">Program initialization and execution</h2>
- <h3 id="The_zero_value">The zero value</h3>
- <p>
- When storage is allocated for a <a href="#Variables">variable</a>,
- either through a declaration or a call of <code>new</code>, or when
- a new value is created, either through a composite literal or a call
- of <code>make</code>,
- and no explicit initialization is provided, the variable or value is
- given a default value. Each element of such a variable or value is
- set to the <i>zero value</i> for its type: <code>false</code> for booleans,
- <code>0</code> for numeric types, <code>""</code>
- for strings, and <code>nil</code> for pointers, functions, interfaces, slices, channels, and maps.
- This initialization is done recursively, so for instance each element of an
- array of structs will have its fields zeroed if no value is specified.
- </p>
- <p>
- These two simple declarations are equivalent:
- </p>
- <pre>
- var i int
- var i int = 0
- </pre>
- <p>
- After
- </p>
- <pre>
- type T struct { i int; f float64; next *T }
- t := new(T)
- </pre>
- <p>
- the following holds:
- </p>
- <pre>
- t.i == 0
- t.f == 0.0
- t.next == nil
- </pre>
- <p>
- The same would also be true after
- </p>
- <pre>
- var t T
- </pre>
- <h3 id="Package_initialization">Package initialization</h3>
- <p>
- Within a package, package-level variable initialization proceeds stepwise,
- with each step selecting the variable earliest in <i>declaration order</i>
- which has no dependencies on uninitialized variables.
- </p>
- <p>
- More precisely, a package-level variable is considered <i>ready for
- initialization</i> if it is not yet initialized and either has
- no <a href="#Variable_declarations">initialization expression</a> or
- its initialization expression has no <i>dependencies</i> on uninitialized variables.
- Initialization proceeds by repeatedly initializing the next package-level
- variable that is earliest in declaration order and ready for initialization,
- until there are no variables ready for initialization.
- </p>
- <p>
- If any variables are still uninitialized when this
- process ends, those variables are part of one or more initialization cycles,
- and the program is not valid.
- </p>
- <p>
- Multiple variables on the left-hand side of a variable declaration initialized
- by single (multi-valued) expression on the right-hand side are initialized
- together: If any of the variables on the left-hand side is initialized, all
- those variables are initialized in the same step.
- </p>
- <pre>
- var x = a
- var a, b = f() // a and b are initialized together, before x is initialized
- </pre>
- <p>
- For the purpose of package initialization, <a href="#Blank_identifier">blank</a>
- variables are treated like any other variables in declarations.
- </p>
- <p>
- The declaration order of variables declared in multiple files is determined
- by the order in which the files are presented to the compiler: Variables
- declared in the first file are declared before any of the variables declared
- in the second file, and so on.
- To ensure reproducible initialization behavior, build systems are encouraged
- to present multiple files belonging to the same package in lexical file name
- order to a compiler.
- </p>
- <p>
- Dependency analysis does not rely on the actual values of the
- variables, only on lexical <i>references</i> to them in the source,
- analyzed transitively. For instance, if a variable <code>x</code>'s
- initialization expression refers to a function whose body refers to
- variable <code>y</code> then <code>x</code> depends on <code>y</code>.
- Specifically:
- </p>
- <ul>
- <li>
- A reference to a variable or function is an identifier denoting that
- variable or function.
- </li>
- <li>
- A reference to a method <code>m</code> is a
- <a href="#Method_values">method value</a> or
- <a href="#Method_expressions">method expression</a> of the form
- <code>t.m</code>, where the (static) type of <code>t</code> is
- not an interface type, and the method <code>m</code> is in the
- <a href="#Method_sets">method set</a> of <code>t</code>.
- It is immaterial whether the resulting function value
- <code>t.m</code> is invoked.
- </li>
- <li>
- A variable, function, or method <code>x</code> depends on a variable
- <code>y</code> if <code>x</code>'s initialization expression or body
- (for functions and methods) contains a reference to <code>y</code>
- or to a function or method that depends on <code>y</code>.
- </li>
- </ul>
- <p>
- For example, given the declarations
- </p>
- <pre>
- var (
- a = c + b // == 9
- b = f() // == 4
- c = f() // == 5
- d = 3 // == 5 after initialization has finished
- )
- func f() int {
- d++
- return d
- }
- </pre>
- <p>
- the initialization order is <code>d</code>, <code>b</code>, <code>c</code>, <code>a</code>.
- Note that the order of subexpressions in initialization expressions is irrelevant:
- <code>a = c + b</code> and <code>a = b + c</code> result in the same initialization
- order in this example.
- </p>
- <p>
- Dependency analysis is performed per package; only references referring
- to variables, functions, and (non-interface) methods declared in the current
- package are considered. If other, hidden, data dependencies exists between
- variables, the initialization order between those variables is unspecified.
- </p>
- <p>
- For instance, given the declarations
- </p>
- <pre>
- var x = I(T{}).ab() // x has an undetected, hidden dependency on a and b
- var _ = sideEffect() // unrelated to x, a, or b
- var a = b
- var b = 42
- type I interface { ab() []int }
- type T struct{}
- func (T) ab() []int { return []int{a, b} }
- </pre>
- <p>
- the variable <code>a</code> will be initialized after <code>b</code> but
- whether <code>x</code> is initialized before <code>b</code>, between
- <code>b</code> and <code>a</code>, or after <code>a</code>, and
- thus also the moment at which <code>sideEffect()</code> is called (before
- or after <code>x</code> is initialized) is not specified.
- </p>
- <p>
- Variables may also be initialized using functions named <code>init</code>
- declared in the package block, with no arguments and no result parameters.
- </p>
- <pre>
- func init() { … }
- </pre>
- <p>
- Multiple such functions may be defined per package, even within a single
- source file. In the package block, the <code>init</code> identifier can
- be used only to declare <code>init</code> functions, yet the identifier
- itself is not <a href="#Declarations_and_scope">declared</a>. Thus
- <code>init</code> functions cannot be referred to from anywhere
- in a program.
- </p>
- <p>
- The entire package is initialized by assigning initial values
- to all its package-level variables followed by calling
- all <code>init</code> functions in the order they appear
- in the source, possibly in multiple files, as presented
- to the compiler.
- </p>
- <h3 id="Program_initialization">Program initialization</h3>
- <p>
- The packages of a complete program are initialized stepwise, one package at a time.
- If a package has imports, the imported packages are initialized
- before initializing the package itself. If multiple packages import
- a package, the imported package will be initialized only once.
- The importing of packages, by construction, guarantees that there
- can be no cyclic initialization dependencies.
- More precisely:
- </p>
- <p>
- Given the list of all packages, sorted by import path, in each step the first
- uninitialized package in the list for which all imported packages (if any) are
- already initialized is <a href="#Package_initialization">initialized</a>.
- This step is repeated until all packages are initialized.
- </p>
- <p>
- Package initialization—variable initialization and the invocation of
- <code>init</code> functions—happens in a single goroutine,
- sequentially, one package at a time.
- An <code>init</code> function may launch other goroutines, which can run
- concurrently with the initialization code. However, initialization
- always sequences
- the <code>init</code> functions: it will not invoke the next one
- until the previous one has returned.
- </p>
- <h3 id="Program_execution">Program execution</h3>
- <p>
- A complete program is created by linking a single, unimported package
- called the <i>main package</i> with all the packages it imports, transitively.
- The main package must
- have package name <code>main</code> and
- declare a function <code>main</code> that takes no
- arguments and returns no value.
- </p>
- <pre>
- func main() { … }
- </pre>
- <p>
- Program execution begins by <a href="#Program_initialization">initializing the program</a>
- and then invoking the function <code>main</code> in package <code>main</code>.
- When that function invocation returns, the program exits.
- It does not wait for other (non-<code>main</code>) goroutines to complete.
- </p>
- <h2 id="Errors">Errors</h2>
- <p>
- The predeclared type <code>error</code> is defined as
- </p>
- <pre>
- type error interface {
- Error() string
- }
- </pre>
- <p>
- It is the conventional interface for representing an error condition,
- with the nil value representing no error.
- For instance, a function to read data from a file might be defined:
- </p>
- <pre>
- func Read(f *File, b []byte) (n int, err error)
- </pre>
- <h2 id="Run_time_panics">Run-time panics</h2>
- <p>
- Execution errors such as attempting to index an array out
- of bounds trigger a <i>run-time panic</i> equivalent to a call of
- the built-in function <a href="#Handling_panics"><code>panic</code></a>
- with a value of the implementation-defined interface type <code>runtime.Error</code>.
- That type satisfies the predeclared interface type
- <a href="#Errors"><code>error</code></a>.
- The exact error values that
- represent distinct run-time error conditions are unspecified.
- </p>
- <pre>
- package runtime
- type Error interface {
- error
- // and perhaps other methods
- }
- </pre>
- <h2 id="System_considerations">System considerations</h2>
- <h3 id="Package_unsafe">Package <code>unsafe</code></h3>
- <p>
- The built-in package <code>unsafe</code>, known to the compiler
- and accessible through the <a href="#Import_declarations">import path</a> <code>"unsafe"</code>,
- provides facilities for low-level programming including operations
- that violate the type system. A package using <code>unsafe</code>
- must be vetted manually for type safety and may not be portable.
- The package provides the following interface:
- </p>
- <pre class="grammar">
- package unsafe
- type ArbitraryType int // shorthand for an arbitrary Go type; it is not a real type
- type Pointer *ArbitraryType
- func Alignof(variable ArbitraryType) uintptr
- func Offsetof(selector ArbitraryType) uintptr
- func Sizeof(variable ArbitraryType) uintptr
- type IntegerType int // shorthand for an integer type; it is not a real type
- func Add(ptr Pointer, len IntegerType) Pointer
- func Slice(ptr *ArbitraryType, len IntegerType) []ArbitraryType
- func SliceData(slice []ArbitraryType) *ArbitraryType
- func String(ptr *byte, len IntegerType) string
- func StringData(str string) *byte
- </pre>
- <!--
- These conversions also apply to type parameters with suitable core types.
- Determine if we can simply use core type instead of underlying type here,
- of if the general conversion rules take care of this.
- -->
- <p>
- A <code>Pointer</code> is a <a href="#Pointer_types">pointer type</a> but a <code>Pointer</code>
- value may not be <a href="#Address_operators">dereferenced</a>.
- Any pointer or value of <a href="#Core_types">core type</a> <code>uintptr</code> can be
- <a href="#Conversions">converted</a> to a type of core type <code>Pointer</code> and vice versa.
- The effect of converting between <code>Pointer</code> and <code>uintptr</code> is implementation-defined.
- </p>
- <pre>
- var f float64
- bits = *(*uint64)(unsafe.Pointer(&f))
- type ptr unsafe.Pointer
- bits = *(*uint64)(ptr(&f))
- func f[P ~*B, B any](p P) uintptr {
- return uintptr(unsafe.Pointer(p))
- }
- var p ptr = nil
- </pre>
- <p>
- The functions <code>Alignof</code> and <code>Sizeof</code> take an expression <code>x</code>
- of any type and return the alignment or size, respectively, of a hypothetical variable <code>v</code>
- as if <code>v</code> was declared via <code>var v = x</code>.
- </p>
- <p>
- The function <code>Offsetof</code> takes a (possibly parenthesized) <a href="#Selectors">selector</a>
- <code>s.f</code>, denoting a field <code>f</code> of the struct denoted by <code>s</code>
- or <code>*s</code>, and returns the field offset in bytes relative to the struct's address.
- If <code>f</code> is an <a href="#Struct_types">embedded field</a>, it must be reachable
- without pointer indirections through fields of the struct.
- For a struct <code>s</code> with field <code>f</code>:
- </p>
- <pre>
- uintptr(unsafe.Pointer(&s)) + unsafe.Offsetof(s.f) == uintptr(unsafe.Pointer(&s.f))
- </pre>
- <p>
- Computer architectures may require memory addresses to be <i>aligned</i>;
- that is, for addresses of a variable to be a multiple of a factor,
- the variable's type's <i>alignment</i>. The function <code>Alignof</code>
- takes an expression denoting a variable of any type and returns the
- alignment of the (type of the) variable in bytes. For a variable
- <code>x</code>:
- </p>
- <pre>
- uintptr(unsafe.Pointer(&x)) % unsafe.Alignof(x) == 0
- </pre>
- <p>
- A (variable of) type <code>T</code> has <i>variable size</i> if <code>T</code>
- is a <a href="#Type_parameter_declarations">type parameter</a>, or if it is an
- array or struct type containing elements
- or fields of variable size. Otherwise the size is <i>constant</i>.
- Calls to <code>Alignof</code>, <code>Offsetof</code>, and <code>Sizeof</code>
- are compile-time <a href="#Constant_expressions">constant expressions</a> of
- type <code>uintptr</code> if their arguments (or the struct <code>s</code> in
- the selector expression <code>s.f</code> for <code>Offsetof</code>) are types
- of constant size.
- </p>
- <p>
- The function <code>Add</code> adds <code>len</code> to <code>ptr</code>
- and returns the updated pointer <code>unsafe.Pointer(uintptr(ptr) + uintptr(len))</code>
- [<a href="#Go_1.17">Go 1.17</a>].
- The <code>len</code> argument must be of <a href="#Numeric_types">integer type</a> or an untyped <a href="#Constants">constant</a>.
- A constant <code>len</code> argument must be <a href="#Representability">representable</a> by a value of type <code>int</code>;
- if it is an untyped constant it is given type <code>int</code>.
- The rules for <a href="/pkg/unsafe#Pointer">valid uses</a> of <code>Pointer</code> still apply.
- </p>
- <p>
- The function <code>Slice</code> returns a slice whose underlying array starts at <code>ptr</code>
- and whose length and capacity are <code>len</code>.
- <code>Slice(ptr, len)</code> is equivalent to
- </p>
- <pre>
- (*[len]ArbitraryType)(unsafe.Pointer(ptr))[:]
- </pre>
- <p>
- except that, as a special case, if <code>ptr</code>
- is <code>nil</code> and <code>len</code> is zero,
- <code>Slice</code> returns <code>nil</code>
- [<a href="#Go_1.17">Go 1.17</a>].
- </p>
- <p>
- The <code>len</code> argument must be of <a href="#Numeric_types">integer type</a> or an untyped <a href="#Constants">constant</a>.
- A constant <code>len</code> argument must be non-negative and <a href="#Representability">representable</a> by a value of type <code>int</code>;
- if it is an untyped constant it is given type <code>int</code>.
- At run time, if <code>len</code> is negative,
- or if <code>ptr</code> is <code>nil</code> and <code>len</code> is not zero,
- a <a href="#Run_time_panics">run-time panic</a> occurs
- [<a href="#Go_1.17">Go 1.17</a>].
- </p>
- <p>
- The function <code>SliceData</code> returns a pointer to the underlying array of the <code>slice</code> argument.
- If the slice's capacity <code>cap(slice)</code> is not zero, that pointer is <code>&slice[:1][0]</code>.
- If <code>slice</code> is <code>nil</code>, the result is <code>nil</code>.
- Otherwise it is a non-<code>nil</code> pointer to an unspecified memory address
- [<a href="#Go_1.20">Go 1.20</a>].
- </p>
- <p>
- The function <code>String</code> returns a <code>string</code> value whose underlying bytes start at
- <code>ptr</code> and whose length is <code>len</code>.
- The same requirements apply to the <code>ptr</code> and <code>len</code> argument as in the function
- <code>Slice</code>. If <code>len</code> is zero, the result is the empty string <code>""</code>.
- Since Go strings are immutable, the bytes passed to <code>String</code> must not be modified afterwards.
- [<a href="#Go_1.20">Go 1.20</a>]
- </p>
- <p>
- The function <code>StringData</code> returns a pointer to the underlying bytes of the <code>str</code> argument.
- For an empty string the return value is unspecified, and may be <code>nil</code>.
- Since Go strings are immutable, the bytes returned by <code>StringData</code> must not be modified
- [<a href="#Go_1.20">Go 1.20</a>].
- </p>
- <h3 id="Size_and_alignment_guarantees">Size and alignment guarantees</h3>
- <p>
- For the <a href="#Numeric_types">numeric types</a>, the following sizes are guaranteed:
- </p>
- <pre class="grammar">
- type size in bytes
- byte, uint8, int8 1
- uint16, int16 2
- uint32, int32, float32 4
- uint64, int64, float64, complex64 8
- complex128 16
- </pre>
- <p>
- The following minimal alignment properties are guaranteed:
- </p>
- <ol>
- <li>For a variable <code>x</code> of any type: <code>unsafe.Alignof(x)</code> is at least 1.
- </li>
- <li>For a variable <code>x</code> of struct type: <code>unsafe.Alignof(x)</code> is the largest of
- all the values <code>unsafe.Alignof(x.f)</code> for each field <code>f</code> of <code>x</code>, but at least 1.
- </li>
- <li>For a variable <code>x</code> of array type: <code>unsafe.Alignof(x)</code> is the same as
- the alignment of a variable of the array's element type.
- </li>
- </ol>
- <p>
- A struct or array type has size zero if it contains no fields (or elements, respectively) that have a size greater than zero. Two distinct zero-size variables may have the same address in memory.
- </p>
- <h2 id="Appendix">Appendix</h2>
- <h3 id="Language_versions">Language versions</h3>
- <p>
- The <a href="/doc/go1compat">Go 1 compatibility guarantee</a> ensures that
- programs written to the Go 1 specification will continue to compile and run
- correctly, unchanged, over the lifetime of that specification.
- More generally, as adjustments are made and features added to the language,
- the compatibility guarantee ensures that a Go program that works with a
- specific Go language version will continue to work with any subsequent version.
- </p>
- <p>
- For instance, the ability to use the prefix <code>0b</code> for binary
- integer literals was introduced with Go 1.13, indicated
- by [<a href="#Go_1.13">Go 1.13</a>] in the section on
- <a href="#Integer_literals">integer literals</a>.
- Source code containing an integer literal such as <code>0b1011</code>
- will be rejected if the implied or required language version used by
- the compiler is older than Go 1.13.
- </p>
- <p>
- The following table describes the minimum language version required for
- features introduced after Go 1.
- </p>
- <h4 id="Go_1.9">Go 1.9</h4>
- <ul>
- <li>
- An <a href="#Alias_declarations">alias declaration</a> may be used to declare an alias name for a type.
- </li>
- </ul>
- <h4 id="Go_1.13">Go 1.13</h4>
- <ul>
- <li>
- <a href="#Integer_literals">Integer literals</a> may use the prefixes <code>0b</code>, <code>0B</code>, <code>0o</code>,
- and <code>0O</code> for binary, and octal literals, respectively.
- </li>
- <li>
- Hexadecimal <a href="#Floating-point_literals">floating-point literals</a> may be written using the prefixes
- <code>0x</code> and <code>0X</code>.
- </li>
- <li>
- The <a href="#Imaginary_literals">imaginary suffix</a> <code>i</code> may be used with any (binary, decimal, hexadecimal)
- integer or floating-point literal, not just decimal literals.
- </li>
- <li>
- The digits of any number literal may be <a href="#Integer_literals">separated</a> (grouped)
- using underscores <code>_</code>.
- </li>
- <li>
- The shift count in a <a href="#Operators">shift operation</a> may be a signed integer type.
- </li>
- </ul>
- <h4 id="Go_1.14">Go 1.14</h4>
- <ul>
- <li>
- Emdedding a method more than once through different <a href="#Embedded_interfaces">embedded interfaces</a>
- is not an error.
- </li>
- </ul>
- <h4 id="Go_1.17">Go 1.17</h4>
- <ul>
- <li>
- A slice may be <a href="#Conversions">converted</a> to an array pointer if the slice and array element
- types match, and the array is not longer than the slice.
- </li>
- <li>
- The built-in <a href="#Package_unsafe">package <code>unsafe</code></a> includes the new functions
- <code>Add</code> and <code>Slice</code>.
- </li>
- </ul>
- <h4 id="Go_1.18">Go 1.18</h4>
- <p>
- The 1.18 release adds polymorphic functions and types ("generics") to the language.
- Specifically:
- </p>
- <ul>
- <li>
- The set of <a href="#Operators_and_punctuation">operators and punctuation</a> includes the new token <code>~</code>.
- </li>
- <li>
- Function and type declarations may declare <a href="#Type_parameter_declarations">type parameters</a>.
- </li>
- <li>
- Interface types may <a href="#General_interfaces">embed arbitrary types</a> (not just type names of interfaces)
- as well as union and <code>~T</code> type elements.
- </li>
- <li>
- The set of <a href="#Predeclared_identifiers">predeclared</a> types includes the new types
- <code>any</code> and <code>comparable</code>.
- </li>
- </ul>
- <h4 id="Go_1.20">Go 1.20</h4>
- <ul>
- <li>
- A slice may be <a href="#Conversions">converted</a> to an array if the slice and array element
- types match and the array is not longer than the slice.
- </li>
- <li>
- The built-in <a href="#Package_unsafe">package <code>unsafe</code></a> includes the new functions
- <code>SliceData</code>, <code>String</code>, and <code>StringData</code>.
- </li>
- <li>
- <a href="#Comparison_operators">Comparable types</a> (such as ordinary interfaces) may satisfy
- <code>comparable</code> constraints, even if the type arguments are not strictly comparable.
- </li>
- </ul>
- <h4 id="Go_1.21">Go 1.21</h4>
- <ul>
- <li>
- The set of <a href="#Predeclared_identifiers">predeclared</a> functions includes the new functions
- <code>min</code>, <code>max</code>, and <code>clear</code>.
- </li>
- <li>
- <a href="#Type_inference">Type inference</a> uses the types of interface methods for inference.
- It also infers type arguments for generic functions assigned to variables or
- passed as arguments to other (possibly generic) functions.
- </li>
- </ul>
- <h4 id="Go_1.22">Go 1.22</h4>
- <ul>
- <li>
- In a <a href="#For_statements">"for" statement</a>, each iteration has its own set of iteration
- variables rather than sharing the same variables in each iteration.
- </li>
- <li>
- A "for" statement with <a href="#For_range">"range" clause</a> may iterate over
- integer values from zero to an upper limit.
- </li>
- </ul>
- <h4 id="Go_1.23">Go 1.23</h4>
- <ul>
- <li>A "for" statement with <a href="#For_range">"range" clause</a> accepts an iterator
- function as range expression.
- </li>
- </ul>
- <h3 id="Type_unification_rules">Type unification rules</h3>
- <p>
- The type unification rules describe if and how two types unify.
- The precise details are relevant for Go implementations,
- affect the specifics of error messages (such as whether
- a compiler reports a type inference or other error),
- and may explain why type inference fails in unusual code situations.
- But by and large these rules can be ignored when writing Go code:
- type inference is designed to mostly "work as expected",
- and the unification rules are fine-tuned accordingly.
- </p>
- <p>
- Type unification is controlled by a <i>matching mode</i>, which may
- be <i>exact</i> or <i>loose</i>.
- As unification recursively descends a composite type structure,
- the matching mode used for elements of the type, the <i>element matching mode</i>,
- remains the same as the matching mode except when two types are unified for
- <a href="#Assignability">assignability</a> (<code>≡<sub>A</sub></code>):
- in this case, the matching mode is <i>loose</i> at the top level but
- then changes to <i>exact</i> for element types, reflecting the fact
- that types don't have to be identical to be assignable.
- </p>
- <p>
- Two types that are not bound type parameters unify exactly if any of
- following conditions is true:
- </p>
- <ul>
- <li>
- Both types are <a href="#Type_identity">identical</a>.
- </li>
- <li>
- Both types have identical structure and their element types
- unify exactly.
- </li>
- <li>
- Exactly one type is an <a href="#Type_inference">unbound</a>
- type parameter with a <a href="#Core_types">core type</a>,
- and that core type unifies with the other type per the
- unification rules for <code>≡<sub>A</sub></code>
- (loose unification at the top level and exact unification
- for element types).
- </li>
- </ul>
- <p>
- If both types are bound type parameters, they unify per the given
- matching modes if:
- </p>
- <ul>
- <li>
- Both type parameters are identical.
- </li>
- <li>
- At most one of the type parameters has a known type argument.
- In this case, the type parameters are <i>joined</i>:
- they both stand for the same type argument.
- If neither type parameter has a known type argument yet,
- a future type argument inferred for one the type parameters
- is simultaneously inferred for both of them.
- </li>
- <li>
- Both type parameters have a known type argument
- and the type arguments unify per the given matching modes.
- </li>
- </ul>
- <p>
- A single bound type parameter <code>P</code> and another type <code>T</code> unify
- per the given matching modes if:
- </p>
- <ul>
- <li>
- <code>P</code> doesn't have a known type argument.
- In this case, <code>T</code> is inferred as the type argument for <code>P</code>.
- </li>
- <li>
- <code>P</code> does have a known type argument <code>A</code>,
- <code>A</code> and <code>T</code> unify per the given matching modes,
- and one of the following conditions is true:
- <ul>
- <li>
- Both <code>A</code> and <code>T</code> are interface types:
- In this case, if both <code>A</code> and <code>T</code> are
- also <a href="#Type_definitions">defined</a> types,
- they must be <a href="#Type_identity">identical</a>.
- Otherwise, if neither of them is a defined type, they must
- have the same number of methods
- (unification of <code>A</code> and <code>T</code> already
- established that the methods match).
- </li>
- <li>
- Neither <code>A</code> nor <code>T</code> are interface types:
- In this case, if <code>T</code> is a defined type, <code>T</code>
- replaces <code>A</code> as the inferred type argument for <code>P</code>.
- </li>
- </ul>
- </li>
- </ul>
- <p>
- Finally, two types that are not bound type parameters unify loosely
- (and per the element matching mode) if:
- </p>
- <ul>
- <li>
- Both types unify exactly.
- </li>
- <li>
- One type is a <a href="#Type_definitions">defined type</a>,
- the other type is a type literal, but not an interface,
- and their underlying types unify per the element matching mode.
- </li>
- <li>
- Both types are interfaces (but not type parameters) with
- identical <a href="#Interface_types">type terms</a>,
- both or neither embed the predeclared type
- <a href="#Predeclared_identifiers">comparable</a>,
- corresponding method types unify exactly,
- and the method set of one of the interfaces is a subset of
- the method set of the other interface.
- </li>
- <li>
- Only one type is an interface (but not a type parameter),
- corresponding methods of the two types unify per the element matching mode,
- and the method set of the interface is a subset of
- the method set of the other type.
- </li>
- <li>
- Both types have the same structure and their element types
- unify per the element matching mode.
- </li>
- </ul>
|