levovix
/
Nim
miroir de https://github.com/nim-lang/Nim


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151215221532154215521562157215821592160216121622163216421652166216721682169217021712172217321742175217621772178217921802181218221832184218521862187218821892190219121922193219421952196219721982199220022012202220322042205220622072208220922102211221222132214221522162217221822192220222122222223222422252226222722282229223022312232223322342235223622372238223922402241224222432244224522462247224822492250225122522253225422552256225722582259226022612262226322642265226622672268226922702271227222732274227522762277227822792280228122822283228422852286228722882289229022912292229322942295229622972298229923002301230223032304230523062307230823092310231123122313231423152316231723182319232023212322232323242325232623272328232923302331233223332334233523362337233823392340234123422343234423452346234723482349235023512352235323542355235623572358235923602361236223632364236523662367236823692370237123722373237423752376237723782379238023812382238323842385238623872388238923902391239223932394239523962397239823992400240124022403240424052406240724082409241024112412241324142415241624172418241924202421242224232424242524262427242824292430243124322433243424352436243724382439244024412442244324442445244624472448244924502451245224532454245524562457245824592460246124622463246424652466246724682469247024712472247324742475247624772478247924802481248224832484248524862487248824892490249124922493249424952496249724982499250025012502250325042505250625072508250925102511251225132514251525162517251825192520252125222523252425252526252725282529253025312532253325342535253625372538253925402541254225432544254525462547254825492550255125522553255425552556255725582559256025612562256325642565256625672568256925702571257225732574257525762577257825792580258125822583258425852586258725882589259025912592259325942595259625972598259926002601260226032604260526062607260826092610261126122613261426152616261726182619262026212622262326242625262626272628262926302631263226332634263526362637263826392640264126422643264426452646264726482649265026512652265326542655265626572658265926602661266226632664266526662667266826692670267126722673267426752676267726782679268026812682268326842685268626872688268926902691269226932694269526962697269826992700270127022703270427052706270727082709271027112712271327142715271627172718271927202721272227232724272527262727272827292730273127322733273427352736273727382739274027412742274327442745274627472748274927502751275227532754275527562757275827592760276127622763276427652766276727682769277027712772277327742775277627772778277927802781278227832784278527862787278827892790279127922793279427952796279727982799280028012802280328042805280628072808280928102811281228132814281528162817281828192820282128222823282428252826282728282829283028312832283328342835283628372838283928402841284228432844284528462847284828492850285128522853285428552856285728582859286028612862286328642865286628672868286928702871287228732874287528762877287828792880288128822883288428852886288728882889289028912892289328942895289628972898289929002901290229032904290529062907290829092910291129122913291429152916291729182919292029212922292329242925292629272928292929302931293229332934293529362937293829392940294129422943294429452946294729482949295029512952295329542955295629572958295929602961296229632964296529662967296829692970297129722973297429752976297729782979298029812982298329842985298629872988298929902991299229932994299529962997299829993000300130023003300430053006300730083009301030113012301330143015301630173018301930203021302230233024302530263027302830293030303130323033303430353036303730383039304030413042304330443045304630473048304930503051305230533054305530563057305830593060306130623063306430653066306730683069307030713072307330743075307630773078307930803081308230833084308530863087308830893090309130923093309430953096309730983099310031013102310331043105310631073108310931103111311231133114311531163117311831193120312131223123312431253126312731283129313031313132313331343135313631373138313931403141314231433144314531463147314831493150315131523153315431553156315731583159316031613162316331643165316631673168316931703171317231733174317531763177317831793180318131823183318431853186318731883189319031913192319331943195319631973198319932003201320232033204320532063207320832093210321132123213321432153216321732183219322032213222322332243225322632273228322932303231323232333234323532363237323832393240324132423243324432453246324732483249325032513252325332543255325632573258325932603261326232633264326532663267326832693270327132723273327432753276327732783279328032813282328332843285328632873288328932903291329232933294329532963297329832993300330133023303330433053306330733083309331033113312331333143315331633173318331933203321332233233324332533263327332833293330333133323333333433353336333733383339334033413342334333443345334633473348334933503351335233533354335533563357335833593360336133623363336433653366336733683369337033713372337333743375337633773378337933803381338233833384338533863387338833893390339133923393339433953396339733983399340034013402340334043405340634073408340934103411341234133414341534163417341834193420342134223423342434253426342734283429343034313432343334343435343634373438343934403441344234433444344534463447344834493450345134523453345434553456345734583459346034613462346334643465346634673468346934703471347234733474347534763477347834793480348134823483348434853486348734883489349034913492349334943495349634973498349935003501350235033504350535063507350835093510351135123513351435153516351735183519352035213522352335243525352635273528352935303531353235333534353535363537353835393540354135423543354435453546354735483549355035513552355335543555355635573558355935603561356235633564356535663567356835693570357135723573357435753576357735783579358035813582358335843585358635873588358935903591359235933594359535963597359835993600360136023603360436053606360736083609361036113612361336143615361636173618361936203621362236233624362536263627362836293630363136323633363436353636363736383639364036413642364336443645364636473648364936503651365236533654365536563657365836593660366136623663366436653666366736683669367036713672367336743675367636773678367936803681368236833684368536863687368836893690369136923693369436953696369736983699370037013702370337043705370637073708370937103711371237133714371537163717371837193720372137223723372437253726372737283729373037313732373337343735373637373738373937403741374237433744374537463747374837493750375137523753375437553756375737583759376037613762376337643765376637673768376937703771377237733774377537763777377837793780378137823783378437853786378737883789379037913792379337943795379637973798379938003801380238033804380538063807380838093810381138123813381438153816381738183819382038213822382338243825382638273828382938303831383238333834383538363837383838393840384138423843384438453846384738483849385038513852385338543855385638573858385938603861386238633864386538663867386838693870387138723873387438753876387738783879388038813882388338843885388638873888388938903891389238933894389538963897389838993900390139023903390439053906390739083909391039113912391339143915391639173918391939203921392239233924392539263927392839293930393139323933393439353936393739383939394039413942394339443945394639473948394939503951395239533954395539563957395839593960396139623963396439653966396739683969397039713972397339743975397639773978397939803981398239833984398539863987398839893990399139923993399439953996399739983999400040014002400340044005400640074008400940104011401240134014401540164017401840194020402140224023402440254026402740284029403040314032403340344035403640374038403940404041404240434044404540464047404840494050405140524053405440554056405740584059406040614062406340644065406640674068406940704071407240734074407540764077407840794080408140824083408440854086408740884089409040914092409340944095409640974098409941004101410241034104410541064107410841094110411141124113411441154116411741184119412041214122412341244125412641274128412941304131413241334134413541364137413841394140414141424143414441454146414741484149415041514152415341544155415641574158415941604161416241634164416541664167416841694170417141724173417441754176417741784179418041814182418341844185418641874188418941904191419241934194419541964197419841994200420142024203420442054206420742084209421042114212421342144215421642174218421942204221422242234224422542264227422842294230423142324233423442354236423742384239424042414242424342444245424642474248424942504251425242534254425542564257425842594260426142624263426442654266426742684269427042714272427342744275427642774278427942804281428242834284428542864287428842894290429142924293429442954296429742984299430043014302430343044305430643074308430943104311431243134314431543164317431843194320432143224323432443254326432743284329433043314332433343344335433643374338433943404341434243434344434543464347434843494350435143524353435443554356435743584359436043614362436343644365436643674368436943704371437243734374437543764377437843794380438143824383438443854386438743884389439043914392439343944395439643974398439944004401440244034404440544064407440844094410441144124413441444154416441744184419442044214422442344244425442644274428442944304431443244334434443544364437443844394440444144424443444444454446444744484449445044514452445344544455445644574458445944604461446244634464446544664467446844694470447144724473447444754476447744784479448044814482448344844485448644874488448944904491449244934494449544964497449844994500450145024503450445054506450745084509451045114512451345144515451645174518451945204521452245234524452545264527452845294530453145324533453445354536453745384539454045414542454345444545454645474548454945504551455245534554455545564557455845594560456145624563456445654566456745684569457045714572457345744575457645774578457945804581458245834584458545864587458845894590459145924593459445954596459745984599460046014602460346044605460646074608460946104611461246134614461546164617461846194620462146224623462446254626462746284629463046314632463346344635463646374638463946404641464246434644464546464647464846494650465146524653465446554656465746584659466046614662466346644665466646674668466946704671467246734674467546764677467846794680468146824683468446854686468746884689469046914692469346944695469646974698469947004701470247034704470547064707470847094710471147124713471447154716471747184719472047214722472347244725472647274728472947304731473247334734473547364737473847394740474147424743474447454746474747484749475047514752475347544755475647574758475947604761476247634764476547664767476847694770477147724773477447754776477747784779478047814782478347844785478647874788478947904791479247934794479547964797479847994800480148024803480448054806480748084809481048114812481348144815481648174818481948204821482248234824482548264827482848294830483148324833483448354836483748384839484048414842484348444845484648474848484948504851485248534854485548564857485848594860486148624863486448654866486748684869487048714872487348744875487648774878487948804881488248834884488548864887488848894890489148924893489448954896489748984899490049014902490349044905490649074908490949104911491249134914491549164917491849194920492149224923492449254926492749284929493049314932493349344935493649374938493949404941494249434944494549464947494849494950495149524953495449554956495749584959496049614962496349644965496649674968496949704971497249734974497549764977497849794980498149824983498449854986498749884989499049914992499349944995499649974998499950005001500250035004500550065007500850095010501150125013501450155016501750185019502050215022502350245025502650275028502950305031503250335034503550365037503850395040504150425043504450455046504750485049505050515052505350545055505650575058505950605061506250635064506550665067506850695070507150725073507450755076507750785079508050815082508350845085508650875088508950905091509250935094509550965097509850995100510151025103510451055106510751085109511051115112511351145115511651175118511951205121512251235124512551265127512851295130513151325133513451355136513751385139514051415142514351445145514651475148514951505151515251535154515551565157515851595160516151625163
							<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!--  This file is generated by Nim. -->
<html xmlns="https://www.w3.org/1999/xhtml" xml:lang="en" lang="en" data-theme="auto">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Nim Manual</title>

<!-- Google fonts -->
<link href='https://fonts.googleapis.com/css?family=Lato:400,600,900' rel='stylesheet' type='text/css'/>
<link href='https://fonts.googleapis.com/css?family=Source+Code+Pro:400,500,600' rel='stylesheet' type='text/css'/>

<!-- Favicon -->
<link rel="shortcut icon" href="data:image/x-icon;base64,AAABAAEAEBAAAAEAIABoBAAAFgAAACgAAAAQAAAAIAAAAAEAIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AAAAAAUAAAAF////AP///wD///8A////AP///wD///8A////AP///wD///8A////AAAAAAIAAABbAAAAlQAAAKIAAACbAAAAmwAAAKIAAACVAAAAWwAAAAL///8A////AP///wD///8A////AAAAABQAAADAAAAAYwAAAA3///8A////AP///wD///8AAAAADQAAAGMAAADAAAAAFP///wD///8A////AP///wAAAACdAAAAOv///wD///8A////AP///wD///8A////AP///wD///8AAAAAOgAAAJ3///8A////AP///wAAAAAnAAAAcP///wAAAAAoAAAASv///wD///8A////AP///wAAAABKAAAAKP///wAAAABwAAAAJ////wD///8AAAAAgQAAABwAAACIAAAAkAAAAJMAAACtAAAAFQAAABUAAACtAAAAkwAAAJAAAACIAAAAHAAAAIH///8A////AAAAAKQAAACrAAAAaP///wD///8AAAAARQAAANIAAADSAAAARf///wD///8AAAAAaAAAAKsAAACk////AAAAADMAAACcAAAAnQAAABj///8A////AP///wAAAAAYAAAAGP///wD///8A////AAAAABgAAACdAAAAnAAAADMAAAB1AAAAwwAAAP8AAADpAAAAsQAAAE4AAAAb////AP///wAAAAAbAAAATgAAALEAAADpAAAA/wAAAMMAAAB1AAAAtwAAAOkAAAD/AAAA/wAAAP8AAADvAAAA3gAAAN4AAADeAAAA3gAAAO8AAAD/AAAA/wAAAP8AAADpAAAAtwAAAGUAAAA/AAAA3wAAAP8AAAD/AAAA/wAAAP8AAAD/AAAA/wAAAP8AAAD/AAAA/wAAAP8AAADfAAAAPwAAAGX///8A////AAAAAEgAAADtAAAAvwAAAL0AAADGAAAA7wAAAO8AAADGAAAAvQAAAL8AAADtAAAASP///wD///8A////AP///wD///8AAAAAO////wD///8A////AAAAAIcAAACH////AP///wD///8AAAAAO////wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A//8AAP//AAD4HwAA7/cAAN/7AAD//wAAoYUAAJ55AACf+QAAh+EAAAAAAADAAwAA4AcAAP5/AAD//wAA//8AAA=="/>
<link rel="icon" type="image/png" sizes="32x32" href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAABmJLR0QA/wD/AP+gvaeTAAAACXBIWXMAAA3XAAAN1wFCKJt4AAAAB3RJTUUH4QQQEwksSS9ZWwAAAk1JREFUWMPtll2ITVEUx39nn/O7Y5qR8f05wtCUUr6ZIS++8pEnkZInPImneaCQ5METNdOkeFBKUhMPRIkHKfEuUZSUlGlKPN2TrgfncpvmnntnmlEyq1Z7t89/rf9a6+y99oZxGZf/XeIq61EdtgKXgdXA0xrYAvBjOIF1AI9zvjcC74BSpndrJPkBWDScTF8Aa4E3wDlgHbASaANmVqlcCnwHvgDvgVfAJ+AikAAvgfVZwLnSVZHZaOuKoQi3ZOMi4NkYkpe1p4J7A8BpYAD49hfIy/oqG0+hLomiKP2L5L+1ubn5115S+3OAn4EnwBlgMzCjyt6ZAnQCJ4A7wOs88iRJHvw50HoujuPBoCKwHWiosy8MdfZnAdcHk8dxXFJ3VQbQlCTJvRBCGdRbD4M6uc5glpY3eAihpN5S5w12diSEcCCEcKUO4ljdr15T76ur1FDDLIQQ3qv71EdDOe3Kxj3leRXyk+pxdWnFWod6Wt2bY3de3aSuUHcPBVimHs7mK9WrmeOF6lR1o9qnzskh2ar2qm1qizpfXaPeVGdlmGN5pb09qMxz1Xb1kLqgzn1RyH7JUXW52lr5e/Kqi9qpto7V1atuUzfnARrV7jEib1T76gG2qxdGmXyiekkt1GswPTtek0aBfJp6YySGBfWg2tPQ0FAYgf1stUfdmdcjarbYJEniKIq6gY/Aw+zWHAC+p2labGpqiorFYgGYCEzN7oQdQClN07O1/EfDyGgC0ALMBdYAi4FyK+4H3gLPsxfR1zRNi+NP7nH5J+QntnXe5B5mpfQAAAAASUVORK5CYII=">

<!-- CSS -->
<link rel="stylesheet" type="text/css" href="nimdoc.out.css?v=2.3.1">

<!-- JS -->
<script type="text/javascript" src="dochack.js?v=2.3.1"></script>
</head>
<body>
  <div class="document" id="documentId">
    <div class="container">
      <h1 class="title">Nim Manual</h1>
      <div class="row">
  <div class="three columns">
    <div class="theme-select-wrapper">
      <label for="theme-select">Theme:&nbsp;</label>
      <select id="theme-select" onchange="setTheme(this.value)">
        <option value="auto">🌗 Match OS</option>
        <option value="dark">🌑 Dark</option>
        <option value="light">🌕 Light</option>
      </select>
    </div>
    <div id="global-links">
      <ul class="simple-boot">
        <li><a href="manual.html">Manual</a></li>
        <li><a href="lib.html">Standard library</a></li>
        <li> <a id="indexLink" href="theindex.html">Index</a></li>
        <li><a href="compiler/theindex.html">Compiler docs</a></li>
        <li><a href="https://nim-lang.github.io/fusion/theindex.html">Fusion docs</a></li>
        <li><a href="https://nim-lang.github.io/Nim/">devel</a>, <a href="https://nim-lang.org/documentation.html">stable</a></li>
      </ul>
    </div>
    <div id="searchInputDiv">
      Search: <input type="search" id="searchInput"
        oninput="search()" />
    </div>
    <div class="search-groupby">
  Group by:
  <select onchange="groupBy(this.value)">
    <option value="section">Section</option>
    <option value="type">Type</option>
  </select>
</div>

    <ul class="simple simple-toc" id="toc-list">
  <li><a class="reference" id="about-this-document_toc" href="#about-this-document">About this document</a></li>
<li><a class="reference" id="definitions_toc" href="#definitions">Definitions</a></li>
<li><a class="reference" id="lexical-analysis_toc" href="#lexical-analysis">Lexical Analysis</a></li>
<ul class="simple"><li><a class="reference" id="lexical-analysis-encoding_toc" href="#lexical-analysis-encoding">Encoding</a></li>
<li><a class="reference" id="lexical-analysis-indentation_toc" href="#lexical-analysis-indentation">Indentation</a></li>
<li><a class="reference" id="lexical-analysis-comments_toc" href="#lexical-analysis-comments">Comments</a></li>
<li><a class="reference" id="lexical-analysis-multiline-comments_toc" href="#lexical-analysis-multiline-comments">Multiline comments</a></li>
<li><a class="reference" id="lexical-analysis-identifiers-amp-keywords_toc" href="#lexical-analysis-identifiers-amp-keywords">Identifiers &amp; Keywords</a></li>
<li><a class="reference" id="lexical-analysis-identifier-equality_toc" href="#lexical-analysis-identifier-equality">Identifier equality</a></li>
<li><a class="reference" id="lexical-analysis-keywords-as-identifiers_toc" href="#lexical-analysis-keywords-as-identifiers">Keywords as identifiers</a></li>
<li><a class="reference" id="lexical-analysis-string-literals_toc" href="#lexical-analysis-string-literals">String literals</a></li>
<li><a class="reference" id="lexical-analysis-triple-quoted-string-literals_toc" href="#lexical-analysis-triple-quoted-string-literals">Triple quoted string literals</a></li>
<li><a class="reference" id="lexical-analysis-raw-string-literals_toc" href="#lexical-analysis-raw-string-literals">Raw string literals</a></li>
<li><a class="reference" id="lexical-analysis-generalized-raw-string-literals_toc" href="#lexical-analysis-generalized-raw-string-literals">Generalized raw string literals</a></li>
<li><a class="reference" id="lexical-analysis-character-literals_toc" href="#lexical-analysis-character-literals">Character literals</a></li>
<li><a class="reference" id="lexical-analysis-numeric-literals_toc" href="#lexical-analysis-numeric-literals">Numeric literals</a></li>
<ul class="simple"><li><a class="reference" id="numeric-literals-custom-numeric-literals_toc" href="#numeric-literals-custom-numeric-literals">Custom numeric literals</a></li>
</ul><li><a class="reference" id="lexical-analysis-operators_toc" href="#lexical-analysis-operators">Operators</a></li>
<li><a class="reference" id="lexical-analysis-unicode-operators_toc" href="#lexical-analysis-unicode-operators">Unicode Operators</a></li>
<li><a class="reference" id="lexical-analysis-other-tokens_toc" href="#lexical-analysis-other-tokens">Other tokens</a></li>
</ul><li><a class="reference" id="syntax_toc" href="#syntax">Syntax</a></li>
<ul class="simple"><li><a class="reference" id="syntax-associativity_toc" href="#syntax-associativity">Associativity</a></li>
<li><a class="reference" id="syntax-precedence_toc" href="#syntax-precedence">Precedence</a></li>
<li><a class="reference" id="syntax-dotminuslike-operators_toc" href="#syntax-dotminuslike-operators">Dot-like operators</a></li>
<li><a class="reference" id="syntax-grammar_toc" href="#syntax-grammar">Grammar</a></li>
</ul><li><a class="reference" id="order-of-evaluation_toc" href="#order-of-evaluation">Order of evaluation</a></li>
<li><a class="reference" id="constants-and-constant-expressions_toc" href="#constants-and-constant-expressions">Constants and Constant Expressions</a></li>
<li><a class="reference" id="restrictions-on-compileminustime-execution_toc" href="#restrictions-on-compileminustime-execution">Restrictions on Compile-Time Execution</a></li>
<li><a class="reference" id="types_toc" href="#types">Types</a></li>
<ul class="simple"><li><a class="reference" id="types-ordinal-types_toc" href="#types-ordinal-types">Ordinal types</a></li>
<li><a class="reference" id="types-preminusdefined-integer-types_toc" href="#types-preminusdefined-integer-types">Pre-defined integer types</a></li>
<li><a class="reference" id="types-subrange-types_toc" href="#types-subrange-types">Subrange types</a></li>
<li><a class="reference" id="types-preminusdefined-floatingminuspoint-types_toc" href="#types-preminusdefined-floatingminuspoint-types">Pre-defined floating-point types</a></li>
<li><a class="reference" id="types-boolean-type_toc" href="#types-boolean-type">Boolean type</a></li>
<li><a class="reference" id="types-character-type_toc" href="#types-character-type">Character type</a></li>
<li><a class="reference" id="types-enumeration-types_toc" href="#types-enumeration-types">Enumeration types</a></li>
<li><a class="reference" id="types-string-type_toc" href="#types-string-type">String type</a></li>
<li><a class="reference" id="types-cstring-type_toc" href="#types-cstring-type">cstring type</a></li>
<li><a class="reference" id="types-structured-types_toc" href="#types-structured-types">Structured types</a></li>
<li><a class="reference" id="types-array-and-sequence-types_toc" href="#types-array-and-sequence-types">Array and sequence types</a></li>
<li><a class="reference" id="types-open-arrays_toc" href="#types-open-arrays">Open arrays</a></li>
<li><a class="reference" id="types-varargs_toc" href="#types-varargs">Varargs</a></li>
<li><a class="reference" id="types-unchecked-arrays_toc" href="#types-unchecked-arrays">Unchecked arrays</a></li>
<li><a class="reference" id="types-tuples-and-object-types_toc" href="#types-tuples-and-object-types">Tuples and object types</a></li>
<li><a class="reference" id="types-object-construction_toc" href="#types-object-construction">Object construction</a></li>
<li><a class="reference" id="types-object-variants_toc" href="#types-object-variants">Object variants</a></li>
<li><a class="reference" id="types-cast-uncheckedassign_toc" href="#types-cast-uncheckedassign">cast uncheckedAssign</a></li>
<li><a class="reference" id="types-default-values-for-object-fields_toc" href="#types-default-values-for-object-fields">Default values for object fields</a></li>
<li><a class="reference" id="types-set-type_toc" href="#types-set-type">Set type</a></li>
<ul class="simple"><li><a class="reference" id="set-type-bit-fields_toc" href="#set-type-bit-fields">Bit fields</a></li>
</ul><li><a class="reference" id="types-reference-and-pointer-types_toc" href="#types-reference-and-pointer-types">Reference and pointer types</a></li>
<li><a class="reference" id="types-nil_toc" href="#types-nil">Nil</a></li>
<li><a class="reference" id="types-mixing-gc-ed-memory-with-nimptr_toc" href="#types-mixing-gc-ed-memory-with-nimptr">Mixing GC'ed memory with <tt class="docutils literal"><span class="pre"><span class="Keyword">ptr</span></span></tt></a></li>
<li><a class="reference" id="types-procedural-type_toc" href="#types-procedural-type">Procedural type</a></li>
<li><a class="reference" id="types-distinct-type_toc" href="#types-distinct-type">Distinct type</a></li>
<ul class="simple"><li><a class="reference" id="distinct-type-modeling-currencies_toc" href="#distinct-type-modeling-currencies">Modeling currencies</a></li>
<li><a class="reference" id="distinct-type-avoiding-sql-injection-attacks_toc" href="#distinct-type-avoiding-sql-injection-attacks">Avoiding SQL injection attacks</a></li>
</ul><li><a class="reference" id="types-auto-type_toc" href="#types-auto-type">Auto type</a></li>
</ul><li><a class="reference" id="type-relations_toc" href="#type-relations">Type relations</a></li>
<ul class="simple"><li><a class="reference" id="type-relations-type-equality_toc" href="#type-relations-type-equality">Type equality</a></li>
<li><a class="reference" id="type-relations-subtype-relation_toc" href="#type-relations-subtype-relation">Subtype relation</a></li>
<li><a class="reference" id="type-relations-convertible-relation_toc" href="#type-relations-convertible-relation">Convertible relation</a></li>
<li><a class="reference" id="type-relations-assignment-compatibility_toc" href="#type-relations-assignment-compatibility">Assignment compatibility</a></li>
</ul><li><a class="reference" id="overload-resolution_toc" href="#overload-resolution">Overload resolution</a></li>
<ul class="simple"><li><a class="reference" id="overload-resolution-first-trialcolon-category-matching_toc" href="#overload-resolution-first-trialcolon-category-matching">First Trial: Category matching</a></li>
<li><a class="reference" id="overload-resolution-second-trialcolon-hierarchical-order-comparison_toc" href="#overload-resolution-second-trialcolon-hierarchical-order-comparison">Second Trial: Hierarchical Order Comparison</a></li>
<li><a class="reference" id="overload-resolution-third-trialcolon-complexity-analysis_toc" href="#overload-resolution-third-trialcolon-complexity-analysis">Third Trial: Complexity Analysis</a></li>
<li><a class="reference" id="overload-resolution-some-examples_toc" href="#overload-resolution-some-examples">Some Examples</a></li>
<li><a class="reference" id="overload-resolution-type-variables-match_toc" href="#overload-resolution-type-variables-match">Type variables match</a></li>
<li><a class="reference" id="overload-resolution-overloading-based-on-var-t_toc" href="#overload-resolution-overloading-based-on-var-t">Overloading based on 'var T'</a></li>
<li><a class="reference" id="overload-resolution-lazy-type-resolution-for-untyped_toc" href="#overload-resolution-lazy-type-resolution-for-untyped">Lazy type resolution for untyped</a></li>
<li><a class="reference" id="overload-resolution-varargs-matching_toc" href="#overload-resolution-varargs-matching">Varargs matching</a></li>
<li><a class="reference" id="overload-resolution-iterable_toc" href="#overload-resolution-iterable">iterable</a></li>
</ul><li><a class="reference" id="overload-disambiguation_toc" href="#overload-disambiguation">Overload disambiguation</a></li>
<ul class="simple"><li><a class="reference" id="overload-disambiguation-named-argument-overloading_toc" href="#overload-disambiguation-named-argument-overloading">Named argument overloading</a></li>
</ul><li><a class="reference" id="statements-and-expressions_toc" href="#statements-and-expressions">Statements and expressions</a></li>
<ul class="simple"><li><a class="reference" id="statements-and-expressions-statement-list-expression_toc" href="#statements-and-expressions-statement-list-expression">Statement list expression</a></li>
<li><a class="reference" id="statements-and-expressions-discard-statement_toc" href="#statements-and-expressions-discard-statement">Discard statement</a></li>
<li><a class="reference" id="statements-and-expressions-void-context_toc" href="#statements-and-expressions-void-context">Void context</a></li>
<li><a class="reference" id="statements-and-expressions-var-statement_toc" href="#statements-and-expressions-var-statement">Var statement</a></li>
<li><a class="reference" id="statements-and-expressions-let-statement_toc" href="#statements-and-expressions-let-statement">Let statement</a></li>
<li><a class="reference" id="statements-and-expressions-special-identifier-nim-underscore_toc" href="#statements-and-expressions-special-identifier-nim-underscore">Special identifier <tt class="docutils literal"><span class="pre"><span class="Identifier">_</span></span></tt> (underscore)</a></li>
<li><a class="reference" id="statements-and-expressions-tuple-unpacking_toc" href="#statements-and-expressions-tuple-unpacking">Tuple unpacking</a></li>
<li><a class="reference" id="statements-and-expressions-const-section_toc" href="#statements-and-expressions-const-section">Const section</a></li>
<li><a class="reference" id="statements-and-expressions-static-statementslashexpression_toc" href="#statements-and-expressions-static-statementslashexpression">Static statement/expression</a></li>
<li><a class="reference" id="statements-and-expressions-if-statement_toc" href="#statements-and-expressions-if-statement">If statement</a></li>
<li><a class="reference" id="statements-and-expressions-case-statement_toc" href="#statements-and-expressions-case-statement">Case statement</a></li>
<li><a class="reference" id="statements-and-expressions-when-statement_toc" href="#statements-and-expressions-when-statement">When statement</a></li>
<li><a class="reference" id="statements-and-expressions-when-nimvm-statement_toc" href="#statements-and-expressions-when-nimvm-statement">When nimvm statement</a></li>
<li><a class="reference" id="statements-and-expressions-return-statement_toc" href="#statements-and-expressions-return-statement">Return statement</a></li>
<li><a class="reference" id="statements-and-expressions-yield-statement_toc" href="#statements-and-expressions-yield-statement">Yield statement</a></li>
<li><a class="reference" id="statements-and-expressions-block-statement_toc" href="#statements-and-expressions-block-statement">Block statement</a></li>
<li><a class="reference" id="statements-and-expressions-break-statement_toc" href="#statements-and-expressions-break-statement">Break statement</a></li>
<li><a class="reference" id="statements-and-expressions-while-statement_toc" href="#statements-and-expressions-while-statement">While statement</a></li>
<li><a class="reference" id="statements-and-expressions-continue-statement_toc" href="#statements-and-expressions-continue-statement">Continue statement</a></li>
<li><a class="reference" id="statements-and-expressions-assembler-statement_toc" href="#statements-and-expressions-assembler-statement">Assembler statement</a></li>
<li><a class="reference" id="statements-and-expressions-using-statement_toc" href="#statements-and-expressions-using-statement">Using statement</a></li>
<li><a class="reference" id="statements-and-expressions-if-expression_toc" href="#statements-and-expressions-if-expression">If expression</a></li>
<li><a class="reference" id="statements-and-expressions-when-expression_toc" href="#statements-and-expressions-when-expression">When expression</a></li>
<li><a class="reference" id="statements-and-expressions-case-expression_toc" href="#statements-and-expressions-case-expression">Case expression</a></li>
<li><a class="reference" id="statements-and-expressions-block-expression_toc" href="#statements-and-expressions-block-expression">Block expression</a></li>
<li><a class="reference" id="statements-and-expressions-table-constructor_toc" href="#statements-and-expressions-table-constructor">Table constructor</a></li>
<li><a class="reference" id="statements-and-expressions-type-conversions_toc" href="#statements-and-expressions-type-conversions">Type conversions</a></li>
<li><a class="reference" id="statements-and-expressions-type-casts_toc" href="#statements-and-expressions-type-casts">Type casts</a></li>
<li><a class="reference" id="statements-and-expressions-the-addr-operator_toc" href="#statements-and-expressions-the-addr-operator">The addr operator</a></li>
<li><a class="reference" id="statements-and-expressions-the-unsafeaddr-operator_toc" href="#statements-and-expressions-the-unsafeaddr-operator">The unsafeAddr operator</a></li>
</ul><li><a class="reference" id="procedures_toc" href="#procedures">Procedures</a></li>
<ul class="simple"><li><a class="reference" id="procedures-export-marker_toc" href="#procedures-export-marker">Export marker</a></li>
<li><a class="reference" id="procedures-method-call-syntax_toc" href="#procedures-method-call-syntax">Method call syntax</a></li>
<li><a class="reference" id="procedures-properties_toc" href="#procedures-properties">Properties</a></li>
<li><a class="reference" id="procedures-command-invocation-syntax_toc" href="#procedures-command-invocation-syntax">Command invocation syntax</a></li>
<li><a class="reference" id="procedures-closures_toc" href="#procedures-closures">Closures</a></li>
<ul class="simple"><li><a class="reference" id="closures-creating-closures-in-loops_toc" href="#closures-creating-closures-in-loops">Creating closures in loops</a></li>
</ul><li><a class="reference" id="procedures-anonymous-procedures_toc" href="#procedures-anonymous-procedures">Anonymous procedures</a></li>
<li><a class="reference" id="procedures-do-notation_toc" href="#procedures-do-notation">Do notation</a></li>
<li><a class="reference" id="procedures-func_toc" href="#procedures-func">Func</a></li>
<li><a class="reference" id="procedures-routines_toc" href="#procedures-routines">Routines</a></li>
<li><a class="reference" id="procedures-type-bound-operators_toc" href="#procedures-type-bound-operators">Type bound operators</a></li>
<li><a class="reference" id="procedures-nonoverloadable-builtins_toc" href="#procedures-nonoverloadable-builtins">Nonoverloadable builtins</a></li>
<li><a class="reference" id="procedures-var-parameters_toc" href="#procedures-var-parameters">Var parameters</a></li>
<li><a class="reference" id="procedures-var-return-type_toc" href="#procedures-var-return-type">Var return type</a></li>
<ul class="simple"><li><a class="reference" id="var-return-type-future-directions_toc" href="#var-return-type-future-directions">Future directions</a></li>
</ul><li><a class="reference" id="procedures-nrvo_toc" href="#procedures-nrvo">NRVO</a></li>
<li><a class="reference" id="procedures-overloading-of-the-subscript-operator_toc" href="#procedures-overloading-of-the-subscript-operator">Overloading of the subscript operator</a></li>
</ul><li><a class="reference" id="methods_toc" href="#methods">Methods</a></li>
<ul class="simple"><li><a class="reference" id="methods-multiminusmethods_toc" href="#methods-multiminusmethods">Multi-methods</a></li>
<li><a class="reference" id="methods-inhibit-dynamic-method-resolution-via-proccall_toc" href="#methods-inhibit-dynamic-method-resolution-via-proccall">Inhibit dynamic method resolution via procCall</a></li>
</ul><li><a class="reference" id="iterators-and-the-for-statement_toc" href="#iterators-and-the-for-statement">Iterators and the for statement</a></li>
<ul class="simple"><li><a class="reference" id="iterators-and-the-for-statement-implicit-itemsslashpairs-invocations_toc" href="#iterators-and-the-for-statement-implicit-itemsslashpairs-invocations">Implicit items/pairs invocations</a></li>
<li><a class="reference" id="iterators-and-the-for-statement-firstminusclass-iterators_toc" href="#iterators-and-the-for-statement-firstminusclass-iterators">First-class iterators</a></li>
</ul><li><a class="reference" id="converters_toc" href="#converters">Converters</a></li>
<li><a class="reference" id="type-sections_toc" href="#type-sections">Type sections</a></li>
<li><a class="reference" id="exception-handling_toc" href="#exception-handling">Exception handling</a></li>
<ul class="simple"><li><a class="reference" id="exception-handling-try-statement_toc" href="#exception-handling-try-statement">Try statement</a></li>
<li><a class="reference" id="exception-handling-try-expression_toc" href="#exception-handling-try-expression">Try expression</a></li>
<li><a class="reference" id="exception-handling-except-clauses_toc" href="#exception-handling-except-clauses">Except clauses</a></li>
<li><a class="reference" id="exception-handling-custom-exceptions_toc" href="#exception-handling-custom-exceptions">Custom exceptions</a></li>
<li><a class="reference" id="exception-handling-defer-statement_toc" href="#exception-handling-defer-statement">Defer statement</a></li>
<li><a class="reference" id="exception-handling-raise-statement_toc" href="#exception-handling-raise-statement">Raise statement</a></li>
<li><a class="reference" id="exception-handling-exception-hierarchy_toc" href="#exception-handling-exception-hierarchy">Exception hierarchy</a></li>
<li><a class="reference" id="exception-handling-imported-exceptions_toc" href="#exception-handling-imported-exceptions">Imported exceptions</a></li>
</ul><li><a class="reference" id="effect-system_toc" href="#effect-system">Effect system</a></li>
<ul class="simple"><li><a class="reference" id="effect-system-exception-tracking_toc" href="#effect-system-exception-tracking">Exception tracking</a></li>
<li><a class="reference" id="effect-system-effectsof-annotation_toc" href="#effect-system-effectsof-annotation">EffectsOf annotation</a></li>
<li><a class="reference" id="effect-system-tag-tracking_toc" href="#effect-system-tag-tracking">Tag tracking</a></li>
<li><a class="reference" id="effect-system-side-effects_toc" href="#effect-system-side-effects">Side effects</a></li>
<li><a class="reference" id="effect-system-gc-safety-effect_toc" href="#effect-system-gc-safety-effect">GC safety effect</a></li>
<li><a class="reference" id="effect-system-effects-pragma_toc" href="#effect-system-effects-pragma">Effects pragma</a></li>
</ul><li><a class="reference" id="generics_toc" href="#generics">Generics</a></li>
<ul class="simple"><li><a class="reference" id="generics-generic-procs_toc" href="#generics-generic-procs">Generic Procs</a></li>
<li><a class="reference" id="generics-is-operator_toc" href="#generics-is-operator">Is operator</a></li>
<li><a class="reference" id="generics-type-classes_toc" href="#generics-type-classes">Type classes</a></li>
<li><a class="reference" id="generics-implicit-generics_toc" href="#generics-implicit-generics">Implicit generics</a></li>
<li><a class="reference" id="generics-generic-inference-restrictions_toc" href="#generics-generic-inference-restrictions">Generic inference restrictions</a></li>
<li><a class="reference" id="generics-symbol-lookup-in-generics_toc" href="#generics-symbol-lookup-in-generics">Symbol lookup in generics</a></li>
<ul class="simple"><li><a class="reference" id="symbol-lookup-in-generics-open-and-closed-symbols_toc" href="#symbol-lookup-in-generics-open-and-closed-symbols">Open and Closed symbols</a></li>
</ul><li><a class="reference" id="generics-mixin-statement_toc" href="#generics-mixin-statement">Mixin statement</a></li>
<li><a class="reference" id="generics-bind-statement_toc" href="#generics-bind-statement">Bind statement</a></li>
<li><a class="reference" id="generics-delegating-bind-statements_toc" href="#generics-delegating-bind-statements">Delegating bind statements</a></li>
</ul><li><a class="reference" id="templates_toc" href="#templates">Templates</a></li>
<ul class="simple"><li><a class="reference" id="templates-typed-vs-untyped-parameters_toc" href="#templates-typed-vs-untyped-parameters">Typed vs untyped parameters</a></li>
<li><a class="reference" id="templates-passing-a-code-block-to-a-template_toc" href="#templates-passing-a-code-block-to-a-template">Passing a code block to a template</a></li>
<li><a class="reference" id="templates-varargs-of-untyped_toc" href="#templates-varargs-of-untyped">Varargs of untyped</a></li>
<li><a class="reference" id="templates-symbol-binding-in-templates_toc" href="#templates-symbol-binding-in-templates">Symbol binding in templates</a></li>
<li><a class="reference" id="templates-identifier-construction_toc" href="#templates-identifier-construction">Identifier construction</a></li>
<li><a class="reference" id="templates-lookup-rules-for-template-parameters_toc" href="#templates-lookup-rules-for-template-parameters">Lookup rules for template parameters</a></li>
<li><a class="reference" id="templates-hygiene-in-templates_toc" href="#templates-hygiene-in-templates">Hygiene in templates</a></li>
<li><a class="reference" id="templates-limitations-of-the-method-call-syntax_toc" href="#templates-limitations-of-the-method-call-syntax">Limitations of the method call syntax</a></li>
</ul><li><a class="reference" id="macros_toc" href="#macros">Macros</a></li>
<ul class="simple"><li><a class="reference" id="macros-debug-example_toc" href="#macros-debug-example">Debug example</a></li>
<li><a class="reference" id="macros-bindsym_toc" href="#macros-bindsym">bindSym</a></li>
<li><a class="reference" id="macros-postminusstatement-blocks_toc" href="#macros-postminusstatement-blocks">Post-statement blocks</a></li>
<li><a class="reference" id="macros-for-loop-macro_toc" href="#macros-for-loop-macro">For loop macro</a></li>
<li><a class="reference" id="macros-case-statement-macros_toc" href="#macros-case-statement-macros">Case statement macros</a></li>
</ul><li><a class="reference" id="special-types_toc" href="#special-types">Special Types</a></li>
<ul class="simple"><li><a class="reference" id="special-types-static-t_toc" href="#special-types-static-t">static[T]</a></li>
<li><a class="reference" id="special-types-typedesc-t_toc" href="#special-types-typedesc-t">typedesc[T]</a></li>
<li><a class="reference" id="special-types-typeof-operator_toc" href="#special-types-typeof-operator">typeof operator</a></li>
</ul><li><a class="reference" id="modules_toc" href="#modules">Modules</a></li>
<ul class="simple"><li><a class="reference" id="modules-import-statement_toc" href="#modules-import-statement">Import statement</a></li>
<li><a class="reference" id="modules-include-statement_toc" href="#modules-include-statement">Include statement</a></li>
<li><a class="reference" id="modules-module-names-in-imports_toc" href="#modules-module-names-in-imports">Module names in imports</a></li>
<li><a class="reference" id="modules-collective-imports-from-a-directory_toc" href="#modules-collective-imports-from-a-directory">Collective imports from a directory</a></li>
<li><a class="reference" id="modules-pseudo-importslashinclude-paths_toc" href="#modules-pseudo-importslashinclude-paths">Pseudo import/include paths</a></li>
<li><a class="reference" id="modules-from-import-statement_toc" href="#modules-from-import-statement">From import statement</a></li>
<li><a class="reference" id="modules-export-statement_toc" href="#modules-export-statement">Export statement</a></li>
<li><a class="reference" id="modules-scope-rules_toc" href="#modules-scope-rules">Scope rules</a></li>
<ul class="simple"><li><a class="reference" id="scope-rules-block-scope_toc" href="#scope-rules-block-scope">Block scope</a></li>
<li><a class="reference" id="scope-rules-tuple-or-object-scope_toc" href="#scope-rules-tuple-or-object-scope">Tuple or object scope</a></li>
<li><a class="reference" id="scope-rules-module-scope_toc" href="#scope-rules-module-scope">Module scope</a></li>
</ul><li><a class="reference" id="modules-packages_toc" href="#modules-packages">Packages</a></li>
</ul><li><a class="reference" id="compiler-messages_toc" href="#compiler-messages">Compiler Messages</a></li>
<li><a class="reference" id="pragmas_toc" href="#pragmas">Pragmas</a></li>
<ul class="simple"><li><a class="reference" id="pragmas-deprecated-pragma_toc" href="#pragmas-deprecated-pragma">deprecated pragma</a></li>
<li><a class="reference" id="pragmas-compiletime-pragma_toc" href="#pragmas-compiletime-pragma">compileTime pragma</a></li>
<li><a class="reference" id="pragmas-noreturn-pragma_toc" href="#pragmas-noreturn-pragma">noreturn pragma</a></li>
<li><a class="reference" id="pragmas-acyclic-pragma_toc" href="#pragmas-acyclic-pragma">acyclic pragma</a></li>
<li><a class="reference" id="pragmas-final-pragma_toc" href="#pragmas-final-pragma">final pragma</a></li>
<li><a class="reference" id="pragmas-shallow-pragma_toc" href="#pragmas-shallow-pragma">shallow pragma</a></li>
<li><a class="reference" id="pragmas-pure-pragma_toc" href="#pragmas-pure-pragma">pure pragma</a></li>
<li><a class="reference" id="pragmas-asmnostackframe-pragma_toc" href="#pragmas-asmnostackframe-pragma">asmNoStackFrame pragma</a></li>
<li><a class="reference" id="pragmas-error-pragma_toc" href="#pragmas-error-pragma">error pragma</a></li>
<li><a class="reference" id="pragmas-fatal-pragma_toc" href="#pragmas-fatal-pragma">fatal pragma</a></li>
<li><a class="reference" id="pragmas-warning-pragma_toc" href="#pragmas-warning-pragma">warning pragma</a></li>
<li><a class="reference" id="pragmas-hint-pragma_toc" href="#pragmas-hint-pragma">hint pragma</a></li>
<li><a class="reference" id="pragmas-line-pragma_toc" href="#pragmas-line-pragma">line pragma</a></li>
<li><a class="reference" id="pragmas-linearscanend-pragma_toc" href="#pragmas-linearscanend-pragma">linearScanEnd pragma</a></li>
<li><a class="reference" id="pragmas-computedgoto-pragma_toc" href="#pragmas-computedgoto-pragma">computedGoto pragma</a></li>
<li><a class="reference" id="pragmas-immediate-pragma_toc" href="#pragmas-immediate-pragma">immediate pragma</a></li>
<li><a class="reference" id="pragmas-redefine-pragma_toc" href="#pragmas-redefine-pragma">redefine pragma</a></li>
<li><a class="reference" id="pragmas-compilation-option-pragmas_toc" href="#pragmas-compilation-option-pragmas">compilation option pragmas</a></li>
<li><a class="reference" id="pragmas-push-and-pop-pragmas_toc" href="#pragmas-push-and-pop-pragmas">push and pop pragmas</a></li>
<li><a class="reference" id="pragmas-register-pragma_toc" href="#pragmas-register-pragma">register pragma</a></li>
<li><a class="reference" id="pragmas-global-pragma_toc" href="#pragmas-global-pragma">global pragma</a></li>
<li><a class="reference" id="pragmas-disabling-certain-messages_toc" href="#pragmas-disabling-certain-messages">Disabling certain messages</a></li>
<li><a class="reference" id="pragmas-used-pragma_toc" href="#pragmas-used-pragma">used pragma</a></li>
<li><a class="reference" id="pragmas-experimental-pragma_toc" href="#pragmas-experimental-pragma">experimental pragma</a></li>
</ul><li><a class="reference" id="implementation-specific-pragmas_toc" href="#implementation-specific-pragmas">Implementation Specific Pragmas</a></li>
<ul class="simple"><li><a class="reference" id="implementation-specific-pragmas-bitsize-pragma_toc" href="#implementation-specific-pragmas-bitsize-pragma">Bitsize pragma</a></li>
<li><a class="reference" id="implementation-specific-pragmas-size-pragma_toc" href="#implementation-specific-pragmas-size-pragma">size pragma</a></li>
<li><a class="reference" id="implementation-specific-pragmas-align-pragma_toc" href="#implementation-specific-pragmas-align-pragma">Align pragma</a></li>
<li><a class="reference" id="implementation-specific-pragmas-noalias-pragma_toc" href="#implementation-specific-pragmas-noalias-pragma">Noalias pragma</a></li>
<li><a class="reference" id="implementation-specific-pragmas-volatile-pragma_toc" href="#implementation-specific-pragmas-volatile-pragma">Volatile pragma</a></li>
<li><a class="reference" id="implementation-specific-pragmas-nodecl-pragma_toc" href="#implementation-specific-pragmas-nodecl-pragma">nodecl pragma</a></li>
<li><a class="reference" id="implementation-specific-pragmas-header-pragma_toc" href="#implementation-specific-pragmas-header-pragma">Header pragma</a></li>
<li><a class="reference" id="implementation-specific-pragmas-incompletestruct-pragma_toc" href="#implementation-specific-pragmas-incompletestruct-pragma">IncompleteStruct pragma</a></li>
<li><a class="reference" id="implementation-specific-pragmas-compile-pragma_toc" href="#implementation-specific-pragmas-compile-pragma">Compile pragma</a></li>
<li><a class="reference" id="implementation-specific-pragmas-link-pragma_toc" href="#implementation-specific-pragmas-link-pragma">Link pragma</a></li>
<li><a class="reference" id="implementation-specific-pragmas-passc-pragma_toc" href="#implementation-specific-pragmas-passc-pragma">passc pragma</a></li>
<li><a class="reference" id="implementation-specific-pragmas-localpassc-pragma_toc" href="#implementation-specific-pragmas-localpassc-pragma">localPassC pragma</a></li>
<li><a class="reference" id="implementation-specific-pragmas-passl-pragma_toc" href="#implementation-specific-pragmas-passl-pragma">passl pragma</a></li>
<li><a class="reference" id="implementation-specific-pragmas-emit-pragma_toc" href="#implementation-specific-pragmas-emit-pragma">Emit pragma</a></li>
<li><a class="reference" id="implementation-specific-pragmas-importcpp-pragma_toc" href="#implementation-specific-pragmas-importcpp-pragma">ImportCpp pragma</a></li>
<ul class="simple"><li><a class="reference" id="importcpp-pragma-namespaces_toc" href="#importcpp-pragma-namespaces">Namespaces</a></li>
<li><a class="reference" id="importcpp-pragma-importcpp-for-enums_toc" href="#importcpp-pragma-importcpp-for-enums">Importcpp for enums</a></li>
<li><a class="reference" id="importcpp-pragma-importcpp-for-procs_toc" href="#importcpp-pragma-importcpp-for-procs">Importcpp for procs</a></li>
<li><a class="reference" id="importcpp-pragma-wrapping-constructors_toc" href="#importcpp-pragma-wrapping-constructors">Wrapping constructors</a></li>
<li><a class="reference" id="importcpp-pragma-wrapping-destructors_toc" href="#importcpp-pragma-wrapping-destructors">Wrapping destructors</a></li>
<li><a class="reference" id="importcpp-pragma-importcpp-for-objects_toc" href="#importcpp-pragma-importcpp-for-objects">Importcpp for objects</a></li>
</ul><li><a class="reference" id="implementation-specific-pragmas-importjs-pragma_toc" href="#implementation-specific-pragmas-importjs-pragma">ImportJs pragma</a></li>
<li><a class="reference" id="implementation-specific-pragmas-importobjc-pragma_toc" href="#implementation-specific-pragmas-importobjc-pragma">ImportObjC pragma</a></li>
<li><a class="reference" id="implementation-specific-pragmas-codegendecl-pragma_toc" href="#implementation-specific-pragmas-codegendecl-pragma">CodegenDecl pragma</a></li>
<li><a class="reference" id="implementation-specific-pragmas-nimcppnonpod-pragma_toc" href="#implementation-specific-pragmas-nimcppnonpod-pragma"><tt class="docutils literal"><span class="pre"><span class="Identifier">cppNonPod</span></span></tt> pragma</a></li>
<li><a class="reference" id="implementation-specific-pragmas-compileminustime-define-pragmas_toc" href="#implementation-specific-pragmas-compileminustime-define-pragmas">compile-time define pragmas</a></li>
</ul><li><a class="reference" id="userminusdefined-pragmas_toc" href="#userminusdefined-pragmas">User-defined pragmas</a></li>
<ul class="simple"><li><a class="reference" id="userminusdefined-pragmas-pragma-pragma_toc" href="#userminusdefined-pragmas-pragma-pragma">pragma pragma</a></li>
<li><a class="reference" id="userminusdefined-pragmas-custom-annotations_toc" href="#userminusdefined-pragmas-custom-annotations">Custom annotations</a></li>
<li><a class="reference" id="userminusdefined-pragmas-macro-pragmas_toc" href="#userminusdefined-pragmas-macro-pragmas">Macro pragmas</a></li>
</ul><li><a class="reference" id="foreign-function-interface_toc" href="#foreign-function-interface">Foreign function interface</a></li>
<ul class="simple"><li><a class="reference" id="foreign-function-interface-importc-pragma_toc" href="#foreign-function-interface-importc-pragma">Importc pragma</a></li>
<li><a class="reference" id="foreign-function-interface-exportc-pragma_toc" href="#foreign-function-interface-exportc-pragma">Exportc pragma</a></li>
<li><a class="reference" id="foreign-function-interface-exportcpp-pragma_toc" href="#foreign-function-interface-exportcpp-pragma">Exportcpp pragma</a></li>
<li><a class="reference" id="foreign-function-interface-extern-pragma_toc" href="#foreign-function-interface-extern-pragma">Extern pragma</a></li>
<li><a class="reference" id="foreign-function-interface-bycopy-pragma_toc" href="#foreign-function-interface-bycopy-pragma">Bycopy pragma</a></li>
<li><a class="reference" id="foreign-function-interface-byref-pragma_toc" href="#foreign-function-interface-byref-pragma">Byref pragma</a></li>
<li><a class="reference" id="foreign-function-interface-varargs-pragma_toc" href="#foreign-function-interface-varargs-pragma">Varargs pragma</a></li>
<li><a class="reference" id="foreign-function-interface-union-pragma_toc" href="#foreign-function-interface-union-pragma">Union pragma</a></li>
<li><a class="reference" id="foreign-function-interface-packed-pragma_toc" href="#foreign-function-interface-packed-pragma">Packed pragma</a></li>
<li><a class="reference" id="foreign-function-interface-dynlib-pragma-for-import_toc" href="#foreign-function-interface-dynlib-pragma-for-import">Dynlib pragma for import</a></li>
<li><a class="reference" id="foreign-function-interface-dynlib-pragma-for-export_toc" href="#foreign-function-interface-dynlib-pragma-for-export">Dynlib pragma for export</a></li>
</ul><li><a class="reference" id="threads_toc" href="#threads">Threads</a></li>
<ul class="simple"><li><a class="reference" id="threads-thread-pragma_toc" href="#threads-thread-pragma">Thread pragma</a></li>
<li><a class="reference" id="threads-threadvar-pragma_toc" href="#threads-threadvar-pragma">Threadvar pragma</a></li>
<li><a class="reference" id="threads-threads-and-exceptions_toc" href="#threads-threads-and-exceptions">Threads and exceptions</a></li>
</ul><li><a class="reference" id="guards-and-locks_toc" href="#guards-and-locks">Guards and locks</a></li>
<ul class="simple"><li><a class="reference" id="guards-and-locks-guards-and-locks-sections_toc" href="#guards-and-locks-guards-and-locks-sections">Guards and locks sections</a></li>
<ul class="simple"><li><a class="reference" id="guards-and-locks-sections-protecting-global-variables_toc" href="#guards-and-locks-sections-protecting-global-variables">Protecting global variables</a></li>
<li><a class="reference" id="guards-and-locks-sections-protecting-general-locations_toc" href="#guards-and-locks-sections-protecting-general-locations">Protecting general locations</a></li>
</ul></ul><li><a class="reference" id="strict-definitions-and-nimout-parameters_toc" href="#strict-definitions-and-nimout-parameters">Strict definitions and <tt class="docutils literal"><span class="pre"><span class="Keyword">out</span></span></tt> parameters</a></li>
<ul class="simple"><li><a class="reference" id="strict-definitions-and-nimout-parameters-nimout-parameters_toc" href="#strict-definitions-and-nimout-parameters-nimout-parameters"><tt class="docutils literal"><span class="pre"><span class="Keyword">out</span></span></tt> parameters</a></li>
<li><a class="reference" id="strict-definitions-and-nimout-parameters-out-parameters-and-exception-handling_toc" href="#strict-definitions-and-nimout-parameters-out-parameters-and-exception-handling">Out parameters and exception handling</a></li>
<li><a class="reference" id="strict-definitions-and-nimout-parameters-out-parameters-and-inheritance_toc" href="#strict-definitions-and-nimout-parameters-out-parameters-and-inheritance">Out parameters and inheritance</a></li>
</ul>
</ul>

  </div>
  <div class="nine columns" id="content">
    <a href="https://github.com/nim-lang/Nim/tree/devel/doc/manual.md#L1" class="link-seesrc" target="_blank">Source</a>&nbsp;&nbsp;
<a href="https://github.com/nim-lang/Nim/edit/devel/doc/manual.md#L1" class="link-seesrc" target="_blank" >Edit</a>&nbsp;&nbsp;

    <div id="tocRoot"></div>
    
    <p class="module-desc"><table class="docinfo" frame="void" rules="none"><col class="docinfo-name" /><col class="docinfo-content" /><tbody valign="top"><tr><th class="docinfo-name">Authors:</th><td>Andreas Rumpf, Zahary Karadjov</td></tr>
<tr><th class="docinfo-name">Version:</th><td>2.3.1</td></tr>
</tbody></table><blockquote class="markdown-quote"><p>&quot;Complexity&quot; seems to be a lot like &quot;energy&quot;: you can transfer it from the end-user to one/some of the other players, but the total amount seems to remain pretty much constant for a given task. -- Ran</p></blockquote>

<h1><a class="toc-backref" id="about-this-document" href="#about-this-document">About this document</a></h1><p><strong>Note</strong>: This document is a draft! Several of Nim's features may need more precise wording. This manual is constantly evolving into a proper specification.</p>
<p><strong>Note</strong>: The experimental features of Nim are covered <a class="reference external" href="manual_experimental.html">here</a>.</p>
<p><strong>Note</strong>: Assignments, moves, and destruction are specified in the <a class="reference external" href="destructors.html">destructors</a> document.</p>
<p>This document describes the lexis, the syntax, and the semantics of the Nim language.</p>
<p>To learn how to compile Nim programs and generate documentation see the <a class="reference external" href="nimc.html">Compiler User Guide</a> and the <a class="reference external" href="docgen.html">DocGen Tools Guide</a>.</p>
<p>The language constructs are explained using an extended BNF, in which <tt class="docutils literal"><span class="pre"><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">)</span><span class="Operator">*</span></span></tt> means 0 or more <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span></span></tt>'s, <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span><span class="Operator">+</span></span></tt> means 1 or more <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span></span></tt>'s, and <tt class="docutils literal"><span class="pre"><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">)</span><span class="Operator">?</span></span></tt> means an optional <em>a</em>. Parentheses may be used to group elements.</p>
<p><tt class="docutils literal"><span class="pre"><span class="Operator">&amp;</span></span></tt> is the lookahead operator; <tt class="docutils literal"><span class="pre"><span class="Operator">&amp;</span><span class="Identifier">a</span></span></tt> means that an <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span></span></tt> is expected but not consumed. It will be consumed in the following rule.</p>
<p>The <tt class="docutils literal"><span class="pre"><span class="Operator">|</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Operator">/</span></span></tt> symbols are used to mark alternatives and have the lowest precedence. <tt class="docutils literal"><span class="pre"><span class="Operator">/</span></span></tt> is the ordered choice that requires the parser to try the alternatives in the given order. <tt class="docutils literal"><span class="pre"><span class="Operator">/</span></span></tt> is often used to ensure the grammar is not ambiguous.</p>
<p>Non-terminals start with a lowercase letter, abstract terminal symbols are in UPPERCASE. Verbatim terminal symbols (including keywords) are quoted with <tt class="docutils literal"><span class="pre"><span class="CharLit">'</span></span></tt>. An example:</p>
<pre>ifStmt = 'if' expr ':' stmts ('elif' expr ':' stmts)* ('else' stmts)?</pre>
<p>The binary <tt class="docutils literal"><span class="pre"><span class="Operator">^*</span></span></tt> operator is used as a shorthand for 0 or more occurrences separated by its second argument; likewise <tt class="docutils literal"><span class="pre"><span class="Operator">^+</span></span></tt> means 1 or more occurrences: <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span> <span class="Operator">^+</span> <span class="Identifier">b</span></span></tt> is short for <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span> <span class="Punctuation">(</span><span class="Identifier">b</span> <span class="Identifier">a</span><span class="Punctuation">)</span><span class="Operator">*</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span> <span class="Operator">^*</span> <span class="Identifier">b</span></span></tt> is short for <tt class="docutils literal"><span class="pre"><span class="Punctuation">(</span><span class="Identifier">a</span> <span class="Punctuation">(</span><span class="Identifier">b</span> <span class="Identifier">a</span><span class="Punctuation">)</span><span class="Operator">*</span><span class="Punctuation">)</span><span class="Operator">?</span></span></tt>. Example:</p>
<pre>arrayConstructor = '[' expr ^* ',' ']'</pre>
<p>Other parts of Nim, like scoping rules or runtime semantics, are described informally.</p>

<h1><a class="toc-backref" id="definitions" href="#definitions">Definitions</a></h1><p>Nim code specifies a computation that acts on a memory consisting of components called <span id="locations_1">locations</span>. A variable is basically a name for a location. Each variable and location is of a certain <span id="type_1">type</span>. The variable's type is called <span id="static-type_1">static type</span>, the location's type is called <span id="dynamic-type_1">dynamic type</span>. If the static type is not the same as the dynamic type, it is a super-type or subtype of the dynamic type.</p>
<p>An <span id="identifier_1">identifier</span> is a symbol declared as a name for a variable, type, procedure, etc. The region of the program over which a declaration applies is called the <span id="scope_1">scope</span> of the declaration. Scopes can be nested. The meaning of an identifier is determined by the smallest enclosing scope in which the identifier is declared unless overloading resolution rules suggest otherwise.</p>
<p>An expression specifies a computation that produces a value or location. Expressions that produce locations are called <span id="lminusvalues_1">l-values</span>. An l-value can denote either a location or the value the location contains, depending on the context.</p>
<p>A Nim <span id="program_1">program</span> consists of one or more text <span id="source-files_1">source files</span> containing Nim code. It is processed by a Nim <span id="compiler_1">compiler</span> into an <span id="executable_1">executable</span>. The nature of this executable depends on the compiler implementation; it may, for example, be a native binary or JavaScript source code.</p>
<p>In a typical Nim program, most of the code is compiled into the executable. However, some code may be executed at <span id="compileminustime_1">compile-time</span>. This can include constant expressions, macro definitions, and Nim procedures used by macro definitions. Most of the Nim language is supported at compile-time, but there are some restrictions -- see <a class="reference internal" href="#restrictions-on-compileminustime-execution">Restrictions on Compile-Time Execution</a> for details. We use the term <span id="runtime_1">runtime</span> to cover both compile-time execution and code execution in the executable.</p>
<p>The compiler parses Nim source code into an internal data structure called the <span id="abstract-syntax-tree_1">abstract syntax tree</span> (<span id="ast_1">AST</span>). Then, before executing the code or compiling it into the executable, it transforms the AST through <span id="semantic-analysis_1">semantic analysis</span>. This adds semantic information such as expression types, identifier meanings, and in some cases expression values. An error detected during semantic analysis is called a <span id="static-error_1">static error</span>. Errors described in this manual are static errors when not otherwise specified.</p>
<p>A <span id="panic_1">panic</span> is an error that the implementation detects and reports at runtime. The method for reporting such errors is via <em>raising exceptions</em> or <em>dying with a fatal error</em>. However, the implementation provides a means to disable these <span id="runtime-checks_1">runtime checks</span>. See the section <a class="reference internal" href="#pragmas">Pragmas</a> for details.</p>
<p>Whether a panic results in an exception or in a fatal error is implementation specific. Thus, the following program is invalid; even though the code purports to catch the <tt class="docutils literal"><span class="pre"><span class="Identifier">IndexDefect</span></span></tt> from an out-of-bounds array access, the compiler may instead choose to allow the program to die with a fatal error.</p>
<p><pre class="listing"><span class="Keyword">var</span> <span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">array</span><span class="Punctuation">[</span><span class="FloatNumber">0.</span><span class="Operator">.</span><span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="Identifier">char</span><span class="Punctuation">]</span>
<span class="Keyword">let</span> <span class="Identifier">i</span> <span class="Operator">=</span> <span class="DecNumber">5</span>
<span class="Keyword">try</span><span class="Punctuation">:</span>
  <span class="Identifier">a</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="CharLit">'N'</span>
<span class="Keyword">except</span> <span class="Identifier">IndexDefect</span><span class="Punctuation">:</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;invalid index&quot;</span></pre></p>
<p>The current implementation allows switching between these different behaviors via <tt class="docutils literal"><span class="pre option">--panics:on|off</span></tt>. When panics are turned on, the program dies with a panic, if they are turned off the runtime errors are turned into exceptions. The benefit of <tt class="docutils literal"><span class="pre option">--panics:on</span></tt> is that it produces smaller binary code and the compiler has more freedom to optimize the code.</p>
<p>An <span id="unchecked-runtime-error_1">unchecked runtime error</span> is an error that is not guaranteed to be detected and can cause the subsequent behavior of the computation to be arbitrary. Unchecked runtime errors cannot occur if only <span id="safe_1">safe</span> language features are used and if no runtime checks are disabled.</p>
<p>A <span id="constant-expression_1">constant expression</span> is an expression whose value can be computed during a semantic analysis of the code in which it appears. It is never an l-value and never has side effects. Constant expressions are not limited to the capabilities of semantic analysis, such as constant folding; they can use all Nim language features that are supported for compile-time execution. Since constant expressions can be used as an input to semantic analysis (such as for defining array bounds), this flexibility requires the compiler to interleave semantic analysis and compile-time code execution.</p>
<p>It is mostly accurate to picture semantic analysis proceeding top to bottom and left to right in the source code, with compile-time code execution interleaved when necessary to compute values that are required for subsequent semantic analysis. We will see much later in this document that macro invocation not only requires this interleaving, but also creates a situation where semantic analysis does not entirely proceed top to bottom and left to right.</p>

<h1><a class="toc-backref" id="lexical-analysis" href="#lexical-analysis">Lexical Analysis</a></h1>
<h2><a class="toc-backref" id="lexical-analysis-encoding" href="#lexical-analysis-encoding">Encoding</a></h2><p>All Nim source files are in the UTF-8 encoding (or its ASCII subset). Other encodings are not supported. Any of the standard platform line termination sequences can be used - the Unix form using ASCII LF (linefeed), the Windows form using the ASCII sequence CR LF (return followed by linefeed), or the old Macintosh form using the ASCII CR (return) character. All of these forms can be used equally, regardless of the platform.</p>

<h2><a class="toc-backref" id="lexical-analysis-indentation" href="#lexical-analysis-indentation">Indentation</a></h2><p>Nim's standard grammar describes an <span id="indentation-sensitive_1">indentation sensitive</span> language. This means that all the control structures are recognized by indentation. Indentation consists only of spaces; tabulators are not allowed.</p>
<p>The indentation handling is implemented as follows: The lexer annotates the following token with the preceding number of spaces; indentation is not a separate token. This trick allows parsing of Nim with only 1 token of lookahead.</p>
<p>The parser uses a stack of indentation levels: the stack consists of integers counting the spaces. The indentation information is queried at strategic places in the parser but ignored otherwise: The pseudo-terminal <tt class="docutils literal"><span class="pre"><span class="Identifier">IND</span><span class="Punctuation">{</span><span class="Operator">&gt;</span><span class="Punctuation">}</span></span></tt> denotes an indentation that consists of more spaces than the entry at the top of the stack; <tt class="docutils literal"><span class="pre"><span class="Identifier">IND</span><span class="Punctuation">{</span><span class="Operator">=</span><span class="Punctuation">}</span></span></tt> an indentation that has the same number of spaces. <tt class="docutils literal"><span class="pre"><span class="Identifier">DED</span></span></tt> is another pseudo terminal that describes the <em>action</em> of popping a value from the stack, <tt class="docutils literal"><span class="pre"><span class="Identifier">IND</span><span class="Punctuation">{</span><span class="Operator">&gt;</span><span class="Punctuation">}</span></span></tt> then implies to push onto the stack.</p>
<p>With this notation we can now easily define the core of the grammar: A block of statements (simplified example):</p>
<pre>ifStmt = 'if' expr ':' stmt
         (IND{=} 'elif' expr ':' stmt)*
         (IND{=} 'else' ':' stmt)?

simpleStmt = ifStmt / ...

stmt = IND{&gt;} stmt ^+ IND{=} DED  # list of statements
     / simpleStmt                 # or a simple statement</pre>

<h2><a class="toc-backref" id="lexical-analysis-comments" href="#lexical-analysis-comments">Comments</a></h2><p>Comments start anywhere outside a string or character literal with the hash character <tt class="docutils literal"><span class="pre"><span class="Comment">#</span></span></tt>. Comments consist of a concatenation of <span id="comment-pieces_1">comment pieces</span>. A comment piece starts with <tt class="docutils literal"><span class="pre"><span class="Comment">#</span></span></tt> and runs until the end of the line. The end of line characters belong to the piece. If the next line only consists of a comment piece with no other tokens between it and the preceding one, it does not start a new comment:</p>
<p><pre class="listing"><span class="Identifier">i</span> <span class="Operator">=</span> <span class="DecNumber">0</span>     <span class="Comment"># This is a single comment over multiple lines.</span>
  <span class="Comment"># The lexer merges these two pieces.</span>
  <span class="Comment"># The comment continues here.</span></pre></p>
<p><span id="documentation-comments_1">Documentation comments</span> are comments that start with two <tt class="docutils literal"><span class="pre"><span class="Comment">##</span></span></tt>. Documentation comments are tokens; they are only allowed at certain places in the input file as they belong to the syntax tree.</p>

<h2><a class="toc-backref" id="lexical-analysis-multiline-comments" href="#lexical-analysis-multiline-comments">Multiline comments</a></h2><p>Starting with version 0.13.0 of the language Nim supports multiline comments. They look like:</p>
<p><pre class="listing"><span class="LongComment">#[Comment here.
Multiple lines
are not a problem.]#</span></pre></p>
<p>Multiline comments support nesting:</p>
<p><pre class="listing"><span class="LongComment">#[  #[ Multiline comment in already
   commented out code. ]#
proc p[T](x: T) = discard
]#</span></pre></p>
<p>Multiline documentation comments also exist and support nesting too:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">foo</span> <span class="Operator">=</span>
  <span class="LongComment">##[Long documentation comment
     here.
  ]##</span></pre></p>
<p>You can also use the <a class="reference external" href="#statements-and-expressions-discard-statement">discard statement</a> together with <a class="reference external" href="#lexical-analysis-triple-quoted-string-literals">triple quoted string literals</a> to create multiline comments:</p>
<p><pre class="listing"><span class="Keyword">discard</span> <span class="LongStringLit">&quot;&quot;&quot; You can have any Nim code text commented
out inside this with no indentation restrictions.
      yes(&quot;May I ask a pointless question?&quot;) &quot;&quot;&quot;</span></pre></p>
<p>This was how multiline comments were done before version 0.13.0, and it is used to provide specifications to <a class="reference external" href="testament.html#writing-unit-tests">testament</a> test framework.</p>

<h2><a class="toc-backref" id="lexical-analysis-identifiers-amp-keywords" href="#lexical-analysis-identifiers-amp-keywords">Identifiers &amp; Keywords</a></h2><p>Identifiers in Nim can be any string of letters, digits and underscores, with the following restrictions:</p>
<ul class="simple"><li>begins with a letter</li>
<li>does not end with an underscore <tt class="docutils literal"><span class="pre"><span class="Identifier">_</span></span></tt></li>
<li><p>two immediate following underscores <tt class="docutils literal"><span class="pre"><span class="Identifier">__</span></span></tt> are not allowed:</p>
<p><pre class="listing">letter ::= 'A'..'Z' | 'a'..'z' | '\x80'..'\xff'
digit ::= '0'..'9'
IDENTIFIER ::= letter ( ['_'] (letter | digit) )*</pre></p>
</li>
</ul>
<p>Currently, any Unicode character with an ordinal value &gt; 127 (non-ASCII) is classified as a <tt class="docutils literal"><span class="pre"><span class="Identifier">letter</span></span></tt> and may thus be part of an identifier but later versions of the language may assign some Unicode characters to belong to the operator characters instead.</p>
<p>The following keywords are reserved and cannot be used as identifiers:</p>
<p><pre class="listing"><span class="Keyword">addr</span> <span class="Keyword">and</span> <span class="Keyword">as</span> <span class="Keyword">asm</span>
<span class="Keyword">bind</span> <span class="Keyword">block</span> <span class="Keyword">break</span>
<span class="Keyword">case</span> <span class="Keyword">cast</span> <span class="Keyword">concept</span> <span class="Keyword">const</span> <span class="Keyword">continue</span> <span class="Keyword">converter</span>
<span class="Keyword">defer</span> <span class="Keyword">discard</span> <span class="Keyword">distinct</span> <span class="Keyword">div</span> <span class="Keyword">do</span>
<span class="Keyword">elif</span> <span class="Keyword">else</span> <span class="Keyword">end</span> <span class="Keyword">enum</span> <span class="Keyword">except</span> <span class="Keyword">export</span>
<span class="Keyword">finally</span> <span class="Keyword">for</span> <span class="Keyword">from</span> <span class="Keyword">func</span>
<span class="Keyword">if</span> <span class="Keyword">import</span> <span class="Keyword">in</span> <span class="Keyword">include</span> <span class="Keyword">interface</span> <span class="Keyword">is</span> <span class="Keyword">isnot</span> <span class="Keyword">iterator</span>
<span class="Keyword">let</span>
<span class="Keyword">macro</span> <span class="Keyword">method</span> <span class="Keyword">mixin</span> <span class="Keyword">mod</span>
<span class="Keyword">nil</span> <span class="Keyword">not</span> <span class="Keyword">notin</span>
<span class="Keyword">object</span> <span class="Keyword">of</span> <span class="Keyword">or</span> <span class="Keyword">out</span>
<span class="Keyword">proc</span> <span class="Keyword">ptr</span>
<span class="Keyword">raise</span> <span class="Keyword">ref</span> <span class="Keyword">return</span>
<span class="Keyword">shl</span> <span class="Keyword">shr</span> <span class="Keyword">static</span>
<span class="Keyword">template</span> <span class="Keyword">try</span> <span class="Keyword">tuple</span> <span class="Keyword">type</span>
<span class="Keyword">using</span>
<span class="Keyword">var</span>
<span class="Keyword">when</span> <span class="Keyword">while</span>
<span class="Keyword">xor</span>
<span class="Keyword">yield</span>
</pre></p>
<p>Some keywords are unused; they are reserved for future developments of the language.</p>

<h2><a class="toc-backref" id="lexical-analysis-identifier-equality" href="#lexical-analysis-identifier-equality">Identifier equality</a></h2><p>Two identifiers are considered equal if the following algorithm returns true:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">sameIdentifier</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">bool</span> <span class="Operator">=</span>
  <span class="Identifier">a</span><span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">]</span> <span class="Operator">==</span> <span class="Identifier">b</span><span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">]</span> <span class="Keyword">and</span>
    <span class="Identifier">a</span><span class="Operator">.</span><span class="Identifier">replace</span><span class="Punctuation">(</span><span class="StringLit">&quot;_&quot;</span><span class="Punctuation">,</span> <span class="StringLit">&quot;&quot;</span><span class="Punctuation">)</span><span class="Operator">.</span><span class="Identifier">toLowerAscii</span> <span class="Operator">==</span> <span class="Identifier">b</span><span class="Operator">.</span><span class="Identifier">replace</span><span class="Punctuation">(</span><span class="StringLit">&quot;_&quot;</span><span class="Punctuation">,</span> <span class="StringLit">&quot;&quot;</span><span class="Punctuation">)</span><span class="Operator">.</span><span class="Identifier">toLowerAscii</span></pre></p>
<p>That means only the first letters are compared in a case-sensitive manner. Other letters are compared case-insensitively within the ASCII range and underscores are ignored.</p>
<p>This rather unorthodox way to do identifier comparisons is called <span id="partial-caseminusinsensitivity_1">partial case-insensitivity</span> and has some advantages over the conventional case sensitivity:</p>
<p>It allows programmers to mostly use their own preferred spelling style, be it humpStyle or snake_style, and libraries written by different programmers cannot use incompatible conventions. A Nim-aware editor or IDE can show the identifiers as preferred. Another advantage is that it frees the programmer from remembering the exact spelling of an identifier. The exception with respect to the first letter allows common code like <tt class="docutils literal"><span class="pre"><span class="Keyword">var</span> <span class="Identifier">foo</span><span class="Punctuation">:</span> <span class="Identifier">Foo</span></span></tt> to be parsed unambiguously.</p>
<p>Note that this rule also applies to keywords, meaning that <tt class="docutils literal"><span class="pre"><span class="Keyword">notin</span></span></tt> is the same as <tt class="docutils literal"><span class="pre"><span class="Keyword">notIn</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Keyword">not_in</span></span></tt> (all-lowercase version (<tt class="docutils literal"><span class="pre"><span class="Keyword">notin</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">isnot</span></span></tt>) is the preferred way of writing keywords).</p>
<p>Historically, Nim was a fully <span id="styleminusinsensitive_1">style-insensitive</span> language. This meant that it was not case-sensitive and underscores were ignored and there was not even a distinction between <tt class="docutils literal"><span class="pre"><span class="Identifier">foo</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">Foo</span></span></tt>.</p>

<h2><a class="toc-backref" id="lexical-analysis-keywords-as-identifiers" href="#lexical-analysis-keywords-as-identifiers">Keywords as identifiers</a></h2><p>If a keyword is enclosed in backticks it loses its keyword property and becomes an ordinary identifier.</p>
<p>Examples</p>
<p><pre class="listing"><span class="Keyword">var</span> <span class="Punctuation">`</span><span class="Keyword">var</span><span class="Punctuation">`</span> <span class="Operator">=</span> <span class="StringLit">&quot;Hello Stropping&quot;</span></pre></p>
<p><pre class="listing"><span class="Keyword">type</span> <span class="Identifier">Obj</span> <span class="Operator">=</span> <span class="Keyword">object</span>
  <span class="Punctuation">`</span><span class="Keyword">type</span><span class="Punctuation">`</span><span class="Punctuation">:</span> <span class="Identifier">int</span>

<span class="Keyword">let</span> <span class="Punctuation">`</span><span class="Keyword">object</span><span class="Punctuation">`</span> <span class="Operator">=</span> <span class="Identifier">Obj</span><span class="Punctuation">(</span><span class="Punctuation">`</span><span class="Keyword">type</span><span class="Punctuation">`</span><span class="Punctuation">:</span> <span class="DecNumber">9</span><span class="Punctuation">)</span>
<span class="Identifier">assert</span> <span class="Punctuation">`</span><span class="Keyword">object</span><span class="Punctuation">`</span> <span class="Keyword">is</span> <span class="Identifier">Obj</span>
<span class="Identifier">assert</span> <span class="Punctuation">`</span><span class="Keyword">object</span><span class="Punctuation">`</span><span class="Operator">.</span><span class="Punctuation">`</span><span class="Keyword">type</span><span class="Punctuation">`</span> <span class="Operator">==</span> <span class="DecNumber">9</span>

<span class="Keyword">var</span> <span class="Punctuation">`</span><span class="Keyword">var</span><span class="Punctuation">`</span> <span class="Operator">=</span> <span class="DecNumber">42</span>
<span class="Keyword">let</span> <span class="Punctuation">`</span><span class="Keyword">let</span><span class="Punctuation">`</span> <span class="Operator">=</span> <span class="DecNumber">8</span>
<span class="Identifier">assert</span> <span class="Punctuation">`</span><span class="Keyword">var</span><span class="Punctuation">`</span> <span class="Operator">+</span> <span class="Punctuation">`</span><span class="Keyword">let</span><span class="Punctuation">`</span> <span class="Operator">==</span> <span class="DecNumber">50</span>

<span class="Keyword">const</span> <span class="Punctuation">`</span><span class="Identifier">assert</span><span class="Punctuation">`</span> <span class="Operator">=</span> <span class="Identifier">true</span>
<span class="Identifier">assert</span> <span class="Punctuation">`</span><span class="Identifier">assert</span><span class="Punctuation">`</span></pre></p>

<h2><a class="toc-backref" id="lexical-analysis-string-literals" href="#lexical-analysis-string-literals">String literals</a></h2><p>Terminal symbol in the grammar: <tt class="docutils literal"><span class="pre"><span class="Identifier">STR_LIT</span></span></tt>.</p>
<p>String literals can be delimited by matching double quotes, and can contain the following <span id="escape-sequences_1">escape sequences</span>:</p>
<table border="1" class="docutils"><tr><th>Escape sequence</th><th>Meaning</th></tr>
<tr><td><tt class="docutils literal"><span class="pre">\p</span></tt></td><td>platform specific newline: CRLF on Windows, LF on Unix</td></tr>
<tr><td><tt class="docutils literal"><span class="pre">\r</span></tt>, <tt class="docutils literal"><span class="pre">\c</span></tt></td><td><span id="carriage-return_1">carriage return</span></td></tr>
<tr><td><tt class="docutils literal"><span class="pre">\n</span></tt>, <tt class="docutils literal"><span class="pre">\l</span></tt></td><td><span id="line-feed_1">line feed</span> (often called <span id="newline_1">newline</span>)</td></tr>
<tr><td><tt class="docutils literal"><span class="pre">\f</span></tt></td><td><span id="form-feed_1">form feed</span></td></tr>
<tr><td><tt class="docutils literal"><span class="pre">\t</span></tt></td><td><span id="tabulator_1">tabulator</span></td></tr>
<tr><td><tt class="docutils literal"><span class="pre">\v</span></tt></td><td><span id="vertical-tabulator_1">vertical tabulator</span></td></tr>
<tr><td><tt class="docutils literal"><span class="pre">\\</span></tt></td><td><span id="backslash_1">backslash</span></td></tr>
<tr><td><tt class="docutils literal"><span class="pre">\&quot;</span></tt></td><td><span id="quotation-mark_1">quotation mark</span></td></tr>
<tr><td><tt class="docutils literal"><span class="pre">\'</span></tt></td><td><span id="apostrophe_1">apostrophe</span></td></tr>
<tr><td><tt class="docutils literal"><span class="pre">\</span></tt> '0'..'9'+</td><td><span id="character-with-decimal-value-d_1">character with decimal value d</span>; all decimal digits directly following are used for the character</td></tr>
<tr><td><tt class="docutils literal"><span class="pre">\a</span></tt></td><td><span id="alert_1">alert</span></td></tr>
<tr><td><tt class="docutils literal"><span class="pre">\b</span></tt></td><td><span id="backspace_1">backspace</span></td></tr>
<tr><td><tt class="docutils literal"><span class="pre">\e</span></tt></td><td><span id="escape_1">escape</span> <span id="esc_1">[ESC]</span></td></tr>
<tr><td><tt class="docutils literal"><span class="pre">\x</span></tt> HH</td><td><span id="character-with-hex-value-hh_1">character with hex value HH</span>; exactly two hex digits are allowed</td></tr>
<tr><td><tt class="docutils literal"><span class="pre">\u</span></tt> HHHH</td><td><span id="unicode-codepoint-with-hex-value-hhhh_1">unicode codepoint with hex value HHHH</span>; exactly four hex digits are allowed</td></tr>
<tr><td><tt class="docutils literal"><span class="pre">\u</span></tt> {H+}</td><td><span id="unicode-codepoint_1">unicode codepoint</span>; all hex digits enclosed in <tt class="docutils literal"><span class="pre"><span class="Punctuation">{</span><span class="Punctuation">}</span></span></tt> are used for the codepoint</td></tr>
</table><p>Strings in Nim may contain any 8-bit value, even embedded zeros. However, some operations may interpret the first binary zero as a terminator.</p>

<h2><a class="toc-backref" id="lexical-analysis-triple-quoted-string-literals" href="#lexical-analysis-triple-quoted-string-literals">Triple quoted string literals</a></h2><p>Terminal symbol in the grammar: <tt class="docutils literal"><span class="pre"><span class="Identifier">TRIPLESTR_LIT</span></span></tt>.</p>
<p>String literals can also be delimited by three double quotes <tt class="docutils literal"><span class="pre"><span class="LongStringLit">&quot;&quot;&quot;</span></span></tt> ... <tt class="docutils literal"><span class="pre"><span class="LongStringLit">&quot;&quot;&quot;</span></span></tt>. Literals in this form may run for several lines, may contain <tt class="docutils literal"><span class="pre"><span class="StringLit">&quot;</span></span></tt> and do not interpret any escape sequences. For convenience, when the opening <tt class="docutils literal"><span class="pre"><span class="LongStringLit">&quot;&quot;&quot;</span></span></tt> is followed by a newline (there may be whitespace between the opening <tt class="docutils literal"><span class="pre"><span class="LongStringLit">&quot;&quot;&quot;</span></span></tt> and the newline), the newline (and the preceding whitespace) is not included in the string. The ending of the string literal is defined by the pattern <tt class="docutils literal"><span class="pre"><span class="LongStringLit">&quot;&quot;&quot;[^&quot;]</span></span></tt>, so this:</p>
<p><pre class="listing"><span class="LongStringLit">&quot;&quot;&quot;&quot;long string within quotes&quot;&quot;&quot;&quot;</span></pre></p>
<p>Produces:</p>
<pre>&quot;long string within quotes&quot;</pre>

<h2><a class="toc-backref" id="lexical-analysis-raw-string-literals" href="#lexical-analysis-raw-string-literals">Raw string literals</a></h2><p>Terminal symbol in the grammar: <tt class="docutils literal"><span class="pre"><span class="Identifier">RSTR_LIT</span></span></tt>.</p>
<p>There are also raw string literals that are preceded with the letter <tt class="docutils literal"><span class="pre"><span class="Identifier">r</span></span></tt> (or <tt class="docutils literal"><span class="pre"><span class="Identifier">R</span></span></tt>) and are delimited by matching double quotes (just like ordinary string literals) and do not interpret the escape sequences. This is especially convenient for regular expressions or Windows paths:</p>
<p><pre class="listing"><span class="Keyword">var</span> <span class="Identifier">f</span> <span class="Operator">=</span> <span class="Identifier">openFile</span><span class="Punctuation">(</span><span class="RawData">r&quot;C:\texts\text.txt&quot;</span><span class="Punctuation">)</span> <span class="Comment"># a raw string, so ``\t`` is no tab</span></pre></p>
<p>To produce a single <tt class="docutils literal"><span class="pre"><span class="StringLit">&quot;</span></span></tt> within a raw string literal, it has to be doubled:</p>
<p><pre class="listing"><span class="RawData">r&quot;a&quot;&quot;</span><span class="RawData">b&quot;</span></pre></p>
<p>Produces:</p>
<pre>a&quot;b</pre>
<p><tt class="docutils literal"><span class="pre"><span class="LongStringLit">r&quot;&quot;&quot;&quot;</span></span></tt> is not possible with this notation, because the three leading quotes introduce a triple quoted string literal. <tt class="docutils literal"><span class="pre"><span class="LongStringLit">r&quot;&quot;&quot;</span></span></tt> is the same as <tt class="docutils literal"><span class="pre"><span class="LongStringLit">&quot;&quot;&quot;</span></span></tt> since triple quoted string literals do not interpret escape sequences either.</p>

<h2><a class="toc-backref" id="lexical-analysis-generalized-raw-string-literals" href="#lexical-analysis-generalized-raw-string-literals">Generalized raw string literals</a></h2><p>Terminal symbols in the grammar: <tt class="docutils literal"><span class="pre"><span class="Identifier">GENERALIZED_STR_LIT</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Identifier">GENERALIZED_TRIPLESTR_LIT</span></span></tt>.</p>
<p>The construct <tt class="docutils literal"><span class="pre"><span class="RawData">identifier&quot;string literal&quot;</span></span></tt> (without whitespace between the identifier and the opening quotation mark) is a generalized raw string literal. It is a shortcut for the construct <tt class="docutils literal"><span class="pre"><span class="Identifier">identifier</span><span class="Punctuation">(</span><span class="RawData">r&quot;string literal&quot;</span><span class="Punctuation">)</span></span></tt>, so it denotes a routine call with a raw string literal as its only argument. Generalized raw string literals are especially convenient for embedding mini languages directly into Nim (for example regular expressions).</p>
<p>The construct <tt class="docutils literal"><span class="pre"><span class="LongStringLit">identifier&quot;&quot;&quot;string literal&quot;&quot;&quot;</span></span></tt> exists too. It is a shortcut for <tt class="docutils literal"><span class="pre"><span class="Identifier">identifier</span><span class="Punctuation">(</span><span class="LongStringLit">&quot;&quot;&quot;string literal&quot;&quot;&quot;</span><span class="Punctuation">)</span></span></tt>.</p>

<h2><a class="toc-backref" id="lexical-analysis-character-literals" href="#lexical-analysis-character-literals">Character literals</a></h2><p>Character literals are enclosed in single quotes <tt class="docutils literal"><span class="pre"><span class="CharLit">''</span></span></tt> and can contain the same escape sequences as strings - with one exception: the platform dependent <span id="newline_2">newline</span> (<tt class="docutils literal"><span class="pre">\p</span></tt>) is not allowed as it may be wider than one character (it can be the pair CR/LF). Here are the valid <span id="escape-sequences_2">escape sequences</span> for character literals:</p>
<table border="1" class="docutils"><tr><th>Escape sequence</th><th>Meaning</th></tr>
<tr><td><tt class="docutils literal"><span class="pre">\r</span></tt>, <tt class="docutils literal"><span class="pre">\c</span></tt></td><td><span id="carriage-return_2">carriage return</span></td></tr>
<tr><td><tt class="docutils literal"><span class="pre">\n</span></tt>, <tt class="docutils literal"><span class="pre">\l</span></tt></td><td><span id="line-feed_2">line feed</span></td></tr>
<tr><td><tt class="docutils literal"><span class="pre">\f</span></tt></td><td><span id="form-feed_2">form feed</span></td></tr>
<tr><td><tt class="docutils literal"><span class="pre">\t</span></tt></td><td><span id="tabulator_2">tabulator</span></td></tr>
<tr><td><tt class="docutils literal"><span class="pre">\v</span></tt></td><td><span id="vertical-tabulator_2">vertical tabulator</span></td></tr>
<tr><td><tt class="docutils literal"><span class="pre">\\</span></tt></td><td><span id="backslash_2">backslash</span></td></tr>
<tr><td><tt class="docutils literal"><span class="pre">\&quot;</span></tt></td><td><span id="quotation-mark_2">quotation mark</span></td></tr>
<tr><td><tt class="docutils literal"><span class="pre">\'</span></tt></td><td><span id="apostrophe_2">apostrophe</span></td></tr>
<tr><td><tt class="docutils literal"><span class="pre">\</span></tt> '0'..'9'+</td><td><span id="character-with-decimal-value-d_2">character with decimal value d</span>; all decimal digits directly following are used for the character</td></tr>
<tr><td><tt class="docutils literal"><span class="pre">\a</span></tt></td><td><span id="alert_2">alert</span></td></tr>
<tr><td><tt class="docutils literal"><span class="pre">\b</span></tt></td><td><span id="backspace_2">backspace</span></td></tr>
<tr><td><tt class="docutils literal"><span class="pre">\e</span></tt></td><td><span id="escape_2">escape</span> <span id="esc_2">[ESC]</span></td></tr>
<tr><td><tt class="docutils literal"><span class="pre">\x</span></tt> HH</td><td><span id="character-with-hex-value-hh_2">character with hex value HH</span>; exactly two hex digits are allowed</td></tr>
</table><p>A character is not a Unicode character but a single byte.</p>
<p>Rationale: It enables the efficient support of <tt class="docutils literal"><span class="pre"><span class="Identifier">array</span><span class="Punctuation">[</span><span class="Identifier">char</span><span class="Punctuation">,</span> <span class="Identifier">int</span><span class="Punctuation">]</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Identifier">set</span><span class="Punctuation">[</span><span class="Identifier">char</span><span class="Punctuation">]</span></span></tt>.</p>
<p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">Rune</span></span></tt> type can represent any Unicode character. <tt class="docutils literal"><span class="pre"><span class="Identifier">Rune</span></span></tt> is declared in the <a class="reference external" href="unicode.html">unicode module</a>.</p>
<p>A character literal that does not end in <tt class="docutils literal"><span class="pre"><span class="CharLit">'</span></span></tt> is interpreted as <tt class="docutils literal"><span class="pre"><span class="CharLit">'</span></span></tt> if there is a preceding backtick token. There must be no whitespace between the preceding backtick token and the character literal. This special case ensures that a declaration like <tt class="docutils literal"><span class="pre">proc `'customLiteral`(s: string)</span></tt> is valid. <tt class="docutils literal"><span class="pre">proc `'customLiteral`(s: string)</span></tt> is the same as <tt class="docutils literal"><span class="pre">proc `'\''customLiteral`(s: string)</span></tt>.</p>
<p>See also <a class="reference internal" href="#numeric-literals-custom-numeric-literals">custom numeric literals</a>.</p>

<h2><a class="toc-backref" id="lexical-analysis-numeric-literals" href="#lexical-analysis-numeric-literals">Numeric literals</a></h2><p>Numeric literals have the form:</p>
<pre>hexdigit = digit | 'A'..'F' | 'a'..'f'
octdigit = '0'..'7'
bindigit = '0'..'1'
unary_minus = '-' # See the section about unary minus
HEX_LIT = unary_minus? '0' ('x' | 'X' ) hexdigit ( ['_'] hexdigit )*
DEC_LIT = unary_minus? digit ( ['_'] digit )*
OCT_LIT = unary_minus? '0' 'o' octdigit ( ['_'] octdigit )*
BIN_LIT = unary_minus? '0' ('b' | 'B' ) bindigit ( ['_'] bindigit )*

INT_LIT = HEX_LIT
        | DEC_LIT
        | OCT_LIT
        | BIN_LIT

INT8_LIT = INT_LIT ['\''] ('i' | 'I') '8'
INT16_LIT = INT_LIT ['\''] ('i' | 'I') '16'
INT32_LIT = INT_LIT ['\''] ('i' | 'I') '32'
INT64_LIT = INT_LIT ['\''] ('i' | 'I') '64'

UINT_LIT = INT_LIT ['\''] ('u' | 'U')
UINT8_LIT = INT_LIT ['\''] ('u' | 'U') '8'
UINT16_LIT = INT_LIT ['\''] ('u' | 'U') '16'
UINT32_LIT = INT_LIT ['\''] ('u' | 'U') '32'
UINT64_LIT = INT_LIT ['\''] ('u' | 'U') '64'

exponent = ('e' | 'E' ) ['+' | '-'] digit ( ['_'] digit )*
FLOAT_LIT = unary_minus? digit (['_'] digit)* (('.' digit (['_'] digit)* [exponent]) |exponent)
FLOAT32_SUFFIX = ('f' | 'F') ['32']
FLOAT32_LIT = HEX_LIT '\'' FLOAT32_SUFFIX
            | (FLOAT_LIT | DEC_LIT | OCT_LIT | BIN_LIT) ['\''] FLOAT32_SUFFIX
FLOAT64_SUFFIX = ( ('f' | 'F') '64' ) | 'd' | 'D'
FLOAT64_LIT = HEX_LIT '\'' FLOAT64_SUFFIX
            | (FLOAT_LIT | DEC_LIT | OCT_LIT | BIN_LIT) ['\''] FLOAT64_SUFFIX

CUSTOM_NUMERIC_LIT = (FLOAT_LIT | INT_LIT) '\'' CUSTOM_NUMERIC_SUFFIX

# CUSTOM_NUMERIC_SUFFIX is any Nim identifier that is not
# a pre-defined type suffix.</pre>
<p>As can be seen in the productions, numeric literals can contain underscores for readability. Integer and floating-point literals may be given in decimal (no prefix), binary (prefix <tt class="docutils literal"><span class="pre"><span class="BinNumber">0b</span></span></tt>), octal (prefix <tt class="docutils literal"><span class="pre"><span class="OctNumber">0o</span></span></tt>), and hexadecimal (prefix <tt class="docutils literal"><span class="pre"><span class="HexNumber">0x</span></span></tt>) notation.</p>
<p>The fact that the unary minus <tt class="docutils literal"><span class="pre"><span class="Operator">-</span></span></tt> in a number literal like <tt class="docutils literal"><span class="pre"><span class="Operator">-</span><span class="DecNumber">1</span></span></tt> is considered to be part of the literal is a late addition to the language. The rationale is that an expression <tt class="docutils literal"><span class="pre"><span class="Operator">-</span><span class="DecNumber">128'i8</span></span></tt> should be valid and without this special case, this would be impossible -- <tt class="docutils literal"><span class="pre"><span class="DecNumber">128</span></span></tt> is not a valid <tt class="docutils literal"><span class="pre"><span class="Identifier">int8</span></span></tt> value, only <tt class="docutils literal"><span class="pre"><span class="Operator">-</span><span class="DecNumber">128</span></span></tt> is.</p>
<p>For the <tt class="docutils literal"><span class="pre"><span class="Identifier">unary_minus</span></span></tt> rule there are further restrictions that are not covered in the formal grammar. For <tt class="docutils literal"><span class="pre"><span class="Operator">-</span></span></tt> to be part of the number literal the immediately preceding character has to be in the set <tt class="docutils literal"><span class="pre"><span class="Punctuation">{</span><span class="Punctuation">'</span> <span class="CharLit">', '</span><span class="Operator">\</span><span class="Identifier">t</span><span class="CharLit">', '</span><span class="Operator">\</span><span class="Identifier">n</span><span class="CharLit">', '</span><span class="Operator">\</span><span class="Identifier">r</span><span class="CharLit">', '</span><span class="Punctuation">,</span><span class="Punctuation">'</span><span class="Punctuation">,</span> <span class="CharLit">';'</span><span class="Punctuation">,</span> <span class="CharLit">'('</span><span class="Punctuation">,</span> <span class="CharLit">'['</span><span class="Punctuation">,</span> <span class="CharLit">'{'</span><span class="Punctuation">}</span></span></tt>. This set was designed to cover most cases in a natural manner.</p>
<p>In the following examples, <tt class="docutils literal"><span class="pre"><span class="Operator">-</span><span class="DecNumber">1</span></span></tt> is a single token:</p>
<p><pre class="listing"><span class="Identifier">echo</span> <span class="Operator">-</span><span class="DecNumber">1</span>
<span class="Identifier">echo</span><span class="Punctuation">(</span><span class="Operator">-</span><span class="DecNumber">1</span><span class="Punctuation">)</span>
<span class="Identifier">echo</span> <span class="Punctuation">[</span><span class="Operator">-</span><span class="DecNumber">1</span><span class="Punctuation">]</span>
<span class="Identifier">echo</span> <span class="DecNumber">3</span><span class="Punctuation">,</span><span class="Operator">-</span><span class="DecNumber">1</span>

<span class="StringLit">&quot;abc&quot;</span><span class="Punctuation">;</span><span class="Operator">-</span><span class="DecNumber">1</span></pre></p>
<p>In the following examples, <tt class="docutils literal"><span class="pre"><span class="Operator">-</span><span class="DecNumber">1</span></span></tt> is parsed as two separate tokens (as <tt class="docutils literal"><span class="pre tok">-</span></tt> <tt class="docutils literal"><span class="pre tok">1</span></tt>):</p>
<p><pre class="listing"><span class="Identifier">echo</span> <span class="Identifier">x</span><span class="Operator">-</span><span class="DecNumber">1</span>
<span class="Identifier">echo</span> <span class="Punctuation">(</span><span class="Identifier">int</span><span class="Punctuation">)</span><span class="Operator">-</span><span class="DecNumber">1</span>
<span class="Identifier">echo</span> <span class="Punctuation">[</span><span class="Identifier">a</span><span class="Punctuation">]</span><span class="Operator">-</span><span class="DecNumber">1</span>
<span class="StringLit">&quot;abc&quot;</span><span class="Operator">-</span><span class="DecNumber">1</span></pre></p>
<p>The suffix starting with an apostrophe (''') is called a <span id="type-suffix_1">type suffix</span>. Literals without a type suffix are of an integer type unless the literal contains a dot or <tt class="docutils literal"><span class="pre"><span class="Identifier">E</span><span class="Operator">|</span><span class="Identifier">e</span></span></tt> in which case it is of type <tt class="docutils literal"><span class="pre"><span class="Identifier">float</span></span></tt>. This integer type is <tt class="docutils literal"><span class="pre"><span class="Identifier">int</span></span></tt> if the literal is in the range <tt class="docutils literal"><span class="pre"><span class="Identifier">low</span><span class="Punctuation">(</span><span class="Identifier">int32</span><span class="Punctuation">)</span><span class="Operator">..</span><span class="Identifier">high</span><span class="Punctuation">(</span><span class="Identifier">int32</span><span class="Punctuation">)</span></span></tt>, otherwise it is <tt class="docutils literal"><span class="pre"><span class="Identifier">int64</span></span></tt>. For notational convenience, the apostrophe of a type suffix is optional if it is not ambiguous (only hexadecimal floating-point literals with a type suffix can be ambiguous).</p>
<p>The pre-defined type suffixes are:</p>
<table border="1" class="docutils"><tr><th>Type Suffix</th><th>Resulting type of literal</th></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="CharLit">'i8</span></span></tt></td><td>int8</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="CharLit">'i16</span></span></tt></td><td>int16</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="CharLit">'i32</span></span></tt></td><td>int32</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="CharLit">'i64</span></span></tt></td><td>int64</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="CharLit">'u</span></span></tt></td><td>uint</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="CharLit">'u8</span></span></tt></td><td>uint8</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="CharLit">'u16</span></span></tt></td><td>uint16</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="CharLit">'u32</span></span></tt></td><td>uint32</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="CharLit">'u64</span></span></tt></td><td>uint64</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="CharLit">'f</span></span></tt></td><td>float32</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="CharLit">'d</span></span></tt></td><td>float64</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="CharLit">'f32</span></span></tt></td><td>float32</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="CharLit">'f64</span></span></tt></td><td>float64</td></tr>
</table><p>Floating-point literals may also be in binary, octal or hexadecimal notation: <tt class="docutils literal"><span class="pre"><span class="FloatNumber">0B0_10001110100_0000101001000111101011101111111011000101001101001001'f64</span></span></tt> is approximately 1.72826e35 according to the IEEE floating-point standard.</p>
<p>Literals must match the datatype, for example, <tt class="docutils literal"><span class="pre"><span class="DecNumber">333'i8</span></span></tt> is an invalid literal. Non-base-10 literals are used mainly for flags and bit pattern representations, therefore the checking is done on bit width and not on value range. Hence: 0b10000000'u8 == 0x80'u8 == 128, but, 0b10000000'i8 == 0x80'i8 == -1 instead of causing an overflow error.</p>

<h3><a class="toc-backref" id="numeric-literals-custom-numeric-literals" href="#numeric-literals-custom-numeric-literals">Custom numeric literals</a></h3><p>If the suffix is not predefined, then the suffix is assumed to be a call to a proc, template, macro or other callable identifier that is passed the string containing the literal. The callable identifier needs to be declared with a special <tt class="docutils literal"><span class="pre">'</span></tt> prefix:</p>
<p><pre class="listing"><span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">strutils</span>
<span class="Keyword">type</span> <span class="Identifier">u4</span> <span class="Operator">=</span> <span class="Keyword">distinct</span> <span class="Identifier">uint8</span> <span class="Comment"># a 4-bit unsigned integer aka &quot;nibble&quot;</span>
<span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Punctuation">'</span><span class="Identifier">u4</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">n</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">u4</span> <span class="Operator">=</span>
  <span class="Comment"># The leading ' is required.</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Punctuation">(</span><span class="Identifier">parseInt</span><span class="Punctuation">(</span><span class="Identifier">n</span><span class="Punctuation">)</span> <span class="Keyword">and</span> <span class="HexNumber">0x0F</span><span class="Punctuation">)</span><span class="Operator">.</span><span class="Identifier">u4</span>

<span class="Keyword">var</span> <span class="Identifier">x</span> <span class="Operator">=</span> <span class="DecNumber">5'</span><span class="Identifier">u4</span></pre></p>
<p>More formally, a custom numeric literal <tt class="docutils literal"><span class="pre"><span class="DecNumber">123'</span><span class="Identifier">custom</span></span></tt> is transformed to r&quot;123&quot;.<tt class="docutils literal"><span class="pre"><span class="CharLit">'custom</span></span></tt> in the parsing step. There is no AST node kind that corresponds to this transformation. The transformation naturally handles the case that additional parameters are passed to the callee:</p>
<p><pre class="listing"><span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">strutils</span>
<span class="Keyword">type</span> <span class="Identifier">u4</span> <span class="Operator">=</span> <span class="Keyword">distinct</span> <span class="Identifier">uint8</span> <span class="Comment"># a 4-bit unsigned integer aka &quot;nibble&quot;</span>
<span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Punctuation">'</span><span class="Identifier">u4</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">n</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">;</span> <span class="Identifier">moreData</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">u4</span> <span class="Operator">=</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Punctuation">(</span><span class="Identifier">parseInt</span><span class="Punctuation">(</span><span class="Identifier">n</span><span class="Punctuation">)</span> <span class="Keyword">and</span> <span class="HexNumber">0x0F</span><span class="Punctuation">)</span><span class="Operator">.</span><span class="Identifier">u4</span>

<span class="Keyword">var</span> <span class="Identifier">x</span> <span class="Operator">=</span> <span class="DecNumber">5'</span><span class="Identifier">u4</span><span class="Punctuation">(</span><span class="DecNumber">123</span><span class="Punctuation">)</span></pre></p>
<p>Custom numeric literals are covered by the grammar rule named <tt class="docutils literal"><span class="pre"><span class="Identifier">CUSTOM_NUMERIC_LIT</span></span></tt>. A custom numeric literal is a single token.</p>

<h2><a class="toc-backref" id="lexical-analysis-operators" href="#lexical-analysis-operators">Operators</a></h2><p>Nim allows user defined operators. An operator is any combination of the following characters:</p>
<pre>=     +     -     *     /     &lt;     &gt;
@     $     ~     &amp;     %     |
!     ?     ^     .     :     \</pre>
<p>(The grammar uses the terminal OPR to refer to operator symbols as defined here.)</p>
<p>These keywords are also operators: <tt class="docutils literal"><span class="pre"><span class="Keyword">and</span> <span class="Keyword">or</span> <span class="Keyword">not</span> <span class="Keyword">xor</span> <span class="Keyword">shl</span> <span class="Keyword">shr</span> <span class="Keyword">div</span> <span class="Keyword">mod</span> <span class="Keyword">in</span> <span class="Keyword">notin</span> <span class="Keyword">is</span> <span class="Keyword">isnot</span> <span class="Keyword">of</span> <span class="Keyword">as</span> <span class="Keyword">from</span></span></tt>.</p>
<p><tt class="docutils literal"><span class="pre tok">.</span></tt>, <tt class="docutils literal"><span class="pre tok">=</span></tt>, <tt class="docutils literal"><span class="pre tok">:</span></tt>, <tt class="docutils literal"><span class="pre tok">::</span></tt> are not available as general operators; they are used for other notational purposes.</p>
<p><tt class="docutils literal"><span class="pre"><span class="Operator">*:</span></span></tt> is as a special case treated as the two tokens <tt class="docutils literal"><span class="pre tok">*</span></tt> and <tt class="docutils literal"><span class="pre tok">:</span></tt> (to support <tt class="docutils literal"><span class="pre"><span class="Keyword">var</span> <span class="Identifier">v</span><span class="Operator">*:</span> <span class="Identifier">T</span></span></tt>).</p>
<p>The <tt class="docutils literal"><span class="pre"><span class="Keyword">not</span></span></tt> keyword is always a unary operator, <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span> <span class="Keyword">not</span> <span class="Identifier">b</span></span></tt> is parsed as <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span><span class="Punctuation">(</span><span class="Keyword">not</span> <span class="Identifier">b</span><span class="Punctuation">)</span></span></tt>, not as <tt class="docutils literal"><span class="pre"><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">)</span> <span class="Keyword">not</span> <span class="Punctuation">(</span><span class="Identifier">b</span><span class="Punctuation">)</span></span></tt>.</p>

<h2><a class="toc-backref" id="lexical-analysis-unicode-operators" href="#lexical-analysis-unicode-operators">Unicode Operators</a></h2><p>These Unicode operators are also parsed as operators:</p>
<pre>∙ ∘ × ★ ⊗ ⊘ ⊙ ⊛ ⊠ ⊡ ∩ ∧ ⊓   # same priority as * (multiplication)
± ⊕ ⊖ ⊞ ⊟ ∪ ∨ ⊔             # same priority as + (addition)</pre>
<p>Unicode operators can be combined with non-Unicode operator symbols. The usual precedence extensions then apply, for example, <tt class="docutils literal"><span class="pre"><span class="Identifier">⊠</span><span class="Operator">=</span></span></tt> is an assignment like operator just like <tt class="docutils literal"><span class="pre"><span class="Operator">*=</span></span></tt> is.</p>
<p>No Unicode normalization step is performed.</p>

<h2><a class="toc-backref" id="lexical-analysis-other-tokens" href="#lexical-analysis-other-tokens">Other tokens</a></h2><p>The following strings denote other tokens:</p>
<pre>`   (    )     {    }     [    ]    ,  ;   [.    .]  {.   .}  (.  .)  [:</pre>
<p>The <span id="slice_1">slice</span> operator <tt class="docutils literal"><span class="pre tok">..</span></tt> takes precedence over other tokens that contain a dot: <tt class="docutils literal"><span class="pre"><span class="Punctuation">{</span><span class="Operator">..</span><span class="Punctuation">}</span></span></tt> are the three tokens <tt class="docutils literal"><span class="pre tok">{</span></tt>, <tt class="docutils literal"><span class="pre tok">..</span></tt>, <tt class="docutils literal"><span class="pre tok">}</span></tt> and not the two tokens <tt class="docutils literal"><span class="pre tok">{.</span></tt>, <tt class="docutils literal"><span class="pre tok">.}</span></tt>.</p>

<h1><a class="toc-backref" id="syntax" href="#syntax">Syntax</a></h1><p>This section lists Nim's standard syntax. How the parser handles the indentation is already described in the <a class="reference internal" href="#lexical-analysis">Lexical Analysis</a> section.</p>
<p>Nim allows user-definable operators. Binary operators have 11 different levels of precedence.</p>

<h2><a class="toc-backref" id="syntax-associativity" href="#syntax-associativity">Associativity</a></h2><p>Binary operators whose first character is <tt class="docutils literal"><span class="pre"><span class="Operator">^</span></span></tt> are right-associative, all other binary operators are left-associative.</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">^/</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">float</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">float</span> <span class="Operator">=</span>
  <span class="Comment"># a right-associative division operator</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">x</span> <span class="Operator">/</span> <span class="Identifier">y</span>
<span class="Identifier">echo</span> <span class="DecNumber">12</span> <span class="Operator">^/</span> <span class="DecNumber">4</span> <span class="Operator">^/</span> <span class="DecNumber">8</span> <span class="Comment"># 24.0 (4 / 8 = 0.5, then 12 / 0.5 = 24.0)</span>
<span class="Identifier">echo</span> <span class="DecNumber">12</span>  <span class="Operator">/</span> <span class="DecNumber">4</span>  <span class="Operator">/</span> <span class="DecNumber">8</span> <span class="Comment"># 0.375 (12 / 4 = 3.0, then 3 / 8 = 0.375)</span></pre></p>

<h2><a class="toc-backref" id="syntax-precedence" href="#syntax-precedence">Precedence</a></h2><p>Unary operators always bind stronger than any binary operator: <tt class="docutils literal"><span class="pre"><span class="Operator">$</span><span class="Identifier">a</span> <span class="Operator">+</span> <span class="Identifier">b</span></span></tt> is <tt class="docutils literal"><span class="pre"><span class="Punctuation">(</span><span class="Operator">$</span><span class="Identifier">a</span><span class="Punctuation">)</span> <span class="Operator">+</span> <span class="Identifier">b</span></span></tt> and not <tt class="docutils literal"><span class="pre"><span class="Operator">$</span><span class="Punctuation">(</span><span class="Identifier">a</span> <span class="Operator">+</span> <span class="Identifier">b</span><span class="Punctuation">)</span></span></tt>.</p>
<p>If a unary operator's first character is <tt class="docutils literal"><span class="pre"><span class="Operator">@</span></span></tt> it is a <span id="sigilminuslike_1">sigil-like</span> operator which binds stronger than a <tt class="docutils literal"><span class="pre"><span class="Identifier">primarySuffix</span></span></tt>: <tt class="docutils literal"><span class="pre"><span class="Operator">@</span><span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">abc</span></span></tt> is parsed as <tt class="docutils literal"><span class="pre"><span class="Punctuation">(</span><span class="Operator">@</span><span class="Identifier">x</span><span class="Punctuation">)</span><span class="Operator">.</span><span class="Identifier">abc</span></span></tt> whereas <tt class="docutils literal"><span class="pre"><span class="Operator">$</span><span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">abc</span></span></tt> is parsed as <tt class="docutils literal"><span class="pre"><span class="Operator">$</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">abc</span><span class="Punctuation">)</span></span></tt>.</p>
<p>For binary operators that are not keywords, the precedence is determined by the following rules:</p>
<p>Operators ending in either <tt class="docutils literal"><span class="pre"><span class="Operator">-&gt;</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Operator">~&gt;</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Operator">=&gt;</span></span></tt> are called <span id="arrow-like_1">arrow like</span>, and have the lowest precedence of all operators.</p>
<p>If the operator ends with <tt class="docutils literal"><span class="pre"><span class="Operator">=</span></span></tt> and its first character is none of <tt class="docutils literal"><span class="pre"><span class="Operator">&lt;</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Operator">&gt;</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Operator">!</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Operator">=</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Operator">~</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Operator">?</span></span></tt>, it is an <em>assignment operator</em> which has the second-lowest precedence.</p>
<p>Otherwise, precedence is determined by the first character.</p>
<table border="1" class="docutils"><tr><th>Precedence level</th><th>Operators</th><th>First character</th><th>Terminal symbol</th></tr>
<tr><td>10 (highest)</td><td></td><td><tt class="docutils literal"><span class="pre"><span class="Operator">$</span> <span class="Operator">^</span></span></tt></td><td>OP10</td></tr>
<tr><td>9</td><td><tt class="docutils literal"><span class="pre"><span class="Operator">*</span> <span class="Operator">/</span> <span class="Keyword">div</span> <span class="Keyword">mod</span> <span class="Keyword">shl</span> <span class="Keyword">shr</span> <span class="Operator">%</span></span></tt></td><td><tt class="docutils literal"><span class="pre"><span class="Operator">*</span> <span class="Operator">%</span> <span class="Operator">\</span> <span class="Operator">/</span></span></tt></td><td>OP9</td></tr>
<tr><td>8</td><td><tt class="docutils literal"><span class="pre"><span class="Operator">+</span> <span class="Operator">-</span></span></tt></td><td><tt class="docutils literal"><span class="pre"><span class="Operator">+</span> <span class="Operator">-</span> <span class="Operator">~</span> <span class="Operator">|</span></span></tt></td><td>OP8</td></tr>
<tr><td>7</td><td><tt class="docutils literal"><span class="pre"><span class="Operator">&amp;</span></span></tt></td><td><tt class="docutils literal"><span class="pre"><span class="Operator">&amp;</span></span></tt></td><td>OP7</td></tr>
<tr><td>6</td><td><tt class="docutils literal"><span class="pre"><span class="Operator">..</span></span></tt></td><td><tt class="docutils literal"><span class="pre"><span class="Operator">.</span></span></tt></td><td>OP6</td></tr>
<tr><td>5</td><td><tt class="docutils literal"><span class="pre"><span class="Operator">==</span> <span class="Operator">&lt;=</span> <span class="Operator">&lt;</span> <span class="Operator">&gt;=</span> <span class="Operator">&gt;</span> <span class="Operator">!=</span> <span class="Keyword">in</span> <span class="Keyword">notin</span> <span class="Keyword">is</span> <span class="Keyword">isnot</span> <span class="Keyword">not</span> <span class="Keyword">of</span> <span class="Keyword">as</span> <span class="Keyword">from</span></span></tt></td><td><tt class="docutils literal"><span class="pre"><span class="Operator">=</span> <span class="Operator">&lt;</span> <span class="Operator">&gt;</span> <span class="Operator">!</span></span></tt></td><td>OP5</td></tr>
<tr><td>4</td><td><tt class="docutils literal"><span class="pre"><span class="Keyword">and</span></span></tt></td><td></td><td>OP4</td></tr>
<tr><td>3</td><td><tt class="docutils literal"><span class="pre"><span class="Keyword">or</span> <span class="Keyword">xor</span></span></tt></td><td></td><td>OP3</td></tr>
<tr><td>2</td><td></td><td><tt class="docutils literal"><span class="pre"><span class="Operator">@</span> <span class="Punctuation">:</span> <span class="Operator">?</span></span></tt></td><td>OP2</td></tr>
<tr><td>1</td><td><em>assignment operator</em> (like <tt class="docutils literal"><span class="pre"><span class="Operator">+=</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Operator">*=</span></span></tt>)</td><td></td><td>OP1</td></tr>
<tr><td>0 (lowest)</td><td><em>arrow like operator</em> (like <tt class="docutils literal"><span class="pre"><span class="Operator">-&gt;</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Operator">=&gt;</span></span></tt>)</td><td></td><td>OP0</td></tr>
</table><p>Whether an operator is used as a prefix operator is also affected by preceding whitespace (this parsing change was introduced with version 0.13.0):</p>
<p><pre class="listing"><span class="Identifier">echo</span> <span class="Operator">$</span><span class="Identifier">foo</span>
<span class="Comment"># is parsed as</span>
<span class="Identifier">echo</span><span class="Punctuation">(</span><span class="Operator">$</span><span class="Identifier">foo</span><span class="Punctuation">)</span></pre></p>
<p>Spacing also determines whether <tt class="docutils literal"><span class="pre"><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">)</span></span></tt> is parsed as an argument list of a call or whether it is parsed as a tuple constructor:</p>
<p><pre class="listing"><span class="Identifier">echo</span><span class="Punctuation">(</span><span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="DecNumber">2</span><span class="Punctuation">)</span> <span class="Comment"># pass 1 and 2 to echo</span></pre></p>
<p><pre class="listing"><span class="Identifier">echo</span> <span class="Punctuation">(</span><span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="DecNumber">2</span><span class="Punctuation">)</span> <span class="Comment"># pass the tuple (1, 2) to echo</span></pre></p>

<h2><a class="toc-backref" id="syntax-dotminuslike-operators" href="#syntax-dotminuslike-operators">Dot-like operators</a></h2><p>Terminal symbol in the grammar: <tt class="docutils literal"><span class="pre"><span class="Identifier">DOTLIKEOP</span></span></tt>.</p>
<p>Dot-like operators are operators starting with <tt class="docutils literal"><span class="pre"><span class="Operator">.</span></span></tt>, but not with <tt class="docutils literal"><span class="pre"><span class="Operator">..</span></span></tt>, for e.g. <tt class="docutils literal"><span class="pre"><span class="Operator">.?</span></span></tt>; they have the same precedence as <tt class="docutils literal"><span class="pre"><span class="Operator">.</span></span></tt>, so that <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span><span class="Operator">.?</span><span class="Identifier">b</span><span class="Operator">.</span><span class="Identifier">c</span></span></tt> is parsed as <tt class="docutils literal"><span class="pre"><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Operator">.?</span><span class="Identifier">b</span><span class="Punctuation">)</span><span class="Operator">.</span><span class="Identifier">c</span></span></tt> instead of <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span><span class="Operator">.?</span><span class="Punctuation">(</span><span class="Identifier">b</span><span class="Operator">.</span><span class="Identifier">c</span><span class="Punctuation">)</span></span></tt>.</p>

<h2><a class="toc-backref" id="syntax-grammar" href="#syntax-grammar">Grammar</a></h2><p>The grammar's start symbol is <tt class="docutils literal"><span class="pre"><span class="Identifier">module</span></span></tt>.</p>
<pre># This file is generated by compiler/parser.nim.
module = complexOrSimpleStmt ^* (';' / IND{=})
comma = ',' COMMENT?
semicolon = ';' COMMENT?
colon = ':' COMMENT?
colcom = ':' COMMENT?
operator =  OP0 | OP1 | OP2 | OP3 | OP4 | OP5 | OP6 | OP7 | OP8 | OP9
         | 'or' | 'xor' | 'and'
         | 'is' | 'isnot' | 'in' | 'notin' | 'of' | 'as' | 'from'
         | 'div' | 'mod' | 'shl' | 'shr' | 'not' | '..'
prefixOperator = operator
optInd = COMMENT? IND?
optPar = (IND{&gt;} | IND{=})?
simpleExpr = arrowExpr (OP0 optInd arrowExpr)* pragma?
arrowExpr = assignExpr (OP1 optInd assignExpr)*
assignExpr = orExpr (OP2 optInd orExpr)*
orExpr = andExpr (OP3 optInd andExpr)*
andExpr = cmpExpr (OP4 optInd cmpExpr)*
cmpExpr = sliceExpr (OP5 optInd sliceExpr)*
sliceExpr = ampExpr (OP6 optInd ampExpr)*
ampExpr = plusExpr (OP7 optInd plusExpr)*
plusExpr = mulExpr (OP8 optInd mulExpr)*
mulExpr = dollarExpr (OP9 optInd dollarExpr)*
dollarExpr = primary (OP10 optInd primary)*
operatorB = OP0 | OP1 | OP2 | OP3 | OP4 | OP5 | OP6 | OP7 | OP8 | OP9 |
            'div' | 'mod' | 'shl' | 'shr' | 'in' | 'notin' |
            'is' | 'isnot' | 'not' | 'of' | 'as' | 'from' | '..' | 'and' | 'or' | 'xor'
symbol = '`' (KEYW|IDENT|literal|(operator|'('|')'|'['|']'|'{'|'}'|'=')+)+ '`'
       | IDENT | 'addr' | 'type' | 'static'
symbolOrKeyword = symbol | KEYW
exprColonEqExpr = expr ((':'|'=') expr
                       / doBlock extraPostExprBlock*)?
exprEqExpr = expr ('=' expr
                  / doBlock extraPostExprBlock*)?
exprList = expr ^+ comma
optionalExprList = expr ^* comma
exprColonEqExprList = exprColonEqExpr (comma exprColonEqExpr)* (comma)?
qualifiedIdent = symbol ('.' optInd symbolOrKeyword)?
setOrTableConstr = '{' ((exprColonEqExpr comma)* | ':' ) '}'
castExpr = 'cast' ('[' optInd typeDesc optPar ']' '(' optInd expr optPar ')') /
parKeyw = 'discard' | 'include' | 'if' | 'while' | 'case' | 'try'
        | 'finally' | 'except' | 'for' | 'block' | 'const' | 'let'
        | 'when' | 'var' | 'mixin'
par = '(' optInd
          ( &amp;parKeyw (ifExpr / complexOrSimpleStmt) ^+ ';'
          | ';' (ifExpr / complexOrSimpleStmt) ^+ ';'
          | pragmaStmt
          | simpleExpr ( (doBlock extraPostExprBlock*)
                       | ('=' expr (';' (ifExpr / complexOrSimpleStmt) ^+ ';' )? )
                       | (':' expr (',' exprColonEqExpr     ^+ ',' )? ) ) )
          optPar ')'
literal = | INT_LIT | INT8_LIT | INT16_LIT | INT32_LIT | INT64_LIT
          | UINT_LIT | UINT8_LIT | UINT16_LIT | UINT32_LIT | UINT64_LIT
          | FLOAT_LIT | FLOAT32_LIT | FLOAT64_LIT
          | STR_LIT | RSTR_LIT | TRIPLESTR_LIT
          | CHAR_LIT | CUSTOM_NUMERIC_LIT
          | NIL
generalizedLit = GENERALIZED_STR_LIT | GENERALIZED_TRIPLESTR_LIT
identOrLiteral = generalizedLit | symbol | literal
               | par | arrayConstr | setOrTableConstr | tupleConstr
               | castExpr
tupleConstr = '(' optInd (exprColonEqExpr comma?)* optPar ')'
arrayConstr = '[' optInd (exprColonEqExpr comma?)* optPar ']'
primarySuffix = '(' (exprColonEqExpr comma?)* ')'
      | '.' optInd symbolOrKeyword ('[:' exprList ']' ( '(' exprColonEqExpr ')' )?)? generalizedLit?
      | DOTLIKEOP optInd symbolOrKeyword generalizedLit?
      | '[' optInd exprColonEqExprList optPar ']'
      | '{' optInd exprColonEqExprList optPar '}'
pragma = '{.' optInd (exprColonEqExpr comma?)* optPar ('.}' | '}')
identVis = symbol OPR?  # postfix position
identVisDot = symbol '.' optInd symbolOrKeyword OPR?
identWithPragma = identVis pragma?
identWithPragmaDot = identVisDot pragma?
declColonEquals = identWithPragma (comma identWithPragma)* comma?
                  (':' optInd typeDescExpr)? ('=' optInd expr)?
identColonEquals = IDENT (comma IDENT)* comma?
     (':' optInd typeDescExpr)? ('=' optInd expr)?)
tupleTypeBracket = '[' optInd (identColonEquals (comma/semicolon)?)* optPar ']'
tupleType = 'tuple' tupleTypeBracket
tupleDecl = 'tuple' (tupleTypeBracket /
    COMMENT? (IND{&gt;} identColonEquals (IND{=} identColonEquals)*)?)
paramList = '(' declColonEquals ^* (comma/semicolon) ')'
paramListArrow = paramList? ('-&gt;' optInd typeDesc)?
paramListColon = paramList? (':' optInd typeDesc)?
doBlock = 'do' paramListArrow pragma? colcom stmt
routineExpr = ('proc' | 'func' | 'iterator') paramListColon pragma? ('=' COMMENT? stmt)?
routineType = ('proc' | 'iterator') paramListColon pragma?
forStmt = 'for' ((varTuple / identWithPragma) ^+ comma) 'in' expr colcom stmt
forExpr = forStmt
expr = (blockExpr
      | ifExpr
      | whenExpr
      | caseStmt
      | forExpr
      | tryExpr)
      / simpleExpr
simplePrimary = SIGILLIKEOP? identOrLiteral primarySuffix*
commandStart = &amp;('`'|IDENT|literal|'cast'|'addr'|'type'|'var'|'out'|
                 'static'|'enum'|'tuple'|'object'|'proc')
primary = simplePrimary (commandStart expr (doBlock extraPostExprBlock*)?)?
        / operatorB primary
        / routineExpr
        / rawTypeDesc
        / prefixOperator primary
rawTypeDesc = (tupleType | routineType | 'enum' | 'object' |
                ('var' | 'out' | 'ref' | 'ptr' | 'distinct') typeDesc?)
                ('not' primary)?
typeDescExpr = (routineType / simpleExpr) ('not' primary)?
typeDesc = rawTypeDesc / typeDescExpr
typeDefValue = ((tupleDecl | enumDecl | objectDecl | conceptDecl |
                 ('ref' | 'ptr' | 'distinct') (tupleDecl | objectDecl))
               / (simpleExpr (exprEqExpr ^+ comma postExprBlocks?)?))
               ('not' primary)?
extraPostExprBlock = ( IND{=} doBlock
                     | IND{=} 'of' exprList ':' stmt
                     | IND{=} 'elif' expr ':' stmt
                     | IND{=} 'except' optionalExprList ':' stmt
                     | IND{=} 'finally' ':' stmt
                     | IND{=} 'else' ':' stmt )
postExprBlocks = (doBlock / ':' (extraPostExprBlock / stmt)) extraPostExprBlock*
exprStmt = simpleExpr postExprBlocks?
         / simplePrimary (exprEqExpr ^+ comma) postExprBlocks?
         / simpleExpr '=' optInd (expr postExprBlocks?)
importStmt = 'import' optInd expr
              ((comma expr)*
              / 'except' optInd (expr ^+ comma))
exportStmt = 'export' optInd expr
              ((comma expr)*
              / 'except' optInd (expr ^+ comma))
includeStmt = 'include' optInd expr ^+ comma
fromStmt = 'from' expr 'import' optInd expr (comma expr)*
returnStmt = 'return' optInd expr?
raiseStmt = 'raise' optInd expr?
yieldStmt = 'yield' optInd expr?
discardStmt = 'discard' optInd expr?
breakStmt = 'break' optInd expr?
continueStmt = 'continue' optInd expr?
condStmt = expr colcom stmt COMMENT?
           (IND{=} 'elif' expr colcom stmt)*
           (IND{=} 'else' colcom stmt)?
ifStmt = 'if' condStmt
whenStmt = 'when' condStmt
condExpr = expr colcom stmt optInd
        ('elif' expr colcom stmt optInd)*
         'else' colcom stmt
ifExpr = 'if' condExpr
whenExpr = 'when' condExpr
whileStmt = 'while' expr colcom stmt
ofBranch = 'of' exprList colcom stmt
ofBranches = ofBranch (IND{=} ofBranch)*
                      (IND{=} 'elif' expr colcom stmt)*
                      (IND{=} 'else' colcom stmt)?
caseStmt = 'case' expr ':'? COMMENT?
            (IND{&gt;} ofBranches DED
            | IND{=} ofBranches)
tryStmt = 'try' colcom stmt &amp;(IND{=}? 'except'|'finally')
           (IND{=}? 'except' optionalExprList colcom stmt)*
           (IND{=}? 'finally' colcom stmt)?
tryExpr = 'try' colcom stmt &amp;(optInd 'except'|'finally')
           (optInd 'except' optionalExprList colcom stmt)*
           (optInd 'finally' colcom stmt)?
blockStmt = 'block' symbol? colcom stmt
blockExpr = 'block' symbol? colcom stmt
staticStmt = 'static' colcom stmt
deferStmt = 'defer' colcom stmt
asmStmt = 'asm' pragma? (STR_LIT | RSTR_LIT | TRIPLESTR_LIT)
genericParam = symbol (comma symbol)* (colon expr)? ('=' optInd expr)?
genericParamList = '[' optInd
  genericParam ^* (comma/semicolon) optPar ']'
pattern = '{' stmt '}'
indAndComment = (IND{&gt;} COMMENT)? | COMMENT?
routine = optInd identVis pattern? genericParamList?
  paramListColon pragma? ('=' COMMENT? stmt)? indAndComment
commentStmt = COMMENT
section(RULE) = COMMENT? RULE / (IND{&gt;} (RULE / COMMENT)^+IND{=} DED)
enumDecl = 'enum' optInd (symbol pragma? optInd ('=' optInd expr COMMENT?)? comma?)+
objectWhen = 'when' expr colcom objectPart COMMENT?
            ('elif' expr colcom objectPart COMMENT?)*
            ('else' colcom objectPart COMMENT?)?
objectBranch = 'of' exprList colcom objectPart
objectBranches = objectBranch (IND{=} objectBranch)*
                      (IND{=} 'elif' expr colcom objectPart)*
                      (IND{=} 'else' colcom objectPart)?
objectCase = 'case' declColonEquals ':'? COMMENT?
            (IND{&gt;} objectBranches DED
            | IND{=} objectBranches)
objectPart = IND{&gt;} objectPart^+IND{=} DED
           / objectWhen / objectCase / 'nil' / 'discard' / declColonEquals
objectDecl = 'object' ('of' typeDesc)? COMMENT? objectPart
conceptParam = ('var' | 'out' | 'ptr' | 'ref' | 'static' | 'type')? symbol
conceptDecl = 'concept' conceptParam ^* ',' (pragma)? ('of' typeDesc ^* ',')?
              &amp;IND{&gt;} stmt
typeDef = identVisDot genericParamList? pragma '=' optInd typeDefValue
            indAndComment?
varTupleLhs = '(' optInd (identWithPragma / varTupleLhs) ^+ comma optPar ')' (':' optInd typeDescExpr)?
varTuple = varTupleLhs '=' optInd expr
colonBody = colcom stmt postExprBlocks?
variable = (varTuple / identColonEquals) colonBody? indAndComment
constant = (varTuple / identWithPragma) (colon typeDesc)? '=' optInd expr indAndComment
bindStmt = 'bind' optInd qualifiedIdent ^+ comma
mixinStmt = 'mixin' optInd qualifiedIdent ^+ comma
pragmaStmt = pragma (':' COMMENT? stmt)?
simpleStmt = ((returnStmt | raiseStmt | yieldStmt | discardStmt | breakStmt
           | continueStmt | pragmaStmt | importStmt | exportStmt | fromStmt
           | includeStmt | commentStmt) / exprStmt) COMMENT?
complexOrSimpleStmt = (ifStmt | whenStmt | whileStmt
                    | tryStmt | forStmt
                    | blockStmt | staticStmt | deferStmt | asmStmt
                    | 'proc' routine
                    | 'method' routine
                    | 'func' routine
                    | 'iterator' routine
                    | 'macro' routine
                    | 'template' routine
                    | 'converter' routine
                    | 'type' section(typeDef)
                    | 'const' section(constant)
                    | ('let' | 'var' | 'using') section(variable)
                    | bindStmt | mixinStmt)
                    / simpleStmt
stmt = (IND{&gt;} complexOrSimpleStmt^+(IND{=} / ';') DED)
     / simpleStmt ^+ ';'
</pre>

<h1><a class="toc-backref" id="order-of-evaluation" href="#order-of-evaluation">Order of evaluation</a></h1><p>Order of evaluation is strictly left-to-right, inside-out as it is typical for most others imperative programming languages:</p>
<p><pre class="listing"><span class="Keyword">var</span> <span class="Identifier">s</span> <span class="Operator">=</span> <span class="StringLit">&quot;&quot;</span>

<span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Identifier">arg</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span>
  <span class="Identifier">s</span><span class="Operator">.</span><span class="Identifier">add</span> <span class="Operator">$</span><span class="Identifier">arg</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">arg</span>

<span class="Keyword">discard</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Identifier">p</span><span class="Punctuation">(</span><span class="DecNumber">1</span><span class="Punctuation">)</span> <span class="Operator">+</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="DecNumber">2</span><span class="Punctuation">)</span><span class="Punctuation">)</span>

<span class="Identifier">doAssert</span> <span class="Identifier">s</span> <span class="Operator">==</span> <span class="StringLit">&quot;123&quot;</span></pre></p>
<p>Assignments are not special, the left-hand-side expression is evaluated before the right-hand side:</p>
<p><pre class="listing"><span class="Keyword">var</span> <span class="Identifier">v</span> <span class="Operator">=</span> <span class="DecNumber">0</span>
<span class="Keyword">proc</span> <span class="Identifier">getI</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">v</span>
  <span class="Identifier">inc</span> <span class="Identifier">v</span>

<span class="Keyword">var</span> <span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">array</span><span class="Punctuation">[</span><span class="FloatNumber">0.</span><span class="Operator">.</span><span class="DecNumber">2</span><span class="Punctuation">,</span> <span class="Identifier">int</span><span class="Punctuation">]</span>

<span class="Keyword">proc</span> <span class="Identifier">someCopy</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">int</span><span class="Punctuation">;</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Identifier">a</span> <span class="Operator">=</span> <span class="Identifier">b</span>

<span class="Identifier">a</span><span class="Punctuation">[</span><span class="Identifier">getI</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Identifier">getI</span><span class="Punctuation">(</span><span class="Punctuation">)</span>

<span class="Identifier">doAssert</span> <span class="Identifier">a</span> <span class="Operator">==</span> <span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="DecNumber">0</span><span class="Punctuation">,</span> <span class="DecNumber">0</span><span class="Punctuation">]</span>

<span class="Identifier">v</span> <span class="Operator">=</span> <span class="DecNumber">0</span>
<span class="Identifier">someCopy</span><span class="Punctuation">(</span><span class="Identifier">b</span><span class="Punctuation">[</span><span class="Identifier">getI</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">]</span><span class="Punctuation">,</span> <span class="Identifier">getI</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">)</span>

<span class="Identifier">doAssert</span> <span class="Identifier">b</span> <span class="Operator">==</span> <span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="DecNumber">0</span><span class="Punctuation">,</span> <span class="DecNumber">0</span><span class="Punctuation">]</span></pre></p>
<p>Rationale: Consistency with overloaded assignment or assignment-like operations, <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span> <span class="Operator">=</span> <span class="Identifier">b</span></span></tt> can be read as <tt class="docutils literal"><span class="pre"><span class="Identifier">performSomeCopy</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">)</span></span></tt>.</p>
<p>However, the concept of &quot;order of evaluation&quot; is only applicable after the code was normalized: The normalization involves template expansions and argument reorderings that have been passed to named parameters:</p>
<p><pre class="listing"><span class="Keyword">var</span> <span class="Identifier">s</span> <span class="Operator">=</span> <span class="StringLit">&quot;&quot;</span>

<span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span>
  <span class="Identifier">s</span><span class="Operator">.</span><span class="Identifier">add</span> <span class="StringLit">&quot;p&quot;</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="DecNumber">5</span>

<span class="Keyword">proc</span> <span class="Identifier">q</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span>
  <span class="Identifier">s</span><span class="Operator">.</span><span class="Identifier">add</span> <span class="StringLit">&quot;q&quot;</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="DecNumber">3</span>

<span class="Comment"># Evaluation order is 'b' before 'a' due to template</span>
<span class="Comment"># expansion's semantics.</span>
<span class="Keyword">template</span> <span class="Identifier">swapArgs</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">untyped</span> <span class="Operator">=</span>
  <span class="Identifier">b</span> <span class="Operator">+</span> <span class="Identifier">a</span>

<span class="Identifier">doAssert</span> <span class="Identifier">swapArgs</span><span class="Punctuation">(</span><span class="Identifier">p</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Operator">+</span> <span class="Identifier">q</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">,</span> <span class="Identifier">q</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Operator">-</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">)</span> <span class="Operator">==</span> <span class="DecNumber">6</span>
<span class="Identifier">doAssert</span> <span class="Identifier">s</span> <span class="Operator">==</span> <span class="StringLit">&quot;qppq&quot;</span>

<span class="Comment"># Evaluation order is not influenced by named parameters:</span>
<span class="Keyword">proc</span> <span class="Identifier">construct</span><span class="Punctuation">(</span><span class="Identifier">first</span><span class="Punctuation">,</span> <span class="Identifier">second</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">discard</span>

<span class="Comment"># 'p' is evaluated before 'q'!</span>
<span class="Identifier">construct</span><span class="Punctuation">(</span><span class="Identifier">second</span> <span class="Operator">=</span> <span class="Identifier">q</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">,</span> <span class="Identifier">first</span> <span class="Operator">=</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">)</span>

<span class="Identifier">doAssert</span> <span class="Identifier">s</span> <span class="Operator">==</span> <span class="StringLit">&quot;qppqpq&quot;</span></pre></p>
<p>Rationale: This is far easier to implement than hypothetical alternatives.</p>

<h1><a class="toc-backref" id="constants-and-constant-expressions" href="#constants-and-constant-expressions">Constants and Constant Expressions</a></h1><p>A <span id="constant_1">constant</span> is a symbol that is bound to the value of a constant expression. Constant expressions are restricted to depend only on the following categories of values and operations, because these are either built into the language or declared and evaluated before semantic analysis of the constant expression:</p>
<ul class="simple"><li>literals</li>
<li>built-in operators</li>
<li>previously declared constants and compile-time variables</li>
<li>previously declared macros and templates</li>
<li>previously declared procedures that have no side effects beyond possibly modifying compile-time variables</li>
</ul>
<p>A constant expression can contain code blocks that may internally use all Nim features supported at compile time (as detailed in the next section below). Within such a code block, it is possible to declare variables and then later read and update them, or declare variables and pass them to procedures that modify them. However, the code in such a block must still adhere to the restrictions listed above for referencing values and operations outside the block.</p>
<p>The ability to access and modify compile-time variables adds flexibility to constant expressions that may be surprising to those coming from other statically typed languages. For example, the following code echoes the beginning of the Fibonacci series <strong>at compile-time</strong>. (This is a demonstration of flexibility in defining constants, not a recommended style for solving this problem.)</p>
<p><pre class="listing"><span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">strformat</span>

<span class="Keyword">var</span> <span class="Identifier">fibN</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">compileTime</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span> <span class="Identifier">int</span>
<span class="Keyword">var</span> <span class="Identifier">fibPrev</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">compileTime</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span> <span class="Identifier">int</span>
<span class="Keyword">var</span> <span class="Identifier">fibPrevPrev</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">compileTime</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span> <span class="Identifier">int</span>

<span class="Keyword">proc</span> <span class="Identifier">nextFib</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Keyword">if</span> <span class="Identifier">fibN</span> <span class="Operator">&lt;</span> <span class="DecNumber">2</span><span class="Punctuation">:</span>
    <span class="Identifier">fibN</span>
  <span class="Keyword">else</span><span class="Punctuation">:</span>
    <span class="Identifier">fibPrevPrev</span> <span class="Operator">+</span> <span class="Identifier">fibPrev</span>
  <span class="Identifier">inc</span><span class="Punctuation">(</span><span class="Identifier">fibN</span><span class="Punctuation">)</span>
  <span class="Identifier">fibPrevPrev</span> <span class="Operator">=</span> <span class="Identifier">fibPrev</span>
  <span class="Identifier">fibPrev</span> <span class="Operator">=</span> <span class="Identifier">result</span>

<span class="Keyword">const</span> <span class="Identifier">f0</span> <span class="Operator">=</span> <span class="Identifier">nextFib</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
<span class="Keyword">const</span> <span class="Identifier">f1</span> <span class="Operator">=</span> <span class="Identifier">nextFib</span><span class="Punctuation">(</span><span class="Punctuation">)</span>

<span class="Keyword">const</span> <span class="Identifier">displayFib</span> <span class="Operator">=</span> <span class="Keyword">block</span><span class="Punctuation">:</span>
  <span class="Keyword">const</span> <span class="Identifier">f2</span> <span class="Operator">=</span> <span class="Identifier">nextFib</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
  <span class="Keyword">var</span> <span class="Identifier">result</span> <span class="Operator">=</span> <span class="RawData">fmt&quot;Fibonacci sequence: {f0}, {f1}, {f2}&quot;</span>
  <span class="Keyword">for</span> <span class="Identifier">i</span> <span class="Keyword">in</span> <span class="FloatNumber">3.</span><span class="Operator">.</span><span class="DecNumber">12</span><span class="Punctuation">:</span>
    <span class="Identifier">add</span><span class="Punctuation">(</span><span class="Identifier">result</span><span class="Punctuation">,</span> <span class="RawData">fmt&quot;, {nextFib()}&quot;</span><span class="Punctuation">)</span>
  <span class="Identifier">result</span>

<span class="Keyword">static</span><span class="Punctuation">:</span>
  <span class="Identifier">echo</span> <span class="Identifier">displayFib</span></pre></p>

<h1><a class="toc-backref" id="restrictions-on-compileminustime-execution" href="#restrictions-on-compileminustime-execution">Restrictions on Compile-Time Execution</a></h1><p>Nim code that will be executed at compile time cannot use the following language features:</p>
<ul class="simple"><li>methods</li>
<li>closure iterators</li>
<li>the <tt class="docutils literal"><span class="pre"><span class="Keyword">cast</span></span></tt> operator</li>
<li>reference (pointer) types</li>
<li>FFI</li>
</ul>
<p>The use of wrappers that use FFI and/or <tt class="docutils literal"><span class="pre"><span class="Keyword">cast</span></span></tt> is also disallowed. Note that these wrappers include the ones in the standard libraries.</p>
<p>Some or all of these restrictions are likely to be lifted over time.</p>

<h1><a class="toc-backref" id="types" href="#types">Types</a></h1><p>All expressions have a type that is known during semantic analysis. Nim is statically typed. One can declare new types, which is in essence defining an identifier that can be used to denote this custom type.</p>
<p>These are the major type classes:</p>
<ul class="simple"><li>ordinal types (consist of integer, bool, character, enumeration (and subranges thereof) types)</li>
<li>floating-point types</li>
<li>string type</li>
<li>structured types</li>
<li>reference (pointer) type</li>
<li>procedural type</li>
<li>generic type</li>
</ul>

<h2><a class="toc-backref" id="types-ordinal-types" href="#types-ordinal-types">Ordinal types</a></h2><p>Ordinal types have the following characteristics:</p>
<ul class="simple"><li>Ordinal types are countable and ordered. This property allows the operation of functions such as <tt class="docutils literal"><span class="pre"><span class="Identifier">inc</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Identifier">ord</span></span></tt>, and <tt class="docutils literal"><span class="pre"><span class="Identifier">dec</span></span></tt> on ordinal types to be defined.</li>
<li>Ordinal types have a smallest possible value, accessible with <tt class="docutils literal"><span class="pre"><span class="Identifier">low</span><span class="Punctuation">(</span><span class="Keyword">type</span><span class="Punctuation">)</span></span></tt>. Trying to count further down than the smallest value produces a panic or a static error.</li>
<li>Ordinal types have a largest possible value, accessible with <tt class="docutils literal"><span class="pre"><span class="Identifier">high</span><span class="Punctuation">(</span><span class="Keyword">type</span><span class="Punctuation">)</span></span></tt>. Trying to count further up than the largest value produces a panic or a static error.</li>
</ul>
<p>Integers, bool, characters, and enumeration types (and subranges of these types) belong to ordinal types.</p>
<p>A distinct type is an ordinal type if its base type is an ordinal type.</p>

<h2><a class="toc-backref" id="types-preminusdefined-integer-types" href="#types-preminusdefined-integer-types">Pre-defined integer types</a></h2><p>These integer types are pre-defined:</p>
<dl class="docutils"><dt><tt class="docutils literal"><span class="pre"><span class="Identifier">int</span></span></tt></dt>
<dd>the generic signed integer type; its size is platform-dependent and has the same size as a pointer. This type should be used in general. An integer literal that has no type suffix is of this type if it is in the range <tt class="docutils literal"><span class="pre"><span class="Identifier">low</span><span class="Punctuation">(</span><span class="Identifier">int32</span><span class="Punctuation">)</span><span class="Operator">..</span><span class="Identifier">high</span><span class="Punctuation">(</span><span class="Identifier">int32</span><span class="Punctuation">)</span></span></tt> otherwise the literal's type is <tt class="docutils literal"><span class="pre"><span class="Identifier">int64</span></span></tt>.</dd>
<dt><tt class="docutils literal"><span class="pre"><span class="Identifier">int</span></span></tt>XX</dt>
<dd>additional signed integer types of XX bits use this naming scheme (example: int16 is a 16-bit wide integer). The current implementation supports <tt class="docutils literal"><span class="pre"><span class="Identifier">int8</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Identifier">int16</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Identifier">int32</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Identifier">int64</span></span></tt>. Literals of these types have the suffix 'iXX.</dd>
<dt><tt class="docutils literal"><span class="pre"><span class="Identifier">uint</span></span></tt></dt>
<dd>the generic <span id="unsigned-integer_1">unsigned integer</span> type; its size is platform-dependent and has the same size as a pointer. An integer literal with the type suffix <tt class="docutils literal"><span class="pre"><span class="CharLit">'u</span></span></tt> is of this type.</dd>
<dt><tt class="docutils literal"><span class="pre"><span class="Identifier">uint</span></span></tt>XX</dt>
<dd>additional unsigned integer types of XX bits use this naming scheme (example: uint16 is a 16-bit wide unsigned integer). The current implementation supports <tt class="docutils literal"><span class="pre"><span class="Identifier">uint8</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Identifier">uint16</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Identifier">uint32</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Identifier">uint64</span></span></tt>. Literals of these types have the suffix 'uXX. Unsigned operations all wrap around; they cannot lead to over- or underflow errors.</dd>
</dl>
<p>In addition to the usual arithmetic operators for signed and unsigned integers (<tt class="docutils literal"><span class="pre"><span class="Operator">+</span> <span class="Operator">-</span> <span class="Operator">*</span></span></tt> etc.) there are also operators that formally work on <em>signed</em> integers but treat their arguments as <em>unsigned</em>: They are mostly provided for backwards compatibility with older versions of the language that lacked unsigned integer types. These unsigned operations for signed integers use the <tt class="docutils literal"><span class="pre"><span class="Operator">%</span></span></tt> suffix as convention:</p>
<table border="1" class="docutils"><tr><th>operation</th><th>meaning</th></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">a</span> <span class="Operator">+%</span> <span class="Identifier">b</span></span></tt></td><td>unsigned integer addition</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">a</span> <span class="Operator">-%</span> <span class="Identifier">b</span></span></tt></td><td>unsigned integer subtraction</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">a</span> <span class="Operator">*%</span> <span class="Identifier">b</span></span></tt></td><td>unsigned integer multiplication</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">a</span> <span class="Operator">/%</span> <span class="Identifier">b</span></span></tt></td><td>unsigned integer division</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">a</span> <span class="Operator">%%</span> <span class="Identifier">b</span></span></tt></td><td>unsigned integer modulo operation</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">a</span> <span class="Operator">&lt;%</span> <span class="Identifier">b</span></span></tt></td><td>treat <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">b</span></span></tt> as unsigned and compare</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">a</span> <span class="Operator">&lt;=%</span> <span class="Identifier">b</span></span></tt></td><td>treat <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">b</span></span></tt> as unsigned and compare</td></tr>
</table><p><span id="automatic-type-conversion_1">Automatic type conversion</span> is performed in expressions where different kinds of integer types are used: the smaller type is converted to the larger.</p>
<p>A <span id="narrowing-type-conversion_1">narrowing type conversion</span> converts a larger to a smaller type (for example <tt class="docutils literal"><span class="pre"><span class="Identifier">int32</span> <span class="Operator">-&gt;</span> <span class="Identifier">int16</span></span></tt>). A <span id="widening-type-conversion_1">widening type conversion</span> converts a smaller type to a larger type (for example <tt class="docutils literal"><span class="pre"><span class="Identifier">int16</span> <span class="Operator">-&gt;</span> <span class="Identifier">int32</span></span></tt>). In Nim only widening type conversions are <em>implicit</em>:</p>
<p><pre class="listing"><span class="Keyword">var</span> <span class="Identifier">myInt16</span> <span class="Operator">=</span> <span class="DecNumber">5</span><span class="Identifier">i16</span>
<span class="Keyword">var</span> <span class="Identifier">myInt</span><span class="Punctuation">:</span> <span class="Identifier">int</span>
<span class="Identifier">myInt16</span> <span class="Operator">+</span> <span class="DecNumber">34</span>     <span class="Comment"># of type `int16`</span>
<span class="Identifier">myInt16</span> <span class="Operator">+</span> <span class="Identifier">myInt</span>  <span class="Comment"># of type `int`</span>
<span class="Identifier">myInt16</span> <span class="Operator">+</span> <span class="DecNumber">2</span><span class="Identifier">i32</span>   <span class="Comment"># of type `int32`</span></pre></p>
<p>However, <tt class="docutils literal"><span class="pre"><span class="Identifier">int</span></span></tt> literals are implicitly convertible to a smaller integer type if the literal's value fits this smaller type and such a conversion is less expensive than other implicit conversions, so <tt class="docutils literal"><span class="pre"><span class="Identifier">myInt16</span> <span class="Operator">+</span> <span class="DecNumber">34</span></span></tt> produces an <tt class="docutils literal"><span class="pre"><span class="Identifier">int16</span></span></tt> result.</p>
<p>For further details, see <a class="reference internal" href="#type-relations-convertible-relation">Convertible relation</a>.</p>

<h2><a class="toc-backref" id="types-subrange-types" href="#types-subrange-types">Subrange types</a></h2><p>A subrange type is a range of values from an ordinal or floating-point type (the base type). To define a subrange type, one must specify its limiting values -- the lowest and highest value of the type. For example:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">Subrange</span> <span class="Operator">=</span> <span class="Identifier">range</span><span class="Punctuation">[</span><span class="FloatNumber">0.</span><span class="Operator">.</span><span class="DecNumber">5</span><span class="Punctuation">]</span>
  <span class="Identifier">PositiveFloat</span> <span class="Operator">=</span> <span class="Identifier">range</span><span class="Punctuation">[</span><span class="FloatNumber">0.0</span><span class="Operator">..</span><span class="Identifier">Inf</span><span class="Punctuation">]</span>
  <span class="Identifier">Positive</span><span class="Operator">*</span> <span class="Operator">=</span> <span class="Identifier">range</span><span class="Punctuation">[</span><span class="FloatNumber">1.</span><span class="Operator">.</span><span class="Identifier">high</span><span class="Punctuation">(</span><span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">]</span> <span class="Comment"># as defined in `system`</span></pre></p>
<p><tt class="docutils literal"><span class="pre"><span class="Identifier">Subrange</span></span></tt> is a subrange of an integer which can only hold the values 0 to 5. <tt class="docutils literal"><span class="pre"><span class="Identifier">PositiveFloat</span></span></tt> defines a subrange of all positive floating-point values. NaN does not belong to any subrange of floating-point types. Assigning any other value to a variable of type <tt class="docutils literal"><span class="pre"><span class="Identifier">Subrange</span></span></tt> is a panic (or a static error if it can be determined during semantic analysis). Assignments from the base type to one of its subrange types (and vice versa) are allowed.</p>
<p>A subrange type has the same size as its base type (<tt class="docutils literal"><span class="pre"><span class="Identifier">int</span></span></tt> in the Subrange example).</p>

<h2><a class="toc-backref" id="types-preminusdefined-floatingminuspoint-types" href="#types-preminusdefined-floatingminuspoint-types">Pre-defined floating-point types</a></h2><p>The following floating-point types are pre-defined:</p>
<dl class="docutils"><dt><tt class="docutils literal"><span class="pre"><span class="Identifier">float</span></span></tt></dt>
<dd>the generic floating-point type; its size used to be platform-dependent, but now it is always mapped to <tt class="docutils literal"><span class="pre"><span class="Identifier">float64</span></span></tt>. This type should be used in general.</dd>
<dt><tt class="docutils literal"><span class="pre"><span class="Identifier">float</span></span></tt>XX</dt>
<dd>an implementation may define additional floating-point types of XX bits using this naming scheme (example: <tt class="docutils literal"><span class="pre"><span class="Identifier">float64</span></span></tt> is a 64-bit wide float). The current implementation supports <tt class="docutils literal"><span class="pre"><span class="Identifier">float32</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">float64</span></span></tt>. Literals of these types have the suffix 'fXX.</dd>
</dl>
<p>Automatic type conversion in expressions with different kinds of floating-point types is performed: See <a class="reference internal" href="#type-relations-convertible-relation">Convertible relation</a> for further details. Arithmetic performed on floating-point types follows the IEEE standard. Integer types are not converted to floating-point types automatically and vice versa.</p>
<p>The IEEE standard defines five types of floating-point exceptions:</p>
<ul class="simple"><li>Invalid: operations with mathematically invalid operands, for example 0.0/0.0, sqrt(-1.0), and log(-37.8).</li>
<li>Division by zero: divisor is zero and dividend is a finite nonzero number, for example 1.0/0.0.</li>
<li>Overflow: operation produces a result that exceeds the range of the exponent, for example MAXDOUBLE+0.0000000000001e308.</li>
<li>Underflow: operation produces a result that is too small to be represented as a normal number, for example, MINDOUBLE * MINDOUBLE.</li>
<li>Inexact: operation produces a result that cannot be represented with infinite precision, for example, 2.0 / 3.0, log(1.1) and 0.1 in input.</li>
</ul>
<p>The IEEE exceptions are either ignored during execution or mapped to the Nim exceptions: <span id="floatinvalidopdefect_1">FloatInvalidOpDefect</span>, <span id="floatdivbyzerodefect_1">FloatDivByZeroDefect</span>, <span id="floatoverflowdefect_1">FloatOverflowDefect</span>, <span id="floatunderflowdefect_1">FloatUnderflowDefect</span>, and <span id="floatinexactdefect_1">FloatInexactDefect</span>. These exceptions inherit from the <span id="floatingpointdefect_1">FloatingPointDefect</span> base class.</p>
<p>Nim provides the pragmas <span id="nanchecks_1">nanChecks</span> and <span id="infchecks_1">infChecks</span> to control whether the IEEE exceptions are ignored or trap a Nim exception:</p>
<p><pre class="listing"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">nanChecks</span><span class="Punctuation">:</span> <span class="Identifier">on</span><span class="Punctuation">,</span> <span class="Identifier">infChecks</span><span class="Punctuation">:</span> <span class="Identifier">on</span><span class="Operator">.</span><span class="Punctuation">}</span>
<span class="Keyword">var</span> <span class="Identifier">a</span> <span class="Operator">=</span> <span class="FloatNumber">1.0</span>
<span class="Keyword">var</span> <span class="Identifier">b</span> <span class="Operator">=</span> <span class="FloatNumber">0.0</span>
<span class="Identifier">echo</span> <span class="Identifier">b</span> <span class="Operator">/</span> <span class="Identifier">b</span> <span class="Comment"># raises FloatInvalidOpDefect</span>
<span class="Identifier">echo</span> <span class="Identifier">a</span> <span class="Operator">/</span> <span class="Identifier">b</span> <span class="Comment"># raises FloatOverflowDefect</span></pre></p>
<p>In the current implementation <tt class="docutils literal"><span class="pre"><span class="Identifier">FloatDivByZeroDefect</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">FloatInexactDefect</span></span></tt> are never raised. <tt class="docutils literal"><span class="pre"><span class="Identifier">FloatOverflowDefect</span></span></tt> is raised instead of <tt class="docutils literal"><span class="pre"><span class="Identifier">FloatDivByZeroDefect</span></span></tt>. There is also a <span id="floatchecks_1">floatChecks</span> pragma that is a short-cut for the combination of <tt class="docutils literal"><span class="pre"><span class="Identifier">nanChecks</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">infChecks</span></span></tt> pragmas. <tt class="docutils literal"><span class="pre"><span class="Identifier">floatChecks</span></span></tt> are turned off as default.</p>
<p>The only operations that are affected by the <tt class="docutils literal"><span class="pre"><span class="Identifier">floatChecks</span></span></tt> pragma are the <tt class="docutils literal"><span class="pre"><span class="Operator">+</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Operator">-</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Operator">*</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Operator">/</span></span></tt> operators for floating-point types.</p>
<p>An implementation should always use the maximum precision available to evaluate floating-point values during semantic analysis; this means expressions like <tt class="docutils literal"><span class="pre"><span class="FloatNumber">0.09'f32</span> <span class="Operator">+</span> <span class="FloatNumber">0.01'f32</span> <span class="Operator">==</span> <span class="FloatNumber">0.09'f64</span> <span class="Operator">+</span> <span class="FloatNumber">0.01'f64</span></span></tt> that are evaluating during constant folding are true.</p>

<h2><a class="toc-backref" id="types-boolean-type" href="#types-boolean-type">Boolean type</a></h2><p>The boolean type is named <span id="bool_1">bool</span> in Nim and can be one of the two pre-defined values <tt class="docutils literal"><span class="pre"><span class="Identifier">true</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">false</span></span></tt>. Conditions in <tt class="docutils literal"><span class="pre"><span class="Keyword">while</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">if</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">elif</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">when</span></span></tt>-statements need to be of type <tt class="docutils literal"><span class="pre"><span class="Identifier">bool</span></span></tt>.</p>
<p>This condition holds:</p>
<p><pre class="listing"><span class="Identifier">ord</span><span class="Punctuation">(</span><span class="Identifier">false</span><span class="Punctuation">)</span> <span class="Operator">==</span> <span class="DecNumber">0</span> <span class="Keyword">and</span> <span class="Identifier">ord</span><span class="Punctuation">(</span><span class="Identifier">true</span><span class="Punctuation">)</span> <span class="Operator">==</span> <span class="DecNumber">1</span></pre></p>
<p>The operators <tt class="docutils literal"><span class="pre"><span class="Keyword">not</span><span class="Punctuation">,</span> <span class="Keyword">and</span><span class="Punctuation">,</span> <span class="Keyword">or</span><span class="Punctuation">,</span> <span class="Keyword">xor</span><span class="Punctuation">,</span> <span class="Operator">&lt;</span><span class="Punctuation">,</span> <span class="Operator">&lt;=</span><span class="Punctuation">,</span> <span class="Operator">&gt;</span><span class="Punctuation">,</span> <span class="Operator">&gt;=</span><span class="Punctuation">,</span> <span class="Operator">!=</span><span class="Punctuation">,</span> <span class="Operator">==</span></span></tt> are defined for the bool type. The <tt class="docutils literal"><span class="pre"><span class="Keyword">and</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Keyword">or</span></span></tt> operators perform short-cut evaluation. Example:</p>
<p><pre class="listing"><span class="Keyword">while</span> <span class="Identifier">p</span> <span class="Operator">!=</span> <span class="Keyword">nil</span> <span class="Keyword">and</span> <span class="Identifier">p</span><span class="Operator">.</span><span class="Identifier">name</span> <span class="Operator">!=</span> <span class="StringLit">&quot;xyz&quot;</span><span class="Punctuation">:</span>
  <span class="Comment"># p.name is not evaluated if p == nil</span>
  <span class="Identifier">p</span> <span class="Operator">=</span> <span class="Identifier">p</span><span class="Operator">.</span><span class="Identifier">next</span></pre></p>
<p>The size of the bool type is one byte.</p>

<h2><a class="toc-backref" id="types-character-type" href="#types-character-type">Character type</a></h2><p>The character type is named <tt class="docutils literal"><span class="pre"><span class="Identifier">char</span></span></tt> in Nim. Its size is one byte. Thus, it cannot represent a UTF-8 character, but a part of it.</p>
<p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">Rune</span></span></tt> type is used for Unicode characters, it can represent any Unicode character. <tt class="docutils literal"><span class="pre"><span class="Identifier">Rune</span></span></tt> is declared in the <a class="reference external" href="unicode.html">unicode module</a>.</p>

<h2><a class="toc-backref" id="types-enumeration-types" href="#types-enumeration-types">Enumeration types</a></h2><p>Enumeration types define a new type whose values consist of the ones specified. The values are ordered. Example:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">Direction</span> <span class="Operator">=</span> <span class="Keyword">enum</span>
    <span class="Identifier">north</span><span class="Punctuation">,</span> <span class="Identifier">east</span><span class="Punctuation">,</span> <span class="Identifier">south</span><span class="Punctuation">,</span> <span class="Identifier">west</span></pre></p>
<p>Now the following holds:</p>
<p><pre class="listing"><span class="Identifier">ord</span><span class="Punctuation">(</span><span class="Identifier">north</span><span class="Punctuation">)</span> <span class="Operator">==</span> <span class="DecNumber">0</span>
<span class="Identifier">ord</span><span class="Punctuation">(</span><span class="Identifier">east</span><span class="Punctuation">)</span> <span class="Operator">==</span> <span class="DecNumber">1</span>
<span class="Identifier">ord</span><span class="Punctuation">(</span><span class="Identifier">south</span><span class="Punctuation">)</span> <span class="Operator">==</span> <span class="DecNumber">2</span>
<span class="Identifier">ord</span><span class="Punctuation">(</span><span class="Identifier">west</span><span class="Punctuation">)</span> <span class="Operator">==</span> <span class="DecNumber">3</span>

<span class="Comment"># Also allowed:</span>
<span class="Identifier">ord</span><span class="Punctuation">(</span><span class="Identifier">Direction</span><span class="Operator">.</span><span class="Identifier">west</span><span class="Punctuation">)</span> <span class="Operator">==</span> <span class="DecNumber">3</span></pre></p>
<p>The implied order is: north &lt; east &lt; south &lt; west. The comparison operators can be used with enumeration types. Instead of <tt class="docutils literal"><span class="pre"><span class="Identifier">north</span></span></tt> etc., the enum value can also be qualified with the enum type that it resides in, <tt class="docutils literal"><span class="pre"><span class="Identifier">Direction</span><span class="Operator">.</span><span class="Identifier">north</span></span></tt>.</p>
<p>For better interfacing to other programming languages, the fields of enum types can be assigned an explicit ordinal value. However, the ordinal values have to be in ascending order. A field whose ordinal value is not explicitly given is assigned the value of the previous field + 1.</p>
<p>An explicit ordered enum can have <em>holes</em>:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">TokenType</span> <span class="Operator">=</span> <span class="Keyword">enum</span>
    <span class="Identifier">a</span> <span class="Operator">=</span> <span class="DecNumber">2</span><span class="Punctuation">,</span> <span class="Identifier">b</span> <span class="Operator">=</span> <span class="DecNumber">4</span><span class="Punctuation">,</span> <span class="Identifier">c</span> <span class="Operator">=</span> <span class="DecNumber">89</span> <span class="Comment"># holes are valid</span></pre></p>
<p>However, it is then not ordinal anymore, so it is impossible to use these enums as an index type for arrays. The procedures <tt class="docutils literal"><span class="pre"><span class="Identifier">inc</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Identifier">dec</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Identifier">succ</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">pred</span></span></tt> are not available for them either.</p>
<p>The compiler supports the built-in stringify operator <tt class="docutils literal"><span class="pre"><span class="Operator">$</span></span></tt> for enumerations. The stringify's result can be controlled by explicitly giving the string values to use:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">MyEnum</span> <span class="Operator">=</span> <span class="Keyword">enum</span>
    <span class="Identifier">valueA</span> <span class="Operator">=</span> <span class="Punctuation">(</span><span class="DecNumber">0</span><span class="Punctuation">,</span> <span class="StringLit">&quot;my value A&quot;</span><span class="Punctuation">)</span><span class="Punctuation">,</span>
    <span class="Identifier">valueB</span> <span class="Operator">=</span> <span class="StringLit">&quot;value B&quot;</span><span class="Punctuation">,</span>
    <span class="Identifier">valueC</span> <span class="Operator">=</span> <span class="DecNumber">2</span><span class="Punctuation">,</span>
    <span class="Identifier">valueD</span> <span class="Operator">=</span> <span class="Punctuation">(</span><span class="DecNumber">3</span><span class="Punctuation">,</span> <span class="StringLit">&quot;abc&quot;</span><span class="Punctuation">)</span></pre></p>
<p>As can be seen from the example, it is possible to both specify a field's ordinal value and its string value by using a tuple. It is also possible to only specify one of them.</p>
<p>An enum can be marked with the <tt class="docutils literal"><span class="pre"><span class="Identifier">pure</span></span></tt> pragma so that its fields are added to a special module-specific hidden scope that is only queried as the last attempt. Only non-ambiguous symbols are added to this scope. But one can always access these via type qualification written as <tt class="docutils literal"><span class="pre"><span class="Identifier">MyEnum</span><span class="Operator">.</span><span class="Identifier">value</span></span></tt>:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">MyEnum</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">pure</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">enum</span>
    <span class="Identifier">valueA</span><span class="Punctuation">,</span> <span class="Identifier">valueB</span><span class="Punctuation">,</span> <span class="Identifier">valueC</span><span class="Punctuation">,</span> <span class="Identifier">valueD</span><span class="Punctuation">,</span> <span class="Identifier">amb</span>
  
  <span class="Identifier">OtherEnum</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">pure</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">enum</span>
    <span class="Identifier">valueX</span><span class="Punctuation">,</span> <span class="Identifier">valueY</span><span class="Punctuation">,</span> <span class="Identifier">valueZ</span><span class="Punctuation">,</span> <span class="Identifier">amb</span>


<span class="Identifier">echo</span> <span class="Identifier">valueA</span> <span class="Comment"># MyEnum.valueA</span>
<span class="Identifier">echo</span> <span class="Identifier">amb</span>    <span class="Comment"># Error: Unclear whether it's MyEnum.amb or OtherEnum.amb</span>
<span class="Identifier">echo</span> <span class="Identifier">MyEnum</span><span class="Operator">.</span><span class="Identifier">amb</span> <span class="Comment"># OK.</span></pre></p>
<p>Enum value names are overloadable, much like routines. If both of the enums <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">U</span></span></tt> have a member named <tt class="docutils literal"><span class="pre"><span class="Identifier">foo</span></span></tt>, then the identifier <tt class="docutils literal"><span class="pre"><span class="Identifier">foo</span></span></tt> corresponds to a choice between <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span><span class="Operator">.</span><span class="Identifier">foo</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">U</span><span class="Operator">.</span><span class="Identifier">foo</span></span></tt>. During overload resolution, the correct type of <tt class="docutils literal"><span class="pre"><span class="Identifier">foo</span></span></tt> is decided from the context. If the type of <tt class="docutils literal"><span class="pre"><span class="Identifier">foo</span></span></tt> is ambiguous, a static error will be produced.</p>
<p><pre class="listing">
<span class="Keyword">type</span>
  <span class="Identifier">E1</span> <span class="Operator">=</span> <span class="Keyword">enum</span>
    <span class="Identifier">value1</span><span class="Punctuation">,</span>
    <span class="Identifier">value2</span>
  <span class="Identifier">E2</span> <span class="Operator">=</span> <span class="Keyword">enum</span>
    <span class="Identifier">value1</span><span class="Punctuation">,</span>
    <span class="Identifier">value2</span> <span class="Operator">=</span> <span class="DecNumber">4</span>

<span class="Keyword">const</span>
  <span class="Identifier">Lookuptable</span> <span class="Operator">=</span> <span class="Punctuation">[</span>
    <span class="Identifier">E1</span><span class="Operator">.</span><span class="Identifier">value1</span><span class="Punctuation">:</span> <span class="StringLit">&quot;1&quot;</span><span class="Punctuation">,</span>
    <span class="Comment"># no need to qualify value2, known to be E1.value2</span>
    <span class="Identifier">value2</span><span class="Punctuation">:</span> <span class="StringLit">&quot;2&quot;</span>
  <span class="Punctuation">]</span>

<span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Identifier">e</span><span class="Punctuation">:</span> <span class="Identifier">E1</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Comment"># disambiguation in 'case' statements:</span>
  <span class="Keyword">case</span> <span class="Identifier">e</span>
  <span class="Keyword">of</span> <span class="Identifier">value1</span><span class="Punctuation">:</span> <span class="Identifier">echo</span> <span class="StringLit">&quot;A&quot;</span>
  <span class="Keyword">of</span> <span class="Identifier">value2</span><span class="Punctuation">:</span> <span class="Identifier">echo</span> <span class="StringLit">&quot;B&quot;</span>

<span class="Identifier">p</span> <span class="Identifier">value2</span></pre></p>
<p>In some cases, ambiguity of enums is resolved depending on the relation between the current scope and the scope the enums were defined in.</p>
<p><pre class="listing"><span class="Comment"># a.nim</span>
<span class="Keyword">type</span> <span class="Identifier">Foo</span><span class="Operator">*</span> <span class="Operator">=</span> <span class="Keyword">enum</span> <span class="Identifier">abc</span>

<span class="Comment"># b.nim</span>
<span class="Keyword">import</span> <span class="Identifier">a</span>
<span class="Keyword">type</span> <span class="Identifier">Bar</span> <span class="Operator">=</span> <span class="Keyword">enum</span> <span class="Identifier">abc</span>
<span class="Identifier">echo</span> <span class="Identifier">abc</span> <span class="Keyword">is</span> <span class="Identifier">Bar</span> <span class="Comment"># true</span>

<span class="Keyword">block</span><span class="Punctuation">:</span>
  <span class="Keyword">type</span> <span class="Identifier">Baz</span> <span class="Operator">=</span> <span class="Keyword">enum</span> <span class="Identifier">abc</span>
  <span class="Identifier">echo</span> <span class="Identifier">abc</span> <span class="Keyword">is</span> <span class="Identifier">Baz</span> <span class="Comment"># true</span></pre></p>
<p>To implement bit fields with enums see <a class="reference internal" href="#set-type-bit-fields">Bit fields</a>.</p>

<h2><a class="toc-backref" id="types-string-type" href="#types-string-type">String type</a></h2><p>All string literals are of the type <tt class="docutils literal"><span class="pre"><span class="Identifier">string</span></span></tt>. A string in Nim is very similar to a sequence of characters. However, strings in Nim are both zero-terminated and have a length field. One can retrieve the length with the builtin <tt class="docutils literal"><span class="pre"><span class="Identifier">len</span></span></tt> procedure; the length never counts the terminating zero.</p>
<p>The terminating zero cannot be accessed unless the string is converted to the <tt class="docutils literal"><span class="pre"><span class="Identifier">cstring</span></span></tt> type first. The terminating zero assures that this conversion can be done in O(1) and without any allocations.</p>
<p>The assignment operator for strings always copies the string. The <tt class="docutils literal"><span class="pre"><span class="Operator">&amp;</span></span></tt> operator concatenates strings.</p>
<p>Most native Nim types support conversion to strings with the special <tt class="docutils literal"><span class="pre"><span class="Operator">$</span></span></tt> proc. When calling the <tt class="docutils literal"><span class="pre"><span class="Identifier">echo</span></span></tt> proc, for example, the built-in stringify operation for the parameter is called:</p>
<p><pre class="listing"><span class="Identifier">echo</span> <span class="DecNumber">3</span> <span class="Comment"># calls `$` for `int`</span></pre></p>
<p>Whenever a user creates a specialized object, implementation of this procedure provides for <tt class="docutils literal"><span class="pre"><span class="Identifier">string</span></span></tt> representation.</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">Person</span> <span class="Operator">=</span> <span class="Keyword">object</span>
    <span class="Identifier">name</span><span class="Punctuation">:</span> <span class="Identifier">string</span>
    <span class="Identifier">age</span><span class="Punctuation">:</span> <span class="Identifier">int</span>

<span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">$</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">p</span><span class="Punctuation">:</span> <span class="Identifier">Person</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">string</span> <span class="Operator">=</span> <span class="Comment"># `$` always returns a string</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">p</span><span class="Operator">.</span><span class="Identifier">name</span> <span class="Operator">&amp;</span> <span class="StringLit">&quot; is &quot;</span> <span class="Operator">&amp;</span>
          <span class="Operator">$</span><span class="Identifier">p</span><span class="Operator">.</span><span class="Identifier">age</span> <span class="Operator">&amp;</span> <span class="Comment"># we *need* the `$` in front of p.age which</span>
                   <span class="Comment"># is natively an integer to convert it to</span>
                   <span class="Comment"># a string</span>
          <span class="StringLit">&quot; years old.&quot;</span></pre></p>
<p>While <tt class="docutils literal"><span class="pre"><span class="Operator">$</span><span class="Identifier">p</span><span class="Operator">.</span><span class="Identifier">name</span></span></tt> can also be used, the <tt class="docutils literal"><span class="pre"><span class="Operator">$</span></span></tt> operation on a string does nothing. Note that we cannot rely on automatic conversion from an <tt class="docutils literal"><span class="pre"><span class="Identifier">int</span></span></tt> to a <tt class="docutils literal"><span class="pre"><span class="Identifier">string</span></span></tt> like we can for the <tt class="docutils literal"><span class="pre"><span class="Identifier">echo</span></span></tt> proc.</p>
<p>Strings are compared by their lexicographical order. All comparison operators are available. Strings can be indexed like arrays (lower bound is 0). Unlike arrays, they can be used in case statements:</p>
<p><pre class="listing"><span class="Keyword">case</span> <span class="Identifier">paramStr</span><span class="Punctuation">(</span><span class="Identifier">i</span><span class="Punctuation">)</span>
<span class="Keyword">of</span> <span class="StringLit">&quot;-v&quot;</span><span class="Punctuation">:</span> <span class="Identifier">incl</span><span class="Punctuation">(</span><span class="Identifier">options</span><span class="Punctuation">,</span> <span class="Identifier">optVerbose</span><span class="Punctuation">)</span>
<span class="Keyword">of</span> <span class="StringLit">&quot;-h&quot;</span><span class="Punctuation">,</span> <span class="StringLit">&quot;-?&quot;</span><span class="Punctuation">:</span> <span class="Identifier">incl</span><span class="Punctuation">(</span><span class="Identifier">options</span><span class="Punctuation">,</span> <span class="Identifier">optHelp</span><span class="Punctuation">)</span>
<span class="Keyword">else</span><span class="Punctuation">:</span> <span class="Identifier">write</span><span class="Punctuation">(</span><span class="Identifier">stdout</span><span class="Punctuation">,</span> <span class="StringLit">&quot;invalid command line option!</span><span class="EscapeSequence">\n</span><span class="StringLit">&quot;</span><span class="Punctuation">)</span></pre></p>
<p>Per convention, all strings are UTF-8 strings, but this is not enforced. For example, when reading strings from binary files, they are merely a sequence of bytes. The index operation <tt class="docutils literal"><span class="pre"><span class="Identifier">s</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span></span></tt> means the i-th <em>char</em> of <tt class="docutils literal"><span class="pre"><span class="Identifier">s</span></span></tt>, not the i-th <em>unichar</em>. The iterator <tt class="docutils literal"><span class="pre"><span class="Identifier">runes</span></span></tt> from the <a class="reference external" href="unicode.html">unicode module</a> can be used for iteration over all Unicode characters.</p>

<h2><a class="toc-backref" id="types-cstring-type" href="#types-cstring-type">cstring type</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">cstring</span></span></tt> type meaning <tt class="docutils literal"><span class="pre"><span class="Identifier">compatible</span> <span class="Identifier">string</span></span></tt> is the native representation of a string for the compilation backend. For the C backend the <tt class="docutils literal"><span class="pre"><span class="Identifier">cstring</span></span></tt> type represents a pointer to a zero-terminated char array compatible with the type <tt class="docutils literal"><span class="pre"><span class="Identifier">char</span><span class="Operator">*</span></span></tt> in ANSI C. Its primary purpose lies in easy interfacing with C. The index operation <tt class="docutils literal"><span class="pre"><span class="Identifier">s</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span></span></tt> means the i-th <em>char</em> of <tt class="docutils literal"><span class="pre"><span class="Identifier">s</span></span></tt>; however no bounds checking for <tt class="docutils literal"><span class="pre"><span class="Identifier">cstring</span></span></tt> is performed making the index operation unsafe.</p>
<p>A Nim <tt class="docutils literal"><span class="pre"><span class="Identifier">string</span></span></tt> is implicitly convertible to <tt class="docutils literal"><span class="pre"><span class="Identifier">cstring</span></span></tt> for convenience. If a Nim string is passed to a C-style variadic proc, it is implicitly converted to <tt class="docutils literal"><span class="pre"><span class="Identifier">cstring</span></span></tt> too:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">printf</span><span class="Punctuation">(</span><span class="Identifier">formatstr</span><span class="Punctuation">:</span> <span class="Identifier">cstring</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importc</span><span class="Punctuation">:</span> <span class="StringLit">&quot;printf&quot;</span><span class="Punctuation">,</span> <span class="Identifier">varargs</span><span class="Punctuation">,</span>
                                  <span class="Identifier">header</span><span class="Punctuation">:</span> <span class="StringLit">&quot;&lt;stdio.h&gt;&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span>

<span class="Identifier">printf</span><span class="Punctuation">(</span><span class="StringLit">&quot;This works %s&quot;</span><span class="Punctuation">,</span> <span class="StringLit">&quot;as expected&quot;</span><span class="Punctuation">)</span></pre></p>
<p>Even though the conversion is implicit, it is not <em>safe</em>: The garbage collector does not consider a <tt class="docutils literal"><span class="pre"><span class="Identifier">cstring</span></span></tt> to be a root and may collect the underlying memory. For this reason, the implicit conversion will be removed in future releases of the Nim compiler. Certain idioms like conversion of a <tt class="docutils literal"><span class="pre"><span class="Keyword">const</span></span></tt> string to <tt class="docutils literal"><span class="pre"><span class="Identifier">cstring</span></span></tt> are safe and will remain to be allowed.</p>
<p>A <tt class="docutils literal"><span class="pre"><span class="Operator">$</span></span></tt> proc is defined for cstrings that returns a string. Thus, to get a nim string from a cstring:</p>
<p><pre class="listing"><span class="Keyword">var</span> <span class="Identifier">str</span><span class="Punctuation">:</span> <span class="Identifier">string</span> <span class="Operator">=</span> <span class="StringLit">&quot;Hello!&quot;</span>
<span class="Keyword">var</span> <span class="Identifier">cstr</span><span class="Punctuation">:</span> <span class="Identifier">cstring</span> <span class="Operator">=</span> <span class="Identifier">str</span>
<span class="Keyword">var</span> <span class="Identifier">newstr</span><span class="Punctuation">:</span> <span class="Identifier">string</span> <span class="Operator">=</span> <span class="Operator">$</span><span class="Identifier">cstr</span></pre></p>
<p><tt class="docutils literal"><span class="pre"><span class="Identifier">cstring</span></span></tt> literals shouldn't be modified.</p>
<p><pre class="listing"><span class="Keyword">var</span> <span class="Identifier">x</span> <span class="Operator">=</span> <span class="RawData">cstring&quot;literals&quot;</span>
<span class="Identifier">x</span><span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="CharLit">'A'</span> <span class="Comment"># This is wrong!!!</span></pre></p>
<p>If the <tt class="docutils literal"><span class="pre"><span class="Identifier">cstring</span></span></tt> originates from a regular memory (not read-only memory), it can be modified:</p>
<p><pre class="listing"><span class="Keyword">var</span> <span class="Identifier">x</span> <span class="Operator">=</span> <span class="StringLit">&quot;123456&quot;</span>
<span class="Identifier">prepareMutation</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span> <span class="Comment"># call `prepareMutation` before modifying the strings</span>
<span class="Keyword">var</span> <span class="Identifier">s</span><span class="Punctuation">:</span> <span class="Identifier">cstring</span> <span class="Operator">=</span> <span class="Identifier">cstring</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span>
<span class="Identifier">s</span><span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="CharLit">'u'</span> <span class="Comment"># This is ok</span></pre></p>
<p><tt class="docutils literal"><span class="pre"><span class="Identifier">cstring</span></span></tt> values may also be used in case statements like strings.</p>

<h2><a class="toc-backref" id="types-structured-types" href="#types-structured-types">Structured types</a></h2><p>A variable of a structured type can hold multiple values at the same time. Structured types can be nested to unlimited levels. Arrays, sequences, tuples, objects, and sets belong to the structured types.</p>

<h2><a class="toc-backref" id="types-array-and-sequence-types" href="#types-array-and-sequence-types">Array and sequence types</a></h2><p>Arrays are a homogeneous type, meaning that each element in the array has the same type. Arrays always have a fixed length specified as a constant expression (except for open arrays). They can be indexed by any ordinal type. A parameter <tt class="docutils literal"><span class="pre"><span class="Identifier">A</span></span></tt> may be an <em>open array</em>, in which case it is indexed by integers from 0 to <tt class="docutils literal"><span class="pre"><span class="Identifier">len</span><span class="Punctuation">(</span><span class="Identifier">A</span><span class="Punctuation">)</span><span class="Operator">-</span><span class="DecNumber">1</span></span></tt>. An array expression may be constructed by the array constructor <tt class="docutils literal"><span class="pre"><span class="Punctuation">[</span><span class="Punctuation">]</span></span></tt>. The element type of this array expression is inferred from the type of the first element. All other elements need to be implicitly convertible to this type.</p>
<p>An array type can be defined using the <tt class="docutils literal"><span class="pre"><span class="Identifier">array</span><span class="Punctuation">[</span><span class="Identifier">size</span><span class="Punctuation">,</span> <span class="Identifier">T</span><span class="Punctuation">]</span></span></tt> syntax, or using <tt class="docutils literal"><span class="pre"><span class="Identifier">array</span><span class="Punctuation">[</span><span class="Identifier">lo</span><span class="Operator">..</span><span class="Identifier">hi</span><span class="Punctuation">,</span> <span class="Identifier">T</span><span class="Punctuation">]</span></span></tt> for arrays that start at an index other than zero.</p>
<p>Sequences are similar to arrays but of dynamic length which may change during runtime (like strings). Sequences are implemented as growable arrays, allocating pieces of memory as items are added. A sequence <tt class="docutils literal"><span class="pre"><span class="Identifier">S</span></span></tt> is always indexed by integers from 0 to <tt class="docutils literal"><span class="pre"><span class="Identifier">len</span><span class="Punctuation">(</span><span class="Identifier">S</span><span class="Punctuation">)</span><span class="Operator">-</span><span class="DecNumber">1</span></span></tt> and its bounds are checked. Sequences can be constructed by the array constructor <tt class="docutils literal"><span class="pre"><span class="Punctuation">[</span><span class="Punctuation">]</span></span></tt> in conjunction with the array to sequence operator <tt class="docutils literal"><span class="pre"><span class="Operator">@</span></span></tt>. Another way to allocate space for a sequence is to call the built-in <tt class="docutils literal"><span class="pre"><span class="Identifier">newSeq</span></span></tt> procedure.</p>
<p>A sequence may be passed to a parameter that is of type <em>open array</em>.</p>
<p>Example:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">IntArray</span> <span class="Operator">=</span> <span class="Identifier">array</span><span class="Punctuation">[</span><span class="FloatNumber">0.</span><span class="Operator">.</span><span class="DecNumber">5</span><span class="Punctuation">,</span> <span class="Identifier">int</span><span class="Punctuation">]</span> <span class="Comment"># an array that is indexed with 0..5</span>
  <span class="Identifier">IntSeq</span> <span class="Operator">=</span> <span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">int</span><span class="Punctuation">]</span> <span class="Comment"># a sequence of integers</span>
<span class="Keyword">var</span>
  <span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">IntArray</span>
  <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">IntSeq</span>
<span class="Identifier">x</span> <span class="Operator">=</span> <span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="DecNumber">2</span><span class="Punctuation">,</span> <span class="DecNumber">3</span><span class="Punctuation">,</span> <span class="DecNumber">4</span><span class="Punctuation">,</span> <span class="DecNumber">5</span><span class="Punctuation">,</span> <span class="DecNumber">6</span><span class="Punctuation">]</span>  <span class="Comment"># [] is the array constructor</span>
<span class="Identifier">y</span> <span class="Operator">=</span> <span class="Operator">@</span><span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="DecNumber">2</span><span class="Punctuation">,</span> <span class="DecNumber">3</span><span class="Punctuation">,</span> <span class="DecNumber">4</span><span class="Punctuation">,</span> <span class="DecNumber">5</span><span class="Punctuation">,</span> <span class="DecNumber">6</span><span class="Punctuation">]</span> <span class="Comment"># the @ turns the array into a sequence</span>

<span class="Keyword">let</span> <span class="Identifier">z</span> <span class="Operator">=</span> <span class="Punctuation">[</span><span class="FloatNumber">1.0</span><span class="Punctuation">,</span> <span class="DecNumber">2</span><span class="Punctuation">,</span> <span class="DecNumber">3</span><span class="Punctuation">,</span> <span class="DecNumber">4</span><span class="Punctuation">]</span> <span class="Comment"># the type of z is array[0..3, float]</span></pre></p>
<p>The lower bound of an array or sequence may be received by the built-in proc <tt class="docutils literal"><span class="pre"><span class="Identifier">low</span><span class="Punctuation">(</span><span class="Punctuation">)</span></span></tt>, the higher bound by <tt class="docutils literal"><span class="pre"><span class="Identifier">high</span><span class="Punctuation">(</span><span class="Punctuation">)</span></span></tt>. The length may be received by <tt class="docutils literal"><span class="pre"><span class="Identifier">len</span><span class="Punctuation">(</span><span class="Punctuation">)</span></span></tt>. <tt class="docutils literal"><span class="pre"><span class="Identifier">low</span><span class="Punctuation">(</span><span class="Punctuation">)</span></span></tt> for a sequence or an open array always returns 0, as this is the first valid index. One can append elements to a sequence with the <tt class="docutils literal"><span class="pre"><span class="Identifier">add</span><span class="Punctuation">(</span><span class="Punctuation">)</span></span></tt> proc or the <tt class="docutils literal"><span class="pre"><span class="Operator">&amp;</span></span></tt> operator, and remove (and get) the last element of a sequence with the <tt class="docutils literal"><span class="pre"><span class="Identifier">pop</span><span class="Punctuation">(</span><span class="Punctuation">)</span></span></tt> proc.</p>
<p>The notation <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span></span></tt> can be used to access the i-th element of <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span></span></tt>.</p>
<p>Arrays are always bounds checked (statically or at runtime). These checks can be disabled via pragmas or invoking the compiler with the <tt class="docutils literal"><span class="pre option">--boundChecks:off</span></tt> command-line switch.</p>
<p>An array constructor can have explicit indexes for readability:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">Values</span> <span class="Operator">=</span> <span class="Keyword">enum</span>
    <span class="Identifier">valA</span><span class="Punctuation">,</span> <span class="Identifier">valB</span><span class="Punctuation">,</span> <span class="Identifier">valC</span>

<span class="Keyword">const</span>
  <span class="Identifier">lookupTable</span> <span class="Operator">=</span> <span class="Punctuation">[</span>
    <span class="Identifier">valA</span><span class="Punctuation">:</span> <span class="StringLit">&quot;A&quot;</span><span class="Punctuation">,</span>
    <span class="Identifier">valB</span><span class="Punctuation">:</span> <span class="StringLit">&quot;B&quot;</span><span class="Punctuation">,</span>
    <span class="Identifier">valC</span><span class="Punctuation">:</span> <span class="StringLit">&quot;C&quot;</span>
  <span class="Punctuation">]</span></pre></p>
<p>If an index is left out, <tt class="docutils literal"><span class="pre"><span class="Identifier">succ</span><span class="Punctuation">(</span><span class="Identifier">lastIndex</span><span class="Punctuation">)</span></span></tt> is used as the index value:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">Values</span> <span class="Operator">=</span> <span class="Keyword">enum</span>
    <span class="Identifier">valA</span><span class="Punctuation">,</span> <span class="Identifier">valB</span><span class="Punctuation">,</span> <span class="Identifier">valC</span><span class="Punctuation">,</span> <span class="Identifier">valD</span><span class="Punctuation">,</span> <span class="Identifier">valE</span>

<span class="Keyword">const</span>
  <span class="Identifier">lookupTable</span> <span class="Operator">=</span> <span class="Punctuation">[</span>
    <span class="Identifier">valA</span><span class="Punctuation">:</span> <span class="StringLit">&quot;A&quot;</span><span class="Punctuation">,</span>
    <span class="StringLit">&quot;B&quot;</span><span class="Punctuation">,</span>
    <span class="Identifier">valC</span><span class="Punctuation">:</span> <span class="StringLit">&quot;C&quot;</span><span class="Punctuation">,</span>
    <span class="StringLit">&quot;D&quot;</span><span class="Punctuation">,</span> <span class="StringLit">&quot;e&quot;</span>
  <span class="Punctuation">]</span></pre></p>

<h2><a class="toc-backref" id="types-open-arrays" href="#types-open-arrays">Open arrays</a></h2><p>Often fixed size arrays turn out to be too inflexible; procedures should be able to deal with arrays of different sizes. The <span id="openarray_1">openarray</span> type allows this; it can only be used for parameters. Open arrays are always indexed with an <tt class="docutils literal"><span class="pre"><span class="Identifier">int</span></span></tt> starting at position 0. The <tt class="docutils literal"><span class="pre"><span class="Identifier">len</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Identifier">low</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">high</span></span></tt> operations are available for open arrays too. Any array with a compatible base type can be passed to an open array parameter, the index type does not matter. In addition to arrays, sequences can also be passed to an open array parameter.</p>
<p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">openarray</span></span></tt> type cannot be nested: multidimensional open arrays are not supported because this is seldom needed and cannot be done efficiently.</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">testOpenArray</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">openArray</span><span class="Punctuation">[</span><span class="Identifier">int</span><span class="Punctuation">]</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Identifier">echo</span> <span class="Identifier">repr</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span>

<span class="Identifier">testOpenArray</span><span class="Punctuation">(</span><span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">,</span><span class="DecNumber">2</span><span class="Punctuation">,</span><span class="DecNumber">3</span><span class="Punctuation">]</span><span class="Punctuation">)</span>  <span class="Comment"># array[]</span>
<span class="Identifier">testOpenArray</span><span class="Punctuation">(</span><span class="Operator">@</span><span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">,</span><span class="DecNumber">2</span><span class="Punctuation">,</span><span class="DecNumber">3</span><span class="Punctuation">]</span><span class="Punctuation">)</span> <span class="Comment"># seq[]</span></pre></p>

<h2><a class="toc-backref" id="types-varargs" href="#types-varargs">Varargs</a></h2><p>A <tt class="docutils literal"><span class="pre"><span class="Identifier">varargs</span></span></tt> parameter is an open array parameter that additionally allows a variable number of arguments to be passed to a procedure. The compiler converts the list of arguments to an array implicitly:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">myWriteln</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">:</span> <span class="Identifier">File</span><span class="Punctuation">,</span> <span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">varargs</span><span class="Punctuation">[</span><span class="Identifier">string</span><span class="Punctuation">]</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">for</span> <span class="Identifier">s</span> <span class="Keyword">in</span> <span class="Identifier">items</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
    <span class="Identifier">write</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">,</span> <span class="Identifier">s</span><span class="Punctuation">)</span>
  <span class="Identifier">write</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">,</span> <span class="StringLit">&quot;</span><span class="EscapeSequence">\n</span><span class="StringLit">&quot;</span><span class="Punctuation">)</span>

<span class="Identifier">myWriteln</span><span class="Punctuation">(</span><span class="Identifier">stdout</span><span class="Punctuation">,</span> <span class="StringLit">&quot;abc&quot;</span><span class="Punctuation">,</span> <span class="StringLit">&quot;def&quot;</span><span class="Punctuation">,</span> <span class="StringLit">&quot;xyz&quot;</span><span class="Punctuation">)</span>
<span class="Comment"># is transformed to:</span>
<span class="Identifier">myWriteln</span><span class="Punctuation">(</span><span class="Identifier">stdout</span><span class="Punctuation">,</span> <span class="Punctuation">[</span><span class="StringLit">&quot;abc&quot;</span><span class="Punctuation">,</span> <span class="StringLit">&quot;def&quot;</span><span class="Punctuation">,</span> <span class="StringLit">&quot;xyz&quot;</span><span class="Punctuation">]</span><span class="Punctuation">)</span></pre></p>
<p>This transformation is only done if the <tt class="docutils literal"><span class="pre"><span class="Identifier">varargs</span></span></tt> parameter is the last parameter in the procedure header. It is also possible to perform type conversions in this context:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">myWriteln</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">:</span> <span class="Identifier">File</span><span class="Punctuation">,</span> <span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">varargs</span><span class="Punctuation">[</span><span class="Identifier">string</span><span class="Punctuation">,</span> <span class="Punctuation">`</span><span class="Operator">$</span><span class="Punctuation">`</span><span class="Punctuation">]</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">for</span> <span class="Identifier">s</span> <span class="Keyword">in</span> <span class="Identifier">items</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
    <span class="Identifier">write</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">,</span> <span class="Identifier">s</span><span class="Punctuation">)</span>
  <span class="Identifier">write</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">,</span> <span class="StringLit">&quot;</span><span class="EscapeSequence">\n</span><span class="StringLit">&quot;</span><span class="Punctuation">)</span>

<span class="Identifier">myWriteln</span><span class="Punctuation">(</span><span class="Identifier">stdout</span><span class="Punctuation">,</span> <span class="DecNumber">123</span><span class="Punctuation">,</span> <span class="StringLit">&quot;abc&quot;</span><span class="Punctuation">,</span> <span class="FloatNumber">4.0</span><span class="Punctuation">)</span>
<span class="Comment"># is transformed to:</span>
<span class="Identifier">myWriteln</span><span class="Punctuation">(</span><span class="Identifier">stdout</span><span class="Punctuation">,</span> <span class="Punctuation">[</span><span class="Operator">$</span><span class="DecNumber">123</span><span class="Punctuation">,</span> <span class="Operator">$</span><span class="StringLit">&quot;abc&quot;</span><span class="Punctuation">,</span> <span class="Operator">$</span><span class="FloatNumber">4.0</span><span class="Punctuation">]</span><span class="Punctuation">)</span></pre></p>
<p>In this example <tt class="docutils literal"><span class="pre"><span class="Operator">$</span></span></tt> is applied to any argument that is passed to the parameter <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span></span></tt>. (Note that <tt class="docutils literal"><span class="pre"><span class="Operator">$</span></span></tt> applied to strings is a nop.)</p>
<p>Note that an explicit array constructor passed to a <tt class="docutils literal"><span class="pre"><span class="Identifier">varargs</span></span></tt> parameter is not wrapped in another implicit array construction:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">takeV</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">varargs</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Keyword">discard</span>

<span class="Identifier">takeV</span><span class="Punctuation">(</span><span class="Punctuation">[</span><span class="DecNumber">123</span><span class="Punctuation">,</span> <span class="DecNumber">2</span><span class="Punctuation">,</span> <span class="DecNumber">1</span><span class="Punctuation">]</span><span class="Punctuation">)</span> <span class="Comment"># takeV's T is &quot;int&quot;, not &quot;array of int&quot;</span></pre></p>
<p><tt class="docutils literal"><span class="pre"><span class="Identifier">varargs</span><span class="Punctuation">[</span><span class="Identifier">typed</span><span class="Punctuation">]</span></span></tt> is treated specially: It matches a variable list of arguments of arbitrary type but <em>always</em> constructs an implicit array. This is required so that the builtin <tt class="docutils literal"><span class="pre"><span class="Identifier">echo</span></span></tt> proc does what is expected:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">echo</span><span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">varargs</span><span class="Punctuation">[</span><span class="Identifier">typed</span><span class="Punctuation">,</span> <span class="Punctuation">`</span><span class="Operator">$</span><span class="Punctuation">`</span><span class="Punctuation">]</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">...</span><span class="Punctuation">}</span>

<span class="Identifier">echo</span> <span class="Operator">@</span><span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="DecNumber">2</span><span class="Punctuation">,</span> <span class="DecNumber">3</span><span class="Punctuation">]</span>
<span class="Comment"># prints &quot;@[1, 2, 3]&quot; and not &quot;123&quot;</span></pre></p>

<h2><a class="toc-backref" id="types-unchecked-arrays" href="#types-unchecked-arrays">Unchecked arrays</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">UncheckedArray</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span></span></tt> type is a special kind of <tt class="docutils literal"><span class="pre"><span class="Identifier">array</span></span></tt> where its bounds are not checked. This is often useful to implement customized flexibly sized arrays. Additionally, an unchecked array is translated into a C array of undetermined size:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">MySeq</span> <span class="Operator">=</span> <span class="Keyword">object</span>
    <span class="Identifier">len</span><span class="Punctuation">,</span> <span class="Identifier">cap</span><span class="Punctuation">:</span> <span class="Identifier">int</span>
    <span class="Identifier">data</span><span class="Punctuation">:</span> <span class="Identifier">UncheckedArray</span><span class="Punctuation">[</span><span class="Identifier">int</span><span class="Punctuation">]</span></pre></p>
<p>Produces roughly this C code:</p>
<p><pre class="listing"><span class="Keyword">typedef</span> <span class="Keyword">struct</span> <span class="Punctuation">{</span>
  <span class="Identifier">NI</span> <span class="Identifier">len</span><span class="Punctuation">;</span>
  <span class="Identifier">NI</span> <span class="Identifier">cap</span><span class="Punctuation">;</span>
  <span class="Identifier">NI</span> <span class="Identifier">data</span><span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Punctuation">;</span>
<span class="Punctuation">}</span> <span class="Identifier">MySeq</span><span class="Punctuation">;</span></pre></p>
<p>The base type of the unchecked array may not contain any GC'ed memory but this is currently not checked.</p>
<p><strong>Future directions</strong>: GC'ed memory should be allowed in unchecked arrays and there should be an explicit annotation of how the GC is to determine the runtime size of the array.</p>

<h2><a class="toc-backref" id="types-tuples-and-object-types" href="#types-tuples-and-object-types">Tuples and object types</a></h2><p>A variable of a tuple or object type is a heterogeneous storage container. A tuple or object defines various named <em>fields</em> of a type. A tuple also defines a lexicographic <em>order</em> of the fields. Tuples are meant to be heterogeneous storage types with few abstractions. The <tt class="docutils literal"><span class="pre"><span class="Punctuation">(</span><span class="Punctuation">)</span></span></tt> syntax can be used to construct tuples. The order of the fields in the constructor must match the order of the tuple's definition. Different tuple-types are <em>equivalent</em> if they specify the same fields of the same type in the same order. The <em>names</em> of the fields also have to be the same.</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">Person</span> <span class="Operator">=</span> <span class="Keyword">tuple</span><span class="Punctuation">[</span><span class="Identifier">name</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">,</span> <span class="Identifier">age</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">]</span> <span class="Comment"># type representing a person:</span>
                                         <span class="Comment"># it consists of a name and an age.</span>
<span class="Keyword">var</span> <span class="Identifier">person</span><span class="Punctuation">:</span> <span class="Identifier">Person</span>
<span class="Identifier">person</span> <span class="Operator">=</span> <span class="Punctuation">(</span><span class="Identifier">name</span><span class="Punctuation">:</span> <span class="StringLit">&quot;Peter&quot;</span><span class="Punctuation">,</span> <span class="Identifier">age</span><span class="Punctuation">:</span> <span class="DecNumber">30</span><span class="Punctuation">)</span>
<span class="Identifier">assert</span> <span class="Identifier">person</span><span class="Operator">.</span><span class="Identifier">name</span> <span class="Operator">==</span> <span class="StringLit">&quot;Peter&quot;</span>
<span class="Comment"># the same, but less readable:</span>
<span class="Identifier">person</span> <span class="Operator">=</span> <span class="Punctuation">(</span><span class="StringLit">&quot;Peter&quot;</span><span class="Punctuation">,</span> <span class="DecNumber">30</span><span class="Punctuation">)</span>
<span class="Identifier">assert</span> <span class="Identifier">person</span><span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">]</span> <span class="Operator">==</span> <span class="StringLit">&quot;Peter&quot;</span>
<span class="Identifier">assert</span> <span class="Identifier">Person</span> <span class="Keyword">is</span> <span class="Punctuation">(</span><span class="Identifier">string</span><span class="Punctuation">,</span> <span class="Identifier">int</span><span class="Punctuation">)</span>
<span class="Identifier">assert</span> <span class="Punctuation">(</span><span class="Identifier">string</span><span class="Punctuation">,</span> <span class="Identifier">int</span><span class="Punctuation">)</span> <span class="Keyword">is</span> <span class="Identifier">Person</span>
<span class="Identifier">assert</span> <span class="Identifier">Person</span> <span class="Keyword">isnot</span> <span class="Keyword">tuple</span><span class="Punctuation">[</span><span class="Identifier">other</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">,</span> <span class="Identifier">age</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">]</span> <span class="Comment"># `other` is a different identifier</span></pre></p>
<p>A tuple with one unnamed field can be constructed with the parentheses and a trailing comma:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">echoUnaryTuple</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Punctuation">(</span><span class="Identifier">int</span><span class="Punctuation">,</span><span class="Punctuation">)</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Identifier">echo</span> <span class="Identifier">a</span><span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">]</span>

<span class="Identifier">echoUnaryTuple</span> <span class="Punctuation">(</span><span class="DecNumber">1</span><span class="Punctuation">,</span><span class="Punctuation">)</span></pre></p>
<p>In fact, a trailing comma is allowed for every tuple construction.</p>
<p>The implementation aligns the fields for the best access performance. The alignment is compatible with the way the C compiler does it.</p>
<p>For consistency  with <tt class="docutils literal"><span class="pre"><span class="Keyword">object</span></span></tt> declarations, tuples in a <tt class="docutils literal"><span class="pre"><span class="Keyword">type</span></span></tt> section can also be defined with indentation instead of <tt class="docutils literal"><span class="pre"><span class="Punctuation">[</span><span class="Punctuation">]</span></span></tt>:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">Person</span> <span class="Operator">=</span> <span class="Keyword">tuple</span>   <span class="Comment"># type representing a person</span>
    <span class="Identifier">name</span><span class="Punctuation">:</span> <span class="Identifier">string</span>   <span class="Comment"># a person consists of a name</span>
    <span class="Identifier">age</span><span class="Punctuation">:</span> <span class="Identifier">Natural</span>   <span class="Comment"># and an age</span></pre></p>
<p>Objects provide many features that tuples do not. Objects provide inheritance and the ability to hide fields from other modules. Objects with inheritance enabled have information about their type at runtime so that the <tt class="docutils literal"><span class="pre"><span class="Keyword">of</span></span></tt> operator can be used to determine the object's type. The <tt class="docutils literal"><span class="pre"><span class="Keyword">of</span></span></tt> operator is similar to the <tt class="docutils literal"><span class="pre"><span class="Identifier">instanceof</span></span></tt> operator in Java.</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">Person</span> <span class="Operator">=</span> <span class="Keyword">object</span> <span class="Keyword">of</span> <span class="Identifier">RootObj</span>
    <span class="Identifier">name</span><span class="Operator">*:</span> <span class="Identifier">string</span>   <span class="Comment"># the * means that `name` is accessible from other modules</span>
    <span class="Identifier">age</span><span class="Punctuation">:</span> <span class="Identifier">int</span>        <span class="Comment"># no * means that the field is hidden</span>
  
  <span class="Identifier">Student</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Keyword">object</span> <span class="Keyword">of</span> <span class="Identifier">Person</span> <span class="Comment"># a student is a person</span>
    <span class="Identifier">id</span><span class="Punctuation">:</span> <span class="Identifier">int</span>                      <span class="Comment"># with an id field</span>

<span class="Keyword">var</span>
  <span class="Identifier">student</span><span class="Punctuation">:</span> <span class="Identifier">Student</span>
  <span class="Identifier">person</span><span class="Punctuation">:</span> <span class="Identifier">Person</span>
<span class="Identifier">assert</span><span class="Punctuation">(</span><span class="Identifier">student</span> <span class="Keyword">of</span> <span class="Identifier">Student</span><span class="Punctuation">)</span> <span class="Comment"># is true</span>
<span class="Identifier">assert</span><span class="Punctuation">(</span><span class="Identifier">student</span> <span class="Keyword">of</span> <span class="Identifier">Person</span><span class="Punctuation">)</span> <span class="Comment"># also true</span></pre></p>
<p>Object fields that should be visible from outside the defining module have to be marked by <tt class="docutils literal"><span class="pre"><span class="Operator">*</span></span></tt>. In contrast to tuples, different object types are never <em>equivalent</em>, they are nominal types whereas tuples are structural. Objects that have no ancestor are implicitly <tt class="docutils literal"><span class="pre"><span class="Identifier">final</span></span></tt> and thus have no hidden type information. One can use the <tt class="docutils literal"><span class="pre"><span class="Identifier">inheritable</span></span></tt> pragma to introduce new object roots apart from <tt class="docutils literal"><span class="pre"><span class="Identifier">system</span><span class="Operator">.</span><span class="Identifier">RootObj</span></span></tt>.</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">Person</span> <span class="Operator">=</span> <span class="Keyword">object</span> <span class="Comment"># example of a final object</span>
    <span class="Identifier">name</span><span class="Operator">*:</span> <span class="Identifier">string</span>
    <span class="Identifier">age</span><span class="Punctuation">:</span> <span class="Identifier">int</span>
  
  <span class="Identifier">Student</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Keyword">object</span> <span class="Keyword">of</span> <span class="Identifier">Person</span> <span class="Comment"># Error: inheritance only works with non-final objects</span>
    <span class="Identifier">id</span><span class="Punctuation">:</span> <span class="Identifier">int</span></pre></p>
<p>The assignment operator for tuples and objects copies each component. The methods to override this copying behavior are described <a class="reference internal" href="#procedures-type-bound-operators">here</a>.</p>

<h2><a class="toc-backref" id="types-object-construction" href="#types-object-construction">Object construction</a></h2><p>Objects can also be created with an <span id="object-construction-expression_1">object construction expression</span> that has the syntax <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span><span class="Punctuation">(</span><span class="Identifier">fieldA</span><span class="Punctuation">:</span> <span class="Identifier">valueA</span><span class="Punctuation">,</span> <span class="Identifier">fieldB</span><span class="Punctuation">:</span> <span class="Identifier">valueB</span><span class="Punctuation">,</span> <span class="Operator">...</span><span class="Punctuation">)</span></span></tt> where <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span></span></tt> is an <tt class="docutils literal"><span class="pre"><span class="Keyword">object</span></span></tt> type or a <tt class="docutils literal"><span class="pre"><span class="Keyword">ref</span> <span class="Keyword">object</span></span></tt> type:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">Student</span> <span class="Operator">=</span> <span class="Keyword">object</span>
    <span class="Identifier">name</span><span class="Punctuation">:</span> <span class="Identifier">string</span>
    <span class="Identifier">age</span><span class="Punctuation">:</span> <span class="Identifier">int</span>
  <span class="Identifier">PStudent</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Identifier">Student</span>
<span class="Keyword">var</span> <span class="Identifier">a1</span> <span class="Operator">=</span> <span class="Identifier">Student</span><span class="Punctuation">(</span><span class="Identifier">name</span><span class="Punctuation">:</span> <span class="StringLit">&quot;Anton&quot;</span><span class="Punctuation">,</span> <span class="Identifier">age</span><span class="Punctuation">:</span> <span class="DecNumber">5</span><span class="Punctuation">)</span>
<span class="Keyword">var</span> <span class="Identifier">a2</span> <span class="Operator">=</span> <span class="Identifier">PStudent</span><span class="Punctuation">(</span><span class="Identifier">name</span><span class="Punctuation">:</span> <span class="StringLit">&quot;Anton&quot;</span><span class="Punctuation">,</span> <span class="Identifier">age</span><span class="Punctuation">:</span> <span class="DecNumber">5</span><span class="Punctuation">)</span>
<span class="Comment"># this also works directly:</span>
<span class="Keyword">var</span> <span class="Identifier">a3</span> <span class="Operator">=</span> <span class="Punctuation">(</span><span class="Keyword">ref</span> <span class="Identifier">Student</span><span class="Punctuation">)</span><span class="Punctuation">(</span><span class="Identifier">name</span><span class="Punctuation">:</span> <span class="StringLit">&quot;Anton&quot;</span><span class="Punctuation">,</span> <span class="Identifier">age</span><span class="Punctuation">:</span> <span class="DecNumber">5</span><span class="Punctuation">)</span>
<span class="Comment"># not all fields need to be mentioned, and they can be mentioned out of order:</span>
<span class="Keyword">var</span> <span class="Identifier">a4</span> <span class="Operator">=</span> <span class="Identifier">Student</span><span class="Punctuation">(</span><span class="Identifier">age</span><span class="Punctuation">:</span> <span class="DecNumber">5</span><span class="Punctuation">)</span></pre></p>
<p>Note that, unlike tuples, objects require the field names along with their values. For a <tt class="docutils literal"><span class="pre"><span class="Keyword">ref</span> <span class="Keyword">object</span></span></tt> type <tt class="docutils literal"><span class="pre"><span class="Identifier">system</span><span class="Operator">.</span><span class="Identifier">new</span></span></tt> is invoked implicitly.</p>

<h2><a class="toc-backref" id="types-object-variants" href="#types-object-variants">Object variants</a></h2><p>Often an object hierarchy is an overkill in certain situations where simple variant types are needed. Object variants are tagged unions discriminated via an enumerated type used for runtime type flexibility, mirroring the concepts of <em>sum types</em> and <em>algebraic data types (ADTs)</em> as found in other languages.</p>
<p>An example:</p>
<p><pre class="listing"><span class="Comment"># This is an example of how an abstract syntax tree could be modelled in Nim</span>
<span class="Keyword">type</span>
  <span class="Identifier">NodeKind</span> <span class="Operator">=</span> <span class="Keyword">enum</span>  <span class="Comment"># the different node types</span>
    <span class="Identifier">nkInt</span><span class="Punctuation">,</span>          <span class="Comment"># a leaf with an integer value</span>
    <span class="Identifier">nkFloat</span><span class="Punctuation">,</span>        <span class="Comment"># a leaf with a float value</span>
    <span class="Identifier">nkString</span><span class="Punctuation">,</span>       <span class="Comment"># a leaf with a string value</span>
    <span class="Identifier">nkAdd</span><span class="Punctuation">,</span>          <span class="Comment"># an addition</span>
    <span class="Identifier">nkSub</span><span class="Punctuation">,</span>          <span class="Comment"># a subtraction</span>
    <span class="Identifier">nkIf</span>            <span class="Comment"># an if statement</span>
  <span class="Identifier">Node</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Identifier">NodeObj</span>
  <span class="Identifier">NodeObj</span> <span class="Operator">=</span> <span class="Keyword">object</span>
    <span class="Keyword">case</span> <span class="Identifier">kind</span><span class="Punctuation">:</span> <span class="Identifier">NodeKind</span>  <span class="Comment"># the `kind` field is the discriminator</span>
    <span class="Keyword">of</span> <span class="Identifier">nkInt</span><span class="Punctuation">:</span> <span class="Identifier">intVal</span><span class="Punctuation">:</span> <span class="Identifier">int</span>
    <span class="Keyword">of</span> <span class="Identifier">nkFloat</span><span class="Punctuation">:</span> <span class="Identifier">floatVal</span><span class="Punctuation">:</span> <span class="Identifier">float</span>
    <span class="Keyword">of</span> <span class="Identifier">nkString</span><span class="Punctuation">:</span> <span class="Identifier">strVal</span><span class="Punctuation">:</span> <span class="Identifier">string</span>
    <span class="Keyword">of</span> <span class="Identifier">nkAdd</span><span class="Punctuation">,</span> <span class="Identifier">nkSub</span><span class="Punctuation">:</span>
      <span class="Identifier">leftOp</span><span class="Punctuation">,</span> <span class="Identifier">rightOp</span><span class="Punctuation">:</span> <span class="Identifier">Node</span>
    <span class="Keyword">of</span> <span class="Identifier">nkIf</span><span class="Punctuation">:</span>
      <span class="Identifier">condition</span><span class="Punctuation">,</span> <span class="Identifier">thenPart</span><span class="Punctuation">,</span> <span class="Identifier">elsePart</span><span class="Punctuation">:</span> <span class="Identifier">Node</span>

<span class="Comment"># create a new case object:</span>
<span class="Keyword">var</span> <span class="Identifier">n</span> <span class="Operator">=</span> <span class="Identifier">Node</span><span class="Punctuation">(</span><span class="Identifier">kind</span><span class="Punctuation">:</span> <span class="Identifier">nkIf</span><span class="Punctuation">,</span> <span class="Identifier">condition</span><span class="Punctuation">:</span> <span class="Keyword">nil</span><span class="Punctuation">)</span>
<span class="Comment"># accessing n.thenPart is valid because the `nkIf` branch is active:</span>
<span class="Identifier">n</span><span class="Operator">.</span><span class="Identifier">thenPart</span> <span class="Operator">=</span> <span class="Identifier">Node</span><span class="Punctuation">(</span><span class="Identifier">kind</span><span class="Punctuation">:</span> <span class="Identifier">nkFloat</span><span class="Punctuation">,</span> <span class="Identifier">floatVal</span><span class="Punctuation">:</span> <span class="FloatNumber">2.0</span><span class="Punctuation">)</span>

<span class="Comment"># the following statement raises an `FieldDefect` exception, because</span>
<span class="Comment"># n.kind's value does not fit and the `nkString` branch is not active:</span>
<span class="Identifier">n</span><span class="Operator">.</span><span class="Identifier">strVal</span> <span class="Operator">=</span> <span class="StringLit">&quot;&quot;</span>

<span class="Comment"># invalid: would change the active object branch:</span>
<span class="Identifier">n</span><span class="Operator">.</span><span class="Identifier">kind</span> <span class="Operator">=</span> <span class="Identifier">nkInt</span>

<span class="Keyword">var</span> <span class="Identifier">x</span> <span class="Operator">=</span> <span class="Identifier">Node</span><span class="Punctuation">(</span><span class="Identifier">kind</span><span class="Punctuation">:</span> <span class="Identifier">nkAdd</span><span class="Punctuation">,</span> <span class="Identifier">leftOp</span><span class="Punctuation">:</span> <span class="Identifier">Node</span><span class="Punctuation">(</span><span class="Identifier">kind</span><span class="Punctuation">:</span> <span class="Identifier">nkInt</span><span class="Punctuation">,</span> <span class="Identifier">intVal</span><span class="Punctuation">:</span> <span class="DecNumber">4</span><span class="Punctuation">)</span><span class="Punctuation">,</span>
                          <span class="Identifier">rightOp</span><span class="Punctuation">:</span> <span class="Identifier">Node</span><span class="Punctuation">(</span><span class="Identifier">kind</span><span class="Punctuation">:</span> <span class="Identifier">nkInt</span><span class="Punctuation">,</span> <span class="Identifier">intVal</span><span class="Punctuation">:</span> <span class="DecNumber">2</span><span class="Punctuation">)</span><span class="Punctuation">)</span>
<span class="Comment"># valid: does not change the active object branch:</span>
<span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">kind</span> <span class="Operator">=</span> <span class="Identifier">nkSub</span></pre></p>
<p>As can be seen from the example, an advantage to an object hierarchy is that no casting between different object types is needed. Yet, access to invalid object fields raises an exception.</p>
<p>The syntax of <tt class="docutils literal"><span class="pre"><span class="Keyword">case</span></span></tt> in an object declaration follows closely the syntax of the <tt class="docutils literal"><span class="pre"><span class="Keyword">case</span></span></tt> statement: The branches in a <tt class="docutils literal"><span class="pre"><span class="Keyword">case</span></span></tt> section may be indented too.</p>
<p>In the example, the <tt class="docutils literal"><span class="pre"><span class="Identifier">kind</span></span></tt> field is called the <span id="discriminator_1">discriminator</span>: For safety, its address cannot be taken and assignments to it are restricted: The new value must not lead to a change of the active object branch. Also, when the fields of a particular branch are specified during object construction, the corresponding discriminator value must be specified as a constant expression.</p>
<p>Instead of changing the active object branch, replace the old object in memory with a new one completely:</p>
<p><pre class="listing"><span class="Keyword">var</span> <span class="Identifier">x</span> <span class="Operator">=</span> <span class="Identifier">Node</span><span class="Punctuation">(</span><span class="Identifier">kind</span><span class="Punctuation">:</span> <span class="Identifier">nkAdd</span><span class="Punctuation">,</span> <span class="Identifier">leftOp</span><span class="Punctuation">:</span> <span class="Identifier">Node</span><span class="Punctuation">(</span><span class="Identifier">kind</span><span class="Punctuation">:</span> <span class="Identifier">nkInt</span><span class="Punctuation">,</span> <span class="Identifier">intVal</span><span class="Punctuation">:</span> <span class="DecNumber">4</span><span class="Punctuation">)</span><span class="Punctuation">,</span>
                          <span class="Identifier">rightOp</span><span class="Punctuation">:</span> <span class="Identifier">Node</span><span class="Punctuation">(</span><span class="Identifier">kind</span><span class="Punctuation">:</span> <span class="Identifier">nkInt</span><span class="Punctuation">,</span> <span class="Identifier">intVal</span><span class="Punctuation">:</span> <span class="DecNumber">2</span><span class="Punctuation">)</span><span class="Punctuation">)</span>
<span class="Comment"># change the node's contents:</span>
<span class="Identifier">x</span><span class="Punctuation">[</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Identifier">NodeObj</span><span class="Punctuation">(</span><span class="Identifier">kind</span><span class="Punctuation">:</span> <span class="Identifier">nkString</span><span class="Punctuation">,</span> <span class="Identifier">strVal</span><span class="Punctuation">:</span> <span class="StringLit">&quot;abc&quot;</span><span class="Punctuation">)</span></pre></p>
<p>Starting with version 0.20 <tt class="docutils literal"><span class="pre"><span class="Identifier">system</span><span class="Operator">.</span><span class="Identifier">reset</span></span></tt> cannot be used anymore to support object branch changes as this never was completely memory safe.</p>
<p>As a special rule, the discriminator kind can also be bounded using a <tt class="docutils literal"><span class="pre"><span class="Keyword">case</span></span></tt> statement. If possible values of the discriminator variable in a <tt class="docutils literal"><span class="pre"><span class="Keyword">case</span></span></tt> statement branch are a subset of discriminator values for the selected object branch, the initialization is considered valid. This analysis only works for immutable discriminators of an ordinal type and disregards <tt class="docutils literal"><span class="pre"><span class="Keyword">elif</span></span></tt> branches. For discriminator values with a <tt class="docutils literal"><span class="pre"><span class="Identifier">range</span></span></tt> type, the compiler checks if the entire range of possible values for the discriminator value is valid for the chosen object branch.</p>
<p>A small example:</p>
<p><pre class="listing"><span class="Keyword">let</span> <span class="Identifier">unknownKind</span> <span class="Operator">=</span> <span class="Identifier">nkSub</span>

<span class="Comment"># invalid: unsafe initialization because the kind field is not statically known:</span>
<span class="Keyword">var</span> <span class="Identifier">y</span> <span class="Operator">=</span> <span class="Identifier">Node</span><span class="Punctuation">(</span><span class="Identifier">kind</span><span class="Punctuation">:</span> <span class="Identifier">unknownKind</span><span class="Punctuation">,</span> <span class="Identifier">strVal</span><span class="Punctuation">:</span> <span class="StringLit">&quot;y&quot;</span><span class="Punctuation">)</span>

<span class="Keyword">var</span> <span class="Identifier">z</span> <span class="Operator">=</span> <span class="Identifier">Node</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
<span class="Keyword">case</span> <span class="Identifier">unknownKind</span>
<span class="Keyword">of</span> <span class="Identifier">nkAdd</span><span class="Punctuation">,</span> <span class="Identifier">nkSub</span><span class="Punctuation">:</span>
  <span class="Comment"># valid: possible values of this branch are a subset of nkAdd/nkSub object branch:</span>
  <span class="Identifier">z</span> <span class="Operator">=</span> <span class="Identifier">Node</span><span class="Punctuation">(</span><span class="Identifier">kind</span><span class="Punctuation">:</span> <span class="Identifier">unknownKind</span><span class="Punctuation">,</span> <span class="Identifier">leftOp</span><span class="Punctuation">:</span> <span class="Identifier">Node</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">,</span> <span class="Identifier">rightOp</span><span class="Punctuation">:</span> <span class="Identifier">Node</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">)</span>
<span class="Keyword">else</span><span class="Punctuation">:</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;ignoring: &quot;</span><span class="Punctuation">,</span> <span class="Identifier">unknownKind</span>

<span class="Comment"># also valid, since unknownKindBounded can only contain the values nkAdd or nkSub</span>
<span class="Keyword">let</span> <span class="Identifier">unknownKindBounded</span> <span class="Operator">=</span> <span class="Identifier">range</span><span class="Punctuation">[</span><span class="Identifier">nkAdd</span><span class="Operator">..</span><span class="Identifier">nkSub</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">unknownKind</span><span class="Punctuation">)</span>
<span class="Identifier">z</span> <span class="Operator">=</span> <span class="Identifier">Node</span><span class="Punctuation">(</span><span class="Identifier">kind</span><span class="Punctuation">:</span> <span class="Identifier">unknownKindBounded</span><span class="Punctuation">,</span> <span class="Identifier">leftOp</span><span class="Punctuation">:</span> <span class="Identifier">Node</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">,</span> <span class="Identifier">rightOp</span><span class="Punctuation">:</span> <span class="Identifier">Node</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">)</span></pre></p>

<h2><a class="toc-backref" id="types-cast-uncheckedassign" href="#types-cast-uncheckedassign">cast uncheckedAssign</a></h2><p>Some restrictions for case objects can be disabled via a <tt class="docutils literal"><span class="pre"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Keyword">cast</span><span class="Punctuation">(</span><span class="Identifier">uncheckedAssign</span><span class="Punctuation">)</span><span class="Operator">.</span><span class="Punctuation">}</span></span></tt> section:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">TokenKind</span><span class="Operator">*</span> <span class="Operator">=</span> <span class="Keyword">enum</span>
    <span class="Identifier">strLit</span><span class="Punctuation">,</span> <span class="Identifier">intLit</span>
  <span class="Identifier">Token</span> <span class="Operator">=</span> <span class="Keyword">object</span>
    <span class="Keyword">case</span> <span class="Identifier">kind</span><span class="Operator">*:</span> <span class="Identifier">TokenKind</span>
    <span class="Keyword">of</span> <span class="Identifier">strLit</span><span class="Punctuation">:</span>
      <span class="Identifier">s</span><span class="Operator">*:</span> <span class="Identifier">string</span>
    <span class="Keyword">of</span> <span class="Identifier">intLit</span><span class="Punctuation">:</span>
      <span class="Identifier">i</span><span class="Operator">*:</span> <span class="Identifier">int64</span>

<span class="Keyword">proc</span> <span class="Identifier">passToVar</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">TokenKind</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Keyword">discard</span>

<span class="Keyword">var</span> <span class="Identifier">t</span> <span class="Operator">=</span> <span class="Identifier">Token</span><span class="Punctuation">(</span><span class="Identifier">kind</span><span class="Punctuation">:</span> <span class="Identifier">strLit</span><span class="Punctuation">,</span> <span class="Identifier">s</span><span class="Punctuation">:</span> <span class="StringLit">&quot;abc&quot;</span><span class="Punctuation">)</span>

<span class="Punctuation">{</span><span class="Operator">.</span><span class="Keyword">cast</span><span class="Punctuation">(</span><span class="Identifier">uncheckedAssign</span><span class="Punctuation">)</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span>
  <span class="Comment"># inside the 'cast' section it is allowed to pass 't.kind' to a 'var T' parameter:</span>
  <span class="Identifier">passToVar</span><span class="Punctuation">(</span><span class="Identifier">t</span><span class="Operator">.</span><span class="Identifier">kind</span><span class="Punctuation">)</span>
  
  <span class="Comment"># inside the 'cast' section it is allowed to set field 's' even though the</span>
  <span class="Comment"># constructed 'kind' field has an unknown value:</span>
  <span class="Identifier">t</span> <span class="Operator">=</span> <span class="Identifier">Token</span><span class="Punctuation">(</span><span class="Identifier">kind</span><span class="Punctuation">:</span> <span class="Identifier">t</span><span class="Operator">.</span><span class="Identifier">kind</span><span class="Punctuation">,</span> <span class="Identifier">s</span><span class="Punctuation">:</span> <span class="StringLit">&quot;abc&quot;</span><span class="Punctuation">)</span>
  
  <span class="Comment"># inside the 'cast' section it is allowed to assign to the 't.kind' field directly:</span>
  <span class="Identifier">t</span><span class="Operator">.</span><span class="Identifier">kind</span> <span class="Operator">=</span> <span class="Identifier">intLit</span></pre></p>

<h2><a class="toc-backref" id="types-default-values-for-object-fields" href="#types-default-values-for-object-fields">Default values for object fields</a></h2><p>Object fields are allowed to have a constant default value. The type of field can be omitted if a default value is given.</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">Foo</span> <span class="Operator">=</span> <span class="Keyword">object</span>
    <span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span> <span class="DecNumber">2</span>
    <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">float</span> <span class="Operator">=</span> <span class="FloatNumber">3.14</span>
    <span class="Identifier">c</span> <span class="Operator">=</span> <span class="StringLit">&quot;I can have a default value&quot;</span>
  
  <span class="Identifier">Bar</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Keyword">object</span>
    <span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span> <span class="DecNumber">2</span>
    <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">float</span> <span class="Operator">=</span> <span class="FloatNumber">3.14</span>
    <span class="Identifier">c</span> <span class="Operator">=</span> <span class="StringLit">&quot;I can have a default value&quot;</span></pre></p>
<p>The explicit initialization uses these defaults which includes an <tt class="docutils literal"><span class="pre"><span class="Keyword">object</span></span></tt> created with an object construction expression or the procedure <tt class="docutils literal"><span class="pre"><span class="Identifier">default</span></span></tt>; a <tt class="docutils literal"><span class="pre"><span class="Keyword">ref</span> <span class="Keyword">object</span></span></tt> created with an object construction expression or the procedure <tt class="docutils literal"><span class="pre"><span class="Identifier">new</span></span></tt>; an array or a tuple with a subtype which has a default created with the procedure <tt class="docutils literal"><span class="pre"><span class="Identifier">default</span></span></tt>.</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">Foo</span> <span class="Operator">=</span> <span class="Keyword">object</span>
    <span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span> <span class="DecNumber">2</span>
    <span class="Identifier">b</span> <span class="Operator">=</span> <span class="FloatNumber">3.0</span>
  <span class="Identifier">Bar</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Keyword">object</span>
    <span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span> <span class="DecNumber">2</span>
    <span class="Identifier">b</span> <span class="Operator">=</span> <span class="FloatNumber">3.0</span>

<span class="Keyword">block</span><span class="Punctuation">:</span> <span class="Comment"># created with an object construction expression</span>
  <span class="Keyword">let</span> <span class="Identifier">x</span> <span class="Operator">=</span> <span class="Identifier">Foo</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
  <span class="Identifier">assert</span> <span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">a</span> <span class="Operator">==</span> <span class="DecNumber">2</span> <span class="Keyword">and</span> <span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">b</span> <span class="Operator">==</span> <span class="FloatNumber">3.0</span>
  
  <span class="Keyword">let</span> <span class="Identifier">y</span> <span class="Operator">=</span> <span class="Identifier">Bar</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
  <span class="Identifier">assert</span> <span class="Identifier">y</span><span class="Operator">.</span><span class="Identifier">a</span> <span class="Operator">==</span> <span class="DecNumber">2</span> <span class="Keyword">and</span> <span class="Identifier">y</span><span class="Operator">.</span><span class="Identifier">b</span> <span class="Operator">==</span> <span class="FloatNumber">3.0</span>

<span class="Keyword">block</span><span class="Punctuation">:</span> <span class="Comment"># created with an object construction expression</span>
  <span class="Keyword">let</span> <span class="Identifier">x</span> <span class="Operator">=</span> <span class="Identifier">default</span><span class="Punctuation">(</span><span class="Identifier">Foo</span><span class="Punctuation">)</span>
  <span class="Identifier">assert</span> <span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">a</span> <span class="Operator">==</span> <span class="DecNumber">2</span> <span class="Keyword">and</span> <span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">b</span> <span class="Operator">==</span> <span class="FloatNumber">3.0</span>
  
  <span class="Keyword">let</span> <span class="Identifier">y</span> <span class="Operator">=</span> <span class="Identifier">default</span><span class="Punctuation">(</span><span class="Identifier">array</span><span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="Identifier">Foo</span><span class="Punctuation">]</span><span class="Punctuation">)</span>
  <span class="Identifier">assert</span> <span class="Identifier">y</span><span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Identifier">a</span> <span class="Operator">==</span> <span class="DecNumber">2</span> <span class="Keyword">and</span> <span class="Identifier">y</span><span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Identifier">b</span> <span class="Operator">==</span> <span class="FloatNumber">3.0</span>
  
  <span class="Keyword">let</span> <span class="Identifier">z</span> <span class="Operator">=</span> <span class="Identifier">default</span><span class="Punctuation">(</span><span class="Keyword">tuple</span><span class="Punctuation">[</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">Foo</span><span class="Punctuation">]</span><span class="Punctuation">)</span>
  <span class="Identifier">assert</span> <span class="Identifier">z</span><span class="Operator">.</span><span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">a</span> <span class="Operator">==</span> <span class="DecNumber">2</span> <span class="Keyword">and</span> <span class="Identifier">z</span><span class="Operator">.</span><span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">b</span> <span class="Operator">==</span> <span class="FloatNumber">3.0</span>

<span class="Keyword">block</span><span class="Punctuation">:</span> <span class="Comment"># created with the procedure `new`</span>
  <span class="Keyword">let</span> <span class="Identifier">y</span> <span class="Operator">=</span> <span class="Identifier">new</span> <span class="Identifier">Bar</span>
  <span class="Identifier">assert</span> <span class="Identifier">y</span><span class="Operator">.</span><span class="Identifier">a</span> <span class="Operator">==</span> <span class="DecNumber">2</span> <span class="Keyword">and</span> <span class="Identifier">y</span><span class="Operator">.</span><span class="Identifier">b</span> <span class="Operator">==</span> <span class="FloatNumber">3.0</span></pre></p>

<h2><a class="toc-backref" id="types-set-type" href="#types-set-type">Set type</a></h2>The set type models the mathematical notion of a set. The set's basetype can only be an ordinal type of a certain size, namely:<ul class="simple"><li><tt class="docutils literal"><span class="pre"><span class="Identifier">int8</span></span></tt>-<tt class="docutils literal"><span class="pre"><span class="Identifier">int16</span></span></tt></li>
<li><tt class="docutils literal"><span class="pre"><span class="Identifier">uint8</span></span></tt>/<tt class="docutils literal"><span class="pre"><span class="Identifier">byte</span></span></tt>-<tt class="docutils literal"><span class="pre"><span class="Identifier">uint16</span></span></tt></li>
<li><tt class="docutils literal"><span class="pre"><span class="Identifier">char</span></span></tt></li>
<li><tt class="docutils literal"><span class="pre"><span class="Keyword">enum</span></span></tt></li>
<li>Ordinal subrange types, i.e. <tt class="docutils literal"><span class="pre"><span class="Identifier">range</span><span class="Punctuation">[</span><span class="Operator">-</span><span class="FloatNumber">10.</span><span class="Operator">.</span><span class="DecNumber">10</span><span class="Punctuation">]</span></span></tt></li>
</ul>
<p>or equivalent. When constructing a set with signed integer literals, the set's base type is defined to be in the range <tt class="docutils literal"><span class="pre"><span class="DecNumber">0</span> <span class="Operator">..</span> <span class="Identifier">DefaultSetElements</span><span class="Operator">-</span><span class="DecNumber">1</span></span></tt> where <tt class="docutils literal"><span class="pre"><span class="Identifier">DefaultSetElements</span></span></tt> is currently always 2^8. The maximum range length for the base type of a set is <tt class="docutils literal"><span class="pre"><span class="Identifier">MaxSetElements</span></span></tt> which is currently always 2^16. Types with a bigger range length are coerced into the range <tt class="docutils literal"><span class="pre"><span class="DecNumber">0</span> <span class="Operator">..</span> <span class="Identifier">MaxSetElements</span><span class="Operator">-</span><span class="DecNumber">1</span></span></tt>.</p>
<p>The reason is that sets are implemented as high performance bit vectors. Attempting to declare a set with a larger type will result in an error:</p>
<p><pre class="listing">  <span class="Keyword">var</span> <span class="Identifier">s</span><span class="Punctuation">:</span> <span class="Identifier">set</span><span class="Punctuation">[</span><span class="Identifier">int64</span><span class="Punctuation">]</span> <span class="Comment"># Error: set is too large; use `std/sets` for ordinal types</span>
                    <span class="Comment"># with more than 2^16 elements</span></pre></p>
<p><strong>Note:</strong> Nim also offers <a class="reference external" href="sets.html">hash sets</a> (which you need to import with <tt class="docutils literal"><span class="pre"><span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">sets</span></span></tt>), which have no such restrictions.</p>
<p>Sets can be constructed via the set constructor: <tt class="docutils literal"><span class="pre"><span class="Punctuation">{</span><span class="Punctuation">}</span></span></tt> is the empty set. The empty set is type compatible with any concrete set type. The constructor can also be used to include elements (and ranges of elements):</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">CharSet</span> <span class="Operator">=</span> <span class="Identifier">set</span><span class="Punctuation">[</span><span class="Identifier">char</span><span class="Punctuation">]</span>
<span class="Keyword">var</span>
  <span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">CharSet</span>
<span class="Identifier">x</span> <span class="Operator">=</span> <span class="Punctuation">{</span><span class="Punctuation">'</span><span class="Identifier">a</span><span class="CharLit">'..'</span><span class="Identifier">z</span><span class="CharLit">', '</span><span class="DecNumber">0'</span><span class="Operator">..</span><span class="CharLit">'9'</span><span class="Punctuation">}</span> <span class="Comment"># This constructs a set that contains the</span>
                         <span class="Comment"># letters from 'a' to 'z' and the digits</span>
                         <span class="Comment"># from '0' to '9'</span></pre></p>
<p>The module <a class="reference external" href="setutils.html">`std/setutils`</a> provides a way to initialize a set from an iterable:</p>
<p><pre class="listing"><span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">setutils</span>

<span class="Keyword">let</span> <span class="Identifier">uniqueChars</span> <span class="Operator">=</span> <span class="Identifier">myString</span><span class="Operator">.</span><span class="Identifier">toSet</span></pre></p>
<p>These operations are supported by sets:</p>
<table border="1" class="docutils"><tr><th>operation</th><th>meaning</th></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">A</span> <span class="Operator">+</span> <span class="Identifier">B</span></span></tt></td><td>union of two sets</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">A</span> <span class="Operator">*</span> <span class="Identifier">B</span></span></tt></td><td>intersection of two sets</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">A</span> <span class="Operator">-</span> <span class="Identifier">B</span></span></tt></td><td>difference of two sets (A without B's elements)</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">A</span> <span class="Operator">==</span> <span class="Identifier">B</span></span></tt></td><td>set equality</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">A</span> <span class="Operator">&lt;=</span> <span class="Identifier">B</span></span></tt></td><td>subset relation (A is subset of B or equal to B)</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">A</span> <span class="Operator">&lt;</span> <span class="Identifier">B</span></span></tt></td><td>strict subset relation (A is a proper subset of B)</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">e</span> <span class="Keyword">in</span> <span class="Identifier">A</span></span></tt></td><td>set membership (A contains element e)</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">e</span> <span class="Keyword">notin</span> <span class="Identifier">A</span></span></tt></td><td>A does not contain element e</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">contains</span><span class="Punctuation">(</span><span class="Identifier">A</span><span class="Punctuation">,</span> <span class="Identifier">e</span><span class="Punctuation">)</span></span></tt></td><td>A contains element e</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">card</span><span class="Punctuation">(</span><span class="Identifier">A</span><span class="Punctuation">)</span></span></tt></td><td>the cardinality of A (number of elements in A)</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">incl</span><span class="Punctuation">(</span><span class="Identifier">A</span><span class="Punctuation">,</span> <span class="Identifier">elem</span><span class="Punctuation">)</span></span></tt></td><td>same as <tt class="docutils literal"><span class="pre"><span class="Identifier">A</span> <span class="Operator">=</span> <span class="Identifier">A</span> <span class="Operator">+</span> <span class="Punctuation">{</span><span class="Identifier">elem</span><span class="Punctuation">}</span></span></tt></td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">excl</span><span class="Punctuation">(</span><span class="Identifier">A</span><span class="Punctuation">,</span> <span class="Identifier">elem</span><span class="Punctuation">)</span></span></tt></td><td>same as <tt class="docutils literal"><span class="pre"><span class="Identifier">A</span> <span class="Operator">=</span> <span class="Identifier">A</span> <span class="Operator">-</span> <span class="Punctuation">{</span><span class="Identifier">elem</span><span class="Punctuation">}</span></span></tt></td></tr>
</table>
<h3><a class="toc-backref" id="set-type-bit-fields" href="#set-type-bit-fields">Bit fields</a></h3><p>Sets are often used to define a type for the <em>flags</em> of a procedure. This is a cleaner (and type safe) solution than defining integer constants that have to be <tt class="docutils literal"><span class="pre"><span class="Keyword">or</span></span></tt>'ed together.</p>
<p>Enum, sets and casting can be used together as in:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">MyFlag</span><span class="Operator">*</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">size</span><span class="Punctuation">:</span> <span class="Identifier">sizeof</span><span class="Punctuation">(</span><span class="Identifier">cint</span><span class="Punctuation">)</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">enum</span>
    <span class="Identifier">A</span>
    <span class="Identifier">B</span>
    <span class="Identifier">C</span>
    <span class="Identifier">D</span>
  <span class="Identifier">MyFlags</span> <span class="Operator">=</span> <span class="Identifier">set</span><span class="Punctuation">[</span><span class="Identifier">MyFlag</span><span class="Punctuation">]</span>

<span class="Keyword">proc</span> <span class="Identifier">toNum</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">:</span> <span class="Identifier">MyFlags</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span> <span class="Keyword">cast</span><span class="Punctuation">[</span><span class="Identifier">cint</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">)</span>
<span class="Keyword">proc</span> <span class="Identifier">toFlags</span><span class="Punctuation">(</span><span class="Identifier">v</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">MyFlags</span> <span class="Operator">=</span> <span class="Keyword">cast</span><span class="Punctuation">[</span><span class="Identifier">MyFlags</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">v</span><span class="Punctuation">)</span>

<span class="Identifier">assert</span> <span class="Identifier">toNum</span><span class="Punctuation">(</span><span class="Punctuation">{</span><span class="Punctuation">}</span><span class="Punctuation">)</span> <span class="Operator">==</span> <span class="DecNumber">0</span>
<span class="Identifier">assert</span> <span class="Identifier">toNum</span><span class="Punctuation">(</span><span class="Punctuation">{</span><span class="Identifier">A</span><span class="Punctuation">}</span><span class="Punctuation">)</span> <span class="Operator">==</span> <span class="DecNumber">1</span>
<span class="Identifier">assert</span> <span class="Identifier">toNum</span><span class="Punctuation">(</span><span class="Punctuation">{</span><span class="Identifier">D</span><span class="Punctuation">}</span><span class="Punctuation">)</span> <span class="Operator">==</span> <span class="DecNumber">8</span>
<span class="Identifier">assert</span> <span class="Identifier">toNum</span><span class="Punctuation">(</span><span class="Punctuation">{</span><span class="Identifier">A</span><span class="Punctuation">,</span> <span class="Identifier">C</span><span class="Punctuation">}</span><span class="Punctuation">)</span> <span class="Operator">==</span> <span class="DecNumber">5</span>
<span class="Identifier">assert</span> <span class="Identifier">toFlags</span><span class="Punctuation">(</span><span class="DecNumber">0</span><span class="Punctuation">)</span> <span class="Operator">==</span> <span class="Punctuation">{</span><span class="Punctuation">}</span>
<span class="Identifier">assert</span> <span class="Identifier">toFlags</span><span class="Punctuation">(</span><span class="DecNumber">7</span><span class="Punctuation">)</span> <span class="Operator">==</span> <span class="Punctuation">{</span><span class="Identifier">A</span><span class="Punctuation">,</span> <span class="Identifier">B</span><span class="Punctuation">,</span> <span class="Identifier">C</span><span class="Punctuation">}</span></pre></p>
<p>Note how the set turns enum values into powers of 2.</p>
<p>If using enums and sets with C, use distinct cint.</p>
<p>For interoperability with C see also the <a class="reference external" href="manual.html#implementation-specific-pragmas-bitsize-pragma">bitsize pragma</a>. </p>

<h2><a class="toc-backref" id="types-reference-and-pointer-types" href="#types-reference-and-pointer-types">Reference and pointer types</a></h2><p>References (similar to pointers in other programming languages) are a way to introduce many-to-one relationships. This means different references can point to and modify the same location in memory (also called <span id="aliasing_1">aliasing</span>).</p>
<p>Nim distinguishes between <span id="traced_1">traced</span> and <span id="untraced_1">untraced</span> references. Untraced references are also called <em>pointers</em>. Traced references point to objects of a garbage-collected heap, untraced references point to manually allocated objects or objects somewhere else in memory. Thus, untraced references are <em>unsafe</em>. However, for certain low-level operations (accessing the hardware) untraced references are unavoidable.</p>
<p>Traced references are declared with the <strong>ref</strong> keyword, untraced references are declared with the <strong>ptr</strong> keyword. In general, a <tt class="docutils literal"><span class="pre"><span class="Keyword">ptr</span> <span class="Identifier">T</span></span></tt> is implicitly convertible to the <tt class="docutils literal"><span class="pre"><span class="Identifier">pointer</span></span></tt> type.</p>
<p>An empty subscript <tt class="docutils literal"><span class="pre"><span class="Punctuation">[</span><span class="Punctuation">]</span></span></tt> notation can be used to de-refer a reference, the <tt class="docutils literal"><span class="pre"><span class="Keyword">addr</span></span></tt> procedure returns the address of an item. An address is always an untraced reference. Thus, the usage of <tt class="docutils literal"><span class="pre"><span class="Keyword">addr</span></span></tt> is an <em>unsafe</em> feature.</p>
<p>The <tt class="docutils literal"><span class="pre"><span class="Operator">.</span></span></tt> (access a tuple/object field operator) and <tt class="docutils literal"><span class="pre"><span class="Punctuation">[</span><span class="Punctuation">]</span></span></tt> (array/string/sequence index operator) operators perform implicit dereferencing operations for reference types:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">Node</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Identifier">NodeObj</span>
  <span class="Identifier">NodeObj</span> <span class="Operator">=</span> <span class="Keyword">object</span>
    <span class="Identifier">le</span><span class="Punctuation">,</span> <span class="Identifier">ri</span><span class="Punctuation">:</span> <span class="Identifier">Node</span>
    <span class="Identifier">data</span><span class="Punctuation">:</span> <span class="Identifier">int</span>

<span class="Keyword">var</span>
  <span class="Identifier">n</span><span class="Punctuation">:</span> <span class="Identifier">Node</span>
<span class="Identifier">new</span><span class="Punctuation">(</span><span class="Identifier">n</span><span class="Punctuation">)</span>
<span class="Identifier">n</span><span class="Operator">.</span><span class="Identifier">data</span> <span class="Operator">=</span> <span class="DecNumber">9</span>
<span class="Comment"># no need to write n[].data; in fact n[].data is highly discouraged!</span></pre></p>
<p>In order to simplify structural type checking, recursive tuples are not valid:</p>
<p><pre class="listing"><span class="Comment"># invalid recursion</span>
<span class="Keyword">type</span> <span class="Identifier">MyTuple</span> <span class="Operator">=</span> <span class="Keyword">tuple</span><span class="Punctuation">[</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Keyword">ref</span> <span class="Identifier">MyTuple</span><span class="Punctuation">]</span></pre></p>
<p>Likewise <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Identifier">T</span></span></tt> is an invalid type.</p>
<p>As a syntactical extension, <tt class="docutils literal"><span class="pre"><span class="Keyword">object</span></span></tt> types can be anonymous if declared in a type section via the <tt class="docutils literal"><span class="pre"><span class="Keyword">ref</span> <span class="Keyword">object</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Keyword">ptr</span> <span class="Keyword">object</span></span></tt> notations. This feature is useful if an object should only gain reference semantics:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">Node</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Keyword">object</span>
    <span class="Identifier">le</span><span class="Punctuation">,</span> <span class="Identifier">ri</span><span class="Punctuation">:</span> <span class="Identifier">Node</span>
    <span class="Identifier">data</span><span class="Punctuation">:</span> <span class="Identifier">int</span></pre></p>
<p>To allocate a new traced object, the built-in procedure <tt class="docutils literal"><span class="pre"><span class="Identifier">new</span></span></tt> has to be used. To deal with untraced memory, the procedures <tt class="docutils literal"><span class="pre"><span class="Identifier">alloc</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Identifier">dealloc</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">realloc</span></span></tt> can be used. The documentation of the <a class="reference external" href="system.html">system</a> module contains further information.</p>

<h2><a class="toc-backref" id="types-nil" href="#types-nil">Nil</a></h2><p>If a reference points to <em>nothing</em>, it has the value <tt class="docutils literal"><span class="pre"><span class="Keyword">nil</span></span></tt>. <tt class="docutils literal"><span class="pre"><span class="Keyword">nil</span></span></tt> is the default value for all <tt class="docutils literal"><span class="pre"><span class="Keyword">ref</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Keyword">ptr</span></span></tt> types. The <tt class="docutils literal"><span class="pre"><span class="Keyword">nil</span></span></tt> value can also be used like any other literal value. For example, it can be used in an assignment like <tt class="docutils literal"><span class="pre"><span class="Identifier">myRef</span> <span class="Operator">=</span> <span class="Keyword">nil</span></span></tt>.</p>
<p>Dereferencing <tt class="docutils literal"><span class="pre"><span class="Keyword">nil</span></span></tt> is an unrecoverable fatal runtime error (and not a panic).</p>
<p>A successful dereferencing operation <tt class="docutils literal"><span class="pre"><span class="Identifier">p</span><span class="Punctuation">[</span><span class="Punctuation">]</span></span></tt> implies that <tt class="docutils literal"><span class="pre"><span class="Identifier">p</span></span></tt> is not nil. This can be exploited by the implementation to optimize code like:</p>
<p><pre class="listing"><span class="Identifier">p</span><span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Identifier">field</span> <span class="Operator">=</span> <span class="DecNumber">3</span>
<span class="Keyword">if</span> <span class="Identifier">p</span> <span class="Operator">!=</span> <span class="Keyword">nil</span><span class="Punctuation">:</span>
  <span class="Comment"># if p were nil, `p[]` would have caused a crash already,</span>
  <span class="Comment"># so we know `p` is always not nil here.</span>
  <span class="Identifier">action</span><span class="Punctuation">(</span><span class="Punctuation">)</span></pre></p>
<p>Into:</p>
<p><pre class="listing"><span class="Identifier">p</span><span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Identifier">field</span> <span class="Operator">=</span> <span class="DecNumber">3</span>
<span class="Identifier">action</span><span class="Punctuation">(</span><span class="Punctuation">)</span></pre></p>
<p><em>Note</em>: This is not comparable to C's &quot;undefined behavior&quot; for dereferencing NULL pointers.</p>

<h2><a class="toc-backref" id="types-mixing-gc-ed-memory-with-nimptr" href="#types-mixing-gc-ed-memory-with-nimptr">Mixing GC'ed memory with <tt class="docutils literal"><span class="pre"><span class="Keyword">ptr</span></span></tt></a></h2><p>Special care has to be taken if an untraced object contains traced objects like traced references, strings, or sequences: in order to free everything properly, the built-in procedure <tt class="docutils literal"><span class="pre"><span class="Identifier">reset</span></span></tt> has to be called before freeing the untraced memory manually:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">Data</span> <span class="Operator">=</span> <span class="Keyword">tuple</span><span class="Punctuation">[</span><span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">,</span> <span class="Identifier">s</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">]</span>

<span class="Comment"># allocate memory for Data on the heap:</span>
<span class="Keyword">var</span> <span class="Identifier">d</span> <span class="Operator">=</span> <span class="Keyword">cast</span><span class="Punctuation">[</span><span class="Keyword">ptr</span> <span class="Identifier">Data</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">alloc0</span><span class="Punctuation">(</span><span class="Identifier">sizeof</span><span class="Punctuation">(</span><span class="Identifier">Data</span><span class="Punctuation">)</span><span class="Punctuation">)</span><span class="Punctuation">)</span>

<span class="Comment"># create a new string on the garbage collected heap:</span>
<span class="Identifier">d</span><span class="Operator">.</span><span class="Identifier">s</span> <span class="Operator">=</span> <span class="StringLit">&quot;abc&quot;</span>

<span class="Comment"># tell the GC that the string is not needed anymore:</span>
<span class="Identifier">reset</span><span class="Punctuation">(</span><span class="Identifier">d</span><span class="Operator">.</span><span class="Identifier">s</span><span class="Punctuation">)</span>

<span class="Comment"># free the memory:</span>
<span class="Identifier">dealloc</span><span class="Punctuation">(</span><span class="Identifier">d</span><span class="Punctuation">)</span></pre></p>
<p>Without the <tt class="docutils literal"><span class="pre"><span class="Identifier">reset</span></span></tt> call the memory allocated for the <tt class="docutils literal"><span class="pre"><span class="Identifier">d</span><span class="Operator">.</span><span class="Identifier">s</span></span></tt> string would never be freed. The example also demonstrates two important features for low-level programming: the <tt class="docutils literal"><span class="pre"><span class="Identifier">sizeof</span></span></tt> proc returns the size of a type or value in bytes. The <tt class="docutils literal"><span class="pre"><span class="Keyword">cast</span></span></tt> operator can circumvent the type system: the compiler is forced to treat the result of the <tt class="docutils literal"><span class="pre"><span class="Identifier">alloc0</span></span></tt> call (which returns an untyped pointer) as if it would have the type <tt class="docutils literal"><span class="pre"><span class="Keyword">ptr</span> <span class="Identifier">Data</span></span></tt>. Casting should only be done if it is unavoidable: it breaks type safety and bugs can lead to mysterious crashes.</p>
<p><strong>Note</strong>: The example only works because the memory is initialized to zero (<tt class="docutils literal"><span class="pre"><span class="Identifier">alloc0</span></span></tt> instead of <tt class="docutils literal"><span class="pre"><span class="Identifier">alloc</span></span></tt> does this): <tt class="docutils literal"><span class="pre"><span class="Identifier">d</span><span class="Operator">.</span><span class="Identifier">s</span></span></tt> is thus initialized to binary zero which the string assignment can handle. One needs to know low-level details like this when mixing garbage-collected data with unmanaged memory.</p>

<h2><a class="toc-backref" id="types-procedural-type" href="#types-procedural-type">Procedural type</a></h2><p>A procedural type is internally a pointer to a procedure. <tt class="docutils literal"><span class="pre"><span class="Keyword">nil</span></span></tt> is an allowed value for a variable of a procedural type.</p>
<p>Examples:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">printItem</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Operator">...</span>

<span class="Keyword">proc</span> <span class="Identifier">forEach</span><span class="Punctuation">(</span><span class="Identifier">c</span><span class="Punctuation">:</span> <span class="Keyword">proc</span> <span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">cdecl</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Operator">...</span>

<span class="Identifier">forEach</span><span class="Punctuation">(</span><span class="Identifier">printItem</span><span class="Punctuation">)</span>  <span class="Comment"># this will NOT compile because calling conventions differ</span></pre></p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">OnMouseMove</span> <span class="Operator">=</span> <span class="Keyword">proc</span> <span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">closure</span><span class="Operator">.</span><span class="Punctuation">}</span>

<span class="Keyword">proc</span> <span class="Identifier">onMouseMove</span><span class="Punctuation">(</span><span class="Identifier">mouseX</span><span class="Punctuation">,</span> <span class="Identifier">mouseY</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Comment"># has default calling convention</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;x: &quot;</span><span class="Punctuation">,</span> <span class="Identifier">mouseX</span><span class="Punctuation">,</span> <span class="StringLit">&quot; y: &quot;</span><span class="Punctuation">,</span> <span class="Identifier">mouseY</span>

<span class="Keyword">proc</span> <span class="Identifier">setOnMouseMove</span><span class="Punctuation">(</span><span class="Identifier">mouseMoveEvent</span><span class="Punctuation">:</span> <span class="Identifier">OnMouseMove</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Keyword">discard</span>

<span class="Comment"># ok, 'onMouseMove' has the default calling convention, which is compatible</span>
<span class="Comment"># to 'closure':</span>
<span class="Identifier">setOnMouseMove</span><span class="Punctuation">(</span><span class="Identifier">onMouseMove</span><span class="Punctuation">)</span></pre></p>
<p>A subtle issue with procedural types is that the calling convention of the procedure influences the type compatibility: procedural types are only compatible if they have the same calling convention. As a special extension, a procedure of the calling convention <tt class="docutils literal"><span class="pre"><span class="Identifier">nimcall</span></span></tt> can be passed to a parameter that expects a proc of the calling convention <tt class="docutils literal"><span class="pre"><span class="Identifier">closure</span></span></tt>.</p>
<p>Nim supports these <span id="calling-conventions_1">calling conventions</span>:</p>
<dl class="docutils"><dt><span id="nimcall_1">nimcall</span></dt>
<dd>is the default convention used for a Nim <strong>proc</strong>. It is the same as <tt class="docutils literal"><span class="pre"><span class="Identifier">fastcall</span></span></tt>, but only for C compilers that support <tt class="docutils literal"><span class="pre"><span class="Identifier">fastcall</span></span></tt>.</dd>
<dt><span id="closure_1">closure</span></dt>
<dd>is the default calling convention for a <strong>procedural type</strong> that lacks any pragma annotations. It indicates that the procedure has a hidden implicit parameter (an <em>environment</em>). Proc vars that have the calling convention <tt class="docutils literal"><span class="pre"><span class="Identifier">closure</span></span></tt> take up two machine words: One for the proc pointer and another one for the pointer to implicitly passed environment.</dd>
<dt><span id="stdcall_1">stdcall</span></dt>
<dd>This is the stdcall convention as specified by Microsoft. The generated C procedure is declared with the <tt class="docutils literal"><span class="pre"><span class="Identifier">__stdcall</span></span></tt> keyword.</dd>
<dt><span id="cdecl_1">cdecl</span></dt>
<dd>The cdecl convention means that a procedure shall use the same convention as the C compiler. Under Windows the generated C procedure is declared with the <tt class="docutils literal"><span class="pre"><span class="Identifier">__cdecl</span></span></tt> keyword.</dd>
<dt><span id="safecall_1">safecall</span></dt>
<dd>This is the safecall convention as specified by Microsoft. The generated C procedure is declared with the <tt class="docutils literal"><span class="pre"><span class="Identifier">__safecall</span></span></tt> keyword. The word <em>safe</em> refers to the fact that all hardware registers shall be pushed to the hardware stack.</dd>
<dt><span id="inline_1">inline</span></dt>
<dd>The inline convention means the caller should not call the procedure, but inline its code directly. Note that Nim does not inline, but leaves this to the C compiler; it generates <tt class="docutils literal"><span class="pre"><span class="Identifier">__inline</span></span></tt> procedures. This is only a hint for the compiler: it may completely ignore it, and it may inline procedures that are not marked as <tt class="docutils literal"><span class="pre"><span class="Identifier">inline</span></span></tt>.</dd>
<dt><span id="noinline_1">noinline</span></dt>
<dd>The backend compiler may inline procedures that are not marked as <tt class="docutils literal"><span class="pre"><span class="Identifier">inline</span></span></tt>. The noinline convention prevents it.</dd>
<dt><span id="fastcall_1">fastcall</span></dt>
<dd>Fastcall means different things to different C compilers. One gets whatever the C <tt class="docutils literal"><span class="pre"><span class="Identifier">__fastcall</span></span></tt> means.</dd>
<dt><span id="thiscall_1">thiscall</span></dt>
<dd>This is the thiscall calling convention as specified by Microsoft, used on C++ class member functions on the x86 architecture.</dd>
<dt><span id="syscall_1">syscall</span></dt>
<dd>The syscall convention is the same as <tt class="docutils literal"><span class="pre"><span class="Identifier">__syscall</span></span></tt> in C. It is used for interrupts.</dd>
<dt><span id="noconv_1">noconv</span></dt>
<dd>The generated C code will not have any explicit calling convention and thus use the C compiler's default calling convention. This is needed because Nim's default calling convention for procedures is <tt class="docutils literal"><span class="pre"><span class="Identifier">fastcall</span></span></tt> to improve speed.</dd>
</dl>
<p>Most calling conventions exist only for the Windows 32-bit platform.</p>
<p>The default calling convention is <tt class="docutils literal"><span class="pre"><span class="Identifier">nimcall</span></span></tt>, unless it is an inner proc (a proc inside of a proc). For an inner proc an analysis is performed whether it accesses its environment. If it does so, it has the calling convention <tt class="docutils literal"><span class="pre"><span class="Identifier">closure</span></span></tt>, otherwise it has the calling convention <tt class="docutils literal"><span class="pre"><span class="Identifier">nimcall</span></span></tt>.</p>

<h2><a class="toc-backref" id="types-distinct-type" href="#types-distinct-type">Distinct type</a></h2><p>A <tt class="docutils literal"><span class="pre"><span class="Keyword">distinct</span></span></tt> type is a new type derived from a <span id="base-type_1">base type</span> that is incompatible with its base type. In particular, it is an essential property of a distinct type that it <strong>does not</strong> imply a subtype relation between it and its base type. Explicit type conversions from a distinct type to its base type and vice versa are allowed. See also <tt class="docutils literal"><span class="pre"><span class="Identifier">distinctBase</span></span></tt> to get the reverse operation.</p>
<p>A distinct type is an ordinal type if its base type is an ordinal type.</p>

<h3><a class="toc-backref" id="distinct-type-modeling-currencies" href="#distinct-type-modeling-currencies">Modeling currencies</a></h3><p>A distinct type can be used to model different physical <span id="units_1">units</span> with a numerical base type, for example. The following example models currencies.</p>
<p>Different currencies should not be mixed in monetary calculations. Distinct types are a perfect tool to model different currencies:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">Dollar</span> <span class="Operator">=</span> <span class="Keyword">distinct</span> <span class="Identifier">int</span>
  <span class="Identifier">Euro</span> <span class="Operator">=</span> <span class="Keyword">distinct</span> <span class="Identifier">int</span>

<span class="Keyword">var</span>
  <span class="Identifier">d</span><span class="Punctuation">:</span> <span class="Identifier">Dollar</span>
  <span class="Identifier">e</span><span class="Punctuation">:</span> <span class="Identifier">Euro</span>

<span class="Identifier">echo</span> <span class="Identifier">d</span> <span class="Operator">+</span> <span class="DecNumber">12</span>
<span class="Comment"># Error: cannot add a number with no unit and a `Dollar`</span></pre></p>
<p>Unfortunately, <tt class="docutils literal"><span class="pre"><span class="Identifier">d</span> <span class="Operator">+</span> <span class="FloatNumber">12.</span><span class="Identifier">Dollar</span></span></tt> is not allowed either, because <tt class="docutils literal"><span class="pre"><span class="Operator">+</span></span></tt> is defined for <tt class="docutils literal"><span class="pre"><span class="Identifier">int</span></span></tt> (among others), not for <tt class="docutils literal"><span class="pre"><span class="Identifier">Dollar</span></span></tt>. So a <tt class="docutils literal"><span class="pre"><span class="Operator">+</span></span></tt> for dollars needs to be defined:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">+</span><span class="Punctuation">`</span> <span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">Dollar</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">Dollar</span> <span class="Operator">=</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">Dollar</span><span class="Punctuation">(</span><span class="Identifier">int</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span> <span class="Operator">+</span> <span class="Identifier">int</span><span class="Punctuation">(</span><span class="Identifier">y</span><span class="Punctuation">)</span><span class="Punctuation">)</span></pre></p>
<p>It does not make sense to multiply a dollar with a dollar, but with a number without unit; and the same holds for division:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">*</span><span class="Punctuation">`</span> <span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">Dollar</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">Dollar</span> <span class="Operator">=</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">Dollar</span><span class="Punctuation">(</span><span class="Identifier">int</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span> <span class="Operator">*</span> <span class="Identifier">y</span><span class="Punctuation">)</span>

<span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">*</span><span class="Punctuation">`</span> <span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">Dollar</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">Dollar</span> <span class="Operator">=</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">Dollar</span><span class="Punctuation">(</span><span class="Identifier">x</span> <span class="Operator">*</span> <span class="Identifier">int</span><span class="Punctuation">(</span><span class="Identifier">y</span><span class="Punctuation">)</span><span class="Punctuation">)</span>

<span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Keyword">div</span><span class="Punctuation">`</span> <span class="Operator">...</span></pre></p>
<p>This quickly gets tedious. The implementations are trivial and the compiler should not generate all this code only to optimize it away later - after all <tt class="docutils literal"><span class="pre"><span class="Operator">+</span></span></tt> for dollars should produce the same binary code as <tt class="docutils literal"><span class="pre"><span class="Operator">+</span></span></tt> for ints. The pragma <span id="borrow_1">borrow</span> has been designed to solve this problem; in principle, it generates the above trivial implementations:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">*</span><span class="Punctuation">`</span> <span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">Dollar</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">Dollar</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">borrow</span><span class="Operator">.</span><span class="Punctuation">}</span>
<span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">*</span><span class="Punctuation">`</span> <span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">Dollar</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">Dollar</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">borrow</span><span class="Operator">.</span><span class="Punctuation">}</span>
<span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Keyword">div</span><span class="Punctuation">`</span> <span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">Dollar</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">Dollar</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">borrow</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>
<p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">borrow</span></span></tt> pragma makes the compiler use the same implementation as the proc that deals with the distinct type's base type, so no code is generated.</p>
<p>But it seems all this boilerplate code needs to be repeated for the <tt class="docutils literal"><span class="pre"><span class="Identifier">Euro</span></span></tt> currency. This can be solved with <a class="reference internal" href="#templates">templates</a>.</p>
<p><pre class="listing"><span class="Keyword">template</span> <span class="Identifier">additive</span><span class="Punctuation">(</span><span class="Identifier">typ</span><span class="Punctuation">:</span> <span class="Identifier">typedesc</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">+</span><span class="Punctuation">`</span> <span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">typ</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">typ</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">borrow</span><span class="Operator">.</span><span class="Punctuation">}</span>
  <span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">-</span><span class="Punctuation">`</span> <span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">typ</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">typ</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">borrow</span><span class="Operator">.</span><span class="Punctuation">}</span>
  
  <span class="Comment"># unary operators:</span>
  <span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">+</span><span class="Punctuation">`</span> <span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">typ</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">typ</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">borrow</span><span class="Operator">.</span><span class="Punctuation">}</span>
  <span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">-</span><span class="Punctuation">`</span> <span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">typ</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">typ</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">borrow</span><span class="Operator">.</span><span class="Punctuation">}</span>

<span class="Keyword">template</span> <span class="Identifier">multiplicative</span><span class="Punctuation">(</span><span class="Identifier">typ</span><span class="Punctuation">,</span> <span class="Identifier">base</span><span class="Punctuation">:</span> <span class="Identifier">typedesc</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">*</span><span class="Punctuation">`</span> <span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">typ</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">base</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">typ</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">borrow</span><span class="Operator">.</span><span class="Punctuation">}</span>
  <span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">*</span><span class="Punctuation">`</span> <span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">base</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">typ</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">typ</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">borrow</span><span class="Operator">.</span><span class="Punctuation">}</span>
  <span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Keyword">div</span><span class="Punctuation">`</span> <span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">typ</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">base</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">typ</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">borrow</span><span class="Operator">.</span><span class="Punctuation">}</span>
  <span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Keyword">mod</span><span class="Punctuation">`</span> <span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">typ</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">base</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">typ</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">borrow</span><span class="Operator">.</span><span class="Punctuation">}</span>

<span class="Keyword">template</span> <span class="Identifier">comparable</span><span class="Punctuation">(</span><span class="Identifier">typ</span><span class="Punctuation">:</span> <span class="Identifier">typedesc</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">&lt;</span><span class="Punctuation">`</span> <span class="Operator">*</span> <span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">typ</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">bool</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">borrow</span><span class="Operator">.</span><span class="Punctuation">}</span>
  <span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">&lt;=</span><span class="Punctuation">`</span> <span class="Operator">*</span> <span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">typ</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">bool</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">borrow</span><span class="Operator">.</span><span class="Punctuation">}</span>
  <span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">==</span><span class="Punctuation">`</span> <span class="Operator">*</span> <span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">typ</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">bool</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">borrow</span><span class="Operator">.</span><span class="Punctuation">}</span>

<span class="Keyword">template</span> <span class="Identifier">defineCurrency</span><span class="Punctuation">(</span><span class="Identifier">typ</span><span class="Punctuation">,</span> <span class="Identifier">base</span><span class="Punctuation">:</span> <span class="Identifier">untyped</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">type</span>
    <span class="Identifier">typ</span><span class="Operator">*</span> <span class="Operator">=</span> <span class="Keyword">distinct</span> <span class="Identifier">base</span>
  <span class="Identifier">additive</span><span class="Punctuation">(</span><span class="Identifier">typ</span><span class="Punctuation">)</span>
  <span class="Identifier">multiplicative</span><span class="Punctuation">(</span><span class="Identifier">typ</span><span class="Punctuation">,</span> <span class="Identifier">base</span><span class="Punctuation">)</span>
  <span class="Identifier">comparable</span><span class="Punctuation">(</span><span class="Identifier">typ</span><span class="Punctuation">)</span>

<span class="Identifier">defineCurrency</span><span class="Punctuation">(</span><span class="Identifier">Dollar</span><span class="Punctuation">,</span> <span class="Identifier">int</span><span class="Punctuation">)</span>
<span class="Identifier">defineCurrency</span><span class="Punctuation">(</span><span class="Identifier">Euro</span><span class="Punctuation">,</span> <span class="Identifier">int</span><span class="Punctuation">)</span></pre></p>
<p>The borrow pragma can also be used to annotate the distinct type to allow certain builtin operations to be lifted:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">Foo</span> <span class="Operator">=</span> <span class="Keyword">object</span>
    <span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">int</span>
    <span class="Identifier">s</span><span class="Punctuation">:</span> <span class="Identifier">string</span>
  
  <span class="Identifier">Bar</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">borrow</span><span class="Punctuation">:</span> <span class="Punctuation">`</span><span class="Operator">.</span><span class="Punctuation">`</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">distinct</span> <span class="Identifier">Foo</span>

<span class="Keyword">var</span> <span class="Identifier">bb</span><span class="Punctuation">:</span> <span class="Keyword">ref</span> <span class="Identifier">Bar</span>
<span class="Identifier">new</span> <span class="Identifier">bb</span>
<span class="Comment"># field access now valid</span>
<span class="Identifier">bb</span><span class="Operator">.</span><span class="Identifier">a</span> <span class="Operator">=</span> <span class="DecNumber">90</span>
<span class="Identifier">bb</span><span class="Operator">.</span><span class="Identifier">s</span> <span class="Operator">=</span> <span class="StringLit">&quot;abc&quot;</span></pre></p>
<p>Currently, only the dot accessor can be borrowed in this way.</p>

<h3><a class="toc-backref" id="distinct-type-avoiding-sql-injection-attacks" href="#distinct-type-avoiding-sql-injection-attacks">Avoiding SQL injection attacks</a></h3><p>An SQL statement that is passed from Nim to an SQL database might be modeled as a string. However, using string templates and filling in the values is vulnerable to the famous <span id="sql-injection-attack_1">SQL injection attack</span>:</p>
<p><pre class="listing"><span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">strutils</span>

<span class="Keyword">proc</span> <span class="Identifier">query</span><span class="Punctuation">(</span><span class="Identifier">db</span><span class="Punctuation">:</span> <span class="Identifier">DbHandle</span><span class="Punctuation">,</span> <span class="Identifier">statement</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Operator">...</span>

<span class="Keyword">var</span>
  <span class="Identifier">username</span><span class="Punctuation">:</span> <span class="Identifier">string</span>

<span class="Identifier">db</span><span class="Operator">.</span><span class="Identifier">query</span><span class="Punctuation">(</span><span class="StringLit">&quot;SELECT FROM users WHERE name = '$1'&quot;</span> <span class="Operator">%</span> <span class="Identifier">username</span><span class="Punctuation">)</span>
<span class="Comment"># Horrible security hole, but the compiler does not mind!</span></pre></p>
<p>This can be avoided by distinguishing strings that contain SQL from strings that don't. Distinct types provide a means to introduce a new string type <tt class="docutils literal"><span class="pre"><span class="Identifier">SQL</span></span></tt> that is incompatible with <tt class="docutils literal"><span class="pre"><span class="Identifier">string</span></span></tt>:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">SQL</span> <span class="Operator">=</span> <span class="Keyword">distinct</span> <span class="Identifier">string</span>

<span class="Keyword">proc</span> <span class="Identifier">query</span><span class="Punctuation">(</span><span class="Identifier">db</span><span class="Punctuation">:</span> <span class="Identifier">DbHandle</span><span class="Punctuation">,</span> <span class="Identifier">statement</span><span class="Punctuation">:</span> <span class="Identifier">SQL</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Operator">...</span>

<span class="Keyword">var</span>
  <span class="Identifier">username</span><span class="Punctuation">:</span> <span class="Identifier">string</span>

<span class="Identifier">db</span><span class="Operator">.</span><span class="Identifier">query</span><span class="Punctuation">(</span><span class="StringLit">&quot;SELECT FROM users WHERE name = '$1'&quot;</span> <span class="Operator">%</span> <span class="Identifier">username</span><span class="Punctuation">)</span>
<span class="Comment"># Static error: `query` expects an SQL string!</span></pre></p>
<p>It is an essential property of abstract types that they <strong>do not</strong> imply a subtype relation between the abstract type and its base type. Explicit type conversions from <tt class="docutils literal"><span class="pre"><span class="Identifier">string</span></span></tt> to <tt class="docutils literal"><span class="pre"><span class="Identifier">SQL</span></span></tt> are allowed:</p>
<p><pre class="listing"><span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Punctuation">[</span><span class="Identifier">strutils</span><span class="Punctuation">,</span> <span class="Identifier">sequtils</span><span class="Punctuation">]</span>

<span class="Keyword">proc</span> <span class="Identifier">properQuote</span><span class="Punctuation">(</span><span class="Identifier">s</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">SQL</span> <span class="Operator">=</span>
  <span class="Comment"># quotes a string properly for an SQL statement</span>
  <span class="Keyword">return</span> <span class="Identifier">SQL</span><span class="Punctuation">(</span><span class="Identifier">s</span><span class="Punctuation">)</span>

<span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">%</span><span class="Punctuation">`</span> <span class="Punctuation">(</span><span class="Identifier">frmt</span><span class="Punctuation">:</span> <span class="Identifier">SQL</span><span class="Punctuation">,</span> <span class="Identifier">values</span><span class="Punctuation">:</span> <span class="Identifier">openarray</span><span class="Punctuation">[</span><span class="Identifier">string</span><span class="Punctuation">]</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">SQL</span> <span class="Operator">=</span>
  <span class="Comment"># quote each argument:</span>
  <span class="Keyword">let</span> <span class="Identifier">v</span> <span class="Operator">=</span> <span class="Identifier">values</span><span class="Operator">.</span><span class="Identifier">mapIt</span><span class="Punctuation">(</span><span class="Identifier">properQuote</span><span class="Punctuation">(</span><span class="Identifier">it</span><span class="Punctuation">)</span><span class="Punctuation">)</span>
  <span class="Comment"># we need a temporary type for the type conversion :-(</span>
  <span class="Keyword">type</span> <span class="Identifier">StrSeq</span> <span class="Operator">=</span> <span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">string</span><span class="Punctuation">]</span>
  <span class="Comment"># call strutils.`%`:</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">SQL</span><span class="Punctuation">(</span><span class="Identifier">string</span><span class="Punctuation">(</span><span class="Identifier">frmt</span><span class="Punctuation">)</span> <span class="Operator">%</span> <span class="Identifier">StrSeq</span><span class="Punctuation">(</span><span class="Identifier">v</span><span class="Punctuation">)</span><span class="Punctuation">)</span>

<span class="Identifier">db</span><span class="Operator">.</span><span class="Identifier">query</span><span class="Punctuation">(</span><span class="StringLit">&quot;SELECT FROM users WHERE name = '$1'&quot;</span><span class="Operator">.</span><span class="Identifier">SQL</span> <span class="Operator">%</span> <span class="Punctuation">[</span><span class="Identifier">username</span><span class="Punctuation">]</span><span class="Punctuation">)</span></pre></p>
<p>Now we have compile-time checking against SQL injection attacks. Since <tt class="docutils literal"><span class="pre"><span class="StringLit">&quot;&quot;</span><span class="Operator">.</span><span class="Identifier">SQL</span></span></tt> is transformed to <tt class="docutils literal"><span class="pre"><span class="Identifier">SQL</span><span class="Punctuation">(</span><span class="StringLit">&quot;&quot;</span><span class="Punctuation">)</span></span></tt> no new syntax is needed for nice looking <tt class="docutils literal"><span class="pre"><span class="Identifier">SQL</span></span></tt> string literals. The hypothetical <tt class="docutils literal"><span class="pre"><span class="Identifier">SQL</span></span></tt> type actually exists in the library as the <a class="reference external" href="db_common.html#SqlQuery">SqlQuery type</a> of modules like <a class="reference external" href="db_sqlite.html">db_sqlite</a>.</p>

<h2><a class="toc-backref" id="types-auto-type" href="#types-auto-type">Auto type</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">auto</span></span></tt> type can only be used for return types and parameters. For return types it causes the compiler to infer the type from the routine body:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">returnsInt</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">auto</span> <span class="Operator">=</span> <span class="DecNumber">1984</span></pre></p>
<p>For parameters it currently creates implicitly generic routines:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">foo</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">auto</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Keyword">discard</span></pre></p>
<p>Is the same as:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">foo</span><span class="Punctuation">[</span><span class="Identifier">T1</span><span class="Punctuation">,</span> <span class="Identifier">T2</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">T1</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">T2</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Keyword">discard</span></pre></p>
<p>However, later versions of the language might change this to mean &quot;infer the parameters' types from the body&quot;. Then the above <tt class="docutils literal"><span class="pre"><span class="Identifier">foo</span></span></tt> would be rejected as the parameters' types can not be inferred from an empty <tt class="docutils literal"><span class="pre"><span class="Keyword">discard</span></span></tt> statement.</p>

<h1><a class="toc-backref" id="type-relations" href="#type-relations">Type relations</a></h1><p>The following section defines several relations on types that are needed to describe the type checking done by the compiler.</p>

<h2><a class="toc-backref" id="type-relations-type-equality" href="#type-relations-type-equality">Type equality</a></h2><p>Nim uses structural type equivalence for most types. Only for objects, enumerations and distinct types and for generic types name equivalence is used.</p>

<h2><a class="toc-backref" id="type-relations-subtype-relation" href="#type-relations-subtype-relation">Subtype relation</a></h2><p>If object <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span></span></tt> inherits from <tt class="docutils literal"><span class="pre"><span class="Identifier">b</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span></span></tt> is a subtype of <tt class="docutils literal"><span class="pre"><span class="Identifier">b</span></span></tt>.</p>
<p>This subtype relation is extended to the types <tt class="docutils literal"><span class="pre"><span class="Keyword">var</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">ref</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">ptr</span></span></tt>. If <tt class="docutils literal"><span class="pre"><span class="Identifier">A</span></span></tt> is a subtype of <tt class="docutils literal"><span class="pre"><span class="Identifier">B</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">A</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">B</span></span></tt> are <tt class="docutils literal"><span class="pre"><span class="Keyword">object</span></span></tt> types then:</p>
<ul class="simple"><li><tt class="docutils literal"><span class="pre"><span class="Keyword">var</span> <span class="Identifier">A</span></span></tt> is a subtype of <tt class="docutils literal"><span class="pre"><span class="Keyword">var</span> <span class="Identifier">B</span></span></tt></li>
<li><tt class="docutils literal"><span class="pre"><span class="Keyword">ref</span> <span class="Identifier">A</span></span></tt> is a subtype of <tt class="docutils literal"><span class="pre"><span class="Keyword">ref</span> <span class="Identifier">B</span></span></tt></li>
<li><tt class="docutils literal"><span class="pre"><span class="Keyword">ptr</span> <span class="Identifier">A</span></span></tt> is a subtype of <tt class="docutils literal"><span class="pre"><span class="Keyword">ptr</span> <span class="Identifier">B</span></span></tt>.</li>
</ul>
<p><strong>Note</strong>: One of the above pointer-indirections is required for assignment from a subtype to its parent type to prevent &quot;object slicing&quot;.</p>

<h2><a class="toc-backref" id="type-relations-convertible-relation" href="#type-relations-convertible-relation">Convertible relation</a></h2><p>A type <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span></span></tt> is <strong>implicitly</strong> convertible to type <tt class="docutils literal"><span class="pre"><span class="Identifier">b</span></span></tt> iff the following algorithm returns true:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">isImplicitlyConvertible</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">PType</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">bool</span> <span class="Operator">=</span>
  <span class="Keyword">if</span> <span class="Identifier">isSubtype</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
    <span class="Keyword">return</span> <span class="Identifier">true</span>
  <span class="Keyword">if</span> <span class="Identifier">isIntLiteral</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
    <span class="Keyword">return</span> <span class="Identifier">b</span> <span class="Keyword">in</span> <span class="Punctuation">{</span><span class="Identifier">int8</span><span class="Punctuation">,</span> <span class="Identifier">int16</span><span class="Punctuation">,</span> <span class="Identifier">int32</span><span class="Punctuation">,</span> <span class="Identifier">int64</span><span class="Punctuation">,</span> <span class="Identifier">int</span><span class="Punctuation">,</span> <span class="Identifier">uint</span><span class="Punctuation">,</span> <span class="Identifier">uint8</span><span class="Punctuation">,</span> <span class="Identifier">uint16</span><span class="Punctuation">,</span>
                 <span class="Identifier">uint32</span><span class="Punctuation">,</span> <span class="Identifier">uint64</span><span class="Punctuation">,</span> <span class="Identifier">float32</span><span class="Punctuation">,</span> <span class="Identifier">float64</span><span class="Punctuation">}</span>
  <span class="Keyword">case</span> <span class="Identifier">a</span><span class="Operator">.</span><span class="Identifier">kind</span>
  <span class="Keyword">of</span> <span class="Identifier">int</span><span class="Punctuation">:</span>     <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">b</span> <span class="Keyword">in</span> <span class="Punctuation">{</span><span class="Identifier">int32</span><span class="Punctuation">,</span> <span class="Identifier">int64</span><span class="Punctuation">}</span>
  <span class="Keyword">of</span> <span class="Identifier">int8</span><span class="Punctuation">:</span>    <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">b</span> <span class="Keyword">in</span> <span class="Punctuation">{</span><span class="Identifier">int16</span><span class="Punctuation">,</span> <span class="Identifier">int32</span><span class="Punctuation">,</span> <span class="Identifier">int64</span><span class="Punctuation">,</span> <span class="Identifier">int</span><span class="Punctuation">}</span>
  <span class="Keyword">of</span> <span class="Identifier">int16</span><span class="Punctuation">:</span>   <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">b</span> <span class="Keyword">in</span> <span class="Punctuation">{</span><span class="Identifier">int32</span><span class="Punctuation">,</span> <span class="Identifier">int64</span><span class="Punctuation">,</span> <span class="Identifier">int</span><span class="Punctuation">}</span>
  <span class="Keyword">of</span> <span class="Identifier">int32</span><span class="Punctuation">:</span>   <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">b</span> <span class="Keyword">in</span> <span class="Punctuation">{</span><span class="Identifier">int64</span><span class="Punctuation">,</span> <span class="Identifier">int</span><span class="Punctuation">}</span>
  <span class="Keyword">of</span> <span class="Identifier">uint</span><span class="Punctuation">:</span>    <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">b</span> <span class="Keyword">in</span> <span class="Punctuation">{</span><span class="Identifier">uint32</span><span class="Punctuation">,</span> <span class="Identifier">uint64</span><span class="Punctuation">}</span>
  <span class="Keyword">of</span> <span class="Identifier">uint8</span><span class="Punctuation">:</span>   <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">b</span> <span class="Keyword">in</span> <span class="Punctuation">{</span><span class="Identifier">uint16</span><span class="Punctuation">,</span> <span class="Identifier">uint32</span><span class="Punctuation">,</span> <span class="Identifier">uint64</span><span class="Punctuation">}</span>
  <span class="Keyword">of</span> <span class="Identifier">uint16</span><span class="Punctuation">:</span>  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">b</span> <span class="Keyword">in</span> <span class="Punctuation">{</span><span class="Identifier">uint32</span><span class="Punctuation">,</span> <span class="Identifier">uint64</span><span class="Punctuation">}</span>
  <span class="Keyword">of</span> <span class="Identifier">uint32</span><span class="Punctuation">:</span>  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">b</span> <span class="Keyword">in</span> <span class="Punctuation">{</span><span class="Identifier">uint64</span><span class="Punctuation">}</span>
  <span class="Keyword">of</span> <span class="Identifier">float32</span><span class="Punctuation">:</span> <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">b</span> <span class="Keyword">in</span> <span class="Punctuation">{</span><span class="Identifier">float64</span><span class="Punctuation">}</span>
  <span class="Keyword">of</span> <span class="Identifier">float64</span><span class="Punctuation">:</span> <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">b</span> <span class="Keyword">in</span> <span class="Punctuation">{</span><span class="Identifier">float32</span><span class="Punctuation">}</span>
  <span class="Keyword">of</span> <span class="Identifier">seq</span><span class="Punctuation">:</span>
    <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">b</span> <span class="Operator">==</span> <span class="Identifier">openArray</span> <span class="Keyword">and</span> <span class="Identifier">typeEquals</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Operator">.</span><span class="Identifier">baseType</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Operator">.</span><span class="Identifier">baseType</span><span class="Punctuation">)</span>
  <span class="Keyword">of</span> <span class="Identifier">array</span><span class="Punctuation">:</span>
    <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">b</span> <span class="Operator">==</span> <span class="Identifier">openArray</span> <span class="Keyword">and</span> <span class="Identifier">typeEquals</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Operator">.</span><span class="Identifier">baseType</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Operator">.</span><span class="Identifier">baseType</span><span class="Punctuation">)</span>
    <span class="Keyword">if</span> <span class="Identifier">a</span><span class="Operator">.</span><span class="Identifier">baseType</span> <span class="Operator">==</span> <span class="Identifier">char</span> <span class="Keyword">and</span> <span class="Identifier">a</span><span class="Operator">.</span><span class="Identifier">indexType</span><span class="Operator">.</span><span class="Identifier">rangeA</span> <span class="Operator">==</span> <span class="DecNumber">0</span><span class="Punctuation">:</span>
      <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">b</span> <span class="Operator">==</span> <span class="Identifier">cstring</span>
  <span class="Keyword">of</span> <span class="Identifier">cstring</span><span class="Punctuation">,</span> <span class="Keyword">ptr</span><span class="Punctuation">:</span>
    <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">b</span> <span class="Operator">==</span> <span class="Identifier">pointer</span>
  <span class="Keyword">of</span> <span class="Identifier">string</span><span class="Punctuation">:</span>
    <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">b</span> <span class="Operator">==</span> <span class="Identifier">cstring</span>
  <span class="Keyword">of</span> <span class="Keyword">proc</span><span class="Punctuation">:</span>
    <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">typeEquals</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">)</span> <span class="Keyword">or</span> <span class="Identifier">compatibleParametersAndEffects</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">)</span></pre></p>
<p>We used the predicate <tt class="docutils literal"><span class="pre"><span class="Identifier">typeEquals</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">)</span></span></tt> for the &quot;type equality&quot; property and the predicate <tt class="docutils literal"><span class="pre"><span class="Identifier">isSubtype</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">)</span></span></tt> for the &quot;subtype relation&quot;. <tt class="docutils literal"><span class="pre"><span class="Identifier">compatibleParametersAndEffects</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">)</span></span></tt> is currently not specified.</p>
<p>Implicit conversions are also performed for Nim's <tt class="docutils literal"><span class="pre"><span class="Identifier">range</span></span></tt> type constructor.</p>
<p>Let <tt class="docutils literal"><span class="pre"><span class="Identifier">a0</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Identifier">b0</span></span></tt> of type <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span></span></tt>.</p>
<p>Let <tt class="docutils literal"><span class="pre"><span class="Identifier">A</span> <span class="Operator">=</span> <span class="Identifier">range</span><span class="Punctuation">[</span><span class="Identifier">a0</span><span class="Operator">..</span><span class="Identifier">b0</span><span class="Punctuation">]</span></span></tt> be the argument's type, <tt class="docutils literal"><span class="pre"><span class="Identifier">F</span></span></tt> the formal parameter's type. Then an implicit conversion from <tt class="docutils literal"><span class="pre"><span class="Identifier">A</span></span></tt> to <tt class="docutils literal"><span class="pre"><span class="Identifier">F</span></span></tt> exists if <tt class="docutils literal"><span class="pre"><span class="Identifier">a0</span> <span class="Operator">&gt;=</span> <span class="Identifier">low</span><span class="Punctuation">(</span><span class="Identifier">F</span><span class="Punctuation">)</span> <span class="Keyword">and</span> <span class="Identifier">b0</span> <span class="Operator">&lt;=</span> <span class="Identifier">high</span><span class="Punctuation">(</span><span class="Identifier">F</span><span class="Punctuation">)</span></span></tt> and both <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">F</span></span></tt> are signed integers or if both are unsigned integers.</p>
<p>A type <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span></span></tt> is <strong>explicitly</strong> convertible to type <tt class="docutils literal"><span class="pre"><span class="Identifier">b</span></span></tt> iff the following algorithm returns true:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">isIntegralType</span><span class="Punctuation">(</span><span class="Identifier">t</span><span class="Punctuation">:</span> <span class="Identifier">PType</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">bool</span> <span class="Operator">=</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">isOrdinal</span><span class="Punctuation">(</span><span class="Identifier">t</span><span class="Punctuation">)</span> <span class="Keyword">or</span> <span class="Identifier">t</span><span class="Operator">.</span><span class="Identifier">kind</span> <span class="Keyword">in</span> <span class="Punctuation">{</span><span class="Identifier">float</span><span class="Punctuation">,</span> <span class="Identifier">float32</span><span class="Punctuation">,</span> <span class="Identifier">float64</span><span class="Punctuation">}</span>

<span class="Keyword">proc</span> <span class="Identifier">isExplicitlyConvertible</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">PType</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">bool</span> <span class="Operator">=</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">false</span>
  <span class="Keyword">if</span> <span class="Identifier">isImplicitlyConvertible</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Keyword">return</span> <span class="Identifier">true</span>
  <span class="Keyword">if</span> <span class="Identifier">typeEquals</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Keyword">return</span> <span class="Identifier">true</span>
  <span class="Keyword">if</span> <span class="Identifier">a</span> <span class="Operator">==</span> <span class="Keyword">distinct</span> <span class="Keyword">and</span> <span class="Identifier">typeEquals</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Operator">.</span><span class="Identifier">baseType</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Keyword">return</span> <span class="Identifier">true</span>
  <span class="Keyword">if</span> <span class="Identifier">b</span> <span class="Operator">==</span> <span class="Keyword">distinct</span> <span class="Keyword">and</span> <span class="Identifier">typeEquals</span><span class="Punctuation">(</span><span class="Identifier">b</span><span class="Operator">.</span><span class="Identifier">baseType</span><span class="Punctuation">,</span> <span class="Identifier">a</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Keyword">return</span> <span class="Identifier">true</span>
  <span class="Keyword">if</span> <span class="Identifier">isIntegralType</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">)</span> <span class="Keyword">and</span> <span class="Identifier">isIntegralType</span><span class="Punctuation">(</span><span class="Identifier">b</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Keyword">return</span> <span class="Identifier">true</span>
  <span class="Keyword">if</span> <span class="Identifier">isSubtype</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">)</span> <span class="Keyword">or</span> <span class="Identifier">isSubtype</span><span class="Punctuation">(</span><span class="Identifier">b</span><span class="Punctuation">,</span> <span class="Identifier">a</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Keyword">return</span> <span class="Identifier">true</span></pre></p>
<p>The convertible relation can be relaxed by a user-defined type <span id="converter_1">converter</span>.</p>
<p><pre class="listing"><span class="Keyword">converter</span> <span class="Identifier">toInt</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">char</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span> <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">ord</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span>

<span class="Keyword">var</span>
  <span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">int</span>
  <span class="Identifier">chr</span><span class="Punctuation">:</span> <span class="Identifier">char</span> <span class="Operator">=</span> <span class="CharLit">'a'</span>

<span class="Comment"># implicit conversion magic happens here</span>
<span class="Identifier">x</span> <span class="Operator">=</span> <span class="Identifier">chr</span>
<span class="Identifier">echo</span> <span class="Identifier">x</span> <span class="Comment"># =&gt; 97</span>
<span class="Comment"># one can use the explicit form too</span>
<span class="Identifier">x</span> <span class="Operator">=</span> <span class="Identifier">chr</span><span class="Operator">.</span><span class="Identifier">toInt</span>
<span class="Identifier">echo</span> <span class="Identifier">x</span> <span class="Comment"># =&gt; 97</span></pre></p>
<p>The type conversion <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">)</span></span></tt> is an L-value if <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span></span></tt> is an L-value and <tt class="docutils literal"><span class="pre"><span class="Identifier">typeEqualsOrDistinct</span><span class="Punctuation">(</span><span class="Identifier">T</span><span class="Punctuation">,</span> <span class="Identifier">typeof</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">)</span><span class="Punctuation">)</span></span></tt> holds.</p>

<h2><a class="toc-backref" id="type-relations-assignment-compatibility" href="#type-relations-assignment-compatibility">Assignment compatibility</a></h2><p>An expression <tt class="docutils literal"><span class="pre"><span class="Identifier">b</span></span></tt> can be assigned to an expression <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span></span></tt> iff <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span></span></tt> is an <tt class="docutils literal"><span class="pre"><span class="Identifier">l</span><span class="Operator">-</span><span class="Identifier">value</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">isImplicitlyConvertible</span><span class="Punctuation">(</span><span class="Identifier">b</span><span class="Operator">.</span><span class="Identifier">typ</span><span class="Punctuation">,</span> <span class="Identifier">a</span><span class="Operator">.</span><span class="Identifier">typ</span><span class="Punctuation">)</span></span></tt> holds.</p>

<h1><a class="toc-backref" id="overload-resolution" href="#overload-resolution">Overload resolution</a></h1><p>In a call <tt class="docutils literal"><span class="pre"><span class="Identifier">p</span><span class="Punctuation">(</span><span class="Identifier">args</span><span class="Punctuation">)</span></span></tt> where <tt class="docutils literal"><span class="pre"><span class="Identifier">p</span></span></tt> may refer to more than one candidate, it is said to be a symbol choice. Overload resolution will attempt to find the best candidate, thus transforming the symbol choice into a resolved symbol. The routine <tt class="docutils literal"><span class="pre"><span class="Identifier">p</span></span></tt> that matches best is selected following a series of trials explained below. In order: Category matching, Hierarchical Order Comparison, and finally, Complexity Analysis.</p>
<p>If multiple candidates match equally well after all trials have been tested, the ambiguity is reported during semantic analysis.</p>

<h2><a class="toc-backref" id="overload-resolution-first-trialcolon-category-matching" href="#overload-resolution-first-trialcolon-category-matching">First Trial: Category matching</a></h2><p>Every arg in <tt class="docutils literal"><span class="pre"><span class="Identifier">args</span></span></tt> needs to match and there are multiple different categories of matches. Let <tt class="docutils literal"><span class="pre"><span class="Identifier">f</span></span></tt> be the formal parameter's type and <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span></span></tt> the type of the argument.</p>
<ol class="simple"><li>Exact match: <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">f</span></span></tt> are of the same type.</li>
<li>Literal match: <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span></span></tt> is an integer literal of value <tt class="docutils literal"><span class="pre"><span class="Identifier">v</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">f</span></span></tt> is a signed or unsigned integer type and <tt class="docutils literal"><span class="pre"><span class="Identifier">v</span></span></tt> is in <tt class="docutils literal"><span class="pre"><span class="Identifier">f</span></span></tt>'s range. Or:  <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span></span></tt> is a floating-point literal of value <tt class="docutils literal"><span class="pre"><span class="Identifier">v</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">f</span></span></tt> is a floating-point type and <tt class="docutils literal"><span class="pre"><span class="Identifier">v</span></span></tt> is in <tt class="docutils literal"><span class="pre"><span class="Identifier">f</span></span></tt>'s range.</li>
<li>Generic match: <tt class="docutils literal"><span class="pre"><span class="Identifier">f</span></span></tt> is a generic type and <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span></span></tt> matches, for instance <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span></span></tt> is <tt class="docutils literal"><span class="pre"><span class="Identifier">int</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">f</span></span></tt> is a generic (constrained) parameter type (like in <tt class="docutils literal"><span class="pre"><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Operator">|</span><span class="Identifier">char</span><span class="Punctuation">]</span></span></tt>).</li>
<li>Subrange or subtype match: <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span></span></tt> is a <tt class="docutils literal"><span class="pre"><span class="Identifier">range</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span></span></tt> matches <tt class="docutils literal"><span class="pre"><span class="Identifier">f</span></span></tt> exactly. Or: <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span></span></tt> is a subtype of <tt class="docutils literal"><span class="pre"><span class="Identifier">f</span></span></tt>.</li>
<li>Integral conversion match: <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span></span></tt> is convertible to <tt class="docutils literal"><span class="pre"><span class="Identifier">f</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">f</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span></span></tt> is some integer or floating-point type.</li>
<li>Conversion match: <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span></span></tt> is convertible to <tt class="docutils literal"><span class="pre"><span class="Identifier">f</span></span></tt>, possibly via a user defined <tt class="docutils literal"><span class="pre"><span class="Keyword">converter</span></span></tt>.</li>
</ol>
<p>Each operand may fall into one of the categories above; the operand's highest priority category. The list above is in order or priority. If a candidate has more priority matches than all other candidates, it is selected as the resolved symbol.</p>
<p>For example, if a candidate with one exact match is compared to a candidate with multiple generic matches and zero exact matches, the candidate with an exact match will win.</p>
<p>Below is a pseudocode interpretation of category matching, <tt class="docutils literal"><span class="pre"><span class="Identifier">count</span><span class="Punctuation">(</span><span class="Identifier">p</span><span class="Punctuation">,</span> <span class="Identifier">m</span><span class="Punctuation">)</span></span></tt> counts the number of matches of the matching category <tt class="docutils literal"><span class="pre"><span class="Identifier">m</span></span></tt> for the routine <tt class="docutils literal"><span class="pre"><span class="Identifier">p</span></span></tt>.</p>
<p>A routine <tt class="docutils literal"><span class="pre"><span class="Identifier">p</span></span></tt> matches better than a routine <tt class="docutils literal"><span class="pre"><span class="Identifier">q</span></span></tt> if the following algorithm returns true:</p>
<p><pre class="listing"><span class="Keyword">for</span> <span class="Identifier">each</span> <span class="Identifier">matching</span> <span class="Identifier">category</span> <span class="Identifier">m</span> <span class="Keyword">in</span> <span class="Punctuation">[</span><span class="StringLit">&quot;exact match&quot;</span><span class="Punctuation">,</span> <span class="StringLit">&quot;literal match&quot;</span><span class="Punctuation">,</span>
                                <span class="StringLit">&quot;generic match&quot;</span><span class="Punctuation">,</span> <span class="StringLit">&quot;subtype match&quot;</span><span class="Punctuation">,</span>
                                <span class="StringLit">&quot;integral match&quot;</span><span class="Punctuation">,</span> <span class="StringLit">&quot;conversion match&quot;</span><span class="Punctuation">]</span><span class="Punctuation">:</span>
  <span class="Keyword">if</span> <span class="Identifier">count</span><span class="Punctuation">(</span><span class="Identifier">p</span><span class="Punctuation">,</span> <span class="Identifier">m</span><span class="Punctuation">)</span> <span class="Operator">&gt;</span> <span class="Identifier">count</span><span class="Punctuation">(</span><span class="Identifier">q</span><span class="Punctuation">,</span> <span class="Identifier">m</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Keyword">return</span> <span class="Identifier">true</span>
  <span class="Keyword">elif</span> <span class="Identifier">count</span><span class="Punctuation">(</span><span class="Identifier">p</span><span class="Punctuation">,</span> <span class="Identifier">m</span><span class="Punctuation">)</span> <span class="Operator">==</span> <span class="Identifier">count</span><span class="Punctuation">(</span><span class="Identifier">q</span><span class="Punctuation">,</span> <span class="Identifier">m</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
    <span class="Keyword">discard</span> <span class="StringLit">&quot;continue with next category m&quot;</span>
  <span class="Keyword">else</span><span class="Punctuation">:</span>
    <span class="Keyword">return</span> <span class="Identifier">false</span>
<span class="Keyword">return</span> <span class="StringLit">&quot;ambiguous&quot;</span></pre></p>

<h2><a class="toc-backref" id="overload-resolution-second-trialcolon-hierarchical-order-comparison" href="#overload-resolution-second-trialcolon-hierarchical-order-comparison">Second Trial: Hierarchical Order Comparison</a></h2><p>The hierarchical order of a type is analogous to its relative specificity. Consider the type defined:</p>
<p><pre class="listing"><span class="Keyword">type</span> <span class="Identifier">A</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Keyword">object</span></pre></p>
<p>Matching formals for this type include <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">object</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Identifier">A</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Identifier">A</span><span class="Punctuation">[</span><span class="Operator">...</span><span class="Punctuation">]</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">A</span><span class="Punctuation">[</span><span class="Identifier">C</span><span class="Punctuation">]</span></span></tt> where <tt class="docutils literal"><span class="pre"><span class="Identifier">C</span></span></tt> is a concrete type, <tt class="docutils literal"><span class="pre"><span class="Identifier">A</span><span class="Punctuation">[</span><span class="Operator">...</span><span class="Punctuation">]</span></span></tt> is a generic typeclass composition and <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span></span></tt> is an unconstrained generic type variable. This list is in order of specificity with respect to <tt class="docutils literal"><span class="pre"><span class="Identifier">A</span></span></tt> as each subsequent category narrows the set of types that are members of their match set.</p>
<p>In this trial, the formal parameters of candidates are compared in order (1st parameter, 2nd parameter, etc.) to search for a candidate that has an unrivaled specificity. If such a formal parameter is found, the candidate it belongs to is chosen as the resolved symbol.</p>

<h2><a class="toc-backref" id="overload-resolution-third-trialcolon-complexity-analysis" href="#overload-resolution-third-trialcolon-complexity-analysis">Third Trial: Complexity Analysis</a></h2><p>A slight clarification: While category matching digests all the formal parameters of a candidate at once (order doesn't matter), specificity comparison and complexity analysis operate on each formal parameter at a time. The following is the final trial to disambiguate a symbol choice when a pair of formal parameters have the same hierarchical order.</p>
<p>The complexity of a type is essentially its number of modifiers and depth of shape. The definition with the <em>highest</em> complexity wins. Consider the following types:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">A</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Keyword">object</span>
  <span class="Identifier">B</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">,</span> <span class="Identifier">H</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Keyword">object</span></pre></p>
<p>Note: The below examples are not exhaustive.</p>
<p>We shall say that:</p>
<ol class="simple"><li><tt class="docutils literal"><span class="pre"><span class="Identifier">A</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span></span></tt> has a higher complexity than <tt class="docutils literal"><span class="pre"><span class="Identifier">A</span></span></tt></li>
<li><tt class="docutils literal"><span class="pre"><span class="Keyword">var</span> <span class="Identifier">A</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span></span></tt> has a higher complexity than <tt class="docutils literal"><span class="pre"><span class="Identifier">A</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span></span></tt></li>
<li><tt class="docutils literal"><span class="pre"><span class="Identifier">A</span><span class="Punctuation">[</span><span class="Identifier">A</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">]</span></span></tt> has a higher complexity than <tt class="docutils literal"><span class="pre"><span class="Identifier">A</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span></span></tt></li>
<li><tt class="docutils literal"><span class="pre"><span class="Identifier">B</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">,</span> <span class="Identifier">H</span><span class="Punctuation">]</span></span></tt> has a higher complexity than <tt class="docutils literal"><span class="pre"><span class="Identifier">A</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span></span></tt> (<tt class="docutils literal"><span class="pre"><span class="Identifier">A</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">B</span></span></tt> are not compatible here, but convoluted versions of this exist)</li>
<li><tt class="docutils literal"><span class="pre"><span class="Identifier">B</span><span class="Punctuation">[</span><span class="Keyword">ptr</span> <span class="Identifier">T</span><span class="Punctuation">,</span> <span class="Identifier">H</span><span class="Punctuation">]</span></span></tt> has a higher complexity than <tt class="docutils literal"><span class="pre"><span class="Identifier">B</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">,</span> <span class="Identifier">H</span><span class="Punctuation">]</span></span></tt></li>
</ol>

<h2><a class="toc-backref" id="overload-resolution-some-examples" href="#overload-resolution-some-examples">Some Examples</a></h2><p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">takesInt</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Identifier">echo</span> <span class="StringLit">&quot;int&quot;</span>
<span class="Keyword">proc</span> <span class="Identifier">takesInt</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Identifier">echo</span> <span class="StringLit">&quot;T&quot;</span>
<span class="Keyword">proc</span> <span class="Identifier">takesInt</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">int16</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Identifier">echo</span> <span class="StringLit">&quot;int16&quot;</span>

<span class="Identifier">takesInt</span><span class="Punctuation">(</span><span class="DecNumber">4</span><span class="Punctuation">)</span> <span class="Comment"># &quot;int&quot;</span>
<span class="Keyword">var</span> <span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">int32</span>
<span class="Identifier">takesInt</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span> <span class="Comment"># &quot;T&quot;</span>
<span class="Keyword">var</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">int16</span>
<span class="Identifier">takesInt</span><span class="Punctuation">(</span><span class="Identifier">y</span><span class="Punctuation">)</span> <span class="Comment"># &quot;int16&quot;</span>
<span class="Keyword">var</span> <span class="Identifier">z</span><span class="Punctuation">:</span> <span class="Identifier">range</span><span class="Punctuation">[</span><span class="FloatNumber">0.</span><span class="Operator">.</span><span class="DecNumber">4</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="DecNumber">0</span>
<span class="Identifier">takesInt</span><span class="Punctuation">(</span><span class="Identifier">z</span><span class="Punctuation">)</span> <span class="Comment"># &quot;T&quot;</span></pre></p>
<p>If the argument <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span></span></tt> matches both the parameter type <tt class="docutils literal"><span class="pre"><span class="Identifier">f</span></span></tt> of <tt class="docutils literal"><span class="pre"><span class="Identifier">p</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">g</span></span></tt> of <tt class="docutils literal"><span class="pre"><span class="Identifier">q</span></span></tt> via a subtyping relation, the inheritance depth is taken into account:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">A</span> <span class="Operator">=</span> <span class="Keyword">object</span> <span class="Keyword">of</span> <span class="Identifier">RootObj</span>
  <span class="Identifier">B</span> <span class="Operator">=</span> <span class="Keyword">object</span> <span class="Keyword">of</span> <span class="Identifier">A</span>
  <span class="Identifier">C</span> <span class="Operator">=</span> <span class="Keyword">object</span> <span class="Keyword">of</span> <span class="Identifier">B</span>

<span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Identifier">obj</span><span class="Punctuation">:</span> <span class="Identifier">A</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;A&quot;</span>

<span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Identifier">obj</span><span class="Punctuation">:</span> <span class="Identifier">B</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;B&quot;</span>

<span class="Keyword">var</span> <span class="Identifier">c</span> <span class="Operator">=</span> <span class="Identifier">C</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
<span class="Comment"># not ambiguous, calls 'B', not 'A' since B is a subtype of A</span>
<span class="Comment"># but not vice versa:</span>
<span class="Identifier">p</span><span class="Punctuation">(</span><span class="Identifier">c</span><span class="Punctuation">)</span>

<span class="Keyword">proc</span> <span class="Identifier">pp</span><span class="Punctuation">(</span><span class="Identifier">obj</span><span class="Punctuation">:</span> <span class="Identifier">A</span><span class="Punctuation">,</span> <span class="Identifier">obj2</span><span class="Punctuation">:</span> <span class="Identifier">B</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Identifier">echo</span> <span class="StringLit">&quot;A B&quot;</span>
<span class="Keyword">proc</span> <span class="Identifier">pp</span><span class="Punctuation">(</span><span class="Identifier">obj</span><span class="Punctuation">:</span> <span class="Identifier">B</span><span class="Punctuation">,</span> <span class="Identifier">obj2</span><span class="Punctuation">:</span> <span class="Identifier">A</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Identifier">echo</span> <span class="StringLit">&quot;B A&quot;</span>

<span class="Comment"># but this is ambiguous:</span>
<span class="Identifier">pp</span><span class="Punctuation">(</span><span class="Identifier">c</span><span class="Punctuation">,</span> <span class="Identifier">c</span><span class="Punctuation">)</span></pre></p>
<p>Likewise, for generic matches, the most specialized generic type (that still matches) is preferred:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">gen</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Keyword">ref</span> <span class="Keyword">ref</span> <span class="Identifier">T</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Identifier">echo</span> <span class="StringLit">&quot;ref ref T&quot;</span>
<span class="Keyword">proc</span> <span class="Identifier">gen</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Keyword">ref</span> <span class="Identifier">T</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Identifier">echo</span> <span class="StringLit">&quot;ref T&quot;</span>
<span class="Keyword">proc</span> <span class="Identifier">gen</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Identifier">echo</span> <span class="StringLit">&quot;T&quot;</span>

<span class="Keyword">var</span> <span class="Identifier">ri</span><span class="Punctuation">:</span> <span class="Keyword">ref</span> <span class="Identifier">int</span>
<span class="Identifier">gen</span><span class="Punctuation">(</span><span class="Identifier">ri</span><span class="Punctuation">)</span> <span class="Comment"># &quot;ref T&quot;</span></pre></p>

<h2><a class="toc-backref" id="overload-resolution-type-variables-match" href="#overload-resolution-type-variables-match">Type variables match</a></h2><p>When overload resolution is considering candidates, the type variable's definition is not overlooked as it is used to define the formal parameter's type via variable substitution.</p>
<p>For example:</p>
<p><pre class="listing"><span class="Keyword">type</span> <span class="Identifier">A</span>
<span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">:</span> <span class="Identifier">A</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">param</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">)</span>
<span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">:</span> <span class="Keyword">object</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">param</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">)</span></pre></p>
<p>These signatures are not ambiguous for a concrete type of <tt class="docutils literal"><span class="pre"><span class="Identifier">A</span></span></tt> even though the formal parameters match (&quot;T&quot; == &quot;T&quot;). Instead <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span></span></tt> is treated as a variable in that (<tt class="docutils literal"><span class="pre"><span class="Identifier">T</span></span></tt> ?= <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span></span></tt>) depending on the bound type of <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span></span></tt> at the time of overload resolution.</p>

<h2><a class="toc-backref" id="overload-resolution-overloading-based-on-var-t" href="#overload-resolution-overloading-based-on-var-t">Overloading based on 'var T'</a></h2><p>If the formal parameter <tt class="docutils literal"><span class="pre"><span class="Identifier">f</span></span></tt> is of type <tt class="docutils literal"><span class="pre"><span class="Keyword">var</span> <span class="Identifier">T</span></span></tt> in addition to the ordinary type checking, the argument is checked to be an <span id="lminusvalue_1">l-value</span>. <tt class="docutils literal"><span class="pre"><span class="Keyword">var</span> <span class="Identifier">T</span></span></tt> matches better than just <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span></span></tt> then.</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">sayHi</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">string</span> <span class="Operator">=</span>
  <span class="Comment"># matches a non-var int</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Operator">$</span><span class="Identifier">x</span>
<span class="Keyword">proc</span> <span class="Identifier">sayHi</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">string</span> <span class="Operator">=</span>
  <span class="Comment"># matches a var int</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Operator">$</span><span class="Punctuation">(</span><span class="Identifier">x</span> <span class="Operator">+</span> <span class="DecNumber">10</span><span class="Punctuation">)</span>

<span class="Keyword">proc</span> <span class="Identifier">sayHello</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">var</span> <span class="Identifier">m</span> <span class="Operator">=</span> <span class="Identifier">x</span> <span class="Comment"># a mutable version of x</span>
  <span class="Identifier">echo</span> <span class="Identifier">sayHi</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span> <span class="Comment"># matches the non-var version of sayHi</span>
  <span class="Identifier">echo</span> <span class="Identifier">sayHi</span><span class="Punctuation">(</span><span class="Identifier">m</span><span class="Punctuation">)</span> <span class="Comment"># matches the var version of sayHi</span>

<span class="Identifier">sayHello</span><span class="Punctuation">(</span><span class="DecNumber">3</span><span class="Punctuation">)</span> <span class="Comment"># 3</span>
            <span class="Comment"># 13</span></pre></p>

<h2><a class="toc-backref" id="overload-resolution-lazy-type-resolution-for-untyped" href="#overload-resolution-lazy-type-resolution-for-untyped">Lazy type resolution for untyped</a></h2><p><strong>Note</strong>: An <span id="unresolved_1">unresolved</span> expression is an expression for which no symbol lookups and no type checking have been performed.</p>
<p>Since templates and macros that are not declared as <tt class="docutils literal"><span class="pre"><span class="Identifier">immediate</span></span></tt> participate in overloading resolution, it's essential to have a way to pass unresolved expressions to a template or macro. This is what the meta-type <tt class="docutils literal"><span class="pre"><span class="Identifier">untyped</span></span></tt> accomplishes:</p>
<p><pre class="listing"><span class="Keyword">template</span> <span class="Identifier">rem</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">untyped</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Keyword">discard</span>

<span class="Identifier">rem</span> <span class="Identifier">unresolvedExpression</span><span class="Punctuation">(</span><span class="Identifier">undeclaredIdentifier</span><span class="Punctuation">)</span></pre></p>
<p>A parameter of type <tt class="docutils literal"><span class="pre"><span class="Identifier">untyped</span></span></tt> always matches any argument (as long as there is any argument passed to it).</p>
<p>But one has to watch out because other overloads might trigger the argument's resolution:</p>
<p><pre class="listing"><span class="Keyword">template</span> <span class="Identifier">rem</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">untyped</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Keyword">discard</span>
<span class="Keyword">proc</span> <span class="Identifier">rem</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Keyword">discard</span>

<span class="Comment"># undeclared identifier: 'unresolvedExpression'</span>
<span class="Identifier">rem</span> <span class="Identifier">unresolvedExpression</span><span class="Punctuation">(</span><span class="Identifier">undeclaredIdentifier</span><span class="Punctuation">)</span></pre></p>
<p><tt class="docutils literal"><span class="pre"><span class="Identifier">untyped</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">varargs</span><span class="Punctuation">[</span><span class="Identifier">untyped</span><span class="Punctuation">]</span></span></tt> are the only metatype that are lazy in this sense, the other metatypes <tt class="docutils literal"><span class="pre"><span class="Identifier">typed</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">typedesc</span></span></tt> are not lazy.</p>

<h2><a class="toc-backref" id="overload-resolution-varargs-matching" href="#overload-resolution-varargs-matching">Varargs matching</a></h2><p>See <a class="reference internal" href="#types-varargs">Varargs</a>.</p>

<h2><a class="toc-backref" id="overload-resolution-iterable" href="#overload-resolution-iterable">iterable</a></h2><p>A called <tt class="docutils literal"><span class="pre"><span class="Keyword">iterator</span></span></tt> yielding type <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span></span></tt> can be passed to a template or macro via a parameter typed as <tt class="docutils literal"><span class="pre"><span class="Identifier">untyped</span></span></tt> (for unresolved expressions) or the type class <tt class="docutils literal"><span class="pre"><span class="Identifier">iterable</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Identifier">iterable</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span></span></tt> (after type checking and overload resolution).</p>
<p><pre class="listing"><span class="Keyword">iterator</span> <span class="Identifier">iota</span><span class="Punctuation">(</span><span class="Identifier">n</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span>
  <span class="Keyword">for</span> <span class="Identifier">i</span> <span class="Keyword">in</span> <span class="FloatNumber">0.</span><span class="Operator">.&lt;</span><span class="Identifier">n</span><span class="Punctuation">:</span> <span class="Keyword">yield</span> <span class="Identifier">i</span>

<span class="Keyword">template</span> <span class="Identifier">toSeq2</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">iterable</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span> <span class="Operator">=</span>
  <span class="Keyword">var</span> <span class="Identifier">ret</span><span class="Punctuation">:</span> <span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span>
  <span class="Identifier">assert</span> <span class="Identifier">a</span><span class="Operator">.</span><span class="Identifier">typeof</span> <span class="Keyword">is</span> <span class="Identifier">T</span>
  <span class="Keyword">for</span> <span class="Identifier">ai</span> <span class="Keyword">in</span> <span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">ret</span><span class="Operator">.</span><span class="Identifier">add</span> <span class="Identifier">ai</span>
  <span class="Identifier">ret</span>

<span class="Identifier">assert</span> <span class="Identifier">iota</span><span class="Punctuation">(</span><span class="DecNumber">3</span><span class="Punctuation">)</span><span class="Operator">.</span><span class="Identifier">toSeq2</span> <span class="Operator">==</span> <span class="Operator">@</span><span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">,</span> <span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="DecNumber">2</span><span class="Punctuation">]</span>
<span class="Identifier">assert</span> <span class="Identifier">toSeq2</span><span class="Punctuation">(</span><span class="FloatNumber">5.</span><span class="Operator">.</span><span class="DecNumber">7</span><span class="Punctuation">)</span> <span class="Operator">==</span> <span class="Operator">@</span><span class="Punctuation">[</span><span class="DecNumber">5</span><span class="Punctuation">,</span> <span class="DecNumber">6</span><span class="Punctuation">,</span> <span class="DecNumber">7</span><span class="Punctuation">]</span>
<span class="Identifier">assert</span> <span class="Keyword">not</span> <span class="Identifier">compiles</span><span class="Punctuation">(</span><span class="Identifier">toSeq2</span><span class="Punctuation">(</span><span class="Operator">@</span><span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">,</span><span class="DecNumber">2</span><span class="Punctuation">]</span><span class="Punctuation">)</span><span class="Punctuation">)</span> <span class="Comment"># seq[int] is not an iterable</span>
<span class="Identifier">assert</span> <span class="Identifier">toSeq2</span><span class="Punctuation">(</span><span class="Identifier">items</span><span class="Punctuation">(</span><span class="Operator">@</span><span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">,</span><span class="DecNumber">2</span><span class="Punctuation">]</span><span class="Punctuation">)</span><span class="Punctuation">)</span> <span class="Operator">==</span> <span class="Operator">@</span><span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="DecNumber">2</span><span class="Punctuation">]</span> <span class="Comment"># but items(@[1,2]) is</span></pre></p>

<h1><a class="toc-backref" id="overload-disambiguation" href="#overload-disambiguation">Overload disambiguation</a></h1><p>For routine calls &quot;overload resolution&quot; is performed. There is a weaker form of overload resolution called <em>overload disambiguation</em> that is performed when an overloaded symbol is used in a context where there is additional type information available. Let <tt class="docutils literal"><span class="pre"><span class="Identifier">p</span></span></tt> be an overloaded symbol. These contexts are:</p>
<ul class="simple"><li>In a function call <tt class="docutils literal"><span class="pre"><span class="Identifier">q</span><span class="Punctuation">(</span><span class="Operator">...</span><span class="Punctuation">,</span> <span class="Identifier">p</span><span class="Punctuation">,</span> <span class="Operator">...</span><span class="Punctuation">)</span></span></tt> when the corresponding formal parameter of <tt class="docutils literal"><span class="pre"><span class="Identifier">q</span></span></tt> is a <tt class="docutils literal"><span class="pre"><span class="Keyword">proc</span></span></tt> type. If <tt class="docutils literal"><span class="pre"><span class="Identifier">q</span></span></tt> itself is overloaded then the cartesian product of every interpretation of <tt class="docutils literal"><span class="pre"><span class="Identifier">q</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">p</span></span></tt> must be considered.</li>
<li>In an object constructor <tt class="docutils literal"><span class="pre"><span class="Identifier">Obj</span><span class="Punctuation">(</span><span class="Operator">...</span><span class="Punctuation">,</span> <span class="Identifier">field</span><span class="Punctuation">:</span> <span class="Identifier">p</span><span class="Punctuation">,</span> <span class="Operator">...</span><span class="Punctuation">)</span></span></tt> when <tt class="docutils literal"><span class="pre"><span class="Identifier">field</span></span></tt> is a <tt class="docutils literal"><span class="pre"><span class="Keyword">proc</span></span></tt> type. Analogous rules exist for array/set/tuple constructors.</li>
<li>In a declaration like <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">T</span> <span class="Operator">=</span> <span class="Identifier">p</span></span></tt> when <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span></span></tt> is a <tt class="docutils literal"><span class="pre"><span class="Keyword">proc</span></span></tt> type.</li>
</ul>
<p>As usual, ambiguous matches produce a compile-time error.</p>

<h2><a class="toc-backref" id="overload-disambiguation-named-argument-overloading" href="#overload-disambiguation-named-argument-overloading">Named argument overloading</a></h2><p>Routines with the same type signature can be called individually if a parameter has different names between them.</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">foo</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;Using x: &quot;</span><span class="Punctuation">,</span> <span class="Identifier">x</span>
<span class="Keyword">proc</span> <span class="Identifier">foo</span><span class="Punctuation">(</span><span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;Using y: &quot;</span><span class="Punctuation">,</span> <span class="Identifier">y</span>

<span class="Identifier">foo</span><span class="Punctuation">(</span><span class="Identifier">x</span> <span class="Operator">=</span> <span class="DecNumber">2</span><span class="Punctuation">)</span> <span class="Comment"># Using x: 2</span>
<span class="Identifier">foo</span><span class="Punctuation">(</span><span class="Identifier">y</span> <span class="Operator">=</span> <span class="DecNumber">2</span><span class="Punctuation">)</span> <span class="Comment"># Using y: 2</span></pre></p>
<p>Not supplying the parameter name in such cases results in an ambiguity error.</p>

<h1><a class="toc-backref" id="statements-and-expressions" href="#statements-and-expressions">Statements and expressions</a></h1><p>Nim uses the common statement/expression paradigm: Statements do not produce a value in contrast to expressions. However, some expressions are statements.</p>
<p>Statements are separated into <span id="simple-statements_1">simple statements</span> and <span id="complex-statements_1">complex statements</span>. Simple statements are statements that cannot contain other statements like assignments, calls, or the <tt class="docutils literal"><span class="pre"><span class="Keyword">return</span></span></tt> statement; complex statements can contain other statements. To avoid the <span id="dangling-else-problem_1">dangling else problem</span>, complex statements always have to be indented. The details can be found in the grammar.</p>

<h2><a class="toc-backref" id="statements-and-expressions-statement-list-expression" href="#statements-and-expressions-statement-list-expression">Statement list expression</a></h2><p>Statements can also occur in an expression context that looks like <tt class="docutils literal"><span class="pre"><span class="Punctuation">(</span><span class="Identifier">stmt1</span><span class="Punctuation">;</span> <span class="Identifier">stmt2</span><span class="Punctuation">;</span> <span class="Operator">...</span><span class="Punctuation">;</span> <span class="Identifier">ex</span><span class="Punctuation">)</span></span></tt>. This is called a statement list expression or <tt class="docutils literal"><span class="pre"><span class="Punctuation">(</span><span class="Punctuation">;</span><span class="Punctuation">)</span></span></tt>. The type of <tt class="docutils literal"><span class="pre"><span class="Punctuation">(</span><span class="Identifier">stmt1</span><span class="Punctuation">;</span> <span class="Identifier">stmt2</span><span class="Punctuation">;</span> <span class="Operator">...</span><span class="Punctuation">;</span> <span class="Identifier">ex</span><span class="Punctuation">)</span></span></tt> is the type of <tt class="docutils literal"><span class="pre"><span class="Identifier">ex</span></span></tt>. All the other statements must be of type <tt class="docutils literal"><span class="pre"><span class="Identifier">void</span></span></tt>. (One can use <tt class="docutils literal"><span class="pre"><span class="Keyword">discard</span></span></tt> to produce a <tt class="docutils literal"><span class="pre"><span class="Identifier">void</span></span></tt> type.) <tt class="docutils literal"><span class="pre"><span class="Punctuation">(</span><span class="Punctuation">;</span><span class="Punctuation">)</span></span></tt> does not introduce a new scope.</p>

<h2><a class="toc-backref" id="statements-and-expressions-discard-statement" href="#statements-and-expressions-discard-statement">Discard statement</a></h2><p>Example:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">x</span> <span class="Operator">+</span> <span class="Identifier">y</span>

<span class="Keyword">discard</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="DecNumber">3</span><span class="Punctuation">,</span> <span class="DecNumber">4</span><span class="Punctuation">)</span> <span class="Comment"># discard the return value of `p`</span></pre></p>
<p>The <tt class="docutils literal"><span class="pre"><span class="Keyword">discard</span></span></tt> statement evaluates its expression for side-effects and throws the expression's resulting value away, and should only be used when ignoring this value is known not to cause problems.</p>
<p>Ignoring the return value of a procedure without using a discard statement is a static error.</p>
<p>The return value can be ignored implicitly if the called proc/iterator has been declared with the <span id="discardable_1">discardable</span> pragma:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">discardable</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">x</span> <span class="Operator">+</span> <span class="Identifier">y</span>

<span class="Identifier">p</span><span class="Punctuation">(</span><span class="DecNumber">3</span><span class="Punctuation">,</span> <span class="DecNumber">4</span><span class="Punctuation">)</span> <span class="Comment"># now valid</span></pre></p>
<p>however the discardable pragma does not work on templates as templates substitute the AST in place. For example:</p>
<p><pre class="listing"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">push</span> <span class="Identifier">discardable</span> <span class="Operator">.</span><span class="Punctuation">}</span>
<span class="Keyword">template</span> <span class="Identifier">example</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">string</span> <span class="Operator">=</span> <span class="StringLit">&quot;https://nim-lang.org&quot;</span>
<span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">pop</span><span class="Operator">.</span><span class="Punctuation">}</span>

<span class="Identifier">example</span><span class="Punctuation">(</span><span class="Punctuation">)</span></pre></p>
<p>This template will resolve into &quot;<a class="reference external" href="https://nim-lang.org">https://nim-lang.org</a>&quot; which is a string literal and since {.discardable.} doesn't apply to literals, the compiler will error.</p>
<p>An empty <tt class="docutils literal"><span class="pre"><span class="Keyword">discard</span></span></tt> statement is often used as a null statement:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">classify</span><span class="Punctuation">(</span><span class="Identifier">s</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">case</span> <span class="Identifier">s</span><span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">]</span>
  <span class="Keyword">of</span> <span class="Identifier">SymChars</span><span class="Punctuation">,</span> <span class="CharLit">'_'</span><span class="Punctuation">:</span> <span class="Identifier">echo</span> <span class="StringLit">&quot;an identifier&quot;</span>
  <span class="Keyword">of</span> <span class="CharLit">'0'</span><span class="Operator">..</span><span class="CharLit">'9'</span><span class="Punctuation">:</span> <span class="Identifier">echo</span> <span class="StringLit">&quot;a number&quot;</span>
  <span class="Keyword">else</span><span class="Punctuation">:</span> <span class="Keyword">discard</span></pre></p>

<h2><a class="toc-backref" id="statements-and-expressions-void-context" href="#statements-and-expressions-void-context">Void context</a></h2><p>In a list of statements, every expression except the last one needs to have the type <tt class="docutils literal"><span class="pre"><span class="Identifier">void</span></span></tt>. In addition to this rule an assignment to the builtin <tt class="docutils literal"><span class="pre"><span class="Identifier">result</span></span></tt> symbol also triggers a mandatory <tt class="docutils literal"><span class="pre"><span class="Identifier">void</span></span></tt> context for the subsequent expressions:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">invalid</span><span class="Operator">*</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">string</span> <span class="Operator">=</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="StringLit">&quot;foo&quot;</span>
  <span class="StringLit">&quot;invalid&quot;</span>  <span class="Comment"># Error: value of type 'string' has to be discarded</span></pre></p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">valid</span><span class="Operator">*</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">string</span> <span class="Operator">=</span>
  <span class="Keyword">let</span> <span class="Identifier">x</span> <span class="Operator">=</span> <span class="DecNumber">317</span>
  <span class="StringLit">&quot;valid&quot;</span></pre></p>

<h2><a class="toc-backref" id="statements-and-expressions-var-statement" href="#statements-and-expressions-var-statement">Var statement</a></h2><p>Var statements declare new local and global variables and initialize them. A comma-separated list of variables can be used to specify variables of the same type:</p>
<p><pre class="listing"><span class="Keyword">var</span>
  <span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span> <span class="DecNumber">0</span>
  <span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">,</span> <span class="Identifier">z</span><span class="Punctuation">:</span> <span class="Identifier">int</span></pre></p>
<p>If an initializer is given, the type can be omitted: the variable is then of the same type as the initializing expression. Variables are always initialized with a default value if there is no initializing expression. The default value depends on the type and is always a zero in binary.</p>
<table border="1" class="docutils"><tr><th>Type</th><th>default value</th></tr>
<tr><td>any integer type</td><td>0</td></tr>
<tr><td>any float</td><td>0.0</td></tr>
<tr><td>char</td><td>'\0'</td></tr>
<tr><td>bool</td><td>false</td></tr>
<tr><td>ref or pointer type</td><td>nil</td></tr>
<tr><td>procedural type</td><td>nil</td></tr>
<tr><td>sequence</td><td><tt class="docutils literal"><span class="pre"><span class="Operator">@</span><span class="Punctuation">[</span><span class="Punctuation">]</span></span></tt></td></tr>
<tr><td>string</td><td><tt class="docutils literal"><span class="pre"><span class="StringLit">&quot;&quot;</span></span></tt></td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Keyword">tuple</span><span class="Punctuation">[</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">A</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">B</span><span class="Punctuation">,</span> <span class="Operator">...</span><span class="Punctuation">]</span></span></tt></td><td>(zeroDefault(A), zeroDefault(B), ...) (analogous for objects)</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">array</span><span class="Punctuation">[</span><span class="FloatNumber">0.</span><span class="Operator">..</span><span class="Punctuation">,</span> <span class="Identifier">T</span><span class="Punctuation">]</span></span></tt></td><td><tt class="docutils literal"><span class="pre"><span class="Punctuation">[</span><span class="Identifier">zeroDefault</span><span class="Punctuation">(</span><span class="Identifier">T</span><span class="Punctuation">)</span><span class="Punctuation">,</span> <span class="Operator">...</span><span class="Punctuation">]</span></span></tt></td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">range</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span></span></tt></td><td>default(T); this may be out of the valid range</td></tr>
<tr><td>T = enum</td><td><tt class="docutils literal"><span class="pre"><span class="Keyword">cast</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="DecNumber">0</span><span class="Punctuation">)</span></span></tt>; this may be an invalid value</td></tr>
</table><p>The implicit initialization can be avoided for optimization reasons with the <span id="noinit_1">noinit</span> pragma:</p>
<p><pre class="listing"><span class="Keyword">var</span>
  <span class="Identifier">a</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">noinit</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span> <span class="Identifier">array</span><span class="Punctuation">[</span><span class="FloatNumber">0.</span><span class="Operator">.</span><span class="DecNumber">1023</span><span class="Punctuation">,</span> <span class="Identifier">char</span><span class="Punctuation">]</span></pre></p>
<p>If a proc is annotated with the <tt class="docutils literal"><span class="pre"><span class="Identifier">noinit</span></span></tt> pragma, this refers to its implicit <tt class="docutils literal"><span class="pre"><span class="Identifier">result</span></span></tt> variable:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">returnUndefinedValue</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">noinit</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">discard</span></pre></p>
<p>The implicit initialization can also be prevented by the <span id="requiresinit_1">requiresInit</span> type pragma. The compiler requires an explicit initialization for the object and all of its fields. However, it does a <span id="control-flow-analysis_1">control flow analysis</span> to prove the variable has been initialized and does not rely on syntactic properties:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">MyObject</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">requiresInit</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">object</span>

<span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Comment"># the following is valid:</span>
  <span class="Keyword">var</span> <span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">MyObject</span>
  <span class="Keyword">if</span> <span class="Identifier">someCondition</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
    <span class="Identifier">x</span> <span class="Operator">=</span> <span class="Identifier">a</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
  <span class="Keyword">else</span><span class="Punctuation">:</span>
    <span class="Identifier">x</span> <span class="Operator">=</span> <span class="Identifier">a</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
  <span class="Comment"># use x</span></pre></p>
<p><tt class="docutils literal"><span class="pre"><span class="Identifier">requiresInit</span></span></tt> pragma can also be applied to <tt class="docutils literal"><span class="pre"><span class="Keyword">distinct</span></span></tt> types.</p>
<p>Given the following distinct type definitions:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">Foo</span> <span class="Operator">=</span> <span class="Keyword">object</span>
    <span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">string</span>
  
  <span class="Identifier">DistinctFoo</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">requiresInit</span><span class="Punctuation">,</span> <span class="Identifier">borrow</span><span class="Punctuation">:</span> <span class="Punctuation">`</span><span class="Operator">.</span><span class="Punctuation">`</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">distinct</span> <span class="Identifier">Foo</span>
  <span class="Identifier">DistinctString</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">requiresInit</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">distinct</span> <span class="Identifier">string</span></pre></p>
<p>The following code blocks will fail to compile:</p>
<p><pre class="listing"><span class="Keyword">var</span> <span class="Identifier">foo</span><span class="Punctuation">:</span> <span class="Identifier">DistinctFoo</span>
<span class="Identifier">foo</span><span class="Operator">.</span><span class="Identifier">x</span> <span class="Operator">=</span> <span class="StringLit">&quot;test&quot;</span>
<span class="Identifier">doAssert</span> <span class="Identifier">foo</span><span class="Operator">.</span><span class="Identifier">x</span> <span class="Operator">==</span> <span class="StringLit">&quot;test&quot;</span></pre></p>
<p><pre class="listing"><span class="Keyword">var</span> <span class="Identifier">s</span><span class="Punctuation">:</span> <span class="Identifier">DistinctString</span>
<span class="Identifier">s</span> <span class="Operator">=</span> <span class="StringLit">&quot;test&quot;</span>
<span class="Identifier">doAssert</span> <span class="Identifier">string</span><span class="Punctuation">(</span><span class="Identifier">s</span><span class="Punctuation">)</span> <span class="Operator">==</span> <span class="StringLit">&quot;test&quot;</span></pre></p>
<p>But these will compile successfully:</p>
<p><pre class="listing"><span class="Keyword">let</span> <span class="Identifier">foo</span> <span class="Operator">=</span> <span class="Identifier">DistinctFoo</span><span class="Punctuation">(</span><span class="Identifier">Foo</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="StringLit">&quot;test&quot;</span><span class="Punctuation">)</span><span class="Punctuation">)</span>
<span class="Identifier">doAssert</span> <span class="Identifier">foo</span><span class="Operator">.</span><span class="Identifier">x</span> <span class="Operator">==</span> <span class="StringLit">&quot;test&quot;</span></pre></p>
<p><pre class="listing"><span class="Keyword">let</span> <span class="Identifier">s</span> <span class="Operator">=</span> <span class="Identifier">DistinctString</span><span class="Punctuation">(</span><span class="StringLit">&quot;test&quot;</span><span class="Punctuation">)</span>
<span class="Identifier">doAssert</span> <span class="Identifier">string</span><span class="Punctuation">(</span><span class="Identifier">s</span><span class="Punctuation">)</span> <span class="Operator">==</span> <span class="StringLit">&quot;test&quot;</span></pre></p>

<h2><a class="toc-backref" id="statements-and-expressions-let-statement" href="#statements-and-expressions-let-statement">Let statement</a></h2><p>A <tt class="docutils literal"><span class="pre"><span class="Keyword">let</span></span></tt> statement declares new local and global <span id="single-assignment_1">single assignment</span> variables and binds a value to them. The syntax is the same as that of the <tt class="docutils literal"><span class="pre"><span class="Keyword">var</span></span></tt> statement, except that the keyword <tt class="docutils literal"><span class="pre"><span class="Keyword">var</span></span></tt> is replaced by the keyword <tt class="docutils literal"><span class="pre"><span class="Keyword">let</span></span></tt>. Let variables are not l-values and can thus not be passed to <tt class="docutils literal"><span class="pre"><span class="Keyword">var</span></span></tt> parameters nor can their address be taken. They cannot be assigned new values.</p>
<p>For let variables, the same pragmas are available as for ordinary variables.</p>
<p>As <tt class="docutils literal"><span class="pre"><span class="Keyword">let</span></span></tt> statements are immutable after creation they need to define a value when they are declared. The only exception to this is if the <tt class="docutils literal"><span class="pre"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importc</span><span class="Operator">.</span><span class="Punctuation">}</span></span></tt> pragma (or any of the other <tt class="docutils literal"><span class="pre"><span class="Identifier">importX</span></span></tt> pragmas) is applied, in this case the value is expected to come from native code, typically a C/C++ <tt class="docutils literal"><span class="pre"><span class="Keyword">const</span></span></tt>.</p>

<h2><a class="toc-backref" id="statements-and-expressions-special-identifier-nim-underscore" href="#statements-and-expressions-special-identifier-nim-underscore">Special identifier <tt class="docutils literal"><span class="pre"><span class="Identifier">_</span></span></tt> (underscore)</a></h2><p>The identifier <tt class="docutils literal"><span class="pre"><span class="Identifier">_</span></span></tt> has a special meaning in declarations. Any definition with the name <tt class="docutils literal"><span class="pre"><span class="Identifier">_</span></span></tt> will not be added to scope, meaning the definition is evaluated, but cannot be used. As a result the name <tt class="docutils literal"><span class="pre"><span class="Identifier">_</span></span></tt> can be indefinitely redefined.</p>
<p><pre class="listing"><span class="Keyword">let</span> <span class="Identifier">_</span> <span class="Operator">=</span> <span class="DecNumber">123</span>
<span class="Identifier">echo</span> <span class="Identifier">_</span> <span class="Comment"># error</span>
<span class="Keyword">let</span> <span class="Identifier">_</span> <span class="Operator">=</span> <span class="DecNumber">456</span> <span class="Comment"># compiles</span></pre></p>

<h2><a class="toc-backref" id="statements-and-expressions-tuple-unpacking" href="#statements-and-expressions-tuple-unpacking">Tuple unpacking</a></h2><p>In a <tt class="docutils literal"><span class="pre"><span class="Keyword">var</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">let</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Keyword">const</span></span></tt> statement tuple unpacking can be performed. The special identifier <tt class="docutils literal"><span class="pre"><span class="Identifier">_</span></span></tt> can be used to ignore some parts of the tuple:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">returnsTuple</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Punctuation">(</span><span class="Identifier">int</span><span class="Punctuation">,</span> <span class="Identifier">int</span><span class="Punctuation">,</span> <span class="Identifier">int</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Punctuation">(</span><span class="DecNumber">4</span><span class="Punctuation">,</span> <span class="DecNumber">2</span><span class="Punctuation">,</span> <span class="DecNumber">3</span><span class="Punctuation">)</span>

<span class="Keyword">let</span> <span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">_</span><span class="Punctuation">,</span> <span class="Identifier">z</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Identifier">returnsTuple</span><span class="Punctuation">(</span><span class="Punctuation">)</span></pre></p>
<p>This is treated as syntax sugar for roughly the following:</p>
<p><pre class="listing"><span class="Keyword">let</span>
  <span class="Identifier">tmpTuple</span> <span class="Operator">=</span> <span class="Identifier">returnsTuple</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
  <span class="Identifier">x</span> <span class="Operator">=</span> <span class="Identifier">tmpTuple</span><span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">]</span>
  <span class="Identifier">z</span> <span class="Operator">=</span> <span class="Identifier">tmpTuple</span><span class="Punctuation">[</span><span class="DecNumber">2</span><span class="Punctuation">]</span></pre></p>
<p>For <tt class="docutils literal"><span class="pre"><span class="Keyword">var</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Keyword">let</span></span></tt> statements, if the value expression is a tuple literal, each expression is directly expanded into an assignment without the use of a temporary variable.</p>
<p><pre class="listing"><span class="Keyword">let</span> <span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">,</span> <span class="Identifier">z</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Punctuation">(</span><span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="DecNumber">2</span><span class="Punctuation">,</span> <span class="DecNumber">3</span><span class="Punctuation">)</span>
<span class="Comment"># becomes</span>
<span class="Keyword">let</span>
  <span class="Identifier">x</span> <span class="Operator">=</span> <span class="DecNumber">1</span>
  <span class="Identifier">y</span> <span class="Operator">=</span> <span class="DecNumber">2</span>
  <span class="Identifier">z</span> <span class="Operator">=</span> <span class="DecNumber">3</span></pre></p>
<p>Tuple unpacking can also be nested:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">returnsNestedTuple</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Punctuation">(</span><span class="Identifier">int</span><span class="Punctuation">,</span> <span class="Punctuation">(</span><span class="Identifier">int</span><span class="Punctuation">,</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">,</span> <span class="Identifier">int</span><span class="Punctuation">,</span> <span class="Identifier">int</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Punctuation">(</span><span class="DecNumber">4</span><span class="Punctuation">,</span> <span class="Punctuation">(</span><span class="DecNumber">5</span><span class="Punctuation">,</span> <span class="DecNumber">7</span><span class="Punctuation">)</span><span class="Punctuation">,</span> <span class="DecNumber">2</span><span class="Punctuation">,</span> <span class="DecNumber">3</span><span class="Punctuation">)</span>

<span class="Keyword">let</span> <span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Punctuation">(</span><span class="Identifier">_</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">)</span><span class="Punctuation">,</span> <span class="Identifier">_</span><span class="Punctuation">,</span> <span class="Identifier">z</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Identifier">returnsNestedTuple</span><span class="Punctuation">(</span><span class="Punctuation">)</span></pre></p>

<h2><a class="toc-backref" id="statements-and-expressions-const-section" href="#statements-and-expressions-const-section">Const section</a></h2><p>A const section declares constants whose values are constant expressions:</p>
<p><pre class="listing"><span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Punctuation">[</span><span class="Identifier">strutils</span><span class="Punctuation">]</span>
<span class="Keyword">const</span>
  <span class="Identifier">roundPi</span> <span class="Operator">=</span> <span class="FloatNumber">3.1415</span>
  <span class="Identifier">constEval</span> <span class="Operator">=</span> <span class="Identifier">contains</span><span class="Punctuation">(</span><span class="StringLit">&quot;abc&quot;</span><span class="Punctuation">,</span> <span class="CharLit">'b'</span><span class="Punctuation">)</span> <span class="Comment"># computed at compile time!</span></pre></p>
<p>Once declared, a constant's symbol can be used as a constant expression.</p>
<p>The value part of a constant declaration opens a new scope for each constant, so no symbols declared in the constant value are accessible outside of it.</p>
<p><pre class="listing"><span class="Keyword">const</span> <span class="Identifier">foo</span> <span class="Operator">=</span> <span class="Punctuation">(</span><span class="Keyword">var</span> <span class="Identifier">a</span> <span class="Operator">=</span> <span class="DecNumber">1</span><span class="Punctuation">;</span> <span class="Identifier">a</span><span class="Punctuation">)</span>
<span class="Keyword">const</span> <span class="Identifier">bar</span> <span class="Operator">=</span> <span class="Identifier">a</span> <span class="Comment"># error</span>
<span class="Keyword">let</span> <span class="Identifier">baz</span> <span class="Operator">=</span> <span class="Identifier">a</span> <span class="Comment"># error</span></pre></p>
<p>See <a class="reference internal" href="#constants-and-constant-expressions">Constants and Constant Expressions</a> for details.</p>

<h2><a class="toc-backref" id="statements-and-expressions-static-statementslashexpression" href="#statements-and-expressions-static-statementslashexpression">Static statement/expression</a></h2><p>A static statement/expression explicitly requires compile-time execution. Even some code that has side effects is permitted in a static block:</p>
<p><pre class="listing"><span class="Keyword">static</span><span class="Punctuation">:</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;echo at compile time&quot;</span></pre></p>
<p><tt class="docutils literal"><span class="pre"><span class="Keyword">static</span></span></tt> can also be used like a routine.</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">getNum</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span> <span class="Identifier">a</span>

<span class="Comment"># Below calls &quot;echo getNum(123)&quot; at compile time.</span>
<span class="Keyword">static</span><span class="Punctuation">:</span>
  <span class="Identifier">echo</span> <span class="Identifier">getNum</span><span class="Punctuation">(</span><span class="DecNumber">123</span><span class="Punctuation">)</span>

<span class="Comment"># Below call evaluates the &quot;getNum(123)&quot; at compile time, but its</span>
<span class="Comment"># result gets used at run time.</span>
<span class="Identifier">echo</span> <span class="Keyword">static</span><span class="Punctuation">(</span><span class="Identifier">getNum</span><span class="Punctuation">(</span><span class="DecNumber">123</span><span class="Punctuation">)</span><span class="Punctuation">)</span></pre></p>
<p>There are limitations on what Nim code can be executed at compile time; see <a class="reference internal" href="#restrictions-on-compileminustime-execution">Restrictions on Compile-Time Execution</a> for details. It's a static error if the compiler cannot execute the block at compile time.</p>

<h2><a class="toc-backref" id="statements-and-expressions-if-statement" href="#statements-and-expressions-if-statement">If statement</a></h2><p>Example:</p>
<p><pre class="listing"><span class="Keyword">var</span> <span class="Identifier">name</span> <span class="Operator">=</span> <span class="Identifier">readLine</span><span class="Punctuation">(</span><span class="Identifier">stdin</span><span class="Punctuation">)</span>

<span class="Keyword">if</span> <span class="Identifier">name</span> <span class="Operator">==</span> <span class="StringLit">&quot;Andreas&quot;</span><span class="Punctuation">:</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;What a nice name!&quot;</span>
<span class="Keyword">elif</span> <span class="Identifier">name</span> <span class="Operator">==</span> <span class="StringLit">&quot;&quot;</span><span class="Punctuation">:</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;Don't you have a name?&quot;</span>
<span class="Keyword">else</span><span class="Punctuation">:</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;Boring name...&quot;</span></pre></p>
<p>The <tt class="docutils literal"><span class="pre"><span class="Keyword">if</span></span></tt> statement is a simple way to make a branch in the control flow: The expression after the keyword <tt class="docutils literal"><span class="pre"><span class="Keyword">if</span></span></tt> is evaluated, if it is true the corresponding statements after the <tt class="docutils literal"><span class="pre"><span class="Punctuation">:</span></span></tt> are executed. Otherwise, the expression after the <tt class="docutils literal"><span class="pre"><span class="Keyword">elif</span></span></tt> is evaluated (if there is an <tt class="docutils literal"><span class="pre"><span class="Keyword">elif</span></span></tt> branch), if it is true the corresponding statements after the <tt class="docutils literal"><span class="pre"><span class="Punctuation">:</span></span></tt> are executed. This goes on until the last <tt class="docutils literal"><span class="pre"><span class="Keyword">elif</span></span></tt>. If all conditions fail, the <tt class="docutils literal"><span class="pre"><span class="Keyword">else</span></span></tt> part is executed. If there is no <tt class="docutils literal"><span class="pre"><span class="Keyword">else</span></span></tt> part, execution continues with the next statement.</p>
<p>In <tt class="docutils literal"><span class="pre"><span class="Keyword">if</span></span></tt> statements, new scopes begin immediately after the <tt class="docutils literal"><span class="pre"><span class="Keyword">if</span></span></tt>/<tt class="docutils literal"><span class="pre"><span class="Keyword">elif</span></span></tt>/<tt class="docutils literal"><span class="pre"><span class="Keyword">else</span></span></tt> keywords and ends after the corresponding <em>then</em> block. For visualization purposes the scopes have been enclosed in <tt class="docutils literal"><span class="pre"><span class="Punctuation">{</span><span class="Operator">|</span> <span class="Operator">|</span><span class="Punctuation">}</span></span></tt> in the following example:</p>
<p><pre class="listing"><span class="Keyword">if</span> <span class="Punctuation">{</span><span class="Operator">|</span> <span class="Punctuation">(</span><span class="Keyword">let</span> <span class="Identifier">m</span> <span class="Operator">=</span> <span class="Identifier">input</span> <span class="Operator">=~</span> <span class="RawData">re&quot;(\w+)=\w+&quot;</span><span class="Punctuation">;</span> <span class="Identifier">m</span><span class="Operator">.</span><span class="Identifier">isMatch</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;key &quot;</span><span class="Punctuation">,</span> <span class="Identifier">m</span><span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">]</span><span class="Punctuation">,</span> <span class="StringLit">&quot; value &quot;</span><span class="Punctuation">,</span> <span class="Identifier">m</span><span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">]</span>  <span class="Operator">|</span><span class="Punctuation">}</span>
<span class="Keyword">elif</span> <span class="Punctuation">{</span><span class="Operator">|</span> <span class="Punctuation">(</span><span class="Keyword">let</span> <span class="Identifier">m</span> <span class="Operator">=</span> <span class="Identifier">input</span> <span class="Operator">=~</span> <span class="RawData">re&quot;&quot;</span><span class="Punctuation">;</span> <span class="Identifier">m</span><span class="Operator">.</span><span class="Identifier">isMatch</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;new m in this scope&quot;</span>  <span class="Operator">|</span><span class="Punctuation">}</span>
<span class="Keyword">else</span><span class="Punctuation">:</span> <span class="Punctuation">{</span><span class="Operator">|</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;m not declared here&quot;</span>  <span class="Operator">|</span><span class="Punctuation">}</span></pre></p>

<h2><a class="toc-backref" id="statements-and-expressions-case-statement" href="#statements-and-expressions-case-statement">Case statement</a></h2><p>Example:</p>
<p><pre class="listing"><span class="Keyword">let</span> <span class="Identifier">line</span> <span class="Operator">=</span> <span class="Identifier">readline</span><span class="Punctuation">(</span><span class="Identifier">stdin</span><span class="Punctuation">)</span>
<span class="Keyword">case</span> <span class="Identifier">line</span>
<span class="Keyword">of</span> <span class="StringLit">&quot;delete-everything&quot;</span><span class="Punctuation">,</span> <span class="StringLit">&quot;restart-computer&quot;</span><span class="Punctuation">:</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;permission denied&quot;</span>
<span class="Keyword">of</span> <span class="StringLit">&quot;go-for-a-walk&quot;</span><span class="Punctuation">:</span>     <span class="Identifier">echo</span> <span class="StringLit">&quot;please yourself&quot;</span>
<span class="Keyword">elif</span> <span class="Identifier">line</span><span class="Operator">.</span><span class="Identifier">len</span> <span class="Operator">==</span> <span class="DecNumber">0</span><span class="Punctuation">:</span>     <span class="Identifier">echo</span> <span class="StringLit">&quot;empty&quot;</span> <span class="Comment"># optional, must come after `of` branches</span>
<span class="Keyword">else</span><span class="Punctuation">:</span>                   <span class="Identifier">echo</span> <span class="StringLit">&quot;unknown command&quot;</span> <span class="Comment"># ditto</span>

<span class="Comment"># indentation of the branches is also allowed; and so is an optional colon</span>
<span class="Comment"># after the selecting expression:</span>
<span class="Keyword">case</span> <span class="Identifier">readline</span><span class="Punctuation">(</span><span class="Identifier">stdin</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
  <span class="Keyword">of</span> <span class="StringLit">&quot;delete-everything&quot;</span><span class="Punctuation">,</span> <span class="StringLit">&quot;restart-computer&quot;</span><span class="Punctuation">:</span>
    <span class="Identifier">echo</span> <span class="StringLit">&quot;permission denied&quot;</span>
  <span class="Keyword">of</span> <span class="StringLit">&quot;go-for-a-walk&quot;</span><span class="Punctuation">:</span>     <span class="Identifier">echo</span> <span class="StringLit">&quot;please yourself&quot;</span>
  <span class="Keyword">else</span><span class="Punctuation">:</span>                   <span class="Identifier">echo</span> <span class="StringLit">&quot;unknown command&quot;</span></pre></p>
<p>The <tt class="docutils literal"><span class="pre"><span class="Keyword">case</span></span></tt> statement is similar to the <tt class="docutils literal"><span class="pre"><span class="Keyword">if</span></span></tt> statement, but it represents a multi-branch selection. The expression after the keyword <tt class="docutils literal"><span class="pre"><span class="Keyword">case</span></span></tt> is evaluated and if its value is in a <em>slicelist</em> the corresponding statements (after the <tt class="docutils literal"><span class="pre"><span class="Keyword">of</span></span></tt> keyword) are executed. If the value is not in any given <em>slicelist</em>, trailing <tt class="docutils literal"><span class="pre"><span class="Keyword">elif</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Keyword">else</span></span></tt> parts are executed using same semantics as for <tt class="docutils literal"><span class="pre"><span class="Keyword">if</span></span></tt> statement, and <tt class="docutils literal"><span class="pre"><span class="Keyword">elif</span></span></tt> is handled just like <tt class="docutils literal"><span class="pre"><span class="Keyword">else</span><span class="Punctuation">:</span> <span class="Keyword">if</span></span></tt>. If there are no <tt class="docutils literal"><span class="pre"><span class="Keyword">else</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Keyword">elif</span></span></tt> parts and not all possible values that <tt class="docutils literal"><span class="pre"><span class="Identifier">expr</span></span></tt> can hold occur in a <em>slicelist</em>, a static error occurs. This holds only for expressions of ordinal types. &quot;All possible values&quot; of <tt class="docutils literal"><span class="pre"><span class="Identifier">expr</span></span></tt> are determined by <tt class="docutils literal"><span class="pre"><span class="Identifier">expr</span></span></tt>'s type. To suppress the static error an <tt class="docutils literal"><span class="pre"><span class="Keyword">else</span><span class="Punctuation">:</span> <span class="Keyword">discard</span></span></tt> should be used.</p>
<p>Only ordinal types, floats, strings and cstrings are allowed as values in case statements.</p>
<p>For non-ordinal types, it is not possible to list every possible value and so these always require an <tt class="docutils literal"><span class="pre"><span class="Keyword">else</span></span></tt> part. An exception to this rule is for the <tt class="docutils literal"><span class="pre"><span class="Identifier">string</span></span></tt> type, which currently doesn't require a trailing <tt class="docutils literal"><span class="pre"><span class="Keyword">else</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Keyword">elif</span></span></tt> branch; it's unspecified whether this will keep working in future versions.</p>
<p>Because case statements are checked for exhaustiveness during semantic analysis, the value in every <tt class="docutils literal"><span class="pre"><span class="Keyword">of</span></span></tt> branch must be a constant expression. This restriction also allows the compiler to generate more performant code.</p>
<p>As a special semantic extension, an expression in an <tt class="docutils literal"><span class="pre"><span class="Keyword">of</span></span></tt> branch of a case statement may evaluate to a set or array constructor; the set or array is then expanded into a list of its elements:</p>
<p><pre class="listing"><span class="Keyword">const</span>
  <span class="Identifier">SymChars</span><span class="Punctuation">:</span> <span class="Identifier">set</span><span class="Punctuation">[</span><span class="Identifier">char</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Punctuation">{</span><span class="Punctuation">'</span><span class="Identifier">a</span><span class="CharLit">'..'</span><span class="Identifier">z</span><span class="CharLit">', '</span><span class="Identifier">A</span><span class="CharLit">'..'</span><span class="Identifier">Z</span><span class="CharLit">', '</span><span class="Operator">\</span><span class="Identifier">x80</span><span class="CharLit">'..'</span><span class="Operator">\</span><span class="Identifier">xFF</span><span class="CharLit">'}</span>

<span class="Keyword">proc</span> <span class="Identifier">classify</span><span class="Punctuation">(</span><span class="Identifier">s</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">case</span> <span class="Identifier">s</span><span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">]</span>
  <span class="Keyword">of</span> <span class="Identifier">SymChars</span><span class="Punctuation">,</span> <span class="CharLit">'_'</span><span class="Punctuation">:</span> <span class="Identifier">echo</span> <span class="StringLit">&quot;an identifier&quot;</span>
  <span class="Keyword">of</span> <span class="CharLit">'0'</span><span class="Operator">..</span><span class="CharLit">'9'</span><span class="Punctuation">:</span> <span class="Identifier">echo</span> <span class="StringLit">&quot;a number&quot;</span>
  <span class="Keyword">else</span><span class="Punctuation">:</span> <span class="Identifier">echo</span> <span class="StringLit">&quot;other&quot;</span>

<span class="Comment"># is equivalent to:</span>
<span class="Keyword">proc</span> <span class="Identifier">classify</span><span class="Punctuation">(</span><span class="Identifier">s</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">case</span> <span class="Identifier">s</span><span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">]</span>
  <span class="Keyword">of</span> <span class="CharLit">'a'</span><span class="Operator">..</span><span class="CharLit">'z'</span><span class="Punctuation">,</span> <span class="CharLit">'A'</span><span class="Operator">..</span><span class="CharLit">'Z'</span><span class="Punctuation">,</span> <span class="CharLit">'\x80'</span><span class="Operator">..</span><span class="CharLit">'\xFF'</span><span class="Punctuation">,</span> <span class="CharLit">'_'</span><span class="Punctuation">:</span> <span class="Identifier">echo</span> <span class="StringLit">&quot;an identifier&quot;</span>
  <span class="Keyword">of</span> <span class="CharLit">'0'</span><span class="Operator">..</span><span class="CharLit">'9'</span><span class="Punctuation">:</span> <span class="Identifier">echo</span> <span class="StringLit">&quot;a number&quot;</span>
  <span class="Keyword">else</span><span class="Punctuation">:</span> <span class="Identifier">echo</span> <span class="StringLit">&quot;other&quot;</span></pre></p>
<p>The <tt class="docutils literal"><span class="pre"><span class="Keyword">case</span></span></tt> statement doesn't produce an l-value, so the following example won't work:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">Foo</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Keyword">object</span>
    <span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">string</span><span class="Punctuation">]</span>

<span class="Keyword">proc</span> <span class="Identifier">get_x</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">Foo</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">string</span><span class="Punctuation">]</span> <span class="Operator">=</span>
  <span class="Comment"># doesn't work</span>
  <span class="Keyword">case</span> <span class="Identifier">true</span>
  <span class="Keyword">of</span> <span class="Identifier">true</span><span class="Punctuation">:</span>
    <span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">x</span>
  <span class="Keyword">else</span><span class="Punctuation">:</span>
    <span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">x</span>

<span class="Keyword">var</span> <span class="Identifier">foo</span> <span class="Operator">=</span> <span class="Identifier">Foo</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Operator">@</span><span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Punctuation">)</span>
<span class="Identifier">foo</span><span class="Operator">.</span><span class="Identifier">get_x</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Operator">.</span><span class="Identifier">add</span><span class="Punctuation">(</span><span class="StringLit">&quot;asd&quot;</span><span class="Punctuation">)</span></pre></p>
<p>This can be fixed by explicitly using <tt class="docutils literal"><span class="pre"><span class="Identifier">result</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Keyword">return</span></span></tt>:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">get_x</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">Foo</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">string</span><span class="Punctuation">]</span> <span class="Operator">=</span>
  <span class="Keyword">case</span> <span class="Identifier">true</span>
  <span class="Keyword">of</span> <span class="Identifier">true</span><span class="Punctuation">:</span>
    <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">x</span>
  <span class="Keyword">else</span><span class="Punctuation">:</span>
    <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">x</span></pre></p>

<h2><a class="toc-backref" id="statements-and-expressions-when-statement" href="#statements-and-expressions-when-statement">When statement</a></h2><p>Example:</p>
<p><pre class="listing"><span class="Keyword">when</span> <span class="Identifier">sizeof</span><span class="Punctuation">(</span><span class="Identifier">int</span><span class="Punctuation">)</span> <span class="Operator">==</span> <span class="DecNumber">2</span><span class="Punctuation">:</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;running on a 16 bit system!&quot;</span>
<span class="Keyword">elif</span> <span class="Identifier">sizeof</span><span class="Punctuation">(</span><span class="Identifier">int</span><span class="Punctuation">)</span> <span class="Operator">==</span> <span class="DecNumber">4</span><span class="Punctuation">:</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;running on a 32 bit system!&quot;</span>
<span class="Keyword">elif</span> <span class="Identifier">sizeof</span><span class="Punctuation">(</span><span class="Identifier">int</span><span class="Punctuation">)</span> <span class="Operator">==</span> <span class="DecNumber">8</span><span class="Punctuation">:</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;running on a 64 bit system!&quot;</span>
<span class="Keyword">else</span><span class="Punctuation">:</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;cannot happen!&quot;</span></pre></p>
<p>The <tt class="docutils literal"><span class="pre"><span class="Keyword">when</span></span></tt> statement is almost identical to the <tt class="docutils literal"><span class="pre"><span class="Keyword">if</span></span></tt> statement with some exceptions:</p>
<ul class="simple"><li>Each condition (<tt class="docutils literal"><span class="pre"><span class="Identifier">expr</span></span></tt>) has to be a constant expression (of type <tt class="docutils literal"><span class="pre"><span class="Identifier">bool</span></span></tt>).</li>
<li>The statements do not open a new scope.</li>
<li>The statements that belong to the expression that evaluated to true are translated by the compiler, the other statements are not checked for semantics! However, each condition is checked for semantics.</li>
</ul>
<p>The <tt class="docutils literal"><span class="pre"><span class="Keyword">when</span></span></tt> statement enables conditional compilation techniques. As a special syntactic extension, the <tt class="docutils literal"><span class="pre"><span class="Keyword">when</span></span></tt> construct is also available within <tt class="docutils literal"><span class="pre"><span class="Keyword">object</span></span></tt> definitions.</p>

<h2><a class="toc-backref" id="statements-and-expressions-when-nimvm-statement" href="#statements-and-expressions-when-nimvm-statement">When nimvm statement</a></h2><p><tt class="docutils literal"><span class="pre"><span class="Identifier">nimvm</span></span></tt> is a special symbol that may be used as the expression of a <tt class="docutils literal"><span class="pre"><span class="Keyword">when</span> <span class="Identifier">nimvm</span></span></tt> statement to differentiate the execution path between compile-time and the executable.</p>
<p>Example:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">someProcThatMayRunInCompileTime</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">bool</span> <span class="Operator">=</span>
  <span class="Keyword">when</span> <span class="Identifier">nimvm</span><span class="Punctuation">:</span>
    <span class="Comment"># This branch is taken at compile time.</span>
    <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">true</span>
  <span class="Keyword">else</span><span class="Punctuation">:</span>
    <span class="Comment"># This branch is taken in the executable.</span>
    <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">false</span>
<span class="Keyword">const</span> <span class="Identifier">ctValue</span> <span class="Operator">=</span> <span class="Identifier">someProcThatMayRunInCompileTime</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
<span class="Keyword">let</span> <span class="Identifier">rtValue</span> <span class="Operator">=</span> <span class="Identifier">someProcThatMayRunInCompileTime</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
<span class="Identifier">assert</span><span class="Punctuation">(</span><span class="Identifier">ctValue</span> <span class="Operator">==</span> <span class="Identifier">true</span><span class="Punctuation">)</span>
<span class="Identifier">assert</span><span class="Punctuation">(</span><span class="Identifier">rtValue</span> <span class="Operator">==</span> <span class="Identifier">false</span><span class="Punctuation">)</span></pre></p>
<p>A <tt class="docutils literal"><span class="pre"><span class="Keyword">when</span> <span class="Identifier">nimvm</span></span></tt> statement must meet the following requirements:</p>
<ul class="simple"><li>Its expression must always be <tt class="docutils literal"><span class="pre"><span class="Identifier">nimvm</span></span></tt>. More complex expressions are not allowed.</li>
<li>It must not contain <tt class="docutils literal"><span class="pre"><span class="Keyword">elif</span></span></tt> branches.</li>
<li>It must contain an <tt class="docutils literal"><span class="pre"><span class="Keyword">else</span></span></tt> branch.</li>
<li>Code in branches must not affect semantics of the code that follows the <tt class="docutils literal"><span class="pre"><span class="Keyword">when</span> <span class="Identifier">nimvm</span></span></tt> statement. E.g. it must not define symbols that are used in the following code.</li>
</ul>

<h2><a class="toc-backref" id="statements-and-expressions-return-statement" href="#statements-and-expressions-return-statement">Return statement</a></h2><p>Example:</p>
<p><pre class="listing"><span class="Keyword">return</span> <span class="DecNumber">40</span> <span class="Operator">+</span> <span class="DecNumber">2</span></pre></p>
<p>The <tt class="docutils literal"><span class="pre"><span class="Keyword">return</span></span></tt> statement ends the execution of the current procedure. It is only allowed in procedures. If there is an <tt class="docutils literal"><span class="pre"><span class="Identifier">expr</span></span></tt>, this is syntactic sugar for:</p>
<p><pre class="listing"><span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">expr</span>
<span class="Keyword">return</span> <span class="Identifier">result</span></pre></p>
<p><tt class="docutils literal"><span class="pre"><span class="Keyword">return</span></span></tt> without an expression is a short notation for <tt class="docutils literal"><span class="pre"><span class="Keyword">return</span> <span class="Identifier">result</span></span></tt> if the proc has a return type. The <span id="result_1">result</span> variable is always the return value of the procedure. It is automatically declared by the compiler. As all variables, <tt class="docutils literal"><span class="pre"><span class="Identifier">result</span></span></tt> is initialized to (binary) zero:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">returnZero</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span>
  <span class="Comment"># implicitly returns 0</span></pre></p>

<h2><a class="toc-backref" id="statements-and-expressions-yield-statement" href="#statements-and-expressions-yield-statement">Yield statement</a></h2><p>Example:</p>
<p><pre class="listing"><span class="Keyword">yield</span> <span class="Punctuation">(</span><span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="DecNumber">2</span><span class="Punctuation">,</span> <span class="DecNumber">3</span><span class="Punctuation">)</span></pre></p>
<p>The <tt class="docutils literal"><span class="pre"><span class="Keyword">yield</span></span></tt> statement is used instead of the <tt class="docutils literal"><span class="pre"><span class="Keyword">return</span></span></tt> statement in iterators. It is only valid in iterators. Execution is returned to the body of the for loop that called the iterator. Yield does not end the iteration process, but the execution is passed back to the iterator if the next iteration starts. See the section about iterators (<a class="reference internal" href="#iterators-and-the-for-statement">Iterators and the for statement</a>) for further information.</p>

<h2><a class="toc-backref" id="statements-and-expressions-block-statement" href="#statements-and-expressions-block-statement">Block statement</a></h2><p>Example:</p>
<p><pre class="listing"><span class="Keyword">var</span> <span class="Identifier">found</span> <span class="Operator">=</span> <span class="Identifier">false</span>
<span class="Keyword">block</span> <span class="Identifier">myblock</span><span class="Punctuation">:</span>
  <span class="Keyword">for</span> <span class="Identifier">i</span> <span class="Keyword">in</span> <span class="FloatNumber">0.</span><span class="Operator">.</span><span class="DecNumber">3</span><span class="Punctuation">:</span>
    <span class="Keyword">for</span> <span class="Identifier">j</span> <span class="Keyword">in</span> <span class="FloatNumber">0.</span><span class="Operator">.</span><span class="DecNumber">3</span><span class="Punctuation">:</span>
      <span class="Keyword">if</span> <span class="Identifier">a</span><span class="Punctuation">[</span><span class="Identifier">j</span><span class="Punctuation">]</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span> <span class="Operator">==</span> <span class="DecNumber">7</span><span class="Punctuation">:</span>
        <span class="Identifier">found</span> <span class="Operator">=</span> <span class="Identifier">true</span>
        <span class="Keyword">break</span> <span class="Identifier">myblock</span> <span class="Comment"># leave the block, in this case both for-loops</span>
<span class="Identifier">echo</span> <span class="Identifier">found</span></pre></p>
<p>The block statement is a means to group statements to a (named) <tt class="docutils literal"><span class="pre"><span class="Keyword">block</span></span></tt>. Inside the block, the <tt class="docutils literal"><span class="pre"><span class="Keyword">break</span></span></tt> statement is allowed to leave the block immediately. A <tt class="docutils literal"><span class="pre"><span class="Keyword">break</span></span></tt> statement can contain a name of a surrounding block to specify which block is to be left.</p>

<h2><a class="toc-backref" id="statements-and-expressions-break-statement" href="#statements-and-expressions-break-statement">Break statement</a></h2><p>Example:</p>
<p><pre class="listing"><span class="Keyword">break</span></pre></p>
<p>The <tt class="docutils literal"><span class="pre"><span class="Keyword">break</span></span></tt> statement is used to leave a block immediately. If <tt class="docutils literal"><span class="pre"><span class="Identifier">symbol</span></span></tt> is given, it is the name of the enclosing block that is to be left. If it is absent, the innermost block is left.</p>

<h2><a class="toc-backref" id="statements-and-expressions-while-statement" href="#statements-and-expressions-while-statement">While statement</a></h2><p>Example:</p>
<p><pre class="listing"><span class="Identifier">echo</span> <span class="StringLit">&quot;Please tell me your password:&quot;</span>
<span class="Keyword">var</span> <span class="Identifier">pw</span> <span class="Operator">=</span> <span class="Identifier">readLine</span><span class="Punctuation">(</span><span class="Identifier">stdin</span><span class="Punctuation">)</span>
<span class="Keyword">while</span> <span class="Identifier">pw</span> <span class="Operator">!=</span> <span class="StringLit">&quot;12345&quot;</span><span class="Punctuation">:</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;Wrong password! Next try:&quot;</span>
  <span class="Identifier">pw</span> <span class="Operator">=</span> <span class="Identifier">readLine</span><span class="Punctuation">(</span><span class="Identifier">stdin</span><span class="Punctuation">)</span></pre></p>
<p>The <tt class="docutils literal"><span class="pre"><span class="Keyword">while</span></span></tt> statement is executed until the <tt class="docutils literal"><span class="pre"><span class="Identifier">expr</span></span></tt> evaluates to false. Endless loops are no error. <tt class="docutils literal"><span class="pre"><span class="Keyword">while</span></span></tt> statements open an <tt class="docutils literal"><span class="pre"><span class="Identifier">implicit</span> <span class="Keyword">block</span></span></tt> so that they can be left with a <tt class="docutils literal"><span class="pre"><span class="Keyword">break</span></span></tt> statement.</p>

<h2><a class="toc-backref" id="statements-and-expressions-continue-statement" href="#statements-and-expressions-continue-statement">Continue statement</a></h2><p>A <tt class="docutils literal"><span class="pre"><span class="Keyword">continue</span></span></tt> statement leads to the immediate next iteration of the surrounding loop construct. It is only allowed within a loop. A continue statement is syntactic sugar for a nested block:</p>
<p><pre class="listing"><span class="Keyword">while</span> <span class="Identifier">expr1</span><span class="Punctuation">:</span>
  <span class="Identifier">stmt1</span>
  <span class="Keyword">continue</span>
  <span class="Identifier">stmt2</span></pre></p>
<p>Is equivalent to:</p>
<p><pre class="listing"><span class="Keyword">while</span> <span class="Identifier">expr1</span><span class="Punctuation">:</span>
  <span class="Keyword">block</span> <span class="Identifier">myBlockName</span><span class="Punctuation">:</span>
    <span class="Identifier">stmt1</span>
    <span class="Keyword">break</span> <span class="Identifier">myBlockName</span>
    <span class="Identifier">stmt2</span></pre></p>

<h2><a class="toc-backref" id="statements-and-expressions-assembler-statement" href="#statements-and-expressions-assembler-statement">Assembler statement</a></h2><p>The direct embedding of assembler code into Nim code is supported by the unsafe <tt class="docutils literal"><span class="pre"><span class="Keyword">asm</span></span></tt> statement. Identifiers in the assembler code that refer to Nim identifiers shall be enclosed in a special character which can be specified in the statement's pragmas. The default special character is <tt class="docutils literal"><span class="pre"><span class="CharLit">'`'</span></span></tt>:</p>
<p><pre class="listing"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">push</span> <span class="Identifier">stackTrace</span><span class="Punctuation">:</span><span class="Identifier">off</span><span class="Operator">.</span><span class="Punctuation">}</span>
<span class="Keyword">proc</span> <span class="Identifier">addInt</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span>
  <span class="Comment"># a in eax, and b in edx</span>
  <span class="Keyword">asm</span> <span class="LongStringLit">&quot;&quot;&quot;
      mov eax, `a`
      add eax, `b`
      jno theEnd
      call `raiseOverflow`
    theEnd:
  &quot;&quot;&quot;</span>
<span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">pop</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>
<p>If the GNU assembler is used, quotes and newlines are inserted automatically:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">addInt</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span>
  <span class="Keyword">asm</span> <span class="LongStringLit">&quot;&quot;&quot;
    addl %%ecx, %%eax
    jno 1
    call `raiseOverflow`
    1:
    :&quot;=a&quot;(`result`)
    :&quot;a&quot;(`a`), &quot;c&quot;(`b`)
  &quot;&quot;&quot;</span></pre></p>
<p>Instead of:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">addInt</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span>
  <span class="Keyword">asm</span> <span class="LongStringLit">&quot;&quot;&quot;
    &quot;addl %%ecx, %%eax\n&quot;
    &quot;jno 1\n&quot;
    &quot;call `raiseOverflow`\n&quot;
    &quot;1: \n&quot;
    :&quot;=a&quot;(`result`)
    :&quot;a&quot;(`a`), &quot;c&quot;(`b`)
  &quot;&quot;&quot;</span></pre></p>

<h2><a class="toc-backref" id="statements-and-expressions-using-statement" href="#statements-and-expressions-using-statement">Using statement</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Keyword">using</span></span></tt> statement provides syntactic convenience in modules where the same parameter names and types are used over and over. Instead of:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">foo</span><span class="Punctuation">(</span><span class="Identifier">c</span><span class="Punctuation">:</span> <span class="Identifier">Context</span><span class="Punctuation">;</span> <span class="Identifier">n</span><span class="Punctuation">:</span> <span class="Identifier">Node</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Operator">...</span>
<span class="Keyword">proc</span> <span class="Identifier">bar</span><span class="Punctuation">(</span><span class="Identifier">c</span><span class="Punctuation">:</span> <span class="Identifier">Context</span><span class="Punctuation">;</span> <span class="Identifier">n</span><span class="Punctuation">:</span> <span class="Identifier">Node</span><span class="Punctuation">,</span> <span class="Identifier">counter</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Operator">...</span>
<span class="Keyword">proc</span> <span class="Identifier">baz</span><span class="Punctuation">(</span><span class="Identifier">c</span><span class="Punctuation">:</span> <span class="Identifier">Context</span><span class="Punctuation">;</span> <span class="Identifier">n</span><span class="Punctuation">:</span> <span class="Identifier">Node</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Operator">...</span></pre></p>
<p>One can tell the compiler about the convention that a parameter of name <tt class="docutils literal"><span class="pre"><span class="Identifier">c</span></span></tt> should default to type <tt class="docutils literal"><span class="pre"><span class="Identifier">Context</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Identifier">n</span></span></tt> should default to <tt class="docutils literal"><span class="pre"><span class="Identifier">Node</span></span></tt> etc.:</p>
<p><pre class="listing"><span class="Keyword">using</span>
  <span class="Identifier">c</span><span class="Punctuation">:</span> <span class="Identifier">Context</span>
  <span class="Identifier">n</span><span class="Punctuation">:</span> <span class="Identifier">Node</span>
  <span class="Identifier">counter</span><span class="Punctuation">:</span> <span class="Identifier">int</span>

<span class="Keyword">proc</span> <span class="Identifier">foo</span><span class="Punctuation">(</span><span class="Identifier">c</span><span class="Punctuation">,</span> <span class="Identifier">n</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Operator">...</span>
<span class="Keyword">proc</span> <span class="Identifier">bar</span><span class="Punctuation">(</span><span class="Identifier">c</span><span class="Punctuation">,</span> <span class="Identifier">n</span><span class="Punctuation">,</span> <span class="Identifier">counter</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Operator">...</span>
<span class="Keyword">proc</span> <span class="Identifier">baz</span><span class="Punctuation">(</span><span class="Identifier">c</span><span class="Punctuation">,</span> <span class="Identifier">n</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Operator">...</span>

<span class="Keyword">proc</span> <span class="Identifier">mixedMode</span><span class="Punctuation">(</span><span class="Identifier">c</span><span class="Punctuation">,</span> <span class="Identifier">n</span><span class="Punctuation">;</span> <span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Comment"># 'c' is inferred to be of the type 'Context'</span>
  <span class="Comment"># 'n' is inferred to be of the type 'Node'</span>
  <span class="Comment"># But 'x' and 'y' are of type 'int'.</span></pre></p>
<p>The <tt class="docutils literal"><span class="pre"><span class="Keyword">using</span></span></tt> section uses the same indentation based grouping syntax as a <tt class="docutils literal"><span class="pre"><span class="Keyword">var</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Keyword">let</span></span></tt> section.</p>
<p>Note that <tt class="docutils literal"><span class="pre"><span class="Keyword">using</span></span></tt> is not applied for <tt class="docutils literal"><span class="pre"><span class="Keyword">template</span></span></tt> since the untyped template parameters default to the type <tt class="docutils literal"><span class="pre"><span class="Identifier">system</span><span class="Operator">.</span><span class="Identifier">untyped</span></span></tt>.</p>
<p>Mixing parameters that should use the <tt class="docutils literal"><span class="pre"><span class="Keyword">using</span></span></tt> declaration with parameters that are explicitly typed is possible and requires a semicolon between them.</p>

<h2><a class="toc-backref" id="statements-and-expressions-if-expression" href="#statements-and-expressions-if-expression">If expression</a></h2><p>An <tt class="docutils literal"><span class="pre"><span class="Keyword">if</span></span></tt> expression is almost like an if statement, but it is an expression. This feature is similar to <em>ternary operators</em> in other languages. Example:</p>
<p><pre class="listing"><span class="Keyword">var</span> <span class="Identifier">y</span> <span class="Operator">=</span> <span class="Keyword">if</span> <span class="Identifier">x</span> <span class="Operator">&gt;</span> <span class="DecNumber">8</span><span class="Punctuation">:</span> <span class="DecNumber">9</span> <span class="Keyword">else</span><span class="Punctuation">:</span> <span class="DecNumber">10</span></pre></p>
<p>An <tt class="docutils literal"><span class="pre"><span class="Keyword">if</span></span></tt> expression always results in a value, so the <tt class="docutils literal"><span class="pre"><span class="Keyword">else</span></span></tt> part is required. <tt class="docutils literal"><span class="pre"><span class="Keyword">elif</span></span></tt> parts are also allowed.</p>

<h2><a class="toc-backref" id="statements-and-expressions-when-expression" href="#statements-and-expressions-when-expression">When expression</a></h2><p>Just like an <tt class="docutils literal"><span class="pre"><span class="Keyword">if</span></span></tt> expression, but corresponding to the <tt class="docutils literal"><span class="pre"><span class="Keyword">when</span></span></tt> statement.</p>

<h2><a class="toc-backref" id="statements-and-expressions-case-expression" href="#statements-and-expressions-case-expression">Case expression</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Keyword">case</span></span></tt> expression is again very similar to the case statement:</p>
<p><pre class="listing"><span class="Keyword">var</span> <span class="Identifier">favoriteFood</span> <span class="Operator">=</span> <span class="Keyword">case</span> <span class="Identifier">animal</span>
  <span class="Keyword">of</span> <span class="StringLit">&quot;dog&quot;</span><span class="Punctuation">:</span> <span class="StringLit">&quot;bones&quot;</span>
  <span class="Keyword">of</span> <span class="StringLit">&quot;cat&quot;</span><span class="Punctuation">:</span> <span class="StringLit">&quot;mice&quot;</span>
  <span class="Keyword">elif</span> <span class="Identifier">animal</span><span class="Operator">.</span><span class="RawData">endsWith&quot;whale&quot;</span><span class="Punctuation">:</span> <span class="StringLit">&quot;plankton&quot;</span>
  <span class="Keyword">else</span><span class="Punctuation">:</span>
    <span class="Identifier">echo</span> <span class="StringLit">&quot;I'm not sure what to serve, but everybody loves ice cream&quot;</span>
    <span class="StringLit">&quot;ice cream&quot;</span></pre></p>
<p>As seen in the above example, the case expression can also introduce side effects. When multiple statements are given for a branch, Nim will use the last expression as the result value.</p>

<h2><a class="toc-backref" id="statements-and-expressions-block-expression" href="#statements-and-expressions-block-expression">Block expression</a></h2><p>A <tt class="docutils literal"><span class="pre"><span class="Keyword">block</span></span></tt> expression is almost like a block statement, but it is an expression that uses the last expression under the block as the value. It is similar to the statement list expression, but the statement list expression does not open a new block scope.</p>
<p><pre class="listing"><span class="Keyword">let</span> <span class="Identifier">a</span> <span class="Operator">=</span> <span class="Keyword">block</span><span class="Punctuation">:</span>
  <span class="Keyword">var</span> <span class="Identifier">fib</span> <span class="Operator">=</span> <span class="Operator">@</span><span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">,</span> <span class="DecNumber">1</span><span class="Punctuation">]</span>
  <span class="Keyword">for</span> <span class="Identifier">i</span> <span class="Keyword">in</span> <span class="FloatNumber">0.</span><span class="Operator">.</span><span class="DecNumber">10</span><span class="Punctuation">:</span>
    <span class="Identifier">fib</span><span class="Operator">.</span><span class="Identifier">add</span> <span class="Identifier">fib</span><span class="Punctuation">[</span><span class="Operator">^</span><span class="DecNumber">1</span><span class="Punctuation">]</span> <span class="Operator">+</span> <span class="Identifier">fib</span><span class="Punctuation">[</span><span class="Operator">^</span><span class="DecNumber">2</span><span class="Punctuation">]</span>
  <span class="Identifier">fib</span></pre></p>

<h2><a class="toc-backref" id="statements-and-expressions-table-constructor" href="#statements-and-expressions-table-constructor">Table constructor</a></h2><p>A table constructor is syntactic sugar for an array constructor:</p>
<p><pre class="listing"><span class="Punctuation">{</span><span class="StringLit">&quot;key1&quot;</span><span class="Punctuation">:</span> <span class="StringLit">&quot;value1&quot;</span><span class="Punctuation">,</span> <span class="StringLit">&quot;key2&quot;</span><span class="Punctuation">,</span> <span class="StringLit">&quot;key3&quot;</span><span class="Punctuation">:</span> <span class="StringLit">&quot;value2&quot;</span><span class="Punctuation">}</span>

<span class="Comment"># is the same as:</span>
<span class="Punctuation">[</span><span class="Punctuation">(</span><span class="StringLit">&quot;key1&quot;</span><span class="Punctuation">,</span> <span class="StringLit">&quot;value1&quot;</span><span class="Punctuation">)</span><span class="Punctuation">,</span> <span class="Punctuation">(</span><span class="StringLit">&quot;key2&quot;</span><span class="Punctuation">,</span> <span class="StringLit">&quot;value2&quot;</span><span class="Punctuation">)</span><span class="Punctuation">,</span> <span class="Punctuation">(</span><span class="StringLit">&quot;key3&quot;</span><span class="Punctuation">,</span> <span class="StringLit">&quot;value2&quot;</span><span class="Punctuation">)</span><span class="Punctuation">]</span></pre></p>
<p>The empty table can be written <tt class="docutils literal"><span class="pre"><span class="Punctuation">{</span><span class="Punctuation">:</span><span class="Punctuation">}</span></span></tt> (in contrast to the empty set which is <tt class="docutils literal"><span class="pre"><span class="Punctuation">{</span><span class="Punctuation">}</span></span></tt>) which is thus another way to write the empty array constructor <tt class="docutils literal"><span class="pre"><span class="Punctuation">[</span><span class="Punctuation">]</span></span></tt>. This slightly unusual way of supporting tables has lots of advantages:</p>
<ul class="simple"><li>The order of the (key,value)-pairs is preserved, thus it is easy to support ordered dicts with for example <tt class="docutils literal"><span class="pre"><span class="Punctuation">{</span><span class="Identifier">key</span><span class="Punctuation">:</span> <span class="Identifier">val</span><span class="Punctuation">}</span><span class="Operator">.</span><span class="Identifier">newOrderedTable</span></span></tt>.</li>
<li>A table literal can be put into a <tt class="docutils literal"><span class="pre"><span class="Keyword">const</span></span></tt> section and the compiler can easily put it into the executable's data section just like it can for arrays and the generated data section requires a minimal amount of memory.</li>
<li>Every table implementation is treated equally syntactically.</li>
<li>Apart from the minimal syntactic sugar, the language core does not need to know about tables.</li>
</ul>

<h2><a class="toc-backref" id="statements-and-expressions-type-conversions" href="#statements-and-expressions-type-conversions">Type conversions</a></h2><p>Syntactically a <em>type conversion</em> is like a procedure call, but a type name replaces the procedure name. A type conversion is always safe in the sense that a failure to convert a type to another results in an exception (if it cannot be determined statically).</p>
<p>Ordinary procs are often preferred over type conversions in Nim: For instance, <tt class="docutils literal"><span class="pre"><span class="Operator">$</span></span></tt> is the <tt class="docutils literal"><span class="pre"><span class="Identifier">toString</span></span></tt> operator by convention and <tt class="docutils literal"><span class="pre"><span class="Identifier">toFloat</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">toInt</span></span></tt> can be used to convert from floating-point to integer or vice versa.</p>
<p>Type conversion can also be used to disambiguate overloaded routines:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Identifier">echo</span> <span class="StringLit">&quot;int&quot;</span>
<span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Identifier">echo</span> <span class="StringLit">&quot;string&quot;</span>

<span class="Keyword">let</span> <span class="Identifier">procVar</span> <span class="Operator">=</span> <span class="Punctuation">(</span><span class="Keyword">proc</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">)</span><span class="Punctuation">)</span><span class="Punctuation">(</span><span class="Identifier">p</span><span class="Punctuation">)</span>
<span class="Identifier">procVar</span><span class="Punctuation">(</span><span class="StringLit">&quot;a&quot;</span><span class="Punctuation">)</span></pre></p>
<p>Since operations on unsigned numbers wrap around and are unchecked so are type conversions to unsigned integers and between unsigned integers. The rationale for this is mostly better interoperability with the C Programming language when algorithms are ported from C to Nim.</p>
<p><strong>Note</strong>: Historically the operations were unchecked and the conversions were sometimes checked but starting with the revision 1.0.4 of this document and the language implementation the conversions too are now <em>always unchecked</em>.</p>

<h2><a class="toc-backref" id="statements-and-expressions-type-casts" href="#statements-and-expressions-type-casts">Type casts</a></h2><p><em>Type casts</em> are a crude mechanism to interpret the bit pattern of an expression as if it would be of another type. Type casts are only needed for low-level programming and are inherently unsafe.</p>
<p><pre class="listing"><span class="Keyword">cast</span><span class="Punctuation">[</span><span class="Identifier">int</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span></pre></p>
<p>The target type of a cast must be a concrete type, for instance, a target type that is a type class (which is non-concrete) would be invalid:</p>
<p><pre class="listing"><span class="Keyword">type</span> <span class="Identifier">Foo</span> <span class="Operator">=</span> <span class="Identifier">int</span> <span class="Keyword">or</span> <span class="Identifier">float</span>
<span class="Keyword">var</span> <span class="Identifier">x</span> <span class="Operator">=</span> <span class="Keyword">cast</span><span class="Punctuation">[</span><span class="Identifier">Foo</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="DecNumber">1</span><span class="Punctuation">)</span> <span class="Comment"># Error: cannot cast to a non concrete type: 'Foo'</span></pre></p>
<p>Type casts should not be confused with <em>type conversions,</em> as mentioned in the prior section. Unlike type conversions, a type cast cannot change the underlying bit pattern of the data being cast (aside from that the size of the target type may differ from the source type). Casting resembles <em>type punning</em> in other languages or C++'s <tt class="docutils literal"><span class="pre"><span class="Identifier">reinterpret_cast</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">bit_cast</span></span></tt> features.</p>
<p>If the size of the target type is larger than the size of the source type, the remaining memory is zeroed.</p>

<h2><a class="toc-backref" id="statements-and-expressions-the-addr-operator" href="#statements-and-expressions-the-addr-operator">The addr operator</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Keyword">addr</span></span></tt> operator returns the address of an l-value. If the type of the location is <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span></span></tt>, the <tt class="docutils literal"><span class="pre"><span class="Keyword">addr</span></span></tt> operator result is of the type <tt class="docutils literal"><span class="pre"><span class="Keyword">ptr</span> <span class="Identifier">T</span></span></tt>. An address is always an untraced reference. Taking the address of an object that resides on the stack is <strong>unsafe</strong>, as the pointer may live longer than the object on the stack and can thus reference a non-existing object. One can get the address of variables. For easier interoperability with other compiled languages such as C, retrieving the address of a <tt class="docutils literal"><span class="pre"><span class="Keyword">let</span></span></tt> variable, a parameter, or a <tt class="docutils literal"><span class="pre"><span class="Keyword">for</span></span></tt> loop variable can be accomplished too:</p>
<p><pre class="listing"><span class="Keyword">let</span> <span class="Identifier">t1</span> <span class="Operator">=</span> <span class="StringLit">&quot;Hello&quot;</span>
<span class="Keyword">var</span>
  <span class="Identifier">t2</span> <span class="Operator">=</span> <span class="Identifier">t1</span>
  <span class="Identifier">t3</span> <span class="Punctuation">:</span> <span class="Identifier">pointer</span> <span class="Operator">=</span> <span class="Keyword">addr</span><span class="Punctuation">(</span><span class="Identifier">t2</span><span class="Punctuation">)</span>
<span class="Identifier">echo</span> <span class="Identifier">repr</span><span class="Punctuation">(</span><span class="Keyword">addr</span><span class="Punctuation">(</span><span class="Identifier">t2</span><span class="Punctuation">)</span><span class="Punctuation">)</span>
<span class="Comment"># --&gt; ref 0x7fff6b71b670 --&gt; 0x10bb81050&quot;Hello&quot;</span>
<span class="Identifier">echo</span> <span class="Keyword">cast</span><span class="Punctuation">[</span><span class="Keyword">ptr</span> <span class="Identifier">string</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">t3</span><span class="Punctuation">)</span><span class="Punctuation">[</span><span class="Punctuation">]</span>
<span class="Comment"># --&gt; Hello</span>
<span class="Comment"># The following line also works</span>
<span class="Identifier">echo</span> <span class="Identifier">repr</span><span class="Punctuation">(</span><span class="Keyword">addr</span><span class="Punctuation">(</span><span class="Identifier">t1</span><span class="Punctuation">)</span><span class="Punctuation">)</span></pre></p>

<h2><a class="toc-backref" id="statements-and-expressions-the-unsafeaddr-operator" href="#statements-and-expressions-the-unsafeaddr-operator">The unsafeAddr operator</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">unsafeAddr</span></span></tt> operator is a deprecated alias for the <tt class="docutils literal"><span class="pre"><span class="Keyword">addr</span></span></tt> operator:</p>
<p><pre class="listing"><span class="Keyword">let</span> <span class="Identifier">myArray</span> <span class="Operator">=</span> <span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="DecNumber">2</span><span class="Punctuation">,</span> <span class="DecNumber">3</span><span class="Punctuation">]</span>
<span class="Identifier">foreignProcThatTakesAnAddr</span><span class="Punctuation">(</span><span class="Identifier">unsafeAddr</span> <span class="Identifier">myArray</span><span class="Punctuation">)</span></pre></p>

<h1><a class="toc-backref" id="procedures" href="#procedures">Procedures</a></h1><p>What most programming languages call <span id="methods_1">methods</span> or <span id="functions_1">functions</span> are called <span id="procedures_1">procedures</span> in Nim. A procedure declaration consists of an identifier, zero or more formal parameters, a return value type and a block of code. Formal parameters are declared as a list of identifiers separated by either comma or semicolon. A parameter is given a type by <tt class="docutils literal"><span class="pre"><span class="Punctuation">:</span> <span class="Identifier">typename</span></span></tt>. The type applies to all parameters immediately before it, until either the beginning of the parameter list, a semicolon separator, or an already typed parameter, is reached. The semicolon can be used to make separation of types and subsequent identifiers more distinct.</p>
<p><pre class="listing"><span class="Comment"># Using only commas</span>
<span class="Keyword">proc</span> <span class="Identifier">foo</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">,</span> <span class="Identifier">c</span><span class="Punctuation">,</span> <span class="Identifier">d</span><span class="Punctuation">:</span> <span class="Identifier">bool</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span>

<span class="Comment"># Using semicolon for visual distinction</span>
<span class="Keyword">proc</span> <span class="Identifier">foo</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">;</span> <span class="Identifier">c</span><span class="Punctuation">,</span> <span class="Identifier">d</span><span class="Punctuation">:</span> <span class="Identifier">bool</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span>

<span class="Comment"># Will fail: a is untyped since ';' stops type propagation.</span>
<span class="Keyword">proc</span> <span class="Identifier">foo</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">;</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">;</span> <span class="Identifier">c</span><span class="Punctuation">,</span> <span class="Identifier">d</span><span class="Punctuation">:</span> <span class="Identifier">bool</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span></pre></p>
<p>A parameter may be declared with a default value which is used if the caller does not provide a value for the argument. The value will be reevaluated every time the function is called.</p>
<p><pre class="listing"><span class="Comment"># b is optional with 47 as its default value.</span>
<span class="Keyword">proc</span> <span class="Identifier">foo</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span> <span class="DecNumber">47</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span></pre></p>
<p>Parameters can be declared mutable and so allow the proc to modify those arguments, by using the type modifier <tt class="docutils literal"><span class="pre"><span class="Keyword">var</span></span></tt>.</p>
<p><pre class="listing"><span class="Comment"># &quot;returning&quot; a value to the caller through the 2nd argument</span>
<span class="Comment"># Notice that the function uses no actual return value at all (ie void)</span>
<span class="Keyword">proc</span> <span class="Identifier">foo</span><span class="Punctuation">(</span><span class="Identifier">inp</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">,</span> <span class="Identifier">outp</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">int</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Identifier">outp</span> <span class="Operator">=</span> <span class="Identifier">inp</span> <span class="Operator">+</span> <span class="DecNumber">47</span></pre></p>
<p>If the proc declaration doesn't have a body, it is a <span id="forward_1">forward</span> declaration. If the proc returns a value, the procedure body can access an implicitly declared variable named <span id="result_2">result</span> that represents the return value. Procs can be overloaded. The overloading resolution algorithm determines which proc is the best match for the arguments. Example:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">toLower</span><span class="Punctuation">(</span><span class="Identifier">c</span><span class="Punctuation">:</span> <span class="Identifier">char</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">char</span> <span class="Operator">=</span> <span class="Comment"># toLower for characters</span>
  <span class="Keyword">if</span> <span class="Identifier">c</span> <span class="Keyword">in</span> <span class="Punctuation">{</span><span class="Punctuation">'</span><span class="Identifier">A</span><span class="CharLit">'..'</span><span class="Identifier">Z</span><span class="CharLit">'}:</span>
    <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">chr</span><span class="Punctuation">(</span><span class="Identifier">ord</span><span class="Punctuation">(</span><span class="Identifier">c</span><span class="Punctuation">)</span> <span class="Operator">+</span> <span class="Punctuation">(</span><span class="Identifier">ord</span><span class="Punctuation">(</span><span class="Punctuation">'</span><span class="Identifier">a</span><span class="CharLit">') - ord('</span><span class="Identifier">A</span><span class="CharLit">')))</span>
  <span class="Keyword">else</span><span class="Punctuation">:</span>
    <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">c</span>

<span class="Keyword">proc</span> <span class="Identifier">toLower</span><span class="Punctuation">(</span><span class="Identifier">s</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">string</span> <span class="Operator">=</span> <span class="Comment"># toLower for strings</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">newString</span><span class="Punctuation">(</span><span class="Identifier">len</span><span class="Punctuation">(</span><span class="Identifier">s</span><span class="Punctuation">)</span><span class="Punctuation">)</span>
  <span class="Keyword">for</span> <span class="Identifier">i</span> <span class="Keyword">in</span> <span class="FloatNumber">0.</span><span class="Operator">.</span><span class="Identifier">len</span><span class="Punctuation">(</span><span class="Identifier">s</span><span class="Punctuation">)</span> <span class="Operator">-</span> <span class="DecNumber">1</span><span class="Punctuation">:</span>
    <span class="Identifier">result</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Identifier">toLower</span><span class="Punctuation">(</span><span class="Identifier">s</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span><span class="Punctuation">)</span> <span class="Comment"># calls toLower for characters; no recursion!</span></pre></p>
<p>Calling a procedure can be done in many ways:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">callme</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">,</span> <span class="Identifier">s</span><span class="Punctuation">:</span> <span class="Identifier">string</span> <span class="Operator">=</span> <span class="StringLit">&quot;&quot;</span><span class="Punctuation">,</span> <span class="Identifier">c</span><span class="Punctuation">:</span> <span class="Identifier">char</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">bool</span> <span class="Operator">=</span> <span class="Identifier">false</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Operator">...</span>

<span class="Comment"># call with positional arguments      # parameter bindings:</span>
<span class="Identifier">callme</span><span class="Punctuation">(</span><span class="DecNumber">0</span><span class="Punctuation">,</span> <span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="StringLit">&quot;abc&quot;</span><span class="Punctuation">,</span> <span class="CharLit">'\t'</span><span class="Punctuation">,</span> <span class="Identifier">true</span><span class="Punctuation">)</span>       <span class="Comment"># (x=0, y=1, s=&quot;abc&quot;, c='\t', b=true)</span>
<span class="Comment"># call with named and positional arguments:</span>
<span class="Identifier">callme</span><span class="Punctuation">(</span><span class="Identifier">y</span><span class="Operator">=</span><span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="Identifier">x</span><span class="Operator">=</span><span class="DecNumber">0</span><span class="Punctuation">,</span> <span class="StringLit">&quot;abd&quot;</span><span class="Punctuation">,</span> <span class="CharLit">'\t'</span><span class="Punctuation">)</span>         <span class="Comment"># (x=0, y=1, s=&quot;abd&quot;, c='\t', b=false)</span>
<span class="Comment"># call with named arguments (order is not relevant):</span>
<span class="Identifier">callme</span><span class="Punctuation">(</span><span class="Identifier">c</span><span class="Operator">=</span><span class="CharLit">'\t'</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Operator">=</span><span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="Identifier">x</span><span class="Operator">=</span><span class="DecNumber">0</span><span class="Punctuation">)</span>              <span class="Comment"># (x=0, y=1, s=&quot;&quot;, c='\t', b=false)</span>
<span class="Comment"># call as a command statement: no () needed:</span>
<span class="Identifier">callme</span> <span class="DecNumber">0</span><span class="Punctuation">,</span> <span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="StringLit">&quot;abc&quot;</span><span class="Punctuation">,</span> <span class="CharLit">'\t'</span>              <span class="Comment"># (x=0, y=1, s=&quot;abc&quot;, c='\t', b=false)</span></pre></p>
<p>A procedure may call itself recursively.</p>
<p><span id="operators_1">Operators</span> are procedures with a special operator symbol as identifier:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">$</span><span class="Punctuation">`</span> <span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">string</span> <span class="Operator">=</span>
  <span class="Comment"># converts an integer to a string; this is a prefix operator.</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">intToStr</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span></pre></p>
<p>Operators with one parameter are prefix operators, operators with two parameters are infix operators. (However, the parser distinguishes these from the operator's position within an expression.) There is no way to declare postfix operators: all postfix operators are built-in and handled by the grammar explicitly.</p>
<p>Any operator can be called like an ordinary proc with the `opr` notation. (Thus an operator can have more than two parameters):</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">*+</span><span class="Punctuation">`</span> <span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">,</span> <span class="Identifier">c</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span>
  <span class="Comment"># Multiply and add</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">a</span> <span class="Operator">*</span> <span class="Identifier">b</span> <span class="Operator">+</span> <span class="Identifier">c</span>

<span class="Identifier">assert</span> <span class="Punctuation">`</span><span class="Operator">*+</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="DecNumber">3</span><span class="Punctuation">,</span> <span class="DecNumber">4</span><span class="Punctuation">,</span> <span class="DecNumber">6</span><span class="Punctuation">)</span> <span class="Operator">==</span> <span class="Punctuation">`</span><span class="Operator">+</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Punctuation">`</span><span class="Operator">*</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">)</span><span class="Punctuation">,</span> <span class="Identifier">c</span><span class="Punctuation">)</span></pre></p>

<h2><a class="toc-backref" id="procedures-export-marker" href="#procedures-export-marker">Export marker</a></h2><p>If a declared symbol is marked with an <span id="asterisk_1">asterisk</span> it is exported from the current module:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">exportedEcho</span><span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">s</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Identifier">echo</span> <span class="Identifier">s</span>
<span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">*</span><span class="Punctuation">`</span><span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">;</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">string</span> <span class="Operator">=</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">newStringOfCap</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Operator">.</span><span class="Identifier">len</span> <span class="Operator">*</span> <span class="Identifier">b</span><span class="Punctuation">)</span>
  <span class="Keyword">for</span> <span class="Identifier">i</span> <span class="Keyword">in</span> <span class="FloatNumber">1.</span><span class="Operator">.</span><span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">result</span><span class="Operator">.</span><span class="Identifier">add</span> <span class="Identifier">a</span>

<span class="Keyword">var</span> <span class="Identifier">exportedVar</span><span class="Operator">*:</span> <span class="Identifier">int</span>
<span class="Keyword">const</span> <span class="Identifier">exportedConst</span><span class="Operator">*</span> <span class="Operator">=</span> <span class="DecNumber">78</span>
<span class="Keyword">type</span>
  <span class="Identifier">ExportedType</span><span class="Operator">*</span> <span class="Operator">=</span> <span class="Keyword">object</span>
    <span class="Identifier">exportedField</span><span class="Operator">*:</span> <span class="Identifier">int</span></pre></p>

<h2><a class="toc-backref" id="procedures-method-call-syntax" href="#procedures-method-call-syntax">Method call syntax</a></h2><p>For object-oriented programming, the syntax <tt class="docutils literal"><span class="pre"><span class="Identifier">obj</span><span class="Operator">.</span><span class="Identifier">methodName</span><span class="Punctuation">(</span><span class="Identifier">args</span><span class="Punctuation">)</span></span></tt> can be used instead of <tt class="docutils literal"><span class="pre"><span class="Identifier">methodName</span><span class="Punctuation">(</span><span class="Identifier">obj</span><span class="Punctuation">,</span> <span class="Identifier">args</span><span class="Punctuation">)</span></span></tt>. The parentheses can be omitted if there are no remaining arguments: <tt class="docutils literal"><span class="pre"><span class="Identifier">obj</span><span class="Operator">.</span><span class="Identifier">len</span></span></tt> (instead of <tt class="docutils literal"><span class="pre"><span class="Identifier">len</span><span class="Punctuation">(</span><span class="Identifier">obj</span><span class="Punctuation">)</span></span></tt>).</p>
<p>This method call syntax is not restricted to objects, it can be used to supply any type of first argument for procedures:</p>
<p><pre class="listing"><span class="Identifier">echo</span> <span class="StringLit">&quot;abc&quot;</span><span class="Operator">.</span><span class="Identifier">len</span> <span class="Comment"># is the same as echo len &quot;abc&quot;</span>
<span class="Identifier">echo</span> <span class="StringLit">&quot;abc&quot;</span><span class="Operator">.</span><span class="Identifier">toUpper</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
<span class="Identifier">echo</span> <span class="Punctuation">{</span><span class="Punctuation">'</span><span class="Identifier">a</span><span class="CharLit">', '</span><span class="Identifier">b</span><span class="CharLit">', '</span><span class="Identifier">c</span><span class="CharLit">'}.card</span>
<span class="Identifier">stdout</span><span class="Operator">.</span><span class="Identifier">writeLine</span><span class="Punctuation">(</span><span class="StringLit">&quot;Hallo&quot;</span><span class="Punctuation">)</span> <span class="Comment"># the same as writeLine(stdout, &quot;Hallo&quot;)</span></pre></p>
<p>Another way to look at the method call syntax is that it provides the missing postfix notation.</p>
<p>The method call syntax conflicts with explicit generic instantiations: <tt class="docutils literal"><span class="pre"><span class="Identifier">p</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span></span></tt> cannot be written as <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">p</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span></span></tt> because <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">p</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span></span></tt> is always parsed as <tt class="docutils literal"><span class="pre"><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">p</span><span class="Punctuation">)</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span></span></tt>.</p>
<p>See also: <a class="reference internal" href="#templates-limitations-of-the-method-call-syntax">Limitations of the method call syntax</a>.</p>
<p>The <tt class="docutils literal"><span class="pre"><span class="Punctuation">[</span><span class="Punctuation">:</span> <span class="Punctuation">]</span></span></tt> notation has been designed to mitigate this issue: <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">p</span><span class="Punctuation">[</span><span class="Punctuation">:</span><span class="Identifier">T</span><span class="Punctuation">]</span></span></tt> is rewritten by the parser to <tt class="docutils literal"><span class="pre"><span class="Identifier">p</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">p</span><span class="Punctuation">[</span><span class="Punctuation">:</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">y</span><span class="Punctuation">)</span></span></tt> is rewritten to <tt class="docutils literal"><span class="pre"><span class="Identifier">p</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">)</span></span></tt>. Note that <tt class="docutils literal"><span class="pre"><span class="Punctuation">[</span><span class="Punctuation">:</span> <span class="Punctuation">]</span></span></tt> has no AST representation, the rewrite is performed directly in the parsing step.</p>

<h2><a class="toc-backref" id="procedures-properties" href="#procedures-properties">Properties</a></h2><p>Nim has no need for <em>get-properties</em>: Ordinary get-procedures that are called with the <em>method call syntax</em> achieve the same. But setting a value is different; for this, a special setter syntax is needed:</p>
<p><pre class="listing"><span class="Comment"># Module asocket</span>
<span class="Keyword">type</span>
  <span class="Identifier">Socket</span><span class="Operator">*</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Keyword">object</span> <span class="Keyword">of</span> <span class="Identifier">RootObj</span>
    <span class="Identifier">host</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Comment"># cannot be accessed from the outside of the module</span>

<span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Identifier">host</span><span class="Operator">=</span><span class="Punctuation">`</span><span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">s</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">Socket</span><span class="Punctuation">,</span> <span class="Identifier">value</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">inline</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
  <span class="Comment">## setter of hostAddr.</span>
  <span class="Comment">## This accesses the 'host' field and is not a recursive call to</span>
  <span class="Comment">## `host=` because the builtin dot access is preferred if it is</span>
  <span class="Comment">## available:</span>
  <span class="Identifier">s</span><span class="Operator">.</span><span class="Identifier">host</span> <span class="Operator">=</span> <span class="Identifier">value</span>

<span class="Keyword">proc</span> <span class="Identifier">host</span><span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">s</span><span class="Punctuation">:</span> <span class="Identifier">Socket</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">inline</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
  <span class="Comment">## getter of hostAddr</span>
  <span class="Comment">## This accesses the 'host' field and is not a recursive call to</span>
  <span class="Comment">## `host` because the builtin dot access is preferred if it is</span>
  <span class="Comment">## available:</span>
  <span class="Identifier">s</span><span class="Operator">.</span><span class="Identifier">host</span></pre></p>
<p><pre class="listing"><span class="Comment"># module B</span>
<span class="Keyword">import</span> <span class="Identifier">asocket</span>
<span class="Keyword">var</span> <span class="Identifier">s</span><span class="Punctuation">:</span> <span class="Identifier">Socket</span>
<span class="Identifier">new</span> <span class="Identifier">s</span>
<span class="Identifier">s</span><span class="Operator">.</span><span class="Identifier">host</span> <span class="Operator">=</span> <span class="DecNumber">34</span>  <span class="Comment"># same as `host=`(s, 34)</span></pre></p>
<p>A proc defined as <tt class="docutils literal"><span class="pre"><span class="Identifier">f</span><span class="Operator">=</span></span></tt> (with the trailing <tt class="docutils literal"><span class="pre"><span class="Operator">=</span></span></tt>) is called a <span id="setter_1">setter</span>. A setter can be called explicitly via the common backticks notation:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Identifier">f</span><span class="Operator">=</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">MyObject</span><span class="Punctuation">;</span> <span class="Identifier">value</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">discard</span>

<span class="Punctuation">`</span><span class="Identifier">f</span><span class="Operator">=</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">myObject</span><span class="Punctuation">,</span> <span class="StringLit">&quot;value&quot;</span><span class="Punctuation">)</span></pre></p>
<p><tt class="docutils literal"><span class="pre"><span class="Identifier">f</span><span class="Operator">=</span></span></tt> can be called implicitly in the pattern <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">f</span> <span class="Operator">=</span> <span class="Identifier">value</span></span></tt> if and only if the type of <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span></span></tt> does not have a field named <tt class="docutils literal"><span class="pre"><span class="Identifier">f</span></span></tt> or if <tt class="docutils literal"><span class="pre"><span class="Identifier">f</span></span></tt> is not visible in the current module. These rules ensure that object fields and accessors can have the same name. Within the module <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">f</span></span></tt> is then always interpreted as field access and outside the module it is interpreted as an accessor proc call.</p>

<h2><a class="toc-backref" id="procedures-command-invocation-syntax" href="#procedures-command-invocation-syntax">Command invocation syntax</a></h2><p>Routines can be invoked without the <tt class="docutils literal"><span class="pre"><span class="Punctuation">(</span><span class="Punctuation">)</span></span></tt> if the call is syntactically a statement. This command invocation syntax also works for expressions, but then only a single argument may follow. This restriction means <tt class="docutils literal"><span class="pre"><span class="Identifier">echo</span> <span class="Identifier">f</span> <span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="Identifier">f</span> <span class="DecNumber">2</span></span></tt> is parsed as <tt class="docutils literal"><span class="pre"><span class="Identifier">echo</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">(</span><span class="DecNumber">1</span><span class="Punctuation">)</span><span class="Punctuation">,</span> <span class="Identifier">f</span><span class="Punctuation">(</span><span class="DecNumber">2</span><span class="Punctuation">)</span><span class="Punctuation">)</span></span></tt> and not as <tt class="docutils literal"><span class="pre"><span class="Identifier">echo</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">(</span><span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="Identifier">f</span><span class="Punctuation">(</span><span class="DecNumber">2</span><span class="Punctuation">)</span><span class="Punctuation">)</span><span class="Punctuation">)</span></span></tt>. The method call syntax may be used to provide one more argument in this case:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">optarg</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span> <span class="DecNumber">0</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span> <span class="Identifier">x</span> <span class="Operator">+</span> <span class="Identifier">y</span>
<span class="Keyword">proc</span> <span class="Identifier">singlearg</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span> <span class="DecNumber">20</span><span class="Operator">*</span><span class="Identifier">x</span>

<span class="Identifier">echo</span> <span class="Identifier">optarg</span> <span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="StringLit">&quot; &quot;</span><span class="Punctuation">,</span> <span class="Identifier">singlearg</span> <span class="DecNumber">2</span>  <span class="Comment"># prints &quot;1 40&quot;</span>

<span class="Keyword">let</span> <span class="Identifier">fail</span> <span class="Operator">=</span> <span class="Identifier">optarg</span> <span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="Identifier">optarg</span> <span class="DecNumber">8</span>   <span class="Comment"># Wrong. Too many arguments for a command call</span>
<span class="Keyword">let</span> <span class="Identifier">x</span> <span class="Operator">=</span> <span class="Identifier">optarg</span><span class="Punctuation">(</span><span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="Identifier">optarg</span> <span class="DecNumber">8</span><span class="Punctuation">)</span>  <span class="Comment"># traditional procedure call with 2 arguments</span>
<span class="Keyword">let</span> <span class="Identifier">y</span> <span class="Operator">=</span> <span class="FloatNumber">1.</span><span class="Identifier">optarg</span> <span class="Identifier">optarg</span> <span class="DecNumber">8</span>    <span class="Comment"># same thing as above, w/o the parenthesis</span>
<span class="Identifier">assert</span> <span class="Identifier">x</span> <span class="Operator">==</span> <span class="Identifier">y</span></pre></p>
<p>The command invocation syntax also can't have complex expressions as arguments. For example: <a class="reference internal" href="#procedures-anonymous-procedures">anonymous procedures</a>, <tt class="docutils literal"><span class="pre"><span class="Keyword">if</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">case</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Keyword">try</span></span></tt>. Function calls with no arguments still need () to distinguish between a call and the function itself as a first-class value.</p>

<h2><a class="toc-backref" id="procedures-closures" href="#procedures-closures">Closures</a></h2><p>Procedures can appear at the top level in a module as well as inside other scopes, in which case they are called nested procs. A nested proc can access local variables from its enclosing scope and if it does so it becomes a closure. Any captured variables are stored in a hidden additional argument to the closure (its environment) and they are accessed by reference by both the closure and its enclosing scope (i.e. any modifications made to them are visible in both places). The closure environment may be allocated on the heap or on the stack if the compiler determines that this would be safe.</p>

<h3><a class="toc-backref" id="closures-creating-closures-in-loops" href="#closures-creating-closures-in-loops">Creating closures in loops</a></h3><p>Since closures capture local variables by reference it is often not wanted behavior inside loop bodies. See <a class="reference external" href=" system.html#closureScope.t,untyped">closureScope</a> and <a class="reference external" href=" sugar.html#capture.m,varargs[typed],untyped">capture</a> for details on how to change this behavior.</p>

<h2><a class="toc-backref" id="procedures-anonymous-procedures" href="#procedures-anonymous-procedures">Anonymous procedures</a></h2><p>Unnamed procedures can be used as lambda expressions to pass into other procedures:</p>
<p><pre class="listing"><span class="Keyword">var</span> <span class="Identifier">cities</span> <span class="Operator">=</span> <span class="Operator">@</span><span class="Punctuation">[</span><span class="StringLit">&quot;Frankfurt&quot;</span><span class="Punctuation">,</span> <span class="StringLit">&quot;Tokyo&quot;</span><span class="Punctuation">,</span> <span class="StringLit">&quot;New York&quot;</span><span class="Punctuation">,</span> <span class="StringLit">&quot;Kyiv&quot;</span><span class="Punctuation">]</span>

<span class="Identifier">cities</span><span class="Operator">.</span><span class="Identifier">sort</span><span class="Punctuation">(</span><span class="Keyword">proc</span> <span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span>
  <span class="Identifier">cmp</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">len</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Operator">.</span><span class="Identifier">len</span><span class="Punctuation">)</span><span class="Punctuation">)</span></pre></p>
<p>Procs as expressions can appear both as nested procs and inside top-level executable code. The  <a class="reference external" href="sugar.html">sugar</a> module contains the <tt class="docutils literal"><span class="pre"><span class="Operator">=&gt;</span></span></tt> macro which enables a more succinct syntax for anonymous procedures resembling lambdas as they are in languages like JavaScript, C#, etc.</p>

<h2><a class="toc-backref" id="procedures-do-notation" href="#procedures-do-notation">Do notation</a></h2><p>As a special convenience notation that keeps most elements of a regular proc expression, the <tt class="docutils literal"><span class="pre"><span class="Keyword">do</span></span></tt> keyword can be used to pass anonymous procedures to routines:</p>
<p><pre class="listing"><span class="Keyword">var</span> <span class="Identifier">cities</span> <span class="Operator">=</span> <span class="Operator">@</span><span class="Punctuation">[</span><span class="StringLit">&quot;Frankfurt&quot;</span><span class="Punctuation">,</span> <span class="StringLit">&quot;Tokyo&quot;</span><span class="Punctuation">,</span> <span class="StringLit">&quot;New York&quot;</span><span class="Punctuation">,</span> <span class="StringLit">&quot;Kyiv&quot;</span><span class="Punctuation">]</span>

<span class="Identifier">sort</span><span class="Punctuation">(</span><span class="Identifier">cities</span><span class="Punctuation">)</span> <span class="Keyword">do</span> <span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">)</span> <span class="Operator">-&gt;</span> <span class="Identifier">int</span><span class="Punctuation">:</span>
  <span class="Identifier">cmp</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">len</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Operator">.</span><span class="Identifier">len</span><span class="Punctuation">)</span>

<span class="Comment"># Less parentheses using the method plus command syntax:</span>
<span class="Identifier">cities</span> <span class="Operator">=</span> <span class="Identifier">cities</span><span class="Operator">.</span><span class="Identifier">map</span> <span class="Keyword">do</span> <span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">)</span> <span class="Operator">-&gt;</span> <span class="Identifier">string</span><span class="Punctuation">:</span>
  <span class="StringLit">&quot;City of &quot;</span> <span class="Operator">&amp;</span> <span class="Identifier">x</span></pre></p>
<p><tt class="docutils literal"><span class="pre"><span class="Keyword">do</span></span></tt> is written after the parentheses enclosing the regular proc parameters. The proc expression represented by the <tt class="docutils literal"><span class="pre"><span class="Keyword">do</span></span></tt> block is appended to the routine call as the last argument. In calls using the command syntax, the <tt class="docutils literal"><span class="pre"><span class="Keyword">do</span></span></tt> block will bind to the immediately preceding expression rather than the command call.</p>
<p><tt class="docutils literal"><span class="pre"><span class="Keyword">do</span></span></tt> with a parameter list or pragma list corresponds to an anonymous <tt class="docutils literal"><span class="pre"><span class="Keyword">proc</span></span></tt>, however <tt class="docutils literal"><span class="pre"><span class="Keyword">do</span></span></tt> without parameters or pragmas is treated as a normal statement list. This allows macros to receive both indented statement lists as an argument in inline calls, as well as a direct mirror of Nim's routine syntax.</p>
<p><pre class="listing"><span class="Comment"># Passing a statement list to an inline macro:</span>
<span class="Identifier">macroResults</span><span class="Operator">.</span><span class="Identifier">add</span> <span class="Identifier">quote</span> <span class="Keyword">do</span><span class="Punctuation">:</span>
  <span class="Keyword">if</span> <span class="Keyword">not</span> <span class="Punctuation">`</span><span class="Identifier">ex</span><span class="Punctuation">`</span><span class="Punctuation">:</span>
    <span class="Identifier">echo</span> <span class="Punctuation">`</span><span class="Identifier">info</span><span class="Punctuation">`</span><span class="Punctuation">,</span> <span class="StringLit">&quot;: Check failed: &quot;</span><span class="Punctuation">,</span> <span class="Punctuation">`</span><span class="Identifier">expString</span><span class="Punctuation">`</span>

<span class="Comment"># Processing a routine definition in a macro:</span>
<span class="Identifier">rpc</span><span class="Punctuation">(</span><span class="Identifier">router</span><span class="Punctuation">,</span> <span class="StringLit">&quot;add&quot;</span><span class="Punctuation">)</span> <span class="Keyword">do</span> <span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span> <span class="Operator">-&gt;</span> <span class="Identifier">int</span><span class="Punctuation">:</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">a</span> <span class="Operator">+</span> <span class="Identifier">b</span></pre></p>

<h2><a class="toc-backref" id="procedures-func" href="#procedures-func">Func</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Keyword">func</span></span></tt> keyword introduces a shortcut for a <span id="nosideeffect_1">noSideEffect</span> proc.</p>
<p><pre class="listing"><span class="Keyword">func</span> <span class="Identifier">binarySearch</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">openArray</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">;</span> <span class="Identifier">elem</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span></pre></p>
<p>Is short for:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">binarySearch</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">openArray</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">;</span> <span class="Identifier">elem</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">noSideEffect</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>

<h2><a class="toc-backref" id="procedures-routines" href="#procedures-routines">Routines</a></h2><p>A routine is a symbol of kind: <tt class="docutils literal"><span class="pre"><span class="Keyword">proc</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">func</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">method</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">iterator</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">macro</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">template</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">converter</span></span></tt>.</p>

<h2><a class="toc-backref" id="procedures-type-bound-operators" href="#procedures-type-bound-operators">Type bound operators</a></h2><p>A type bound operator is a <tt class="docutils literal"><span class="pre"><span class="Keyword">proc</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Keyword">func</span></span></tt> whose name starts with <tt class="docutils literal"><span class="pre"><span class="Operator">=</span></span></tt> but isn't an operator (i.e. containing only symbols, such as <tt class="docutils literal"><span class="pre"><span class="Operator">==</span></span></tt>). These are unrelated to setters (see <a class="reference internal" href="#procedures-properties">Properties</a>), which instead end in <tt class="docutils literal"><span class="pre"><span class="Operator">=</span></span></tt>. A type bound operator declared for a type applies to the type regardless of whether the operator is in scope (including if it is private).</p>
<p><pre class="listing"><span class="Comment"># foo.nim:</span>
<span class="Keyword">var</span> <span class="Identifier">witness</span><span class="Operator">*</span> <span class="Operator">=</span> <span class="DecNumber">0</span>
<span class="Keyword">type</span> <span class="Identifier">Foo</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Keyword">object</span>
<span class="Keyword">proc</span> <span class="Identifier">initFoo</span><span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">T</span><span class="Punctuation">:</span> <span class="Identifier">typedesc</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">Foo</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Keyword">discard</span>
<span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">destroy</span><span class="Punctuation">`</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">Foo</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Identifier">witness</span><span class="Operator">.</span><span class="Identifier">inc</span> <span class="Comment"># type bound operator</span>

<span class="Comment"># main.nim:</span>
<span class="Keyword">import</span> <span class="Identifier">foo</span>
<span class="Keyword">block</span><span class="Punctuation">:</span>
  <span class="Keyword">var</span> <span class="Identifier">a</span> <span class="Operator">=</span> <span class="Identifier">initFoo</span><span class="Punctuation">(</span><span class="Identifier">int</span><span class="Punctuation">)</span>
  <span class="Identifier">doAssert</span> <span class="Identifier">witness</span> <span class="Operator">==</span> <span class="DecNumber">0</span>
<span class="Identifier">doAssert</span> <span class="Identifier">witness</span> <span class="Operator">==</span> <span class="DecNumber">1</span>
<span class="Keyword">block</span><span class="Punctuation">:</span>
  <span class="Keyword">var</span> <span class="Identifier">a</span> <span class="Operator">=</span> <span class="Identifier">initFoo</span><span class="Punctuation">(</span><span class="Identifier">int</span><span class="Punctuation">)</span>
  <span class="Identifier">doAssert</span> <span class="Identifier">witness</span> <span class="Operator">==</span> <span class="DecNumber">1</span>
  <span class="Punctuation">`</span><span class="Operator">=</span><span class="Identifier">destroy</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">)</span> <span class="Comment"># can be called explicitly, even without being in scope</span>
  <span class="Identifier">doAssert</span> <span class="Identifier">witness</span> <span class="Operator">==</span> <span class="DecNumber">2</span>
<span class="Comment"># will still be called upon exiting scope</span>
<span class="Identifier">doAssert</span> <span class="Identifier">witness</span> <span class="Operator">==</span> <span class="DecNumber">3</span></pre></p>
<p>Type bound operators are: <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">destroy</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">copy</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">sink</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">trace</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">deepcopy</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">wasMoved</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">dup</span></span></tt>.</p>
<p>These operations can be <em>overridden</em> instead of <em>overloaded</em>. This means that the implementation is automatically lifted to structured types. For instance, if the type <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span></span></tt> has an overridden assignment operator <tt class="docutils literal"><span class="pre"><span class="Operator">=</span></span></tt>, this operator is also used for assignments of the type <tt class="docutils literal"><span class="pre"><span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span></span></tt>.</p>
<p>Since these operations are bound to a type, they have to be bound to a nominal type for reasons of simplicity of implementation; this means an overridden <tt class="docutils literal"><span class="pre"><span class="Identifier">deepCopy</span></span></tt> for <tt class="docutils literal"><span class="pre"><span class="Keyword">ref</span> <span class="Identifier">T</span></span></tt> is really bound to <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span></span></tt> and not to <tt class="docutils literal"><span class="pre"><span class="Keyword">ref</span> <span class="Identifier">T</span></span></tt>. This also means that one cannot override <tt class="docutils literal"><span class="pre"><span class="Identifier">deepCopy</span></span></tt> for both <tt class="docutils literal"><span class="pre"><span class="Keyword">ptr</span> <span class="Identifier">T</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Keyword">ref</span> <span class="Identifier">T</span></span></tt> at the same time, instead a distinct or object helper type has to be used for one pointer type.</p>
<p>For more details on some of those procs, see <a class="reference external" href="destructors.html#lifetimeminustracking-hooks">Lifetime-tracking hooks</a>.</p>

<h2><a class="toc-backref" id="procedures-nonoverloadable-builtins" href="#procedures-nonoverloadable-builtins">Nonoverloadable builtins</a></h2><p>The following built-in procs cannot be overloaded for reasons of implementation simplicity (they require specialized semantic checking):</p>
<pre>declared, defined, definedInScope, compiles, sizeof,
is, shallowCopy, getAst, astToStr, spawn, procCall</pre>
<p>Thus, they act more like keywords than like ordinary identifiers; unlike a keyword however, a redefinition may <span id="shadow_1">shadow</span> the definition in the <a class="reference external" href="system.html">system</a> module. From this list the following should not be written in dot notation <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">f</span></span></tt> since <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span></span></tt> cannot be type-checked before it gets passed to <tt class="docutils literal"><span class="pre"><span class="Identifier">f</span></span></tt>:</p>
<pre>declared, defined, definedInScope, compiles, getAst, astToStr</pre>

<h2><a class="toc-backref" id="procedures-var-parameters" href="#procedures-var-parameters">Var parameters</a></h2><p>The type of a parameter may be prefixed with the <tt class="docutils literal"><span class="pre"><span class="Keyword">var</span></span></tt> keyword:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">divmod</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">;</span> <span class="Identifier">res</span><span class="Punctuation">,</span> <span class="Identifier">remainder</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">int</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Identifier">res</span> <span class="Operator">=</span> <span class="Identifier">a</span> <span class="Keyword">div</span> <span class="Identifier">b</span>
  <span class="Identifier">remainder</span> <span class="Operator">=</span> <span class="Identifier">a</span> <span class="Keyword">mod</span> <span class="Identifier">b</span>

<span class="Keyword">var</span>
  <span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">int</span>

<span class="Identifier">divmod</span><span class="Punctuation">(</span><span class="DecNumber">8</span><span class="Punctuation">,</span> <span class="DecNumber">5</span><span class="Punctuation">,</span> <span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">)</span> <span class="Comment"># modifies x and y</span>
<span class="Identifier">assert</span> <span class="Identifier">x</span> <span class="Operator">==</span> <span class="DecNumber">1</span>
<span class="Identifier">assert</span> <span class="Identifier">y</span> <span class="Operator">==</span> <span class="DecNumber">3</span></pre></p>
<p>In the example, <tt class="docutils literal"><span class="pre"><span class="Identifier">res</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">remainder</span></span></tt> are <tt class="docutils literal"><span class="pre"><span class="Keyword">var</span> <span class="Identifier">parameters</span></span></tt>. Var parameters can be modified by the procedure and the changes are visible to the caller. The argument passed to a var parameter has to be an l-value. Var parameters are implemented as hidden pointers. The above example is equivalent to:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">divmod</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">;</span> <span class="Identifier">res</span><span class="Punctuation">,</span> <span class="Identifier">remainder</span><span class="Punctuation">:</span> <span class="Keyword">ptr</span> <span class="Identifier">int</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Identifier">res</span><span class="Punctuation">[</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Identifier">a</span> <span class="Keyword">div</span> <span class="Identifier">b</span>
  <span class="Identifier">remainder</span><span class="Punctuation">[</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Identifier">a</span> <span class="Keyword">mod</span> <span class="Identifier">b</span>

<span class="Keyword">var</span>
  <span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">int</span>
<span class="Identifier">divmod</span><span class="Punctuation">(</span><span class="DecNumber">8</span><span class="Punctuation">,</span> <span class="DecNumber">5</span><span class="Punctuation">,</span> <span class="Keyword">addr</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span><span class="Punctuation">,</span> <span class="Keyword">addr</span><span class="Punctuation">(</span><span class="Identifier">y</span><span class="Punctuation">)</span><span class="Punctuation">)</span>
<span class="Identifier">assert</span> <span class="Identifier">x</span> <span class="Operator">==</span> <span class="DecNumber">1</span>
<span class="Identifier">assert</span> <span class="Identifier">y</span> <span class="Operator">==</span> <span class="DecNumber">3</span></pre></p>
<p>In the examples, var parameters or pointers are used to provide two return values. This can be done in a cleaner way by returning a tuple:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">divmod</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Keyword">tuple</span><span class="Punctuation">[</span><span class="Identifier">res</span><span class="Punctuation">,</span> <span class="Identifier">remainder</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">]</span> <span class="Operator">=</span>
  <span class="Punctuation">(</span><span class="Identifier">a</span> <span class="Keyword">div</span> <span class="Identifier">b</span><span class="Punctuation">,</span> <span class="Identifier">a</span> <span class="Keyword">mod</span> <span class="Identifier">b</span><span class="Punctuation">)</span>

<span class="Keyword">var</span> <span class="Identifier">t</span> <span class="Operator">=</span> <span class="Identifier">divmod</span><span class="Punctuation">(</span><span class="DecNumber">8</span><span class="Punctuation">,</span> <span class="DecNumber">5</span><span class="Punctuation">)</span>

<span class="Identifier">assert</span> <span class="Identifier">t</span><span class="Operator">.</span><span class="Identifier">res</span> <span class="Operator">==</span> <span class="DecNumber">1</span>
<span class="Identifier">assert</span> <span class="Identifier">t</span><span class="Operator">.</span><span class="Identifier">remainder</span> <span class="Operator">==</span> <span class="DecNumber">3</span></pre></p>
<p>One can use <span id="tuple-unpacking_1">tuple unpacking</span> to access the tuple's fields:</p>
<p><pre class="listing"><span class="Keyword">var</span> <span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Identifier">divmod</span><span class="Punctuation">(</span><span class="DecNumber">8</span><span class="Punctuation">,</span> <span class="DecNumber">5</span><span class="Punctuation">)</span> <span class="Comment"># tuple unpacking</span>
<span class="Identifier">assert</span> <span class="Identifier">x</span> <span class="Operator">==</span> <span class="DecNumber">1</span>
<span class="Identifier">assert</span> <span class="Identifier">y</span> <span class="Operator">==</span> <span class="DecNumber">3</span></pre></p>
<p><strong>Note</strong>: <tt class="docutils literal"><span class="pre"><span class="Keyword">var</span></span></tt> parameters are never necessary for efficient parameter passing. Since non-var parameters cannot be modified the compiler is always free to pass arguments by reference if it considers it can speed up execution.</p>

<h2><a class="toc-backref" id="procedures-var-return-type" href="#procedures-var-return-type">Var return type</a></h2><p>A proc, converter, or iterator may return a <tt class="docutils literal"><span class="pre"><span class="Keyword">var</span></span></tt> type which means that the returned value is an l-value and can be modified by the caller:</p>
<p><pre class="listing"><span class="Keyword">var</span> <span class="Identifier">g</span> <span class="Operator">=</span> <span class="DecNumber">0</span>

<span class="Keyword">proc</span> <span class="Identifier">writeAccessToG</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">int</span> <span class="Operator">=</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">g</span>

<span class="Identifier">writeAccessToG</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="DecNumber">6</span>
<span class="Identifier">assert</span> <span class="Identifier">g</span> <span class="Operator">==</span> <span class="DecNumber">6</span></pre></p>
<p>It is a static error if the implicitly introduced pointer could be used to access a location beyond its lifetime:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">writeAccessToG</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">int</span> <span class="Operator">=</span>
  <span class="Keyword">var</span> <span class="Identifier">g</span> <span class="Operator">=</span> <span class="DecNumber">0</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">g</span> <span class="Comment"># Error!</span></pre></p>
<p>For iterators, a component of a tuple return type can have a <tt class="docutils literal"><span class="pre"><span class="Keyword">var</span></span></tt> type too:</p>
<p><pre class="listing"><span class="Keyword">iterator</span> <span class="Identifier">mpairs</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">string</span><span class="Punctuation">]</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Keyword">tuple</span><span class="Punctuation">[</span><span class="Identifier">key</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">,</span> <span class="Identifier">val</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">string</span><span class="Punctuation">]</span> <span class="Operator">=</span>
  <span class="Keyword">for</span> <span class="Identifier">i</span> <span class="Keyword">in</span> <span class="FloatNumber">0.</span><span class="Operator">.</span><span class="Identifier">a</span><span class="Operator">.</span><span class="Identifier">high</span><span class="Punctuation">:</span>
    <span class="Keyword">yield</span> <span class="Punctuation">(</span><span class="Identifier">i</span><span class="Punctuation">,</span> <span class="Identifier">a</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span><span class="Punctuation">)</span></pre></p>
<p>In the standard library every name of a routine that returns a <tt class="docutils literal"><span class="pre"><span class="Keyword">var</span></span></tt> type starts with the prefix <tt class="docutils literal"><span class="pre"><span class="Identifier">m</span></span></tt> per convention.</p>
<p>Memory safety for returning by <tt class="docutils literal"><span class="pre"><span class="Keyword">var</span> <span class="Identifier">T</span></span></tt> is ensured by a simple borrowing rule: If <tt class="docutils literal"><span class="pre"><span class="Identifier">result</span></span></tt> does not refer to a location pointing to the heap (that is in <tt class="docutils literal"><span class="pre"><span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">X</span></span></tt> the <tt class="docutils literal"><span class="pre"><span class="Identifier">X</span></span></tt> involves a <tt class="docutils literal"><span class="pre"><span class="Keyword">ptr</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Keyword">ref</span></span></tt> access) then it has to be derived from the routine's first parameter:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">forward</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">T</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">T</span> <span class="Operator">=</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">x</span> <span class="Comment"># ok, derived from the first parameter.</span>

<span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Identifier">param</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">int</span> <span class="Operator">=</span>
  <span class="Keyword">var</span> <span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">int</span>
  <span class="Comment"># we know 'forward' provides a view into the location derived from</span>
  <span class="Comment"># its first argument 'x'.</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">forward</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span> <span class="Comment"># Error: location is derived from `x`</span>
                      <span class="Comment"># which is not p's first parameter and lives</span>
                      <span class="Comment"># on the stack.</span></pre></p>
<p>In other words, the lifetime of what <tt class="docutils literal"><span class="pre"><span class="Identifier">result</span></span></tt> points to is attached to the lifetime of the first parameter and that is enough knowledge to verify memory safety at the call site. </p>

<h3><a class="toc-backref" id="var-return-type-future-directions" href="#var-return-type-future-directions">Future directions</a></h3><p>Later versions of Nim can be more precise about the borrowing rule with a syntax like:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">foo</span><span class="Punctuation">(</span><span class="Identifier">other</span><span class="Punctuation">:</span> <span class="Identifier">Y</span><span class="Punctuation">;</span> <span class="Identifier">container</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">X</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">T</span> <span class="Keyword">from</span> <span class="Identifier">container</span></pre></p>
<p>Here <tt class="docutils literal"><span class="pre"><span class="Keyword">var</span> <span class="Identifier">T</span> <span class="Keyword">from</span> <span class="Identifier">container</span></span></tt> explicitly exposes that the location is derived from the second parameter (called 'container' in this case). The syntax <tt class="docutils literal"><span class="pre"><span class="Keyword">var</span> <span class="Identifier">T</span> <span class="Keyword">from</span> <span class="Identifier">p</span></span></tt> specifies a type <tt class="docutils literal"><span class="pre"><span class="Identifier">varTy</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">,</span> <span class="DecNumber">2</span><span class="Punctuation">]</span></span></tt> which is incompatible with <tt class="docutils literal"><span class="pre"><span class="Identifier">varTy</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">,</span> <span class="DecNumber">1</span><span class="Punctuation">]</span></span></tt>.</p>

<h2><a class="toc-backref" id="procedures-nrvo" href="#procedures-nrvo">NRVO</a></h2><p><strong>Note</strong>: This section describes the current implementation. This part of the language specification will be changed. See <a class="reference external" href="https://github.com/nim-lang/RFCs/issues/230">https://github.com/nim-lang/RFCs/issues/230</a> for more information.</p>
<p>The return value is represented inside the body of a routine as the special <span id="result_3">result</span> variable. This allows for a mechanism much like C++'s &quot;named return value optimization&quot; (<span id="nrvo_1">NRVO</span>). NRVO means that the stores to <tt class="docutils literal"><span class="pre"><span class="Identifier">result</span></span></tt> inside <tt class="docutils literal"><span class="pre"><span class="Identifier">p</span></span></tt> directly affect the destination <tt class="docutils literal"><span class="pre"><span class="Identifier">dest</span></span></tt> in <tt class="docutils literal"><span class="pre"><span class="Keyword">let</span><span class="Operator">/</span><span class="Keyword">var</span> <span class="Identifier">dest</span> <span class="Operator">=</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Identifier">args</span><span class="Punctuation">)</span></span></tt> (definition of <tt class="docutils literal"><span class="pre"><span class="Identifier">dest</span></span></tt>) and also in <tt class="docutils literal"><span class="pre"><span class="Identifier">dest</span> <span class="Operator">=</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Identifier">args</span><span class="Punctuation">)</span></span></tt> (assignment to <tt class="docutils literal"><span class="pre"><span class="Identifier">dest</span></span></tt>). This is achieved by rewriting <tt class="docutils literal"><span class="pre"><span class="Identifier">dest</span> <span class="Operator">=</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Identifier">args</span><span class="Punctuation">)</span></span></tt> to <tt class="docutils literal"><span class="pre"><span class="Identifier">p</span><span class="CharLit">'(args, dest)</span></span></tt> where <tt class="docutils literal"><span class="pre"><span class="Identifier">p</span><span class="CharLit">'</span></span></tt> is a variation of <tt class="docutils literal"><span class="pre"><span class="Identifier">p</span></span></tt> that returns <tt class="docutils literal"><span class="pre"><span class="Identifier">void</span></span></tt> and receives a hidden mutable parameter representing <tt class="docutils literal"><span class="pre"><span class="Identifier">result</span></span></tt>.</p>
<p>Informally:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">BigT</span> <span class="Operator">=</span> <span class="Operator">...</span>

<span class="Keyword">var</span> <span class="Identifier">x</span> <span class="Operator">=</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
<span class="Identifier">x</span> <span class="Operator">=</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Punctuation">)</span>

<span class="Comment"># is roughly turned into:</span>

<span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Identifier">result</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">BigT</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Operator">...</span>

<span class="Keyword">var</span> <span class="Identifier">x</span><span class="Punctuation">;</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span>
<span class="Identifier">p</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span></pre></p>
<p>Let <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span></span></tt>'s be <tt class="docutils literal"><span class="pre"><span class="Identifier">p</span></span></tt>'s return type. NRVO applies for <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span></span></tt> if <tt class="docutils literal"><span class="pre"><span class="Identifier">sizeof</span><span class="Punctuation">(</span><span class="Identifier">T</span><span class="Punctuation">)</span> <span class="Operator">&gt;=</span> <span class="Identifier">N</span></span></tt> (where <tt class="docutils literal"><span class="pre"><span class="Identifier">N</span></span></tt> is implementation dependent), in other words, it applies for &quot;big&quot; structures.</p>
<p>If <tt class="docutils literal"><span class="pre"><span class="Identifier">p</span></span></tt> can raise an exception, NRVO applies regardless. This can produce observable differences in behavior:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">BigT</span> <span class="Operator">=</span> <span class="Identifier">array</span><span class="Punctuation">[</span><span class="DecNumber">16</span><span class="Punctuation">,</span> <span class="Identifier">int</span><span class="Punctuation">]</span>

<span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Identifier">raiseAt</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">BigT</span> <span class="Operator">=</span>
  <span class="Keyword">for</span> <span class="Identifier">i</span> <span class="Keyword">in</span> <span class="FloatNumber">0.</span><span class="Operator">.</span><span class="Identifier">high</span><span class="Punctuation">(</span><span class="Identifier">result</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
    <span class="Keyword">if</span> <span class="Identifier">i</span> <span class="Operator">==</span> <span class="Identifier">raiseAt</span><span class="Punctuation">:</span> <span class="Keyword">raise</span> <span class="Identifier">newException</span><span class="Punctuation">(</span><span class="Identifier">ValueError</span><span class="Punctuation">,</span> <span class="StringLit">&quot;interception&quot;</span><span class="Punctuation">)</span>
    <span class="Identifier">result</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Identifier">i</span>

<span class="Keyword">proc</span> <span class="Identifier">main</span> <span class="Operator">=</span>
  <span class="Keyword">var</span> <span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">BigT</span>
  <span class="Keyword">try</span><span class="Punctuation">:</span>
    <span class="Identifier">x</span> <span class="Operator">=</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="DecNumber">8</span><span class="Punctuation">)</span>
  <span class="Keyword">except</span> <span class="Identifier">ValueError</span><span class="Punctuation">:</span>
    <span class="Identifier">doAssert</span> <span class="Identifier">x</span> <span class="Operator">==</span> <span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">,</span> <span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="DecNumber">2</span><span class="Punctuation">,</span> <span class="DecNumber">3</span><span class="Punctuation">,</span> <span class="DecNumber">4</span><span class="Punctuation">,</span> <span class="DecNumber">5</span><span class="Punctuation">,</span> <span class="DecNumber">6</span><span class="Punctuation">,</span> <span class="DecNumber">7</span><span class="Punctuation">,</span> <span class="DecNumber">0</span><span class="Punctuation">,</span> <span class="DecNumber">0</span><span class="Punctuation">,</span> <span class="DecNumber">0</span><span class="Punctuation">,</span> <span class="DecNumber">0</span><span class="Punctuation">,</span> <span class="DecNumber">0</span><span class="Punctuation">,</span> <span class="DecNumber">0</span><span class="Punctuation">,</span> <span class="DecNumber">0</span><span class="Punctuation">,</span> <span class="DecNumber">0</span><span class="Punctuation">]</span>

<span class="Identifier">main</span><span class="Punctuation">(</span><span class="Punctuation">)</span></pre></p>
<p>The compiler can produce a warning in these cases, however this behavior is turned off by default. It can be enabled for a section of code via the <tt class="docutils literal"><span class="pre"><span class="Identifier">warning</span><span class="Punctuation">[</span><span class="Identifier">ObservableStores</span><span class="Punctuation">]</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">push</span></span></tt>/<tt class="docutils literal"><span class="pre"><span class="Identifier">pop</span></span></tt> pragmas. Take the above code as an example:</p>
<p><pre class="listing"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">push</span> <span class="Identifier">warning</span><span class="Punctuation">[</span><span class="Identifier">ObservableStores</span><span class="Punctuation">]</span><span class="Punctuation">:</span> <span class="Identifier">on</span><span class="Operator">.</span><span class="Punctuation">}</span>
<span class="Identifier">main</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
<span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">pop</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>

<h2><a class="toc-backref" id="procedures-overloading-of-the-subscript-operator" href="#procedures-overloading-of-the-subscript-operator">Overloading of the subscript operator</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Punctuation">[</span><span class="Punctuation">]</span></span></tt> subscript operator for arrays/openarrays/sequences can be overloaded for any type (with some exceptions) by defining a routine with the name <tt class="docutils literal"><span class="pre"><span class="Punctuation">[</span><span class="Punctuation">]</span></span></tt>.</p>
<p><pre class="listing"><span class="Keyword">type</span> <span class="Identifier">Foo</span> <span class="Operator">=</span> <span class="Keyword">object</span>
  <span class="Identifier">data</span><span class="Punctuation">:</span> <span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">int</span><span class="Punctuation">]</span>

<span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">foo</span><span class="Punctuation">:</span> <span class="Identifier">Foo</span><span class="Punctuation">,</span> <span class="Identifier">i</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">foo</span><span class="Operator">.</span><span class="Identifier">data</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span>

<span class="Keyword">let</span> <span class="Identifier">foo</span> <span class="Operator">=</span> <span class="Identifier">Foo</span><span class="Punctuation">(</span><span class="Identifier">data</span><span class="Punctuation">:</span> <span class="Operator">@</span><span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="DecNumber">2</span><span class="Punctuation">,</span> <span class="DecNumber">3</span><span class="Punctuation">]</span><span class="Punctuation">)</span>
<span class="Identifier">echo</span> <span class="Identifier">foo</span><span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">]</span> <span class="Comment"># 2</span></pre></p>
<p>Assignment to subscripts can also be overloaded by naming a routine <tt class="docutils literal"><span class="pre"><span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Operator">=</span></span></tt>, which has precedence over assigning to the result of <tt class="docutils literal"><span class="pre"><span class="Punctuation">[</span><span class="Punctuation">]</span></span></tt>.</p>
<p><pre class="listing"><span class="Keyword">type</span> <span class="Identifier">Foo</span> <span class="Operator">=</span> <span class="Keyword">object</span>
  <span class="Identifier">data</span><span class="Punctuation">:</span> <span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">int</span><span class="Punctuation">]</span>

<span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">foo</span><span class="Punctuation">:</span> <span class="Identifier">Foo</span><span class="Punctuation">,</span> <span class="Identifier">i</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">foo</span><span class="Operator">.</span><span class="Identifier">data</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span>
<span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Operator">=</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">foo</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">Foo</span><span class="Punctuation">,</span> <span class="Identifier">i</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">,</span> <span class="Identifier">val</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Identifier">foo</span><span class="Operator">.</span><span class="Identifier">data</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Identifier">val</span>

<span class="Keyword">var</span> <span class="Identifier">foo</span> <span class="Operator">=</span> <span class="Identifier">Foo</span><span class="Punctuation">(</span><span class="Identifier">data</span><span class="Punctuation">:</span> <span class="Operator">@</span><span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="DecNumber">2</span><span class="Punctuation">,</span> <span class="DecNumber">3</span><span class="Punctuation">]</span><span class="Punctuation">)</span>
<span class="Identifier">echo</span> <span class="Identifier">foo</span><span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">]</span> <span class="Comment"># 2</span>
<span class="Identifier">foo</span><span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="DecNumber">5</span>
<span class="Identifier">echo</span> <span class="Identifier">foo</span><span class="Operator">.</span><span class="Identifier">data</span> <span class="Comment"># @[1, 5, 3]</span>
<span class="Identifier">echo</span> <span class="Identifier">foo</span><span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">]</span> <span class="Comment"># 5</span></pre></p>
<p>Overloads of the subscript operator cannot be applied to routine or type symbols themselves, as this conflicts with the syntax for instantiating generic parameters, i.e. <tt class="docutils literal"><span class="pre"><span class="Identifier">foo</span><span class="Punctuation">[</span><span class="Identifier">int</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="DecNumber">2</span><span class="Punctuation">,</span> <span class="DecNumber">3</span><span class="Punctuation">)</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Identifier">Foo</span><span class="Punctuation">[</span><span class="Identifier">int</span><span class="Punctuation">]</span></span></tt>.</p>

<h1><a class="toc-backref" id="methods" href="#methods">Methods</a></h1><p>Procedures always use static dispatch. Methods use dynamic dispatch. For dynamic dispatch to work on an object it should be a reference type.</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">Expression</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Keyword">object</span> <span class="Keyword">of</span> <span class="Identifier">RootObj</span> <span class="Comment">## abstract base class for an expression</span>
  <span class="Identifier">Literal</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Keyword">object</span> <span class="Keyword">of</span> <span class="Identifier">Expression</span>
    <span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">int</span>
  <span class="Identifier">PlusExpr</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Keyword">object</span> <span class="Keyword">of</span> <span class="Identifier">Expression</span>
    <span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">Expression</span>

<span class="Keyword">method</span> <span class="Identifier">eval</span><span class="Punctuation">(</span><span class="Identifier">e</span><span class="Punctuation">:</span> <span class="Identifier">Expression</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">base</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
  <span class="Comment"># override this base method</span>
  <span class="Keyword">raise</span> <span class="Identifier">newException</span><span class="Punctuation">(</span><span class="Identifier">CatchableError</span><span class="Punctuation">,</span> <span class="StringLit">&quot;Method without implementation override&quot;</span><span class="Punctuation">)</span>

<span class="Keyword">method</span> <span class="Identifier">eval</span><span class="Punctuation">(</span><span class="Identifier">e</span><span class="Punctuation">:</span> <span class="Identifier">Literal</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span> <span class="Keyword">return</span> <span class="Identifier">e</span><span class="Operator">.</span><span class="Identifier">x</span>

<span class="Keyword">method</span> <span class="Identifier">eval</span><span class="Punctuation">(</span><span class="Identifier">e</span><span class="Punctuation">:</span> <span class="Identifier">PlusExpr</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span>
  <span class="Comment"># watch out: relies on dynamic binding</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">eval</span><span class="Punctuation">(</span><span class="Identifier">e</span><span class="Operator">.</span><span class="Identifier">a</span><span class="Punctuation">)</span> <span class="Operator">+</span> <span class="Identifier">eval</span><span class="Punctuation">(</span><span class="Identifier">e</span><span class="Operator">.</span><span class="Identifier">b</span><span class="Punctuation">)</span>

<span class="Keyword">proc</span> <span class="Identifier">newLit</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">Literal</span> <span class="Operator">=</span>
  <span class="Identifier">new</span><span class="Punctuation">(</span><span class="Identifier">result</span><span class="Punctuation">)</span>
  <span class="Identifier">result</span><span class="Operator">.</span><span class="Identifier">x</span> <span class="Operator">=</span> <span class="Identifier">x</span>

<span class="Keyword">proc</span> <span class="Identifier">newPlus</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">Expression</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">PlusExpr</span> <span class="Operator">=</span>
  <span class="Identifier">new</span><span class="Punctuation">(</span><span class="Identifier">result</span><span class="Punctuation">)</span>
  <span class="Identifier">result</span><span class="Operator">.</span><span class="Identifier">a</span> <span class="Operator">=</span> <span class="Identifier">a</span>
  <span class="Identifier">result</span><span class="Operator">.</span><span class="Identifier">b</span> <span class="Operator">=</span> <span class="Identifier">b</span>

<span class="Identifier">echo</span> <span class="Identifier">eval</span><span class="Punctuation">(</span><span class="Identifier">newPlus</span><span class="Punctuation">(</span><span class="Identifier">newPlus</span><span class="Punctuation">(</span><span class="Identifier">newLit</span><span class="Punctuation">(</span><span class="DecNumber">1</span><span class="Punctuation">)</span><span class="Punctuation">,</span> <span class="Identifier">newLit</span><span class="Punctuation">(</span><span class="DecNumber">2</span><span class="Punctuation">)</span><span class="Punctuation">)</span><span class="Punctuation">,</span> <span class="Identifier">newLit</span><span class="Punctuation">(</span><span class="DecNumber">4</span><span class="Punctuation">)</span><span class="Punctuation">)</span><span class="Punctuation">)</span></pre></p>
<p>In the example the constructors <tt class="docutils literal"><span class="pre"><span class="Identifier">newLit</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">newPlus</span></span></tt> are procs because they should use static binding, but <tt class="docutils literal"><span class="pre"><span class="Identifier">eval</span></span></tt> is a method because it requires dynamic binding.</p>
<p>As can be seen in the example, base methods have to be annotated with the <span id="base_1">base</span> pragma. The <tt class="docutils literal"><span class="pre"><span class="Identifier">base</span></span></tt> pragma also acts as a reminder for the programmer that a base method <tt class="docutils literal"><span class="pre"><span class="Identifier">m</span></span></tt> is used as the foundation to determine all the effects that a call to <tt class="docutils literal"><span class="pre"><span class="Identifier">m</span></span></tt> might cause.</p>
<p><strong>Note</strong>: Compile-time execution is not (yet) supported for methods.</p>
<p><strong>Note</strong>: Starting from Nim 0.20, generic methods are deprecated.</p>

<h2><a class="toc-backref" id="methods-multiminusmethods" href="#methods-multiminusmethods">Multi-methods</a></h2><p><strong>Note:</strong> Starting from Nim 0.20, to use multi-methods one must explicitly pass <tt class="docutils literal"><span class="pre option">--multimethods:on</span></tt> when compiling.</p>
<p>In a multi-method, all parameters that have an object type are used for the dispatching:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">Thing</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Keyword">object</span> <span class="Keyword">of</span> <span class="Identifier">RootObj</span>
  <span class="Identifier">Unit</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Keyword">object</span> <span class="Keyword">of</span> <span class="Identifier">Thing</span>
    <span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">int</span>

<span class="Keyword">method</span> <span class="Identifier">collide</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">Thing</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">base</span><span class="Punctuation">,</span> <span class="Identifier">inline</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
  <span class="Identifier">quit</span> <span class="StringLit">&quot;to override!&quot;</span>

<span class="Keyword">method</span> <span class="Identifier">collide</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">Thing</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">Unit</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">inline</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;1&quot;</span>

<span class="Keyword">method</span> <span class="Identifier">collide</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">Unit</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">Thing</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">inline</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;2&quot;</span>

<span class="Keyword">var</span> <span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">Unit</span>
<span class="Identifier">new</span> <span class="Identifier">a</span>
<span class="Identifier">new</span> <span class="Identifier">b</span>
<span class="Identifier">collide</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">)</span> <span class="Comment"># output: 2</span></pre></p>

<h2><a class="toc-backref" id="methods-inhibit-dynamic-method-resolution-via-proccall" href="#methods-inhibit-dynamic-method-resolution-via-proccall">Inhibit dynamic method resolution via procCall</a></h2><p>Dynamic method resolution can be inhibited via the builtin <span id="systemdotproccall_1">system.procCall</span>. This is somewhat comparable to the <span id="super_1">super</span> keyword that traditional OOP languages offer.</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">Thing</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Keyword">object</span> <span class="Keyword">of</span> <span class="Identifier">RootObj</span>
  <span class="Identifier">Unit</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Keyword">object</span> <span class="Keyword">of</span> <span class="Identifier">Thing</span>
    <span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">int</span>

<span class="Keyword">method</span> <span class="Identifier">m</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">Thing</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">base</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;base&quot;</span>

<span class="Keyword">method</span> <span class="Identifier">m</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">Unit</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Comment"># Call the base method:</span>
  <span class="Identifier">procCall</span> <span class="Identifier">m</span><span class="Punctuation">(</span><span class="Identifier">Thing</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">)</span><span class="Punctuation">)</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;1&quot;</span></pre></p>

<h1><a class="toc-backref" id="iterators-and-the-for-statement" href="#iterators-and-the-for-statement">Iterators and the for statement</a></h1><p>The <span id="for_1">for</span> statement is an abstract mechanism to iterate over the elements of a container. It relies on an <span id="iterator_1">iterator</span> to do so. Like <tt class="docutils literal"><span class="pre"><span class="Keyword">while</span></span></tt> statements, <tt class="docutils literal"><span class="pre"><span class="Keyword">for</span></span></tt> statements open an <span id="implicit-block_1">implicit block</span> so that they can be left with a <tt class="docutils literal"><span class="pre"><span class="Keyword">break</span></span></tt> statement.</p>
<p>The <tt class="docutils literal"><span class="pre"><span class="Keyword">for</span></span></tt> loop declares iteration variables - their scope reaches until the end of the loop body. The iteration variables' types are inferred by the return type of the iterator.</p>
<p>An iterator is similar to a procedure, except that it can be called in the context of a <tt class="docutils literal"><span class="pre"><span class="Keyword">for</span></span></tt> loop. Iterators provide a way to specify the iteration over an abstract type. The <tt class="docutils literal"><span class="pre"><span class="Keyword">yield</span></span></tt> statement in the called iterator plays a key role in the execution of a <tt class="docutils literal"><span class="pre"><span class="Keyword">for</span></span></tt> loop. Whenever a <tt class="docutils literal"><span class="pre"><span class="Keyword">yield</span></span></tt> statement is reached, the data is bound to the <tt class="docutils literal"><span class="pre"><span class="Keyword">for</span></span></tt> loop variables and control continues in the body of the <tt class="docutils literal"><span class="pre"><span class="Keyword">for</span></span></tt> loop. The iterator's local variables and execution state are automatically saved between calls. Example:</p>
<p><pre class="listing"><span class="Comment"># this definition exists in the system module</span>
<span class="Keyword">iterator</span> <span class="Identifier">items</span><span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">char</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">inline</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
  <span class="Keyword">var</span> <span class="Identifier">i</span> <span class="Operator">=</span> <span class="DecNumber">0</span>
  <span class="Keyword">while</span> <span class="Identifier">i</span> <span class="Operator">&lt;</span> <span class="Identifier">len</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
    <span class="Keyword">yield</span> <span class="Identifier">a</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span>
    <span class="Identifier">inc</span><span class="Punctuation">(</span><span class="Identifier">i</span><span class="Punctuation">)</span>

<span class="Keyword">for</span> <span class="Identifier">ch</span> <span class="Keyword">in</span> <span class="Identifier">items</span><span class="Punctuation">(</span><span class="StringLit">&quot;hello world&quot;</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Comment"># `ch` is an iteration variable</span>
  <span class="Identifier">echo</span> <span class="Identifier">ch</span></pre></p>
<p>The compiler generates code as if the programmer had written this:</p>
<p><pre class="listing"><span class="Keyword">var</span> <span class="Identifier">i</span> <span class="Operator">=</span> <span class="DecNumber">0</span>
<span class="Keyword">while</span> <span class="Identifier">i</span> <span class="Operator">&lt;</span> <span class="Identifier">len</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
  <span class="Keyword">var</span> <span class="Identifier">ch</span> <span class="Operator">=</span> <span class="Identifier">a</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span>
  <span class="Identifier">echo</span> <span class="Identifier">ch</span>
  <span class="Identifier">inc</span><span class="Punctuation">(</span><span class="Identifier">i</span><span class="Punctuation">)</span></pre></p>
<p>If the iterator yields a tuple, there can be as many iteration variables as there are components in the tuple. The i'th iteration variable's type is the type of the i'th component. In other words, implicit tuple unpacking in a for loop context is supported.</p>

<h2><a class="toc-backref" id="iterators-and-the-for-statement-implicit-itemsslashpairs-invocations" href="#iterators-and-the-for-statement-implicit-itemsslashpairs-invocations">Implicit items/pairs invocations</a></h2><p>If the for loop expression <tt class="docutils literal"><span class="pre"><span class="Identifier">e</span></span></tt> does not denote an iterator and the for loop has exactly 1 variable, the for loop expression is rewritten to <tt class="docutils literal"><span class="pre"><span class="Identifier">items</span><span class="Punctuation">(</span><span class="Identifier">e</span><span class="Punctuation">)</span></span></tt>; i.e. an <tt class="docutils literal"><span class="pre"><span class="Identifier">items</span></span></tt> iterator is implicitly invoked:</p>
<p><pre class="listing"><span class="Keyword">for</span> <span class="Identifier">x</span> <span class="Keyword">in</span> <span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">,</span><span class="DecNumber">2</span><span class="Punctuation">,</span><span class="DecNumber">3</span><span class="Punctuation">]</span><span class="Punctuation">:</span> <span class="Identifier">echo</span> <span class="Identifier">x</span></pre></p>
<p>If the for loop has exactly 2 variables, a <tt class="docutils literal"><span class="pre"><span class="Identifier">pairs</span></span></tt> iterator is implicitly invoked.</p>
<p>Symbol lookup of the identifiers <tt class="docutils literal"><span class="pre"><span class="Identifier">items</span></span></tt>/<tt class="docutils literal"><span class="pre"><span class="Identifier">pairs</span></span></tt> is performed after the rewriting step, so that all overloads of <tt class="docutils literal"><span class="pre"><span class="Identifier">items</span></span></tt>/<tt class="docutils literal"><span class="pre"><span class="Identifier">pairs</span></span></tt> are taken into account.</p>

<h2><a class="toc-backref" id="iterators-and-the-for-statement-firstminusclass-iterators" href="#iterators-and-the-for-statement-firstminusclass-iterators">First-class iterators</a></h2><p>There are 2 kinds of iterators in Nim: <em>inline</em> and <em>closure</em> iterators. An <span id="inline-iterator_1">inline iterator</span> is an iterator that's always inlined by the compiler leading to zero overhead for the abstraction, but may result in a heavy increase in code size.</p>
<p>Caution: the body of a for loop over an inline iterator is inlined into each <tt class="docutils literal"><span class="pre"><span class="Keyword">yield</span></span></tt> statement appearing in the iterator code, so ideally the code should be refactored to contain a single yield when possible to avoid code bloat.</p>
<p>Inline iterators are second class citizens; They can be passed as parameters only to other inlining code facilities like templates, macros, and other inline iterators.</p>
<p>In contrast to that, a <span id="closure-iterator_1">closure iterator</span> can be passed around more freely:</p>
<p><pre class="listing"><span class="Keyword">iterator</span> <span class="Identifier">count0</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">closure</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
  <span class="Keyword">yield</span> <span class="DecNumber">0</span>

<span class="Keyword">iterator</span> <span class="Identifier">count2</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">closure</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
  <span class="Keyword">var</span> <span class="Identifier">x</span> <span class="Operator">=</span> <span class="DecNumber">1</span>
  <span class="Keyword">yield</span> <span class="Identifier">x</span>
  <span class="Identifier">inc</span> <span class="Identifier">x</span>
  <span class="Keyword">yield</span> <span class="Identifier">x</span>

<span class="Keyword">proc</span> <span class="Identifier">invoke</span><span class="Punctuation">(</span><span class="Identifier">iter</span><span class="Punctuation">:</span> <span class="Keyword">iterator</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">closure</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">for</span> <span class="Identifier">x</span> <span class="Keyword">in</span> <span class="Identifier">iter</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">echo</span> <span class="Identifier">x</span>

<span class="Identifier">invoke</span><span class="Punctuation">(</span><span class="Identifier">count0</span><span class="Punctuation">)</span>
<span class="Identifier">invoke</span><span class="Punctuation">(</span><span class="Identifier">count2</span><span class="Punctuation">)</span></pre></p>
<p>Closure iterators and inline iterators have some restrictions:</p>
<ol class="simple"><li>For now, a closure iterator cannot be executed at compile time.</li>
<li><tt class="docutils literal"><span class="pre"><span class="Keyword">return</span></span></tt> is allowed in a closure iterator but not in an inline iterator (but rarely useful) and ends the iteration.</li>
<li>Inline iterators cannot be recursive.</li>
<li>Neither inline nor closure iterators have the special <tt class="docutils literal"><span class="pre"><span class="Identifier">result</span></span></tt> variable.</li>
</ol>
<p>Iterators that are neither marked <tt class="docutils literal"><span class="pre"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">closure</span><span class="Operator">.</span><span class="Punctuation">}</span></span></tt> nor <tt class="docutils literal"><span class="pre"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">inline</span><span class="Operator">.</span><span class="Punctuation">}</span></span></tt> explicitly default to being inline, but this may change in future versions of the implementation.</p>
<p>The <tt class="docutils literal"><span class="pre"><span class="Keyword">iterator</span></span></tt> type is always of the calling convention <tt class="docutils literal"><span class="pre"><span class="Identifier">closure</span></span></tt> implicitly; the following example shows how to use iterators to implement a <span id="collaborative-tasking_1">collaborative tasking</span> system:</p>
<p><pre class="listing"><span class="Comment"># simple tasking:</span>
<span class="Keyword">type</span>
  <span class="Identifier">Task</span> <span class="Operator">=</span> <span class="Keyword">iterator</span> <span class="Punctuation">(</span><span class="Identifier">ticker</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span>

<span class="Keyword">iterator</span> <span class="Identifier">a1</span><span class="Punctuation">(</span><span class="Identifier">ticker</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">closure</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;a1: A&quot;</span>
  <span class="Keyword">yield</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;a1: B&quot;</span>
  <span class="Keyword">yield</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;a1: C&quot;</span>
  <span class="Keyword">yield</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;a1: D&quot;</span>

<span class="Keyword">iterator</span> <span class="Identifier">a2</span><span class="Punctuation">(</span><span class="Identifier">ticker</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">closure</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;a2: A&quot;</span>
  <span class="Keyword">yield</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;a2: B&quot;</span>
  <span class="Keyword">yield</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;a2: C&quot;</span>

<span class="Keyword">proc</span> <span class="Identifier">runTasks</span><span class="Punctuation">(</span><span class="Identifier">t</span><span class="Punctuation">:</span> <span class="Identifier">varargs</span><span class="Punctuation">[</span><span class="Identifier">Task</span><span class="Punctuation">]</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">var</span> <span class="Identifier">ticker</span> <span class="Operator">=</span> <span class="DecNumber">0</span>
  <span class="Keyword">while</span> <span class="Identifier">true</span><span class="Punctuation">:</span>
    <span class="Keyword">let</span> <span class="Identifier">x</span> <span class="Operator">=</span> <span class="Identifier">t</span><span class="Punctuation">[</span><span class="Identifier">ticker</span> <span class="Keyword">mod</span> <span class="Identifier">t</span><span class="Operator">.</span><span class="Identifier">len</span><span class="Punctuation">]</span>
    <span class="Keyword">if</span> <span class="Identifier">finished</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Keyword">break</span>
    <span class="Identifier">x</span><span class="Punctuation">(</span><span class="Identifier">ticker</span><span class="Punctuation">)</span>
    <span class="Identifier">inc</span> <span class="Identifier">ticker</span>

<span class="Identifier">runTasks</span><span class="Punctuation">(</span><span class="Identifier">a1</span><span class="Punctuation">,</span> <span class="Identifier">a2</span><span class="Punctuation">)</span></pre></p>
<p>The builtin <tt class="docutils literal"><span class="pre"><span class="Identifier">system</span><span class="Operator">.</span><span class="Identifier">finished</span></span></tt> can be used to determine if an iterator has finished its operation; no exception is raised on an attempt to invoke an iterator that has already finished its work.</p>
<p>Note that <tt class="docutils literal"><span class="pre"><span class="Identifier">system</span><span class="Operator">.</span><span class="Identifier">finished</span></span></tt> is error-prone to use because it only returns <tt class="docutils literal"><span class="pre"><span class="Identifier">true</span></span></tt> one iteration after the iterator has finished:</p>
<p><pre class="listing"><span class="Keyword">iterator</span> <span class="Identifier">mycount</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">closure</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
  <span class="Keyword">var</span> <span class="Identifier">x</span> <span class="Operator">=</span> <span class="Identifier">a</span>
  <span class="Keyword">while</span> <span class="Identifier">x</span> <span class="Operator">&lt;=</span> <span class="Identifier">b</span><span class="Punctuation">:</span>
    <span class="Keyword">yield</span> <span class="Identifier">x</span>
    <span class="Identifier">inc</span> <span class="Identifier">x</span>

<span class="Keyword">var</span> <span class="Identifier">c</span> <span class="Operator">=</span> <span class="Identifier">mycount</span> <span class="Comment"># instantiate the iterator</span>
<span class="Keyword">while</span> <span class="Keyword">not</span> <span class="Identifier">finished</span><span class="Punctuation">(</span><span class="Identifier">c</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
  <span class="Identifier">echo</span> <span class="Identifier">c</span><span class="Punctuation">(</span><span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="DecNumber">3</span><span class="Punctuation">)</span>

<span class="Comment"># Produces</span>
<span class="DecNumber">1</span>
<span class="DecNumber">2</span>
<span class="DecNumber">3</span>
<span class="DecNumber">0</span></pre></p>
<p>Instead, this code has to be used:</p>
<p><pre class="listing"><span class="Keyword">var</span> <span class="Identifier">c</span> <span class="Operator">=</span> <span class="Identifier">mycount</span> <span class="Comment"># instantiate the iterator</span>
<span class="Keyword">while</span> <span class="Identifier">true</span><span class="Punctuation">:</span>
  <span class="Keyword">let</span> <span class="Identifier">value</span> <span class="Operator">=</span> <span class="Identifier">c</span><span class="Punctuation">(</span><span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="DecNumber">3</span><span class="Punctuation">)</span>
  <span class="Keyword">if</span> <span class="Identifier">finished</span><span class="Punctuation">(</span><span class="Identifier">c</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Keyword">break</span> <span class="Comment"># and discard 'value'!</span>
  <span class="Identifier">echo</span> <span class="Identifier">value</span></pre></p>
<p>It helps to think that the iterator actually returns a pair <tt class="docutils literal"><span class="pre"><span class="Punctuation">(</span><span class="Identifier">value</span><span class="Punctuation">,</span> <span class="Identifier">done</span><span class="Punctuation">)</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">finished</span></span></tt> is used to access the hidden <tt class="docutils literal"><span class="pre"><span class="Identifier">done</span></span></tt> field.</p>
<p>Closure iterators are <em>resumable functions</em> and so one has to provide the arguments to every call. To get around this limitation one can capture parameters of an outer factory proc:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">mycount</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Keyword">iterator</span> <span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Keyword">iterator</span> <span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span>
    <span class="Keyword">var</span> <span class="Identifier">x</span> <span class="Operator">=</span> <span class="Identifier">a</span>
    <span class="Keyword">while</span> <span class="Identifier">x</span> <span class="Operator">&lt;=</span> <span class="Identifier">b</span><span class="Punctuation">:</span>
      <span class="Keyword">yield</span> <span class="Identifier">x</span>
      <span class="Identifier">inc</span> <span class="Identifier">x</span>

<span class="Keyword">let</span> <span class="Identifier">foo</span> <span class="Operator">=</span> <span class="Identifier">mycount</span><span class="Punctuation">(</span><span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="DecNumber">4</span><span class="Punctuation">)</span>

<span class="Keyword">for</span> <span class="Identifier">f</span> <span class="Keyword">in</span> <span class="Identifier">foo</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
  <span class="Identifier">echo</span> <span class="Identifier">f</span></pre></p>
<p>The call can be made more like an inline iterator with a for loop macro:</p>
<p><pre class="listing"><span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">macros</span>
<span class="Keyword">macro</span> <span class="Identifier">toItr</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">ForLoopStmt</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">untyped</span> <span class="Operator">=</span>
  <span class="Keyword">let</span> <span class="Identifier">expr</span> <span class="Operator">=</span> <span class="Identifier">x</span><span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">]</span>
  <span class="Keyword">let</span> <span class="Identifier">call</span> <span class="Operator">=</span> <span class="Identifier">x</span><span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">]</span><span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">]</span> <span class="Comment"># Get foo out of toItr(foo)</span>
  <span class="Keyword">let</span> <span class="Identifier">body</span> <span class="Operator">=</span> <span class="Identifier">x</span><span class="Punctuation">[</span><span class="DecNumber">2</span><span class="Punctuation">]</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">quote</span> <span class="Keyword">do</span><span class="Punctuation">:</span>
    <span class="Keyword">block</span><span class="Punctuation">:</span>
      <span class="Keyword">let</span> <span class="Identifier">itr</span> <span class="Operator">=</span> <span class="Punctuation">`</span><span class="Identifier">call</span><span class="Punctuation">`</span>
      <span class="Keyword">for</span> <span class="Punctuation">`</span><span class="Identifier">expr</span><span class="Punctuation">`</span> <span class="Keyword">in</span> <span class="Identifier">itr</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
          <span class="Punctuation">`</span><span class="Identifier">body</span><span class="Punctuation">`</span>

<span class="Keyword">for</span> <span class="Identifier">f</span> <span class="Keyword">in</span> <span class="Identifier">toItr</span><span class="Punctuation">(</span><span class="Identifier">mycount</span><span class="Punctuation">(</span><span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="DecNumber">4</span><span class="Punctuation">)</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Comment"># using early `proc mycount`</span>
  <span class="Identifier">echo</span> <span class="Identifier">f</span></pre></p>
<p>Because of full backend function call apparatus involvement, closure iterator invocation is typically higher cost than inline iterators. Adornment by a macro wrapper at the call site like this is a possibly useful reminder.</p>
<p>The factory <tt class="docutils literal"><span class="pre"><span class="Keyword">proc</span></span></tt>, as an ordinary procedure, can be recursive. The above macro allows such recursion to look much like a recursive iterator would. For example:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">recCountDown</span><span class="Punctuation">(</span><span class="Identifier">n</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Keyword">iterator</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Keyword">iterator</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span>
    <span class="Keyword">if</span> <span class="Identifier">n</span> <span class="Operator">&gt;</span> <span class="DecNumber">0</span><span class="Punctuation">:</span>
      <span class="Keyword">yield</span> <span class="Identifier">n</span>
      <span class="Keyword">for</span> <span class="Identifier">e</span> <span class="Keyword">in</span> <span class="Identifier">toItr</span><span class="Punctuation">(</span><span class="Identifier">recCountDown</span><span class="Punctuation">(</span><span class="Identifier">n</span> <span class="Operator">-</span> <span class="DecNumber">1</span><span class="Punctuation">)</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
        <span class="Keyword">yield</span> <span class="Identifier">e</span>

<span class="Keyword">for</span> <span class="Identifier">i</span> <span class="Keyword">in</span> <span class="Identifier">toItr</span><span class="Punctuation">(</span><span class="Identifier">recCountDown</span><span class="Punctuation">(</span><span class="DecNumber">6</span><span class="Punctuation">)</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Comment"># Emits: 6 5 4 3 2 1</span>
  <span class="Identifier">echo</span> <span class="Identifier">i</span></pre></p>
<p>See also <a class="reference internal" href="#overload-resolution-iterable">iterable</a> for passing iterators to templates and macros.</p>

<h1><a class="toc-backref" id="converters" href="#converters">Converters</a></h1><p>A converter is like an ordinary proc except that it enhances the &quot;implicitly convertible&quot; type relation (see <a class="reference internal" href="#type-relations-convertible-relation">Convertible relation</a>):</p>
<p><pre class="listing"><span class="Comment"># bad style ahead: Nim is not C.</span>
<span class="Keyword">converter</span> <span class="Identifier">toBool</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">bool</span> <span class="Operator">=</span> <span class="Identifier">x</span> <span class="Operator">!=</span> <span class="DecNumber">0</span>

<span class="Keyword">if</span> <span class="DecNumber">4</span><span class="Punctuation">:</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;compiles&quot;</span></pre></p>
<p>A converter can also be explicitly invoked for improved readability. Note that implicit converter chaining is not supported: If there is a converter from type A to type B and from type B to type C, the implicit conversion from A to C is not provided.</p>

<h1><a class="toc-backref" id="type-sections" href="#type-sections">Type sections</a></h1><p>Example:</p>
<p><pre class="listing"><span class="Keyword">type</span> <span class="Comment"># example demonstrating mutually recursive types</span>
  <span class="Identifier">Node</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Keyword">object</span>  <span class="Comment"># an object managed by the garbage collector (ref)</span>
    <span class="Identifier">le</span><span class="Punctuation">,</span> <span class="Identifier">ri</span><span class="Punctuation">:</span> <span class="Identifier">Node</span>     <span class="Comment"># left and right subtrees</span>
    <span class="Identifier">sym</span><span class="Punctuation">:</span> <span class="Keyword">ref</span> <span class="Identifier">Sym</span>     <span class="Comment"># leaves contain a reference to a Sym</span>
  
  <span class="Identifier">Sym</span> <span class="Operator">=</span> <span class="Keyword">object</span>       <span class="Comment"># a symbol</span>
    <span class="Identifier">name</span><span class="Punctuation">:</span> <span class="Identifier">string</span>     <span class="Comment"># the symbol's name</span>
    <span class="Identifier">line</span><span class="Punctuation">:</span> <span class="Identifier">int</span>        <span class="Comment"># the line the symbol was declared in</span>
    <span class="Identifier">code</span><span class="Punctuation">:</span> <span class="Identifier">Node</span>       <span class="Comment"># the symbol's abstract syntax tree</span></pre></p>
<p>A type section begins with the <tt class="docutils literal"><span class="pre"><span class="Keyword">type</span></span></tt> keyword. It contains multiple type definitions. A type definition binds a type to a name. Type definitions can be recursive or even mutually recursive. Mutually recursive types are only possible within a single <tt class="docutils literal"><span class="pre"><span class="Keyword">type</span></span></tt> section. Nominal types like <tt class="docutils literal"><span class="pre"><span class="Identifier">objects</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Identifier">enums</span></span></tt> can only be defined in a <tt class="docutils literal"><span class="pre"><span class="Keyword">type</span></span></tt> section.</p>

<h1><a class="toc-backref" id="exception-handling" href="#exception-handling">Exception handling</a></h1>
<h2><a class="toc-backref" id="exception-handling-try-statement" href="#exception-handling-try-statement">Try statement</a></h2><p>Example:</p>
<p><pre class="listing"><span class="Comment"># read the first two lines of a text file that should contain numbers</span>
<span class="Comment"># and tries to add them</span>
<span class="Keyword">var</span>
  <span class="Identifier">f</span><span class="Punctuation">:</span> <span class="Identifier">File</span>
<span class="Keyword">if</span> <span class="Identifier">open</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">,</span> <span class="StringLit">&quot;numbers.txt&quot;</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
  <span class="Keyword">try</span><span class="Punctuation">:</span>
    <span class="Keyword">var</span> <span class="Identifier">a</span> <span class="Operator">=</span> <span class="Identifier">readLine</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">)</span>
    <span class="Keyword">var</span> <span class="Identifier">b</span> <span class="Operator">=</span> <span class="Identifier">readLine</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">)</span>
    <span class="Identifier">echo</span> <span class="StringLit">&quot;sum: &quot;</span> <span class="Operator">&amp;</span> <span class="Operator">$</span><span class="Punctuation">(</span><span class="Identifier">parseInt</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">)</span> <span class="Operator">+</span> <span class="Identifier">parseInt</span><span class="Punctuation">(</span><span class="Identifier">b</span><span class="Punctuation">)</span><span class="Punctuation">)</span>
  <span class="Keyword">except</span> <span class="Identifier">OverflowDefect</span><span class="Punctuation">:</span>
    <span class="Identifier">echo</span> <span class="StringLit">&quot;overflow!&quot;</span>
  <span class="Keyword">except</span> <span class="Identifier">ValueError</span><span class="Punctuation">,</span> <span class="Identifier">IOError</span><span class="Punctuation">:</span>
    <span class="Identifier">echo</span> <span class="StringLit">&quot;catch multiple exceptions!&quot;</span>
  <span class="Keyword">except</span> <span class="Identifier">CatchableError</span><span class="Punctuation">:</span>
    <span class="Identifier">echo</span> <span class="StringLit">&quot;Catchable exception!&quot;</span>
  <span class="Keyword">finally</span><span class="Punctuation">:</span>
    <span class="Identifier">close</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">)</span></pre></p>
<p>The statements after the <tt class="docutils literal"><span class="pre"><span class="Keyword">try</span></span></tt> are executed in sequential order unless an exception <tt class="docutils literal"><span class="pre"><span class="Identifier">e</span></span></tt> is raised. If the exception type of <tt class="docutils literal"><span class="pre"><span class="Identifier">e</span></span></tt> matches any listed in an <tt class="docutils literal"><span class="pre"><span class="Keyword">except</span></span></tt> clause, the corresponding statements are executed. The statements following the <tt class="docutils literal"><span class="pre"><span class="Keyword">except</span></span></tt> clauses are called <span id="exception-handlers_1">exception handlers</span>.</p>
<p>If there is a <span id="finally_1">finally</span> clause, it is always executed after the exception handlers.</p>
<p>The exception is <em>consumed</em> in an exception handler. However, an exception handler may raise another exception. If the exception is not handled, it is propagated through the call stack. This means that often the rest of the procedure - that is not within a <tt class="docutils literal"><span class="pre"><span class="Keyword">finally</span></span></tt> clause - is not executed (if an exception occurs).</p>

<h2><a class="toc-backref" id="exception-handling-try-expression" href="#exception-handling-try-expression">Try expression</a></h2><p>Try can also be used as an expression; the type of the <tt class="docutils literal"><span class="pre"><span class="Keyword">try</span></span></tt> branch then needs to fit the types of <tt class="docutils literal"><span class="pre"><span class="Keyword">except</span></span></tt> branches, but the type of the <tt class="docutils literal"><span class="pre"><span class="Keyword">finally</span></span></tt> branch always has to be <tt class="docutils literal"><span class="pre"><span class="Identifier">void</span></span></tt>:</p>
<p><pre class="listing"><span class="Keyword">from</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">strutils</span> <span class="Keyword">import</span> <span class="Identifier">parseInt</span>

<span class="Keyword">let</span> <span class="Identifier">x</span> <span class="Operator">=</span> <span class="Keyword">try</span><span class="Punctuation">:</span> <span class="Identifier">parseInt</span><span class="Punctuation">(</span><span class="StringLit">&quot;133a&quot;</span><span class="Punctuation">)</span>
        <span class="Keyword">except</span> <span class="Identifier">ValueError</span><span class="Punctuation">:</span> <span class="Operator">-</span><span class="DecNumber">1</span>
        <span class="Keyword">finally</span><span class="Punctuation">:</span> <span class="Identifier">echo</span> <span class="StringLit">&quot;hi&quot;</span></pre></p>
<p>To prevent confusing code there is a parsing limitation; if the <tt class="docutils literal"><span class="pre"><span class="Keyword">try</span></span></tt> follows a <tt class="docutils literal"><span class="pre"><span class="Punctuation">(</span></span></tt> it has to be written as a one liner:</p>
<p><pre class="listing"><span class="Keyword">from</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">strutils</span> <span class="Keyword">import</span> <span class="Identifier">parseInt</span>
<span class="Keyword">let</span> <span class="Identifier">x</span> <span class="Operator">=</span> <span class="Punctuation">(</span><span class="Keyword">try</span><span class="Punctuation">:</span> <span class="Identifier">parseInt</span><span class="Punctuation">(</span><span class="StringLit">&quot;133a&quot;</span><span class="Punctuation">)</span> <span class="Keyword">except</span> <span class="Identifier">ValueError</span><span class="Punctuation">:</span> <span class="Operator">-</span><span class="DecNumber">1</span><span class="Punctuation">)</span></pre></p>

<h2><a class="toc-backref" id="exception-handling-except-clauses" href="#exception-handling-except-clauses">Except clauses</a></h2><p>Within an <tt class="docutils literal"><span class="pre"><span class="Keyword">except</span></span></tt> clause it is possible to access the current exception using the following syntax:</p>
<p><pre class="listing"><span class="Keyword">try</span><span class="Punctuation">:</span>
  <span class="Comment"># ...</span>
<span class="Keyword">except</span> <span class="Identifier">IOError</span> <span class="Keyword">as</span> <span class="Identifier">e</span><span class="Punctuation">:</span>
  <span class="Comment"># Now use &quot;e&quot;</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;I/O error: &quot;</span> <span class="Operator">&amp;</span> <span class="Identifier">e</span><span class="Operator">.</span><span class="Identifier">msg</span></pre></p>
<p>Alternatively, it is possible to use <tt class="docutils literal"><span class="pre"><span class="Identifier">getCurrentException</span></span></tt> to retrieve the exception that has been raised:</p>
<p><pre class="listing"><span class="Keyword">try</span><span class="Punctuation">:</span>
  <span class="Comment"># ...</span>
<span class="Keyword">except</span> <span class="Identifier">IOError</span><span class="Punctuation">:</span>
  <span class="Keyword">let</span> <span class="Identifier">e</span> <span class="Operator">=</span> <span class="Identifier">getCurrentException</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
  <span class="Comment"># Now use &quot;e&quot;</span></pre></p>
<p>Note that <tt class="docutils literal"><span class="pre"><span class="Identifier">getCurrentException</span></span></tt> always returns a <tt class="docutils literal"><span class="pre"><span class="Keyword">ref</span> <span class="Identifier">Exception</span></span></tt> type. If a variable of the proper type is needed (in the example above, <tt class="docutils literal"><span class="pre"><span class="Identifier">IOError</span></span></tt>), one must convert it explicitly:</p>
<p><pre class="listing"><span class="Keyword">try</span><span class="Punctuation">:</span>
  <span class="Comment"># ...</span>
<span class="Keyword">except</span> <span class="Identifier">IOError</span><span class="Punctuation">:</span>
  <span class="Keyword">let</span> <span class="Identifier">e</span> <span class="Operator">=</span> <span class="Punctuation">(</span><span class="Keyword">ref</span> <span class="Identifier">IOError</span><span class="Punctuation">)</span><span class="Punctuation">(</span><span class="Identifier">getCurrentException</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">)</span>
  <span class="Comment"># &quot;e&quot; is now of the proper type</span></pre></p>
<p>However, this is seldom needed. The most common case is to extract an error message from <tt class="docutils literal"><span class="pre"><span class="Identifier">e</span></span></tt>, and for such situations, it is enough to use <tt class="docutils literal"><span class="pre"><span class="Identifier">getCurrentExceptionMsg</span></span></tt>:</p>
<p><pre class="listing"><span class="Keyword">try</span><span class="Punctuation">:</span>
  <span class="Comment"># ...</span>
<span class="Keyword">except</span> <span class="Identifier">CatchableError</span><span class="Punctuation">:</span>
  <span class="Identifier">echo</span> <span class="Identifier">getCurrentExceptionMsg</span><span class="Punctuation">(</span><span class="Punctuation">)</span></pre></p>

<h2><a class="toc-backref" id="exception-handling-custom-exceptions" href="#exception-handling-custom-exceptions">Custom exceptions</a></h2><p>It is possible to create custom exceptions. A custom exception is a custom type:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">LoadError</span><span class="Operator">*</span> <span class="Operator">=</span> <span class="Keyword">object</span> <span class="Keyword">of</span> <span class="Identifier">Exception</span></pre></p>
<p>Ending the custom exception's name with <tt class="docutils literal"><span class="pre"><span class="Identifier">Error</span></span></tt> is recommended.</p>
<p>Custom exceptions can be raised just like any other exception, e.g.:</p>
<p><pre class="listing"><span class="Keyword">raise</span> <span class="Identifier">newException</span><span class="Punctuation">(</span><span class="Identifier">LoadError</span><span class="Punctuation">,</span> <span class="StringLit">&quot;Failed to load data&quot;</span><span class="Punctuation">)</span></pre></p>

<h2><a class="toc-backref" id="exception-handling-defer-statement" href="#exception-handling-defer-statement">Defer statement</a></h2><p>Instead of a <tt class="docutils literal"><span class="pre"><span class="Keyword">try</span> <span class="Keyword">finally</span></span></tt> statement a <tt class="docutils literal"><span class="pre"><span class="Keyword">defer</span></span></tt> statement can be used, which avoids lexical nesting and offers more flexibility in terms of scoping as shown below.</p>
<p>Any statements following the <tt class="docutils literal"><span class="pre"><span class="Keyword">defer</span></span></tt> will be considered to be in an implicit try block in the current block:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">main</span> <span class="Operator">=</span>
  <span class="Keyword">var</span> <span class="Identifier">f</span> <span class="Operator">=</span> <span class="Identifier">open</span><span class="Punctuation">(</span><span class="StringLit">&quot;numbers.txt&quot;</span><span class="Punctuation">,</span> <span class="Identifier">fmWrite</span><span class="Punctuation">)</span>
  <span class="Keyword">defer</span><span class="Punctuation">:</span> <span class="Identifier">close</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">)</span>
  <span class="Identifier">f</span><span class="Operator">.</span><span class="Identifier">write</span> <span class="StringLit">&quot;abc&quot;</span>
  <span class="Identifier">f</span><span class="Operator">.</span><span class="Identifier">write</span> <span class="StringLit">&quot;def&quot;</span></pre></p>
<p>Is rewritten to:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">main</span> <span class="Operator">=</span>
  <span class="Keyword">var</span> <span class="Identifier">f</span> <span class="Operator">=</span> <span class="Identifier">open</span><span class="Punctuation">(</span><span class="StringLit">&quot;numbers.txt&quot;</span><span class="Punctuation">)</span>
  <span class="Keyword">try</span><span class="Punctuation">:</span>
    <span class="Identifier">f</span><span class="Operator">.</span><span class="Identifier">write</span> <span class="StringLit">&quot;abc&quot;</span>
    <span class="Identifier">f</span><span class="Operator">.</span><span class="Identifier">write</span> <span class="StringLit">&quot;def&quot;</span>
  <span class="Keyword">finally</span><span class="Punctuation">:</span>
    <span class="Identifier">close</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">)</span></pre></p>
<p>When <tt class="docutils literal"><span class="pre"><span class="Keyword">defer</span></span></tt> is at the outermost scope of a template/macro, its scope extends to the block where the template/macro is called from:</p>
<p><pre class="listing"><span class="Keyword">template</span> <span class="Identifier">safeOpenDefer</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">,</span> <span class="Identifier">path</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">var</span> <span class="Identifier">f</span> <span class="Operator">=</span> <span class="Identifier">open</span><span class="Punctuation">(</span><span class="Identifier">path</span><span class="Punctuation">,</span> <span class="Identifier">fmWrite</span><span class="Punctuation">)</span>
  <span class="Keyword">defer</span><span class="Punctuation">:</span> <span class="Identifier">close</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">)</span>

<span class="Keyword">template</span> <span class="Identifier">safeOpenFinally</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">,</span> <span class="Identifier">path</span><span class="Punctuation">,</span> <span class="Identifier">body</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">var</span> <span class="Identifier">f</span> <span class="Operator">=</span> <span class="Identifier">open</span><span class="Punctuation">(</span><span class="Identifier">path</span><span class="Punctuation">,</span> <span class="Identifier">fmWrite</span><span class="Punctuation">)</span>
  <span class="Keyword">try</span><span class="Punctuation">:</span> <span class="Identifier">body</span> <span class="Comment"># without `defer`, `body` must be specified as parameter</span>
  <span class="Keyword">finally</span><span class="Punctuation">:</span> <span class="Identifier">close</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">)</span>

<span class="Keyword">block</span><span class="Punctuation">:</span>
  <span class="Identifier">safeOpenDefer</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">,</span> <span class="StringLit">&quot;/tmp/z01.txt&quot;</span><span class="Punctuation">)</span>
  <span class="Identifier">f</span><span class="Operator">.</span><span class="Identifier">write</span> <span class="StringLit">&quot;abc&quot;</span>
<span class="Keyword">block</span><span class="Punctuation">:</span>
  <span class="Identifier">safeOpenFinally</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">,</span> <span class="StringLit">&quot;/tmp/z01.txt&quot;</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
    <span class="Identifier">f</span><span class="Operator">.</span><span class="Identifier">write</span> <span class="StringLit">&quot;abc&quot;</span> <span class="Comment"># adds a lexical scope</span>
<span class="Keyword">block</span><span class="Punctuation">:</span>
  <span class="Keyword">var</span> <span class="Identifier">f</span> <span class="Operator">=</span> <span class="Identifier">open</span><span class="Punctuation">(</span><span class="StringLit">&quot;/tmp/z01.txt&quot;</span><span class="Punctuation">,</span> <span class="Identifier">fmWrite</span><span class="Punctuation">)</span>
  <span class="Keyword">try</span><span class="Punctuation">:</span>
    <span class="Identifier">f</span><span class="Operator">.</span><span class="Identifier">write</span> <span class="StringLit">&quot;abc&quot;</span> <span class="Comment"># adds a lexical scope</span>
  <span class="Keyword">finally</span><span class="Punctuation">:</span> <span class="Identifier">close</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">)</span></pre></p>
<p>Top-level <tt class="docutils literal"><span class="pre"><span class="Keyword">defer</span></span></tt> statements are not supported since it's unclear what such a statement should refer to.</p>

<h2><a class="toc-backref" id="exception-handling-raise-statement" href="#exception-handling-raise-statement">Raise statement</a></h2><p>Example:</p>
<p><pre class="listing"><span class="Keyword">raise</span> <span class="Identifier">newException</span><span class="Punctuation">(</span><span class="Identifier">IOError</span><span class="Punctuation">,</span> <span class="StringLit">&quot;IO failed&quot;</span><span class="Punctuation">)</span></pre></p>
<p>Apart from built-in operations like array indexing, memory allocation, etc. the <tt class="docutils literal"><span class="pre"><span class="Keyword">raise</span></span></tt> statement is the only way to raise an exception.</p>
<p>If no exception name is given, the current exception is <span id="reminusraised_1">re-raised</span>. The <span id="reraisedefect_1">ReraiseDefect</span> exception is raised if there is no exception to re-raise. It follows that the <tt class="docutils literal"><span class="pre"><span class="Keyword">raise</span></span></tt> statement <em>always</em> raises an exception.</p>

<h2><a class="toc-backref" id="exception-handling-exception-hierarchy" href="#exception-handling-exception-hierarchy">Exception hierarchy</a></h2><p>The exception tree is defined in the <a class="reference external" href="system.html">system</a> module. Every exception inherits from <tt class="docutils literal"><span class="pre"><span class="Identifier">system</span><span class="Operator">.</span><span class="Identifier">Exception</span></span></tt>. Exceptions that indicate programming bugs inherit from <tt class="docutils literal"><span class="pre"><span class="Identifier">system</span><span class="Operator">.</span><span class="Identifier">Defect</span></span></tt> (which is a subtype of <tt class="docutils literal"><span class="pre"><span class="Identifier">Exception</span></span></tt>) and are strictly speaking not catchable as they can also be mapped to an operation that terminates the whole process. If panics are turned into exceptions, these exceptions inherit from <tt class="docutils literal"><span class="pre"><span class="Identifier">Defect</span></span></tt>.</p>
<p>Exceptions that indicate any other runtime error that can be caught inherit from <tt class="docutils literal"><span class="pre"><span class="Identifier">system</span><span class="Operator">.</span><span class="Identifier">CatchableError</span></span></tt> (which is a subtype of <tt class="docutils literal"><span class="pre"><span class="Identifier">Exception</span></span></tt>).</p>
<p><pre class="listing">Exception
|-- CatchableError
|   |-- IOError
|   |   `-- EOFError
|   |-- OSError
|   |-- ResourceExhaustedError
|   `-- ValueError
|       `-- KeyError
`-- Defect
    |-- AccessViolationDefect
    |-- ArithmeticDefect
    |   |-- DivByZeroDefect
    |   `-- OverflowDefect
    |-- AssertionDefect
    |-- DeadThreadDefect
    |-- FieldDefect
    |-- FloatingPointDefect
    |   |-- FloatDivByZeroDefect
    |   |-- FloatInvalidOpDefect
    |   |-- FloatOverflowDefect
    |   |-- FloatUnderflowDefect
    |   `-- InexactDefect
    |-- IndexDefect
    |-- NilAccessDefect
    |-- ObjectAssignmentDefect
    |-- ObjectConversionDefect
    |-- OutOfMemoryDefect
    |-- RangeDefect
    |-- ReraiseDefect
    `-- StackOverflowDefect</pre></p>

<h2><a class="toc-backref" id="exception-handling-imported-exceptions" href="#exception-handling-imported-exceptions">Imported exceptions</a></h2><p>It is possible to raise/catch imported C++ exceptions. Types imported using <tt class="docutils literal"><span class="pre"><span class="Identifier">importcpp</span></span></tt> can be raised or caught. Exceptions are raised by value and caught by reference. Example:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">CStdException</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importcpp</span><span class="Punctuation">:</span> <span class="StringLit">&quot;std::exception&quot;</span><span class="Punctuation">,</span> <span class="Identifier">header</span><span class="Punctuation">:</span> <span class="StringLit">&quot;&lt;exception&gt;&quot;</span><span class="Punctuation">,</span> <span class="Identifier">inheritable</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">object</span>
    <span class="Comment">## does not inherit from `RootObj`, so we use `inheritable` instead</span>
  <span class="Identifier">CRuntimeError</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">requiresInit</span><span class="Punctuation">,</span> <span class="Identifier">importcpp</span><span class="Punctuation">:</span> <span class="StringLit">&quot;std::runtime_error&quot;</span><span class="Punctuation">,</span> <span class="Identifier">header</span><span class="Punctuation">:</span> <span class="StringLit">&quot;&lt;stdexcept&gt;&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">object</span> <span class="Keyword">of</span> <span class="Identifier">CStdException</span>
    <span class="Comment">## `CRuntimeError` has no default constructor =&gt; `requiresInit`</span>
<span class="Keyword">proc</span> <span class="Identifier">what</span><span class="Punctuation">(</span><span class="Identifier">s</span><span class="Punctuation">:</span> <span class="Identifier">CStdException</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">cstring</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importcpp</span><span class="Punctuation">:</span> <span class="StringLit">&quot;((char *)#.what())&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span>
<span class="Keyword">proc</span> <span class="Identifier">initRuntimeError</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">cstring</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">CRuntimeError</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importcpp</span><span class="Punctuation">:</span> <span class="StringLit">&quot;std::runtime_error(@)&quot;</span><span class="Punctuation">,</span> <span class="Identifier">constructor</span><span class="Operator">.</span><span class="Punctuation">}</span>
<span class="Keyword">proc</span> <span class="Identifier">initStdException</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">CStdException</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importcpp</span><span class="Punctuation">:</span> <span class="StringLit">&quot;std::exception()&quot;</span><span class="Punctuation">,</span> <span class="Identifier">constructor</span><span class="Operator">.</span><span class="Punctuation">}</span>

<span class="Keyword">proc</span> <span class="Identifier">fn</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">let</span> <span class="Identifier">a</span> <span class="Operator">=</span> <span class="Identifier">initRuntimeError</span><span class="Punctuation">(</span><span class="StringLit">&quot;foo&quot;</span><span class="Punctuation">)</span>
  <span class="Identifier">doAssert</span> <span class="Operator">$</span><span class="Identifier">a</span><span class="Operator">.</span><span class="Identifier">what</span> <span class="Operator">==</span> <span class="StringLit">&quot;foo&quot;</span>
  <span class="Keyword">var</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">cstring</span>
  <span class="Keyword">try</span><span class="Punctuation">:</span> <span class="Keyword">raise</span> <span class="Identifier">initRuntimeError</span><span class="Punctuation">(</span><span class="StringLit">&quot;foo2&quot;</span><span class="Punctuation">)</span>
  <span class="Keyword">except</span> <span class="Identifier">CStdException</span> <span class="Keyword">as</span> <span class="Identifier">e</span><span class="Punctuation">:</span>
    <span class="Identifier">doAssert</span> <span class="Identifier">e</span> <span class="Keyword">is</span> <span class="Identifier">CStdException</span>
    <span class="Identifier">b</span> <span class="Operator">=</span> <span class="Identifier">e</span><span class="Operator">.</span><span class="Identifier">what</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
  <span class="Identifier">doAssert</span> <span class="Operator">$</span><span class="Identifier">b</span> <span class="Operator">==</span> <span class="StringLit">&quot;foo2&quot;</span>
  
  <span class="Keyword">try</span><span class="Punctuation">:</span> <span class="Keyword">raise</span> <span class="Identifier">initStdException</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
  <span class="Keyword">except</span> <span class="Identifier">CStdException</span><span class="Punctuation">:</span> <span class="Keyword">discard</span>
  
  <span class="Keyword">try</span><span class="Punctuation">:</span> <span class="Keyword">raise</span> <span class="Identifier">initRuntimeError</span><span class="Punctuation">(</span><span class="StringLit">&quot;foo3&quot;</span><span class="Punctuation">)</span>
  <span class="Keyword">except</span> <span class="Identifier">CRuntimeError</span> <span class="Keyword">as</span> <span class="Identifier">e</span><span class="Punctuation">:</span>
    <span class="Identifier">b</span> <span class="Operator">=</span> <span class="Identifier">e</span><span class="Operator">.</span><span class="Identifier">what</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
  <span class="Keyword">except</span> <span class="Identifier">CStdException</span><span class="Punctuation">:</span>
    <span class="Identifier">doAssert</span> <span class="Identifier">false</span>
  <span class="Identifier">doAssert</span> <span class="Operator">$</span><span class="Identifier">b</span> <span class="Operator">==</span> <span class="StringLit">&quot;foo3&quot;</span>

<span class="Identifier">fn</span><span class="Punctuation">(</span><span class="Punctuation">)</span></pre></p>
<p><strong>Note:</strong> <tt class="docutils literal"><span class="pre"><span class="Identifier">getCurrentException</span><span class="Punctuation">(</span><span class="Punctuation">)</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">getCurrentExceptionMsg</span><span class="Punctuation">(</span><span class="Punctuation">)</span></span></tt> are not available for imported exceptions from C++. One needs to use the <tt class="docutils literal"><span class="pre"><span class="Keyword">except</span> <span class="Identifier">ImportedException</span> <span class="Keyword">as</span> <span class="Identifier">x</span><span class="Punctuation">:</span></span></tt> syntax and rely on functionality of the <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span></span></tt> object to get exception details.</p>

<h1><a class="toc-backref" id="effect-system" href="#effect-system">Effect system</a></h1><p><strong>Note</strong>: The rules for effect tracking changed with the release of version 1.6 of the Nim compiler.</p>

<h2><a class="toc-backref" id="effect-system-exception-tracking" href="#effect-system-exception-tracking">Exception tracking</a></h2><p>Nim supports exception tracking. The <span id="raises_1">raises</span> pragma can be used to explicitly define which exceptions a proc/iterator/method/converter is allowed to raise. The compiler verifies this:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Identifier">what</span><span class="Punctuation">:</span> <span class="Identifier">bool</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">raises</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Identifier">IOError</span><span class="Punctuation">,</span> <span class="Identifier">OSError</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
  <span class="Keyword">if</span> <span class="Identifier">what</span><span class="Punctuation">:</span> <span class="Keyword">raise</span> <span class="Identifier">newException</span><span class="Punctuation">(</span><span class="Identifier">IOError</span><span class="Punctuation">,</span> <span class="StringLit">&quot;IO&quot;</span><span class="Punctuation">)</span>
  <span class="Keyword">else</span><span class="Punctuation">:</span> <span class="Keyword">raise</span> <span class="Identifier">newException</span><span class="Punctuation">(</span><span class="Identifier">OSError</span><span class="Punctuation">,</span> <span class="StringLit">&quot;OS&quot;</span><span class="Punctuation">)</span></pre></p>
<p>An empty <tt class="docutils literal"><span class="pre"><span class="Identifier">raises</span></span></tt> list (<tt class="docutils literal"><span class="pre"><span class="Identifier">raises</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Punctuation">]</span></span></tt>) means that no exception may be raised:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">bool</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">raises</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
  <span class="Keyword">try</span><span class="Punctuation">:</span>
    <span class="Identifier">unsafeCall</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
    <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">true</span>
  <span class="Keyword">except</span> <span class="Identifier">CatchableError</span><span class="Punctuation">:</span>
    <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">false</span></pre></p>
<p>A <tt class="docutils literal"><span class="pre"><span class="Identifier">raises</span></span></tt> list can also be attached to a proc type. This affects type compatibility:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">Callback</span> <span class="Operator">=</span> <span class="Keyword">proc</span> <span class="Punctuation">(</span><span class="Identifier">s</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">raises</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Identifier">IOError</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Punctuation">}</span>
<span class="Keyword">var</span>
  <span class="Identifier">c</span><span class="Punctuation">:</span> <span class="Identifier">Callback</span>

<span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">raise</span> <span class="Identifier">newException</span><span class="Punctuation">(</span><span class="Identifier">OSError</span><span class="Punctuation">,</span> <span class="StringLit">&quot;OS&quot;</span><span class="Punctuation">)</span>

<span class="Identifier">c</span> <span class="Operator">=</span> <span class="Identifier">p</span> <span class="Comment"># type error</span></pre></p>
<p>For a routine <tt class="docutils literal"><span class="pre"><span class="Identifier">p</span></span></tt>, the compiler uses inference rules to determine the set of possibly raised exceptions; the algorithm operates on <tt class="docutils literal"><span class="pre"><span class="Identifier">p</span></span></tt>'s call graph:</p>
<ol class="simple"><li>Every indirect call via some proc type <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span></span></tt> is assumed to raise <tt class="docutils literal"><span class="pre"><span class="Identifier">system</span><span class="Operator">.</span><span class="Identifier">Exception</span></span></tt> (the base type of the exception hierarchy) and thus any exception unless <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span></span></tt> has an explicit <tt class="docutils literal"><span class="pre"><span class="Identifier">raises</span></span></tt> list. However, if the call is of the form <tt class="docutils literal"><span class="pre"><span class="Identifier">f</span><span class="Punctuation">(</span><span class="Operator">...</span><span class="Punctuation">)</span></span></tt> where <tt class="docutils literal"><span class="pre"><span class="Identifier">f</span></span></tt> is a parameter of the currently analyzed routine that is marked as <tt class="docutils literal"><span class="pre"><span class="Operator">.</span><span class="Identifier">effectsOf</span><span class="Punctuation">:</span> <span class="Identifier">f</span></span></tt>, it is ignored. The call is optimistically assumed to have no effect. Rule 2 compensates for this case.</li>
<li>Every expression <tt class="docutils literal"><span class="pre"><span class="Identifier">e</span></span></tt> of some proc type within a call that is passed to parameter marked as <tt class="docutils literal"><span class="pre"><span class="Operator">.</span><span class="Identifier">effectsOf</span></span></tt> of proc <tt class="docutils literal"><span class="pre"><span class="Identifier">p</span></span></tt> is assumed to be called indirectly and thus its raises list is added to <tt class="docutils literal"><span class="pre"><span class="Identifier">p</span></span></tt>'s raises list.</li>
<li>Every call to a proc <tt class="docutils literal"><span class="pre"><span class="Identifier">q</span></span></tt> which has an unknown body (due to a forward declaration) is assumed to raise <tt class="docutils literal"><span class="pre"><span class="Identifier">system</span><span class="Operator">.</span><span class="Identifier">Exception</span></span></tt> unless <tt class="docutils literal"><span class="pre"><span class="Identifier">q</span></span></tt> has an explicit <tt class="docutils literal"><span class="pre"><span class="Identifier">raises</span></span></tt> list. Procs that are <tt class="docutils literal"><span class="pre"><span class="Identifier">importc</span></span></tt>'ed are assumed to have <tt class="docutils literal"><span class="pre"><span class="Operator">.</span><span class="Identifier">raises</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Punctuation">]</span></span></tt>, unless explicitly declared otherwise.</li>
<li>Every call to a method <tt class="docutils literal"><span class="pre"><span class="Identifier">m</span></span></tt> is assumed to raise <tt class="docutils literal"><span class="pre"><span class="Identifier">system</span><span class="Operator">.</span><span class="Identifier">Exception</span></span></tt> unless <tt class="docutils literal"><span class="pre"><span class="Identifier">m</span></span></tt> has an explicit <tt class="docutils literal"><span class="pre"><span class="Identifier">raises</span></span></tt> list.</li>
<li>For every other call, the analysis can determine an exact <tt class="docutils literal"><span class="pre"><span class="Identifier">raises</span></span></tt> list.</li>
<li>For determining a <tt class="docutils literal"><span class="pre"><span class="Identifier">raises</span></span></tt> list, the <tt class="docutils literal"><span class="pre"><span class="Keyword">raise</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Keyword">try</span></span></tt> statements of <tt class="docutils literal"><span class="pre"><span class="Identifier">p</span></span></tt> are taken into consideration.</li>
</ol>
<p>Exceptions inheriting from <tt class="docutils literal"><span class="pre"><span class="Identifier">system</span><span class="Operator">.</span><span class="Identifier">Defect</span></span></tt> are not tracked with the <tt class="docutils literal"><span class="pre"><span class="Operator">.</span><span class="Identifier">raises</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Punctuation">]</span></span></tt> exception tracking mechanism. This is more consistent with the built-in operations. The following code is valid:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">mydiv</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">raises</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
  <span class="Identifier">a</span> <span class="Keyword">div</span> <span class="Identifier">b</span> <span class="Comment"># can raise an DivByZeroDefect</span></pre></p>
<p>And so is:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">mydiv</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">raises</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
  <span class="Keyword">if</span> <span class="Identifier">b</span> <span class="Operator">==</span> <span class="DecNumber">0</span><span class="Punctuation">:</span> <span class="Keyword">raise</span> <span class="Identifier">newException</span><span class="Punctuation">(</span><span class="Identifier">DivByZeroDefect</span><span class="Punctuation">,</span> <span class="StringLit">&quot;division by zero&quot;</span><span class="Punctuation">)</span>
  <span class="Keyword">else</span><span class="Punctuation">:</span> <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">a</span> <span class="Keyword">div</span> <span class="Identifier">b</span></pre></p>
<p>The reason for this is that <tt class="docutils literal"><span class="pre"><span class="Identifier">DivByZeroDefect</span></span></tt> inherits from <tt class="docutils literal"><span class="pre"><span class="Identifier">Defect</span></span></tt> and with <tt class="docutils literal"><span class="pre option">--panics:on</span></tt> Defects become unrecoverable errors. (Since version 1.4 of the language.)</p>

<h2><a class="toc-backref" id="effect-system-effectsof-annotation" href="#effect-system-effectsof-annotation">EffectsOf annotation</a></h2><p>Rules 1-2 of the exception tracking inference rules (see the previous section) ensure the following works:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">weDontRaiseButMaybeTheCallback</span><span class="Punctuation">(</span><span class="Identifier">callback</span><span class="Punctuation">:</span> <span class="Keyword">proc</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">raises</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Punctuation">,</span> <span class="Identifier">effectsOf</span><span class="Punctuation">:</span> <span class="Identifier">callback</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
  <span class="Identifier">callback</span><span class="Punctuation">(</span><span class="Punctuation">)</span>

<span class="Keyword">proc</span> <span class="Identifier">doRaise</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">raises</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Identifier">IOError</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
  <span class="Keyword">raise</span> <span class="Identifier">newException</span><span class="Punctuation">(</span><span class="Identifier">IOError</span><span class="Punctuation">,</span> <span class="StringLit">&quot;IO&quot;</span><span class="Punctuation">)</span>

<span class="Keyword">proc</span> <span class="Identifier">use</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">raises</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
  <span class="Comment"># doesn't compile! Can raise IOError!</span>
  <span class="Identifier">weDontRaiseButMaybeTheCallback</span><span class="Punctuation">(</span><span class="Identifier">doRaise</span><span class="Punctuation">)</span></pre></p>
<p>As can be seen from the example, a parameter of type <tt class="docutils literal"><span class="pre"><span class="Keyword">proc</span> <span class="Punctuation">(</span><span class="Operator">...</span><span class="Punctuation">)</span></span></tt> can be annotated as <tt class="docutils literal"><span class="pre"><span class="Operator">.</span><span class="Identifier">effectsOf</span></span></tt>. Such a parameter allows for effect polymorphism: The proc <tt class="docutils literal"><span class="pre"><span class="Identifier">weDontRaiseButMaybeTheCallback</span></span></tt> raises the exceptions that <tt class="docutils literal"><span class="pre"><span class="Identifier">callback</span></span></tt> raises.</p>
<p>So in many cases a callback does not cause the compiler to be overly conservative in its effect analysis:</p>
<p><pre class="listing"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">push</span> <span class="Identifier">warningAsError</span><span class="Punctuation">[</span><span class="Identifier">Effect</span><span class="Punctuation">]</span><span class="Punctuation">:</span> <span class="Identifier">on</span><span class="Operator">.</span><span class="Punctuation">}</span>

<span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">algorithm</span>

<span class="Keyword">type</span>
  <span class="Identifier">MyInt</span> <span class="Operator">=</span> <span class="Keyword">distinct</span> <span class="Identifier">int</span>

<span class="Keyword">var</span> <span class="Identifier">toSort</span> <span class="Operator">=</span> <span class="Operator">@</span><span class="Punctuation">[</span><span class="Identifier">MyInt</span> <span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="Identifier">MyInt</span> <span class="DecNumber">2</span><span class="Punctuation">,</span> <span class="Identifier">MyInt</span> <span class="DecNumber">3</span><span class="Punctuation">]</span>

<span class="Keyword">proc</span> <span class="Identifier">cmpN</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">MyInt</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span>
  <span class="Identifier">cmp</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Operator">.</span><span class="Identifier">int</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Operator">.</span><span class="Identifier">int</span><span class="Punctuation">)</span>

<span class="Keyword">proc</span> <span class="Identifier">harmless</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">raises</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
  <span class="Identifier">toSort</span><span class="Operator">.</span><span class="Identifier">sort</span> <span class="Identifier">cmpN</span>

<span class="Keyword">proc</span> <span class="Identifier">cmpE</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">MyInt</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">raises</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Identifier">Exception</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
  <span class="Identifier">cmp</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Operator">.</span><span class="Identifier">int</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Operator">.</span><span class="Identifier">int</span><span class="Punctuation">)</span>

<span class="Keyword">proc</span> <span class="Identifier">harmful</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">raises</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
  <span class="Comment"># does not compile, `sort` can now raise Exception</span>
  <span class="Identifier">toSort</span><span class="Operator">.</span><span class="Identifier">sort</span> <span class="Identifier">cmpE</span></pre></p>

<h2><a class="toc-backref" id="effect-system-tag-tracking" href="#effect-system-tag-tracking">Tag tracking</a></h2><p>Exception tracking is part of Nim's <span id="effect-system_1">effect system</span>. Raising an exception is an <em>effect</em>. Other effects can also be defined. A user defined effect is a means to <em>tag</em> a routine and to perform checks against this tag:</p>
<p><pre class="listing"><span class="Keyword">type</span> <span class="Identifier">IO</span> <span class="Operator">=</span> <span class="Keyword">object</span> <span class="Comment">## input/output effect</span>
<span class="Keyword">proc</span> <span class="Identifier">readLine</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">string</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">tags</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Identifier">IO</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">discard</span>

<span class="Keyword">proc</span> <span class="Identifier">no_effects_please</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">tags</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
  <span class="Comment"># the compiler prevents this:</span>
  <span class="Keyword">let</span> <span class="Identifier">x</span> <span class="Operator">=</span> <span class="Identifier">readLine</span><span class="Punctuation">(</span><span class="Punctuation">)</span></pre></p>
<p>A tag has to be a type name. A <tt class="docutils literal"><span class="pre"><span class="Identifier">tags</span></span></tt> list - like a <tt class="docutils literal"><span class="pre"><span class="Identifier">raises</span></span></tt> list - can also be attached to a proc type. This affects type compatibility.</p>
<p>The inference for tag tracking is analogous to the inference for exception tracking.</p>
<p>There is also a way which can be used to forbid certain effects:</p>
<p><pre class="listing"><span class="Keyword">type</span> <span class="Identifier">IO</span> <span class="Operator">=</span> <span class="Keyword">object</span> <span class="Comment">## input/output effect</span>
<span class="Keyword">proc</span> <span class="Identifier">readLine</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">string</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">tags</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Identifier">IO</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">discard</span>
<span class="Keyword">proc</span> <span class="Identifier">echoLine</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">void</span> <span class="Operator">=</span> <span class="Keyword">discard</span>

<span class="Keyword">proc</span> <span class="Identifier">no_IO_please</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">forbids</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Identifier">IO</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
  <span class="Comment"># this is OK because it didn't define any tag:</span>
  <span class="Identifier">echoLine</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
  <span class="Comment"># the compiler prevents this:</span>
  <span class="Keyword">let</span> <span class="Identifier">y</span> <span class="Operator">=</span> <span class="Identifier">readLine</span><span class="Punctuation">(</span><span class="Punctuation">)</span></pre></p>
<p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">forbids</span></span></tt> pragma defines a list of illegal effects - if any statement invokes any of those effects, the compilation will fail. Procedure types with any disallowed effect are the subtypes of equal procedure types without such lists:</p>
<p><pre class="listing"><span class="Keyword">type</span> <span class="Identifier">MyEffect</span> <span class="Operator">=</span> <span class="Keyword">object</span>
<span class="Keyword">type</span> <span class="Identifier">ProcType1</span> <span class="Operator">=</span> <span class="Keyword">proc</span> <span class="Punctuation">(</span><span class="Identifier">i</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">void</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">forbids</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Identifier">MyEffect</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Punctuation">}</span>
<span class="Keyword">type</span> <span class="Identifier">ProcType2</span> <span class="Operator">=</span> <span class="Keyword">proc</span> <span class="Punctuation">(</span><span class="Identifier">i</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">void</span>

<span class="Keyword">proc</span> <span class="Identifier">caller1</span><span class="Punctuation">(</span><span class="Identifier">p</span><span class="Punctuation">:</span> <span class="Identifier">ProcType1</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">void</span> <span class="Operator">=</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="DecNumber">1</span><span class="Punctuation">)</span>
<span class="Keyword">proc</span> <span class="Identifier">caller2</span><span class="Punctuation">(</span><span class="Identifier">p</span><span class="Punctuation">:</span> <span class="Identifier">ProcType2</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">void</span> <span class="Operator">=</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="DecNumber">1</span><span class="Punctuation">)</span>

<span class="Keyword">proc</span> <span class="Identifier">effectful</span><span class="Punctuation">(</span><span class="Identifier">i</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">void</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">tags</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Identifier">MyEffect</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Identifier">echo</span> <span class="Operator">$</span><span class="Identifier">i</span>
<span class="Keyword">proc</span> <span class="Identifier">effectless</span><span class="Punctuation">(</span><span class="Identifier">i</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">void</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">forbids</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Identifier">MyEffect</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Identifier">echo</span> <span class="Operator">$</span><span class="Identifier">i</span>

<span class="Keyword">proc</span> <span class="Identifier">toBeCalled1</span><span class="Punctuation">(</span><span class="Identifier">i</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">void</span> <span class="Operator">=</span> <span class="Identifier">effectful</span><span class="Punctuation">(</span><span class="Identifier">i</span><span class="Punctuation">)</span>
<span class="Keyword">proc</span> <span class="Identifier">toBeCalled2</span><span class="Punctuation">(</span><span class="Identifier">i</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">void</span> <span class="Operator">=</span> <span class="Identifier">effectless</span><span class="Punctuation">(</span><span class="Identifier">i</span><span class="Punctuation">)</span>

<span class="Comment">## this will fail because toBeCalled1 uses MyEffect which was forbidden by ProcType1:</span>
<span class="Identifier">caller1</span><span class="Punctuation">(</span><span class="Identifier">toBeCalled1</span><span class="Punctuation">)</span>
<span class="Comment">## this is OK because both toBeCalled2 and ProcType1 have the same requirements:</span>
<span class="Identifier">caller1</span><span class="Punctuation">(</span><span class="Identifier">toBeCalled2</span><span class="Punctuation">)</span>
<span class="Comment">## these are OK because ProcType2 doesn't have any effect requirement:</span>
<span class="Identifier">caller2</span><span class="Punctuation">(</span><span class="Identifier">toBeCalled1</span><span class="Punctuation">)</span>
<span class="Identifier">caller2</span><span class="Punctuation">(</span><span class="Identifier">toBeCalled2</span><span class="Punctuation">)</span></pre></p>
<p><tt class="docutils literal"><span class="pre"><span class="Identifier">ProcType2</span></span></tt> is a subtype of <tt class="docutils literal"><span class="pre"><span class="Identifier">ProcType1</span></span></tt>. Unlike with the <tt class="docutils literal"><span class="pre"><span class="Identifier">tags</span></span></tt> pragma, the parent context - the function which calls other functions with forbidden effects - doesn't inherit the forbidden list of effects.</p>

<h2><a class="toc-backref" id="effect-system-side-effects" href="#effect-system-side-effects">Side effects</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">noSideEffect</span></span></tt> pragma is used to mark a proc/iterator that can have only side effects through parameters. This means that the proc/iterator only changes locations that are reachable from its parameters and the return value only depends on the parameters. If none of its parameters have the type <tt class="docutils literal"><span class="pre"><span class="Keyword">var</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">ref</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">ptr</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Identifier">cstring</span></span></tt>, or <tt class="docutils literal"><span class="pre"><span class="Keyword">proc</span></span></tt>, then no locations are modified.</p>
<p>In other words, a routine has no side effects if it does not access a threadlocal or global variable and it does not call any routine that has a side effect.</p>
<p>It is a static error to mark a proc/iterator to have no side effect if the compiler cannot verify this.</p>
<p>As a special semantic rule, the built-in <a class="reference external" href=" system.html#debugEcho,varargs[typed,]">debugEcho</a> pretends to be free of side effects so that it can be used for debugging routines marked as <tt class="docutils literal"><span class="pre"><span class="Identifier">noSideEffect</span></span></tt>.</p>
<p><tt class="docutils literal"><span class="pre"><span class="Keyword">func</span></span></tt> is syntactic sugar for a proc with no side effects:</p>
<p><pre class="listing"><span class="Keyword">func</span> <span class="Punctuation">`</span><span class="Operator">+</span><span class="Punctuation">`</span> <span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span></pre></p>
<p>To override the compiler's side effect analysis a <tt class="docutils literal"><span class="pre"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">noSideEffect</span><span class="Operator">.</span><span class="Punctuation">}</span></span></tt> <tt class="docutils literal"><span class="pre"><span class="Keyword">cast</span></span></tt> pragma block can be used:</p>
<p><pre class="listing"><span class="Keyword">func</span> <span class="Identifier">f</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Punctuation">{</span><span class="Operator">.</span><span class="Keyword">cast</span><span class="Punctuation">(</span><span class="Identifier">noSideEffect</span><span class="Punctuation">)</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span>
    <span class="Identifier">echo</span> <span class="StringLit">&quot;test&quot;</span></pre></p>
<p><strong>Side effects are usually inferred. The inference for side effects is analogous to the inference for exception tracking.</strong></p>
<p>When the compiler cannot infer side effects, as is the case for imported functions, one can annotate them with the <tt class="docutils literal"><span class="pre"><span class="Identifier">sideEffect</span></span></tt> pragma.</p>

<h2><a class="toc-backref" id="effect-system-gc-safety-effect" href="#effect-system-gc-safety-effect">GC safety effect</a></h2><p>We call a proc <tt class="docutils literal"><span class="pre"><span class="Identifier">p</span></span></tt> <span id="gc-safe_1">GC safe</span> when it doesn't access any global variable that contains GC'ed memory (<tt class="docutils literal"><span class="pre"><span class="Identifier">string</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Identifier">seq</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">ref</span></span></tt> or a closure) either directly or indirectly through a call to a GC unsafe proc.</p>
<p><strong>The GC safety property is usually inferred. The inference for GC safety is analogous to the inference for exception tracking.</strong></p>
<p>The <span id="gcsafe_1">gcsafe</span> annotation can be used to mark a proc to be gcsafe, otherwise this property is inferred by the compiler. Note that <tt class="docutils literal"><span class="pre"><span class="Identifier">noSideEffect</span></span></tt> implies <tt class="docutils literal"><span class="pre"><span class="Identifier">gcsafe</span></span></tt>.</p>
<p>Routines that are imported from C are always assumed to be <tt class="docutils literal"><span class="pre"><span class="Identifier">gcsafe</span></span></tt>.</p>
<p>To override the compiler's gcsafety analysis a <tt class="docutils literal"><span class="pre"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Keyword">cast</span><span class="Punctuation">(</span><span class="Identifier">gcsafe</span><span class="Punctuation">)</span><span class="Operator">.</span><span class="Punctuation">}</span></span></tt> pragma block can be used:</p>
<p><pre class="listing"><span class="Keyword">var</span>
  <span class="Identifier">someGlobal</span><span class="Punctuation">:</span> <span class="Identifier">string</span> <span class="Operator">=</span> <span class="StringLit">&quot;some string here&quot;</span>
  <span class="Identifier">perThread</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">threadvar</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span> <span class="Identifier">string</span>

<span class="Keyword">proc</span> <span class="Identifier">setPerThread</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Punctuation">{</span><span class="Operator">.</span><span class="Keyword">cast</span><span class="Punctuation">(</span><span class="Identifier">gcsafe</span><span class="Punctuation">)</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span>
    <span class="Identifier">deepCopy</span><span class="Punctuation">(</span><span class="Identifier">perThread</span><span class="Punctuation">,</span> <span class="Identifier">someGlobal</span><span class="Punctuation">)</span></pre></p>
<p>See also:</p>
<ul class="simple"><li><a class="reference external" href="mm.html">Shared heap memory management</a>.</li>
</ul>

<h2><a class="toc-backref" id="effect-system-effects-pragma" href="#effect-system-effects-pragma">Effects pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">effects</span></span></tt> pragma has been designed to assist the programmer with the effects analysis. It is a statement that makes the compiler output all inferred effects up to the <tt class="docutils literal"><span class="pre"><span class="Identifier">effects</span></span></tt>'s position:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Identifier">what</span><span class="Punctuation">:</span> <span class="Identifier">bool</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">if</span> <span class="Identifier">what</span><span class="Punctuation">:</span>
    <span class="Keyword">raise</span> <span class="Identifier">newException</span><span class="Punctuation">(</span><span class="Identifier">IOError</span><span class="Punctuation">,</span> <span class="StringLit">&quot;IO&quot;</span><span class="Punctuation">)</span>
    <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">effects</span><span class="Operator">.</span><span class="Punctuation">}</span>
  <span class="Keyword">else</span><span class="Punctuation">:</span>
    <span class="Keyword">raise</span> <span class="Identifier">newException</span><span class="Punctuation">(</span><span class="Identifier">OSError</span><span class="Punctuation">,</span> <span class="StringLit">&quot;OS&quot;</span><span class="Punctuation">)</span></pre></p>
<p>The compiler produces a hint message that <tt class="docutils literal"><span class="pre"><span class="Identifier">IOError</span></span></tt> can be raised. <tt class="docutils literal"><span class="pre"><span class="Identifier">OSError</span></span></tt> is not listed as it cannot be raised in the branch the <tt class="docutils literal"><span class="pre"><span class="Identifier">effects</span></span></tt> pragma appears in.</p>

<h1><a class="toc-backref" id="generics" href="#generics">Generics</a></h1><p>Generics are Nim's means to parametrize procs, iterators or types with <span id="type-parameters_1">type parameters</span>. Depending on the context, the brackets are used either to introduce type parameters or to instantiate a generic proc, iterator, or type.</p>
<p>The following example shows how a generic binary tree can be modeled:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">BinaryTree</span><span class="Operator">*</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Keyword">object</span> <span class="Comment"># BinaryTree is a generic type with</span>
                              <span class="Comment"># generic parameter `T`</span>
    <span class="Identifier">le</span><span class="Punctuation">,</span> <span class="Identifier">ri</span><span class="Punctuation">:</span> <span class="Identifier">BinaryTree</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span>     <span class="Comment"># left and right subtrees; may be nil</span>
    <span class="Identifier">data</span><span class="Punctuation">:</span> <span class="Identifier">T</span>                   <span class="Comment"># the data stored in a node</span>

<span class="Keyword">proc</span> <span class="Identifier">newNode</span><span class="Operator">*</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">data</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">BinaryTree</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span> <span class="Operator">=</span>
  <span class="Comment"># constructor for a node</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">BinaryTree</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">le</span><span class="Punctuation">:</span> <span class="Keyword">nil</span><span class="Punctuation">,</span> <span class="Identifier">ri</span><span class="Punctuation">:</span> <span class="Keyword">nil</span><span class="Punctuation">,</span> <span class="Identifier">data</span><span class="Punctuation">:</span> <span class="Identifier">data</span><span class="Punctuation">)</span>

<span class="Keyword">proc</span> <span class="Identifier">add</span><span class="Operator">*</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">root</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">BinaryTree</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">,</span> <span class="Identifier">n</span><span class="Punctuation">:</span> <span class="Identifier">BinaryTree</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Comment"># insert a node into the tree</span>
  <span class="Keyword">if</span> <span class="Identifier">root</span> <span class="Operator">==</span> <span class="Keyword">nil</span><span class="Punctuation">:</span>
    <span class="Identifier">root</span> <span class="Operator">=</span> <span class="Identifier">n</span>
  <span class="Keyword">else</span><span class="Punctuation">:</span>
    <span class="Keyword">var</span> <span class="Identifier">it</span> <span class="Operator">=</span> <span class="Identifier">root</span>
    <span class="Keyword">while</span> <span class="Identifier">it</span> <span class="Operator">!=</span> <span class="Keyword">nil</span><span class="Punctuation">:</span>
      <span class="Comment"># compare the data items; uses the generic `cmp` proc</span>
      <span class="Comment"># that works for any type that has a `==` and `&lt;` operator</span>
      <span class="Keyword">var</span> <span class="Identifier">c</span> <span class="Operator">=</span> <span class="Identifier">cmp</span><span class="Punctuation">(</span><span class="Identifier">it</span><span class="Operator">.</span><span class="Identifier">data</span><span class="Punctuation">,</span> <span class="Identifier">n</span><span class="Operator">.</span><span class="Identifier">data</span><span class="Punctuation">)</span>
      <span class="Keyword">if</span> <span class="Identifier">c</span> <span class="Operator">&lt;</span> <span class="DecNumber">0</span><span class="Punctuation">:</span>
        <span class="Keyword">if</span> <span class="Identifier">it</span><span class="Operator">.</span><span class="Identifier">le</span> <span class="Operator">==</span> <span class="Keyword">nil</span><span class="Punctuation">:</span>
          <span class="Identifier">it</span><span class="Operator">.</span><span class="Identifier">le</span> <span class="Operator">=</span> <span class="Identifier">n</span>
          <span class="Keyword">return</span>
        <span class="Identifier">it</span> <span class="Operator">=</span> <span class="Identifier">it</span><span class="Operator">.</span><span class="Identifier">le</span>
      <span class="Keyword">else</span><span class="Punctuation">:</span>
        <span class="Keyword">if</span> <span class="Identifier">it</span><span class="Operator">.</span><span class="Identifier">ri</span> <span class="Operator">==</span> <span class="Keyword">nil</span><span class="Punctuation">:</span>
          <span class="Identifier">it</span><span class="Operator">.</span><span class="Identifier">ri</span> <span class="Operator">=</span> <span class="Identifier">n</span>
          <span class="Keyword">return</span>
        <span class="Identifier">it</span> <span class="Operator">=</span> <span class="Identifier">it</span><span class="Operator">.</span><span class="Identifier">ri</span>

<span class="Keyword">proc</span> <span class="Identifier">add</span><span class="Operator">*</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">root</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">BinaryTree</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">,</span> <span class="Identifier">data</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Comment"># convenience proc:</span>
  <span class="Identifier">add</span><span class="Punctuation">(</span><span class="Identifier">root</span><span class="Punctuation">,</span> <span class="Identifier">newNode</span><span class="Punctuation">(</span><span class="Identifier">data</span><span class="Punctuation">)</span><span class="Punctuation">)</span>

<span class="Keyword">iterator</span> <span class="Identifier">preorder</span><span class="Operator">*</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">root</span><span class="Punctuation">:</span> <span class="Identifier">BinaryTree</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">T</span> <span class="Operator">=</span>
  <span class="Comment"># Preorder traversal of a binary tree.</span>
  <span class="Comment"># This uses an explicit stack (which is more efficient than</span>
  <span class="Comment"># a recursive iterator factory).</span>
  <span class="Keyword">var</span> <span class="Identifier">stack</span><span class="Punctuation">:</span> <span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">BinaryTree</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Operator">@</span><span class="Punctuation">[</span><span class="Identifier">root</span><span class="Punctuation">]</span>
  <span class="Keyword">while</span> <span class="Identifier">stack</span><span class="Operator">.</span><span class="Identifier">len</span> <span class="Operator">&gt;</span> <span class="DecNumber">0</span><span class="Punctuation">:</span>
    <span class="Keyword">var</span> <span class="Identifier">n</span> <span class="Operator">=</span> <span class="Identifier">stack</span><span class="Operator">.</span><span class="Identifier">pop</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
    <span class="Keyword">while</span> <span class="Identifier">n</span> <span class="Operator">!=</span> <span class="Keyword">nil</span><span class="Punctuation">:</span>
      <span class="Keyword">yield</span> <span class="Identifier">n</span><span class="Operator">.</span><span class="Identifier">data</span>
      <span class="Identifier">add</span><span class="Punctuation">(</span><span class="Identifier">stack</span><span class="Punctuation">,</span> <span class="Identifier">n</span><span class="Operator">.</span><span class="Identifier">ri</span><span class="Punctuation">)</span>  <span class="Comment"># push right subtree onto the stack</span>
      <span class="Identifier">n</span> <span class="Operator">=</span> <span class="Identifier">n</span><span class="Operator">.</span><span class="Identifier">le</span>          <span class="Comment"># and follow the left pointer</span>

<span class="Keyword">var</span>
  <span class="Identifier">root</span><span class="Punctuation">:</span> <span class="Identifier">BinaryTree</span><span class="Punctuation">[</span><span class="Identifier">string</span><span class="Punctuation">]</span> <span class="Comment"># instantiate a BinaryTree with `string`</span>
<span class="Identifier">add</span><span class="Punctuation">(</span><span class="Identifier">root</span><span class="Punctuation">,</span> <span class="Identifier">newNode</span><span class="Punctuation">(</span><span class="StringLit">&quot;hello&quot;</span><span class="Punctuation">)</span><span class="Punctuation">)</span> <span class="Comment"># instantiates `newNode` and `add`</span>
<span class="Identifier">add</span><span class="Punctuation">(</span><span class="Identifier">root</span><span class="Punctuation">,</span> <span class="StringLit">&quot;world&quot;</span><span class="Punctuation">)</span>          <span class="Comment"># instantiates the second `add` proc</span>
<span class="Keyword">for</span> <span class="Identifier">str</span> <span class="Keyword">in</span> <span class="Identifier">preorder</span><span class="Punctuation">(</span><span class="Identifier">root</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
  <span class="Identifier">stdout</span><span class="Operator">.</span><span class="Identifier">writeLine</span><span class="Punctuation">(</span><span class="Identifier">str</span><span class="Punctuation">)</span></pre></p>
<p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span></span></tt> is called a <span id="generic-type-parameter_1">generic type parameter</span> or a <span id="type-variable_1">type variable</span>.</p>

<h2><a class="toc-backref" id="generics-generic-procs" href="#generics-generic-procs">Generic Procs</a></h2><p>Let's consider the anatomy of a generic <tt class="docutils literal"><span class="pre"><span class="Keyword">proc</span></span></tt> to agree on defined terminology.</p>
<p><pre class="listing"><span class="Identifier">p</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">:</span> <span class="Identifier">t</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">arg1</span><span class="Punctuation">:</span> <span class="Identifier">f</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">y</span></pre></p>
<ul class="simple"><li><tt class="docutils literal"><span class="pre"><span class="Identifier">p</span></span></tt>: Callee symbol</li>
<li><tt class="docutils literal"><span class="pre"><span class="Punctuation">[</span><span class="Operator">...</span><span class="Punctuation">]</span></span></tt>: Generic parameters</li>
<li><tt class="docutils literal"><span class="pre"><span class="Identifier">T</span><span class="Punctuation">:</span> <span class="Identifier">t</span></span></tt>: Generic constraint</li>
<li><tt class="docutils literal"><span class="pre"><span class="Identifier">T</span></span></tt>: Type variable</li>
<li><tt class="docutils literal"><span class="pre"><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">:</span> <span class="Identifier">t</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">arg1</span><span class="Punctuation">:</span> <span class="Identifier">f</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">y</span></span></tt>: Formal signature</li>
<li><tt class="docutils literal"><span class="pre"><span class="Identifier">arg1</span><span class="Punctuation">:</span> <span class="Identifier">f</span></span></tt>: Formal parameter</li>
<li><tt class="docutils literal"><span class="pre"><span class="Identifier">f</span></span></tt>: Formal parameter type</li>
<li><tt class="docutils literal"><span class="pre"><span class="Identifier">y</span></span></tt>: Formal return type</li>
</ul>
<p>The use of the word &quot;formal&quot; here is to denote the symbols as they are defined by the programmer, not as they may be at compile time contextually. Since generics may be instantiated and types bound, we have more than one entity to think about when generics are involved.</p>
<p>The usage of a generic will resolve the formally defined expression into an instance of that expression bound to only concrete types. This process is called &quot;instantiation&quot;.</p>
<p>Brackets at the site of a generic's formal definition specify the &quot;constraints&quot; as in:</p>
<p><pre class="listing"><span class="Keyword">type</span> <span class="Identifier">Foo</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Keyword">object</span>
<span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">[</span><span class="Identifier">H</span><span class="Punctuation">;</span><span class="Identifier">T</span><span class="Punctuation">:</span> <span class="Identifier">Foo</span><span class="Punctuation">[</span><span class="Identifier">H</span><span class="Punctuation">]</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">param</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">H</span></pre></p>
<p>A constraint definition may have more than one symbol defined by separating each definition by a <tt class="docutils literal"><span class="pre"><span class="Punctuation">;</span></span></tt>. Notice how <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span></span></tt> is composed of <tt class="docutils literal"><span class="pre"><span class="Identifier">H</span></span></tt> and the return  type of <tt class="docutils literal"><span class="pre"><span class="Identifier">p</span></span></tt> is defined as <tt class="docutils literal"><span class="pre"><span class="Identifier">H</span></span></tt>. When this generic proc is instantiated <tt class="docutils literal"><span class="pre"><span class="Identifier">H</span></span></tt> will be bound to a concrete type, thus making <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span></span></tt> concrete and the return type of <tt class="docutils literal"><span class="pre"><span class="Identifier">p</span></span></tt> will be bound to the same concrete type used to define <tt class="docutils literal"><span class="pre"><span class="Identifier">H</span></span></tt>.</p>
<p>Brackets at the site of usage can be used to supply concrete types to instantiate the generic in the same order that the symbols are defined in the constraint. Alternatively, type bindings may be inferred by the compiler in some situations, allowing for cleaner code.</p>

<h2><a class="toc-backref" id="generics-is-operator" href="#generics-is-operator">Is operator</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Keyword">is</span></span></tt> operator is evaluated during semantic analysis to check for type equivalence. It is therefore very useful for type specialization within generic code:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">Table</span><span class="Punctuation">[</span><span class="Identifier">Key</span><span class="Punctuation">,</span> <span class="Identifier">Value</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Keyword">object</span>
    <span class="Identifier">keys</span><span class="Punctuation">:</span> <span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">Key</span><span class="Punctuation">]</span>
    <span class="Identifier">values</span><span class="Punctuation">:</span> <span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">Value</span><span class="Punctuation">]</span>
    <span class="Keyword">when</span> <span class="Keyword">not</span> <span class="Punctuation">(</span><span class="Identifier">Key</span> <span class="Keyword">is</span> <span class="Identifier">string</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Comment"># empty value for strings used for optimization</span>
      <span class="Identifier">deletedKeys</span><span class="Punctuation">:</span> <span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">bool</span><span class="Punctuation">]</span></pre></p>

<h2><a class="toc-backref" id="generics-type-classes" href="#generics-type-classes">Type classes</a></h2><p>A type class is a special pseudo-type that can be used to match against types in the context of overload resolution or the <tt class="docutils literal"><span class="pre"><span class="Keyword">is</span></span></tt> operator. Nim supports the following built-in type classes:</p>
<table border="1" class="docutils"><tr><th>type class</th><th>matches</th></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Keyword">object</span></span></tt></td><td>any object type</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Keyword">tuple</span></span></tt></td><td>any tuple type</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Keyword">enum</span></span></tt></td><td>any enumeration</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Keyword">proc</span></span></tt></td><td>any proc type</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Keyword">iterator</span></span></tt></td><td>any iterator type</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Keyword">ref</span></span></tt></td><td>any <tt class="docutils literal"><span class="pre"><span class="Keyword">ref</span></span></tt> type</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Keyword">ptr</span></span></tt></td><td>any <tt class="docutils literal"><span class="pre"><span class="Keyword">ptr</span></span></tt> type</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Keyword">var</span></span></tt></td><td>any <tt class="docutils literal"><span class="pre"><span class="Keyword">var</span></span></tt> type</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Keyword">distinct</span></span></tt></td><td>any distinct type</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">array</span></span></tt></td><td>any array type</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">set</span></span></tt></td><td>any set type</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">seq</span></span></tt></td><td>any seq type</td></tr>
<tr><td><tt class="docutils literal"><span class="pre"><span class="Identifier">auto</span></span></tt></td><td>any type</td></tr>
</table><p>Furthermore, every generic type automatically creates a type class of the same name that will match any instantiation of the generic type.</p>
<p>Type classes can be combined using the standard boolean operators to form more complex type classes:</p>
<p><pre class="listing"><span class="Comment"># create a type class that will match all tuple and object types</span>
<span class="Keyword">type</span> <span class="Identifier">RecordType</span> <span class="Operator">=</span> <span class="Punctuation">(</span><span class="Keyword">tuple</span> <span class="Keyword">or</span> <span class="Keyword">object</span><span class="Punctuation">)</span>

<span class="Keyword">proc</span> <span class="Identifier">printFields</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">:</span> <span class="Identifier">RecordType</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">rec</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">for</span> <span class="Identifier">key</span><span class="Punctuation">,</span> <span class="Identifier">value</span> <span class="Keyword">in</span> <span class="Identifier">fieldPairs</span><span class="Punctuation">(</span><span class="Identifier">rec</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
    <span class="Identifier">echo</span> <span class="Identifier">key</span><span class="Punctuation">,</span> <span class="StringLit">&quot; = &quot;</span><span class="Punctuation">,</span> <span class="Identifier">value</span></pre></p>
<p>Type constraints on generic parameters can be grouped with <tt class="docutils literal"><span class="pre"><span class="Punctuation">,</span></span></tt> and propagation stops with <tt class="docutils literal"><span class="pre"><span class="Punctuation">;</span></span></tt>, similarly to parameters for macros and templates:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">fn1</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">;</span> <span class="Identifier">U</span><span class="Punctuation">,</span> <span class="Identifier">V</span><span class="Punctuation">:</span> <span class="Identifier">SomeFloat</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Keyword">discard</span> <span class="Comment"># T is unconstrained</span>
<span class="Keyword">template</span> <span class="Identifier">fn2</span><span class="Punctuation">(</span><span class="Identifier">t</span><span class="Punctuation">;</span> <span class="Identifier">u</span><span class="Punctuation">,</span> <span class="Identifier">v</span><span class="Punctuation">:</span> <span class="Identifier">SomeFloat</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Keyword">discard</span> <span class="Comment"># t is unconstrained</span></pre></p>
<p>Whilst the syntax of type classes appears to resemble that of ADTs/algebraic data types in ML-like languages, it should be understood that type classes are static constraints to be enforced at type instantiations. Type classes are not really types in themselves but are instead a system of providing generic &quot;checks&quot; that ultimately <em>resolve</em> to some singular type. Type classes do not allow for runtime type dynamism, unlike object variants or methods.</p>
<p>As an example, the following would not compile:</p>
<p><pre class="listing"><span class="Keyword">type</span> <span class="Identifier">TypeClass</span> <span class="Operator">=</span> <span class="Identifier">int</span> <span class="Operator">|</span> <span class="Identifier">string</span>
<span class="Keyword">var</span> <span class="Identifier">foo</span><span class="Punctuation">:</span> <span class="Identifier">TypeClass</span> <span class="Operator">=</span> <span class="DecNumber">2</span> <span class="Comment"># foo's type is resolved to an int here</span>
<span class="Identifier">foo</span> <span class="Operator">=</span> <span class="StringLit">&quot;this will fail&quot;</span> <span class="Comment"># error here, because foo is an int</span></pre></p>
<p>Nim allows for type classes and regular types to be specified as <span id="type-constraints_1">type constraints</span> of the generic type parameter:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">onlyIntOrString</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Operator">|</span><span class="Identifier">string</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Keyword">discard</span>

<span class="Identifier">onlyIntOrString</span><span class="Punctuation">(</span><span class="DecNumber">450</span><span class="Punctuation">,</span> <span class="DecNumber">616</span><span class="Punctuation">)</span> <span class="Comment"># valid</span>
<span class="Identifier">onlyIntOrString</span><span class="Punctuation">(</span><span class="FloatNumber">5.0</span><span class="Punctuation">,</span> <span class="FloatNumber">0.0</span><span class="Punctuation">)</span> <span class="Comment"># type mismatch</span>
<span class="Identifier">onlyIntOrString</span><span class="Punctuation">(</span><span class="StringLit">&quot;xy&quot;</span><span class="Punctuation">,</span> <span class="DecNumber">50</span><span class="Punctuation">)</span> <span class="Comment"># invalid as 'T' cannot be both at the same time</span></pre></p>
<p><tt class="docutils literal"><span class="pre"><span class="Keyword">proc</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Keyword">iterator</span></span></tt> type classes also accept a calling convention pragma to restrict the calling convention of the matching <tt class="docutils literal"><span class="pre"><span class="Keyword">proc</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Keyword">iterator</span></span></tt> type.</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">onlyClosure</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">:</span> <span class="Keyword">proc</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">closure</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Keyword">discard</span>

<span class="Identifier">onlyClosure</span><span class="Punctuation">(</span><span class="Keyword">proc</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Identifier">echo</span> <span class="StringLit">&quot;hello&quot;</span><span class="Punctuation">)</span> <span class="Comment"># valid</span>
<span class="Keyword">proc</span> <span class="Identifier">foo</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">nimcall</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">discard</span>
<span class="Identifier">onlyClosure</span><span class="Punctuation">(</span><span class="Identifier">foo</span><span class="Punctuation">)</span> <span class="Comment"># type mismatch</span></pre></p>

<h2><a class="toc-backref" id="generics-implicit-generics" href="#generics-implicit-generics">Implicit generics</a></h2><p>A type class can be used directly as the parameter's type.</p>
<p><pre class="listing"><span class="Comment"># create a type class that will match all tuple and object types</span>
<span class="Keyword">type</span> <span class="Identifier">RecordType</span> <span class="Operator">=</span> <span class="Punctuation">(</span><span class="Keyword">tuple</span> <span class="Keyword">or</span> <span class="Keyword">object</span><span class="Punctuation">)</span>

<span class="Keyword">proc</span> <span class="Identifier">printFields</span><span class="Punctuation">(</span><span class="Identifier">rec</span><span class="Punctuation">:</span> <span class="Identifier">RecordType</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">for</span> <span class="Identifier">key</span><span class="Punctuation">,</span> <span class="Identifier">value</span> <span class="Keyword">in</span> <span class="Identifier">fieldPairs</span><span class="Punctuation">(</span><span class="Identifier">rec</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
    <span class="Identifier">echo</span> <span class="Identifier">key</span><span class="Punctuation">,</span> <span class="StringLit">&quot; = &quot;</span><span class="Punctuation">,</span> <span class="Identifier">value</span></pre></p>
<p>Procedures utilizing type classes in such a manner are considered to be <span id="implicitly-generic_1">implicitly generic</span>. They will be instantiated once for each unique combination of parameter types used within the program.</p>
<p>By default, during overload resolution, each named type class will bind to exactly one concrete type. We call such type classes <span id="bind-once_1">bind once</span> types. Here is an example taken directly from the system module to illustrate this:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">==</span><span class="Punctuation">`</span><span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Keyword">tuple</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">bool</span> <span class="Operator">=</span>
  <span class="Comment">## requires `x` and `y` to be of the same tuple type</span>
  <span class="Comment">## generic `==` operator for tuples that is lifted from the components</span>
  <span class="Comment">## of `x` and `y`.</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">true</span>
  <span class="Keyword">for</span> <span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span> <span class="Keyword">in</span> <span class="Identifier">fields</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
    <span class="Keyword">if</span> <span class="Identifier">a</span> <span class="Operator">!=</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">false</span></pre></p>
<p>Alternatively, the <tt class="docutils literal"><span class="pre"><span class="Keyword">distinct</span></span></tt> type modifier can be applied to the type class to allow each parameter matching the type class to bind to a different type. Such type classes are called <span id="bind-many_1">bind many</span> types.</p>
<p>Procs written with the implicitly generic style will often need to refer to the type parameters of the matched generic type. They can be easily accessed using the dot syntax:</p>
<p><pre class="listing"><span class="Keyword">type</span> <span class="Identifier">Matrix</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">,</span> <span class="Identifier">Rows</span><span class="Punctuation">,</span> <span class="Identifier">Columns</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Keyword">object</span>
  <span class="Operator">...</span>

<span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">m</span><span class="Punctuation">:</span> <span class="Identifier">Matrix</span><span class="Punctuation">,</span> <span class="Identifier">row</span><span class="Punctuation">,</span> <span class="Identifier">col</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">Matrix</span><span class="Operator">.</span><span class="Identifier">T</span> <span class="Operator">=</span>
  <span class="Identifier">m</span><span class="Operator">.</span><span class="Identifier">data</span><span class="Punctuation">[</span><span class="Identifier">col</span> <span class="Operator">*</span> <span class="Identifier">high</span><span class="Punctuation">(</span><span class="Identifier">Matrix</span><span class="Operator">.</span><span class="Identifier">Columns</span><span class="Punctuation">)</span> <span class="Operator">+</span> <span class="Identifier">row</span><span class="Punctuation">]</span></pre></p>
<p>Here are more examples that illustrate implicit generics:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Identifier">t</span><span class="Punctuation">:</span> <span class="Identifier">Table</span><span class="Punctuation">;</span> <span class="Identifier">k</span><span class="Punctuation">:</span> <span class="Identifier">Table</span><span class="Operator">.</span><span class="Identifier">Key</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">Table</span><span class="Operator">.</span><span class="Identifier">Value</span>

<span class="Comment"># is roughly the same as:</span>

<span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">[</span><span class="Identifier">Key</span><span class="Punctuation">,</span> <span class="Identifier">Value</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">t</span><span class="Punctuation">:</span> <span class="Identifier">Table</span><span class="Punctuation">[</span><span class="Identifier">Key</span><span class="Punctuation">,</span> <span class="Identifier">Value</span><span class="Punctuation">]</span><span class="Punctuation">;</span> <span class="Identifier">k</span><span class="Punctuation">:</span> <span class="Identifier">Key</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">Value</span></pre></p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">Table</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">Table</span><span class="Punctuation">)</span>

<span class="Comment"># is roughly the same as:</span>

<span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">[</span><span class="Identifier">Key</span><span class="Punctuation">,</span> <span class="Identifier">Value</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">Table</span><span class="Punctuation">[</span><span class="Identifier">Key</span><span class="Punctuation">,</span> <span class="Identifier">Value</span><span class="Punctuation">]</span><span class="Punctuation">)</span></pre></p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">Table</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Keyword">distinct</span> <span class="Identifier">Table</span><span class="Punctuation">)</span>

<span class="Comment"># is roughly the same as:</span>

<span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">[</span><span class="Identifier">Key</span><span class="Punctuation">,</span> <span class="Identifier">Value</span><span class="Punctuation">,</span> <span class="Identifier">KeyB</span><span class="Punctuation">,</span> <span class="Identifier">ValueB</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">Table</span><span class="Punctuation">[</span><span class="Identifier">Key</span><span class="Punctuation">,</span> <span class="Identifier">Value</span><span class="Punctuation">]</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">Table</span><span class="Punctuation">[</span><span class="Identifier">KeyB</span><span class="Punctuation">,</span> <span class="Identifier">ValueB</span><span class="Punctuation">]</span><span class="Punctuation">)</span></pre></p>
<p><tt class="docutils literal"><span class="pre"><span class="Identifier">typedesc</span></span></tt> used as a parameter type also introduces an implicit generic. <tt class="docutils literal"><span class="pre"><span class="Identifier">typedesc</span></span></tt> has its own set of rules:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">typedesc</span><span class="Punctuation">)</span>

<span class="Comment"># is roughly the same as:</span>

<span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">typedesc</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">)</span></pre></p>
<p><tt class="docutils literal"><span class="pre"><span class="Identifier">typedesc</span></span></tt> is a &quot;bind many&quot; type class:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">typedesc</span><span class="Punctuation">)</span>

<span class="Comment"># is roughly the same as:</span>

<span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">,</span> <span class="Identifier">T2</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">typedesc</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">typedesc</span><span class="Punctuation">[</span><span class="Identifier">T2</span><span class="Punctuation">]</span><span class="Punctuation">)</span></pre></p>
<p>A parameter of type <tt class="docutils literal"><span class="pre"><span class="Identifier">typedesc</span></span></tt> is itself usable as a type. If it is used as a type, it's the underlying type. In other words, one level of &quot;typedesc&quot;-ness is stripped off:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">typedesc</span><span class="Punctuation">;</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">a</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Keyword">discard</span>

<span class="Comment"># is roughly the same as:</span>
<span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">typedesc</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">;</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Keyword">discard</span>

<span class="Comment"># hence this is a valid call:</span>
<span class="Identifier">p</span><span class="Punctuation">(</span><span class="Identifier">int</span><span class="Punctuation">,</span> <span class="DecNumber">4</span><span class="Punctuation">)</span>
<span class="Comment"># as parameter 'a' requires a type, but 'b' requires a value.</span></pre></p>

<h2><a class="toc-backref" id="generics-generic-inference-restrictions" href="#generics-generic-inference-restrictions">Generic inference restrictions</a></h2><p>The types <tt class="docutils literal"><span class="pre"><span class="Keyword">var</span> <span class="Identifier">T</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">typedesc</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span></span></tt> cannot be inferred in a generic instantiation. The following is not allowed:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">g</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">:</span> <span class="Keyword">proc</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">)</span><span class="Punctuation">;</span> <span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Identifier">f</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span>

<span class="Keyword">proc</span> <span class="Identifier">c</span><span class="Punctuation">(</span><span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Identifier">echo</span> <span class="Identifier">y</span>
<span class="Keyword">proc</span> <span class="Identifier">v</span><span class="Punctuation">(</span><span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">int</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Identifier">y</span> <span class="Operator">+=</span> <span class="DecNumber">100</span>
<span class="Keyword">var</span> <span class="Identifier">i</span><span class="Punctuation">:</span> <span class="Identifier">int</span>

<span class="Comment"># allowed: infers 'T' to be of type 'int'</span>
<span class="Identifier">g</span><span class="Punctuation">(</span><span class="Identifier">c</span><span class="Punctuation">,</span> <span class="DecNumber">42</span><span class="Punctuation">)</span>

<span class="Comment"># not valid: 'T' is not inferred to be of type 'var int'</span>
<span class="Identifier">g</span><span class="Punctuation">(</span><span class="Identifier">v</span><span class="Punctuation">,</span> <span class="Identifier">i</span><span class="Punctuation">)</span>

<span class="Comment"># also not allowed: explicit instantiation via 'var int'</span>
<span class="Identifier">g</span><span class="Punctuation">[</span><span class="Keyword">var</span> <span class="Identifier">int</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">v</span><span class="Punctuation">,</span> <span class="Identifier">i</span><span class="Punctuation">)</span></pre></p>

<h2><a class="toc-backref" id="generics-symbol-lookup-in-generics" href="#generics-symbol-lookup-in-generics">Symbol lookup in generics</a></h2>
<h3><a class="toc-backref" id="symbol-lookup-in-generics-open-and-closed-symbols" href="#symbol-lookup-in-generics-open-and-closed-symbols">Open and Closed symbols</a></h3><p>The symbol binding rules in generics are slightly subtle: There are &quot;open&quot; and &quot;closed&quot; symbols. A &quot;closed&quot; symbol cannot be re-bound in the instantiation context, an &quot;open&quot; symbol can. Per default, overloaded symbols are open and every other symbol is closed.</p>
<p>Open symbols are looked up in two different contexts: Both the context at definition and the context at instantiation are considered:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">Index</span> <span class="Operator">=</span> <span class="Keyword">distinct</span> <span class="Identifier">int</span>

<span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">==</span><span class="Punctuation">`</span> <span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">Index</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">bool</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">borrow</span><span class="Operator">.</span><span class="Punctuation">}</span>

<span class="Keyword">var</span> <span class="Identifier">a</span> <span class="Operator">=</span> <span class="Punctuation">(</span><span class="DecNumber">0</span><span class="Punctuation">,</span> <span class="FloatNumber">0.</span><span class="Identifier">Index</span><span class="Punctuation">)</span>
<span class="Keyword">var</span> <span class="Identifier">b</span> <span class="Operator">=</span> <span class="Punctuation">(</span><span class="DecNumber">0</span><span class="Punctuation">,</span> <span class="FloatNumber">0.</span><span class="Identifier">Index</span><span class="Punctuation">)</span>

<span class="Identifier">echo</span> <span class="Identifier">a</span> <span class="Operator">==</span> <span class="Identifier">b</span> <span class="Comment"># works!</span></pre></p>
<p>In the example, the <a class="reference external" href="system.html#%3D%3D%2CT%2CT_2">generic `==` for tuples</a> (as defined in the system module) uses the <tt class="docutils literal"><span class="pre"><span class="Operator">==</span></span></tt> operators of the tuple's components. However, the <tt class="docutils literal"><span class="pre"><span class="Operator">==</span></span></tt> for the <tt class="docutils literal"><span class="pre"><span class="Identifier">Index</span></span></tt> type is defined <em>after</em> the <tt class="docutils literal"><span class="pre"><span class="Operator">==</span></span></tt> for tuples; yet the example compiles as the instantiation takes the currently defined symbols into account too.</p>

<h2><a class="toc-backref" id="generics-mixin-statement" href="#generics-mixin-statement">Mixin statement</a></h2><p>A symbol can be forced to be open by a <span id="mixin_1">mixin</span> declaration:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">create</span><span class="Operator">*</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Keyword">ref</span> <span class="Identifier">T</span> <span class="Operator">=</span>
  <span class="Comment"># there is no overloaded 'init' here, so we need to state that it's an</span>
  <span class="Comment"># open symbol explicitly:</span>
  <span class="Keyword">mixin</span> <span class="Identifier">init</span>
  <span class="Identifier">new</span> <span class="Identifier">result</span>
  <span class="Identifier">init</span> <span class="Identifier">result</span></pre></p>
<p><tt class="docutils literal"><span class="pre"><span class="Keyword">mixin</span></span></tt> statements only make sense in templates and generics.</p>

<h2><a class="toc-backref" id="generics-bind-statement" href="#generics-bind-statement">Bind statement</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Keyword">bind</span></span></tt> statement is the counterpart to the <tt class="docutils literal"><span class="pre"><span class="Keyword">mixin</span></span></tt> statement. It can be used to explicitly declare identifiers that should be bound early (i.e. the identifiers should be looked up in the scope of the template/generic definition):</p>
<p><pre class="listing"><span class="Comment"># Module A</span>
<span class="Keyword">var</span>
  <span class="Identifier">lastId</span> <span class="Operator">=</span> <span class="DecNumber">0</span>

<span class="Keyword">template</span> <span class="Identifier">genId</span><span class="Operator">*:</span> <span class="Identifier">untyped</span> <span class="Operator">=</span>
  <span class="Keyword">bind</span> <span class="Identifier">lastId</span>
  <span class="Identifier">inc</span><span class="Punctuation">(</span><span class="Identifier">lastId</span><span class="Punctuation">)</span>
  <span class="Identifier">lastId</span></pre></p>
<p><pre class="listing"><span class="Comment"># Module B</span>
<span class="Keyword">import</span> <span class="Identifier">A</span>

<span class="Identifier">echo</span> <span class="Identifier">genId</span><span class="Punctuation">(</span><span class="Punctuation">)</span></pre></p>
<p>But a <tt class="docutils literal"><span class="pre"><span class="Keyword">bind</span></span></tt> is rarely useful because symbol binding from the definition scope is the default.</p>
<p><tt class="docutils literal"><span class="pre"><span class="Keyword">bind</span></span></tt> statements only make sense in templates and generics.</p>

<h2><a class="toc-backref" id="generics-delegating-bind-statements" href="#generics-delegating-bind-statements">Delegating bind statements</a></h2><p>The following example outlines a problem that can arise when generic instantiations cross multiple different modules:</p>
<p><pre class="listing"><span class="Comment"># module A</span>
<span class="Keyword">proc</span> <span class="Identifier">genericA</span><span class="Operator">*</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">mixin</span> <span class="Identifier">init</span>
  <span class="Identifier">init</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span></pre></p>
<p><pre class="listing"><span class="Keyword">import</span> <span class="Identifier">C</span>

<span class="Comment"># module B</span>
<span class="Keyword">proc</span> <span class="Identifier">genericB</span><span class="Operator">*</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Comment"># Without the `bind init` statement C's init proc is</span>
  <span class="Comment"># not available when `genericB` is instantiated:</span>
  <span class="Keyword">bind</span> <span class="Identifier">init</span>
  <span class="Identifier">genericA</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span></pre></p>
<p><pre class="listing"><span class="Comment"># module C</span>
<span class="Keyword">type</span> <span class="Identifier">O</span> <span class="Operator">=</span> <span class="Keyword">object</span>
<span class="Keyword">proc</span> <span class="Identifier">init</span><span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">O</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Keyword">discard</span></pre></p>
<p><pre class="listing"><span class="Comment"># module main</span>
<span class="Keyword">import</span> <span class="Identifier">B</span><span class="Punctuation">,</span> <span class="Identifier">C</span>

<span class="Identifier">genericB</span> <span class="Identifier">O</span><span class="Punctuation">(</span><span class="Punctuation">)</span></pre></p>
<p>In module B has an <tt class="docutils literal"><span class="pre"><span class="Identifier">init</span></span></tt> proc from module C in its scope that is not taken into account when <tt class="docutils literal"><span class="pre"><span class="Identifier">genericB</span></span></tt> is instantiated which leads to the instantiation of <tt class="docutils literal"><span class="pre"><span class="Identifier">genericA</span></span></tt>. The solution is to <span id="forward_2">forward</span> these symbols by a <tt class="docutils literal"><span class="pre"><span class="Keyword">bind</span></span></tt> statement inside <tt class="docutils literal"><span class="pre"><span class="Identifier">genericB</span></span></tt>.</p>

<h1><a class="toc-backref" id="templates" href="#templates">Templates</a></h1><p>A template is a simple form of a macro: It is a simple substitution mechanism that operates on Nim's abstract syntax trees. It is processed in the semantic pass of the compiler.</p>
<p>The syntax to <em>invoke</em> a template is the same as calling a procedure.</p>
<p>Example:</p>
<p><pre class="listing"><span class="Keyword">template</span> <span class="Punctuation">`</span><span class="Operator">!=</span><span class="Punctuation">`</span> <span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">untyped</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">untyped</span> <span class="Operator">=</span>
  <span class="Comment"># this definition exists in the system module</span>
  <span class="Keyword">not</span> <span class="Punctuation">(</span><span class="Identifier">a</span> <span class="Operator">==</span> <span class="Identifier">b</span><span class="Punctuation">)</span>

<span class="Identifier">assert</span><span class="Punctuation">(</span><span class="DecNumber">5</span> <span class="Operator">!=</span> <span class="DecNumber">6</span><span class="Punctuation">)</span> <span class="Comment"># the compiler rewrites that to: assert(not (5 == 6))</span></pre></p>
<p>The <tt class="docutils literal"><span class="pre"><span class="Operator">!=</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Operator">&gt;</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Operator">&gt;=</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">in</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">notin</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">isnot</span></span></tt> operators are in fact templates:</p>
<p><tt class="docutils literal"><span class="pre"><span class="Identifier">a</span> <span class="Operator">&gt;</span> <span class="Identifier">b</span></span></tt> is transformed into <tt class="docutils literal"><span class="pre"><span class="Identifier">b</span> <span class="Operator">&lt;</span> <span class="Identifier">a</span></span></tt>.<br/><tt class="docutils literal"><span class="pre"><span class="Identifier">a</span> <span class="Keyword">in</span> <span class="Identifier">b</span></span></tt> is transformed into <tt class="docutils literal"><span class="pre"><span class="Identifier">contains</span><span class="Punctuation">(</span><span class="Identifier">b</span><span class="Punctuation">,</span> <span class="Identifier">a</span><span class="Punctuation">)</span></span></tt>.<br/><tt class="docutils literal"><span class="pre"><span class="Keyword">notin</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Keyword">isnot</span></span></tt> have the obvious meanings.<br/></p><p>The &quot;types&quot; of templates can be the symbols <tt class="docutils literal"><span class="pre"><span class="Identifier">untyped</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Identifier">typed</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Identifier">typedesc</span></span></tt>. These are &quot;meta types&quot;, they can only be used in certain contexts. Regular types can be used too; this implies that <tt class="docutils literal"><span class="pre"><span class="Identifier">typed</span></span></tt> expressions are expected.</p>

<h2><a class="toc-backref" id="templates-typed-vs-untyped-parameters" href="#templates-typed-vs-untyped-parameters">Typed vs untyped parameters</a></h2><p>An <tt class="docutils literal"><span class="pre"><span class="Identifier">untyped</span></span></tt> parameter means that symbol lookups and type resolution is not performed before the expression is passed to the template. This means that <em>undeclared</em> identifiers, for example, can be passed to the template:</p>
<p><pre class="listing"><span class="Keyword">template</span> <span class="Identifier">declareInt</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">untyped</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">var</span> <span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">int</span>

<span class="Identifier">declareInt</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span> <span class="Comment"># valid</span>
<span class="Identifier">x</span> <span class="Operator">=</span> <span class="DecNumber">3</span></pre></p>
<p><pre class="listing"><span class="Keyword">template</span> <span class="Identifier">declareInt</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">typed</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">var</span> <span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">int</span>

<span class="Identifier">declareInt</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span> <span class="Comment"># invalid, because x has not been declared and so it has no type</span></pre></p>
<p>A template where every parameter is <tt class="docutils literal"><span class="pre"><span class="Identifier">untyped</span></span></tt> is called an <span id="immediate_1">immediate</span> template. For historical reasons, templates can be explicitly annotated with an <tt class="docutils literal"><span class="pre"><span class="Identifier">immediate</span></span></tt> pragma and then these templates do not take part in overloading resolution and the parameters' types are <em>ignored</em> by the compiler. Explicit immediate templates are now deprecated.</p>
<p><strong>Note</strong>: For historical reasons, <tt class="docutils literal"><span class="pre"><span class="Identifier">stmt</span></span></tt> was an alias for <tt class="docutils literal"><span class="pre"><span class="Identifier">typed</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">expr</span></span></tt> was an alias for <tt class="docutils literal"><span class="pre"><span class="Identifier">untyped</span></span></tt>, but they are removed.</p>

<h2><a class="toc-backref" id="templates-passing-a-code-block-to-a-template" href="#templates-passing-a-code-block-to-a-template">Passing a code block to a template</a></h2><p>One can pass a block of statements as the last argument to a template following the special <tt class="docutils literal"><span class="pre"><span class="Punctuation">:</span></span></tt> syntax:</p>
<p><pre class="listing"><span class="Keyword">template</span> <span class="Identifier">withFile</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">,</span> <span class="Identifier">fn</span><span class="Punctuation">,</span> <span class="Identifier">mode</span><span class="Punctuation">,</span> <span class="Identifier">actions</span><span class="Punctuation">:</span> <span class="Identifier">untyped</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">untyped</span> <span class="Operator">=</span>
  <span class="Keyword">var</span> <span class="Identifier">f</span><span class="Punctuation">:</span> <span class="Identifier">File</span>
  <span class="Keyword">if</span> <span class="Identifier">open</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">,</span> <span class="Identifier">fn</span><span class="Punctuation">,</span> <span class="Identifier">mode</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
    <span class="Keyword">try</span><span class="Punctuation">:</span>
      <span class="Identifier">actions</span>
    <span class="Keyword">finally</span><span class="Punctuation">:</span>
      <span class="Identifier">close</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">)</span>
  <span class="Keyword">else</span><span class="Punctuation">:</span>
    <span class="Identifier">quit</span><span class="Punctuation">(</span><span class="StringLit">&quot;cannot open: &quot;</span> <span class="Operator">&amp;</span> <span class="Identifier">fn</span><span class="Punctuation">)</span>

<span class="Identifier">withFile</span><span class="Punctuation">(</span><span class="Identifier">txt</span><span class="Punctuation">,</span> <span class="StringLit">&quot;ttempl3.txt&quot;</span><span class="Punctuation">,</span> <span class="Identifier">fmWrite</span><span class="Punctuation">)</span><span class="Punctuation">:</span>  <span class="Comment"># special colon</span>
  <span class="Identifier">txt</span><span class="Operator">.</span><span class="Identifier">writeLine</span><span class="Punctuation">(</span><span class="StringLit">&quot;line 1&quot;</span><span class="Punctuation">)</span>
  <span class="Identifier">txt</span><span class="Operator">.</span><span class="Identifier">writeLine</span><span class="Punctuation">(</span><span class="StringLit">&quot;line 2&quot;</span><span class="Punctuation">)</span></pre></p>
<p>In the example, the two <tt class="docutils literal"><span class="pre"><span class="Identifier">writeLine</span></span></tt> statements are bound to the <tt class="docutils literal"><span class="pre"><span class="Identifier">actions</span></span></tt> parameter.</p>
<p>Usually, to pass a block of code to a template, the parameter that accepts the block needs to be of type <tt class="docutils literal"><span class="pre"><span class="Identifier">untyped</span></span></tt>. Because symbol lookups are then delayed until template instantiation time:</p>
<p><pre class="listing"><span class="Keyword">template</span> <span class="Identifier">t</span><span class="Punctuation">(</span><span class="Identifier">body</span><span class="Punctuation">:</span> <span class="Identifier">typed</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">proc</span> <span class="Identifier">p</span> <span class="Operator">=</span> <span class="Identifier">echo</span> <span class="StringLit">&quot;hey&quot;</span>
  <span class="Keyword">block</span><span class="Punctuation">:</span>
    <span class="Identifier">body</span>

<span class="Identifier">t</span><span class="Punctuation">:</span>
  <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Punctuation">)</span>  <span class="Comment"># fails with 'undeclared identifier: p'</span></pre></p>
<p>The above code fails with the error message that <tt class="docutils literal"><span class="pre"><span class="Identifier">p</span></span></tt> is not declared. The reason for this is that the <tt class="docutils literal"><span class="pre"><span class="Identifier">p</span><span class="Punctuation">(</span><span class="Punctuation">)</span></span></tt> body is type-checked before getting passed to the <tt class="docutils literal"><span class="pre"><span class="Identifier">body</span></span></tt> parameter and type checking in Nim implies symbol lookups. The same code works with <tt class="docutils literal"><span class="pre"><span class="Identifier">untyped</span></span></tt> as the passed body is not required to be type-checked:</p>
<p><pre class="listing"><span class="Keyword">template</span> <span class="Identifier">t</span><span class="Punctuation">(</span><span class="Identifier">body</span><span class="Punctuation">:</span> <span class="Identifier">untyped</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">proc</span> <span class="Identifier">p</span> <span class="Operator">=</span> <span class="Identifier">echo</span> <span class="StringLit">&quot;hey&quot;</span>
  <span class="Keyword">block</span><span class="Punctuation">:</span>
    <span class="Identifier">body</span>

<span class="Identifier">t</span><span class="Punctuation">:</span>
  <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Punctuation">)</span>  <span class="Comment"># compiles</span></pre></p>

<h2><a class="toc-backref" id="templates-varargs-of-untyped" href="#templates-varargs-of-untyped">Varargs of untyped</a></h2><p>In addition to the <tt class="docutils literal"><span class="pre"><span class="Identifier">untyped</span></span></tt> meta-type that prevents type checking, there is also <tt class="docutils literal"><span class="pre"><span class="Identifier">varargs</span><span class="Punctuation">[</span><span class="Identifier">untyped</span><span class="Punctuation">]</span></span></tt> so that not even the number of parameters is fixed:</p>
<p><pre class="listing"><span class="Keyword">template</span> <span class="Identifier">hideIdentifiers</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">varargs</span><span class="Punctuation">[</span><span class="Identifier">untyped</span><span class="Punctuation">]</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Keyword">discard</span>

<span class="Identifier">hideIdentifiers</span><span class="Punctuation">(</span><span class="Identifier">undeclared1</span><span class="Punctuation">,</span> <span class="Identifier">undeclared2</span><span class="Punctuation">)</span></pre></p>
<p>However, since a template cannot iterate over varargs, this feature is generally much more useful for macros.</p>

<h2><a class="toc-backref" id="templates-symbol-binding-in-templates" href="#templates-symbol-binding-in-templates">Symbol binding in templates</a></h2><p>A template is a <span id="hygienic_1">hygienic</span> macro and so opens a new scope. Most symbols are bound from the definition scope of the template:</p>
<p><pre class="listing"><span class="Comment"># Module A</span>
<span class="Keyword">var</span>
  <span class="Identifier">lastId</span> <span class="Operator">=</span> <span class="DecNumber">0</span>

<span class="Keyword">template</span> <span class="Identifier">genId</span><span class="Operator">*:</span> <span class="Identifier">untyped</span> <span class="Operator">=</span>
  <span class="Identifier">inc</span><span class="Punctuation">(</span><span class="Identifier">lastId</span><span class="Punctuation">)</span>
  <span class="Identifier">lastId</span></pre></p>
<p><pre class="listing"><span class="Comment"># Module B</span>
<span class="Keyword">import</span> <span class="Identifier">A</span>

<span class="Identifier">echo</span> <span class="Identifier">genId</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Comment"># Works as 'lastId' has been bound in 'genId's defining scope</span></pre></p>
<p>As in generics, symbol binding can be influenced via <tt class="docutils literal"><span class="pre"><span class="Keyword">mixin</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Keyword">bind</span></span></tt> statements.</p>

<h2><a class="toc-backref" id="templates-identifier-construction" href="#templates-identifier-construction">Identifier construction</a></h2><p>In templates, identifiers can be constructed with the backticks notation:</p>
<p><pre class="listing"><span class="Keyword">template</span> <span class="Identifier">typedef</span><span class="Punctuation">(</span><span class="Identifier">name</span><span class="Punctuation">:</span> <span class="Identifier">untyped</span><span class="Punctuation">,</span> <span class="Identifier">typ</span><span class="Punctuation">:</span> <span class="Identifier">typedesc</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">type</span>
    <span class="Punctuation">`</span><span class="Identifier">T</span> <span class="Identifier">name</span><span class="Punctuation">`</span><span class="Operator">*</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">inject</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Identifier">typ</span>
    <span class="Punctuation">`</span><span class="Identifier">P</span> <span class="Identifier">name</span><span class="Punctuation">`</span><span class="Operator">*</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">inject</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Punctuation">`</span><span class="Identifier">T</span> <span class="Identifier">name</span><span class="Punctuation">`</span>

<span class="Identifier">typedef</span><span class="Punctuation">(</span><span class="Identifier">myint</span><span class="Punctuation">,</span> <span class="Identifier">int</span><span class="Punctuation">)</span>
<span class="Keyword">var</span> <span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">PMyInt</span></pre></p>
<p>In the example, <tt class="docutils literal"><span class="pre"><span class="Identifier">name</span></span></tt> is instantiated with <tt class="docutils literal"><span class="pre"><span class="Identifier">myint</span></span></tt>, so `T name` becomes <tt class="docutils literal"><span class="pre"><span class="Identifier">Tmyint</span></span></tt>.</p>

<h2><a class="toc-backref" id="templates-lookup-rules-for-template-parameters" href="#templates-lookup-rules-for-template-parameters">Lookup rules for template parameters</a></h2><p>A parameter <tt class="docutils literal"><span class="pre"><span class="Identifier">p</span></span></tt> in a template is even substituted in the expression <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">p</span></span></tt>. Thus, template arguments can be used as field names and a global symbol can be shadowed by the same argument name even when fully qualified:</p>
<p><pre class="listing"><span class="Comment"># module 'm'</span>

<span class="Keyword">type</span>
  <span class="Identifier">Lev</span> <span class="Operator">=</span> <span class="Keyword">enum</span>
    <span class="Identifier">levA</span><span class="Punctuation">,</span> <span class="Identifier">levB</span>

<span class="Keyword">var</span> <span class="Identifier">abclev</span> <span class="Operator">=</span> <span class="Identifier">levB</span>

<span class="Keyword">template</span> <span class="Identifier">tstLev</span><span class="Punctuation">(</span><span class="Identifier">abclev</span><span class="Punctuation">:</span> <span class="Identifier">Lev</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Identifier">echo</span> <span class="Identifier">abclev</span><span class="Punctuation">,</span> <span class="StringLit">&quot; &quot;</span><span class="Punctuation">,</span> <span class="Identifier">m</span><span class="Operator">.</span><span class="Identifier">abclev</span>

<span class="Identifier">tstLev</span><span class="Punctuation">(</span><span class="Identifier">levA</span><span class="Punctuation">)</span>
<span class="Comment"># produces: 'levA levA'</span></pre></p>
<p>But the global symbol can properly be captured by a <tt class="docutils literal"><span class="pre"><span class="Keyword">bind</span></span></tt> statement:</p>
<p><pre class="listing"><span class="Comment"># module 'm'</span>

<span class="Keyword">type</span>
  <span class="Identifier">Lev</span> <span class="Operator">=</span> <span class="Keyword">enum</span>
    <span class="Identifier">levA</span><span class="Punctuation">,</span> <span class="Identifier">levB</span>

<span class="Keyword">var</span> <span class="Identifier">abclev</span> <span class="Operator">=</span> <span class="Identifier">levB</span>

<span class="Keyword">template</span> <span class="Identifier">tstLev</span><span class="Punctuation">(</span><span class="Identifier">abclev</span><span class="Punctuation">:</span> <span class="Identifier">Lev</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">bind</span> <span class="Identifier">m</span><span class="Operator">.</span><span class="Identifier">abclev</span>
  <span class="Identifier">echo</span> <span class="Identifier">abclev</span><span class="Punctuation">,</span> <span class="StringLit">&quot; &quot;</span><span class="Punctuation">,</span> <span class="Identifier">m</span><span class="Operator">.</span><span class="Identifier">abclev</span>

<span class="Identifier">tstLev</span><span class="Punctuation">(</span><span class="Identifier">levA</span><span class="Punctuation">)</span>
<span class="Comment"># produces: 'levA levB'</span></pre></p>

<h2><a class="toc-backref" id="templates-hygiene-in-templates" href="#templates-hygiene-in-templates">Hygiene in templates</a></h2><p>Per default, templates are <span id="hygienic_2">hygienic</span>: Local identifiers declared in a template cannot be accessed in the instantiation context:</p>
<p><pre class="listing"><span class="Keyword">template</span> <span class="Identifier">newException</span><span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">exceptn</span><span class="Punctuation">:</span> <span class="Identifier">typedesc</span><span class="Punctuation">,</span> <span class="Identifier">message</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">untyped</span> <span class="Operator">=</span>
  <span class="Keyword">var</span>
    <span class="Identifier">e</span><span class="Punctuation">:</span> <span class="Keyword">ref</span> <span class="Identifier">exceptn</span>  <span class="Comment"># e is implicitly gensym'ed here</span>
  <span class="Identifier">new</span><span class="Punctuation">(</span><span class="Identifier">e</span><span class="Punctuation">)</span>
  <span class="Identifier">e</span><span class="Operator">.</span><span class="Identifier">msg</span> <span class="Operator">=</span> <span class="Identifier">message</span>
  <span class="Identifier">e</span>

<span class="Comment"># so this works:</span>
<span class="Keyword">let</span> <span class="Identifier">e</span> <span class="Operator">=</span> <span class="StringLit">&quot;message&quot;</span>
<span class="Keyword">raise</span> <span class="Identifier">newException</span><span class="Punctuation">(</span><span class="Identifier">IoError</span><span class="Punctuation">,</span> <span class="Identifier">e</span><span class="Punctuation">)</span></pre></p>
<p>Whether a symbol that is declared in a template is exposed to the instantiation scope is controlled by the <span id="inject_1">inject</span> and <span id="gensym_1">gensym</span> pragmas: <tt class="docutils literal"><span class="pre"><span class="Identifier">gensym</span></span></tt>'ed symbols are not exposed but <tt class="docutils literal"><span class="pre"><span class="Identifier">inject</span></span></tt>'ed symbols are.</p>
<p>The default for symbols of entity <tt class="docutils literal"><span class="pre"><span class="Keyword">type</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">var</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">let</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Keyword">const</span></span></tt> is <tt class="docutils literal"><span class="pre"><span class="Identifier">gensym</span></span></tt>. For <tt class="docutils literal"><span class="pre"><span class="Keyword">proc</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">iterator</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">converter</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">template</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">macro</span></span></tt>, the default is <tt class="docutils literal"><span class="pre"><span class="Identifier">inject</span></span></tt>, but if a <tt class="docutils literal"><span class="pre"><span class="Identifier">gensym</span></span></tt> symbol with the same name is defined in the same syntax-level scope, it will be <tt class="docutils literal"><span class="pre"><span class="Identifier">gensym</span></span></tt> by default. This can be overridden by marking the routine as <tt class="docutils literal"><span class="pre"><span class="Identifier">inject</span></span></tt>.</p>
<p>If the name of the entity is passed as a template parameter, it is an <tt class="docutils literal"><span class="pre"><span class="Identifier">inject</span></span></tt>'ed symbol:</p>
<p><pre class="listing"><span class="Keyword">template</span> <span class="Identifier">withFile</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">,</span> <span class="Identifier">fn</span><span class="Punctuation">,</span> <span class="Identifier">mode</span><span class="Punctuation">:</span> <span class="Identifier">untyped</span><span class="Punctuation">,</span> <span class="Identifier">actions</span><span class="Punctuation">:</span> <span class="Identifier">untyped</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">untyped</span> <span class="Operator">=</span>
  <span class="Keyword">block</span><span class="Punctuation">:</span>
    <span class="Keyword">var</span> <span class="Identifier">f</span><span class="Punctuation">:</span> <span class="Identifier">File</span>  <span class="Comment"># since 'f' is a template parameter, it's injected implicitly</span>
    <span class="Operator">...</span>

<span class="Identifier">withFile</span><span class="Punctuation">(</span><span class="Identifier">txt</span><span class="Punctuation">,</span> <span class="StringLit">&quot;ttempl3.txt&quot;</span><span class="Punctuation">,</span> <span class="Identifier">fmWrite</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
  <span class="Identifier">txt</span><span class="Operator">.</span><span class="Identifier">writeLine</span><span class="Punctuation">(</span><span class="StringLit">&quot;line 1&quot;</span><span class="Punctuation">)</span>
  <span class="Identifier">txt</span><span class="Operator">.</span><span class="Identifier">writeLine</span><span class="Punctuation">(</span><span class="StringLit">&quot;line 2&quot;</span><span class="Punctuation">)</span></pre></p>
<p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">inject</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">gensym</span></span></tt> pragmas are second class annotations; they have no semantics outside a template definition and cannot be abstracted over:</p>
<p><pre class="listing"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">pragma</span> <span class="Identifier">myInject</span><span class="Punctuation">:</span> <span class="Identifier">inject</span><span class="Operator">.</span><span class="Punctuation">}</span>

<span class="Keyword">template</span> <span class="Identifier">t</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">var</span> <span class="Identifier">x</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">myInject</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Comment"># does NOT work</span></pre></p>
<p>To get rid of hygiene in templates, one can use the <span id="dirty_1">dirty</span> pragma for a template. <tt class="docutils literal"><span class="pre"><span class="Identifier">inject</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">gensym</span></span></tt> have no effect in <tt class="docutils literal"><span class="pre"><span class="Identifier">dirty</span></span></tt> templates.</p>
<p><tt class="docutils literal"><span class="pre"><span class="Identifier">gensym</span></span></tt>'ed symbols cannot be used as <tt class="docutils literal"><span class="pre"><span class="Identifier">field</span></span></tt> in the <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">field</span></span></tt> syntax. Nor can they be used in the <tt class="docutils literal"><span class="pre"><span class="Identifier">ObjectConstruction</span><span class="Punctuation">(</span><span class="Identifier">field</span><span class="Punctuation">:</span> <span class="Identifier">value</span><span class="Punctuation">)</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">namedParameterCall</span><span class="Punctuation">(</span><span class="Identifier">field</span> <span class="Operator">=</span> <span class="Identifier">value</span><span class="Punctuation">)</span></span></tt> syntactic constructs.</p>
<p>The reason for this is that code like</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">T</span> <span class="Operator">=</span> <span class="Keyword">object</span>
    <span class="Identifier">f</span><span class="Punctuation">:</span> <span class="Identifier">int</span>

<span class="Keyword">template</span> <span class="Identifier">tmp</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">let</span> <span class="Identifier">f</span> <span class="Operator">=</span> <span class="DecNumber">34</span>
  <span class="Identifier">echo</span> <span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">f</span><span class="Punctuation">,</span> <span class="Identifier">T</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">:</span> <span class="DecNumber">4</span><span class="Punctuation">)</span></pre></p>
<p>should work as expected.</p>
<p>However, this means that the method call syntax is not available for <tt class="docutils literal"><span class="pre"><span class="Identifier">gensym</span></span></tt>'ed symbols:</p>
<p><pre class="listing"><span class="Keyword">template</span> <span class="Identifier">tmp</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">type</span>
    <span class="Identifier">T</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">gensym</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Identifier">int</span>
  
  <span class="Identifier">echo</span> <span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">T</span> <span class="Comment"># invalid: instead use:  'echo T(x)'.</span>

<span class="Identifier">tmp</span><span class="Punctuation">(</span><span class="DecNumber">12</span><span class="Punctuation">)</span></pre></p>

<h2><a class="toc-backref" id="templates-limitations-of-the-method-call-syntax" href="#templates-limitations-of-the-method-call-syntax">Limitations of the method call syntax</a></h2><p>The expression <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span></span></tt> in <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">f</span></span></tt> needs to be semantically checked (that means symbol lookup and type checking) before it can be decided that it needs to be rewritten to <tt class="docutils literal"><span class="pre"><span class="Identifier">f</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span></span></tt>. Therefore, the dot syntax has some limitations when it is used to invoke templates/macros:</p>
<p><pre class="listing"><span class="Keyword">template</span> <span class="Identifier">declareVar</span><span class="Punctuation">(</span><span class="Identifier">name</span><span class="Punctuation">:</span> <span class="Identifier">untyped</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">const</span> <span class="Identifier">name</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">inject</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="DecNumber">45</span>

<span class="Comment"># Doesn't compile:</span>
<span class="Identifier">unknownIdentifier</span><span class="Operator">.</span><span class="Identifier">declareVar</span></pre></p>
<p>It is also not possible to use fully qualified identifiers with module symbol in method call syntax. The order in which the dot operator binds to symbols prohibits this.</p>
<p><pre class="listing"><span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">sequtils</span>

<span class="Keyword">var</span> <span class="Identifier">myItems</span> <span class="Operator">=</span> <span class="Operator">@</span><span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">,</span><span class="DecNumber">3</span><span class="Punctuation">,</span><span class="DecNumber">3</span><span class="Punctuation">,</span><span class="DecNumber">7</span><span class="Punctuation">]</span>
<span class="Keyword">let</span> <span class="Identifier">N1</span> <span class="Operator">=</span> <span class="Identifier">count</span><span class="Punctuation">(</span><span class="Identifier">myItems</span><span class="Punctuation">,</span> <span class="DecNumber">3</span><span class="Punctuation">)</span> <span class="Comment"># OK</span>
<span class="Keyword">let</span> <span class="Identifier">N2</span> <span class="Operator">=</span> <span class="Identifier">sequtils</span><span class="Operator">.</span><span class="Identifier">count</span><span class="Punctuation">(</span><span class="Identifier">myItems</span><span class="Punctuation">,</span> <span class="DecNumber">3</span><span class="Punctuation">)</span> <span class="Comment"># fully qualified, OK</span>
<span class="Keyword">let</span> <span class="Identifier">N3</span> <span class="Operator">=</span> <span class="Identifier">myItems</span><span class="Operator">.</span><span class="Identifier">count</span><span class="Punctuation">(</span><span class="DecNumber">3</span><span class="Punctuation">)</span> <span class="Comment"># OK</span>
<span class="Keyword">let</span> <span class="Identifier">N4</span> <span class="Operator">=</span> <span class="Identifier">myItems</span><span class="Operator">.</span><span class="Identifier">sequtils</span><span class="Operator">.</span><span class="Identifier">count</span><span class="Punctuation">(</span><span class="DecNumber">3</span><span class="Punctuation">)</span> <span class="Comment"># illegal, `myItems.sequtils` can't be resolved</span></pre></p>
<p>This means that when for some reason a procedure needs a disambiguation through the module name, the call needs to be written in function call syntax.</p>

<h1><a class="toc-backref" id="macros" href="#macros">Macros</a></h1><p>A macro is a special function that is executed at compile time. Normally, the input for a macro is an abstract syntax tree (AST) of the code that is passed to it. The macro can then do transformations on it and return the transformed AST. This can be used to add custom language features and implement <span id="domainminusspecific-languages_1">domain-specific languages</span>.</p>
<p>Macro invocation is a case where semantic analysis does <strong>not</strong> entirely proceed top to bottom and left to right. Instead, semantic analysis happens at least twice:</p>
<ul class="simple"><li>Semantic analysis recognizes and resolves the macro invocation.</li>
<li>The compiler executes the macro body (which may invoke other procs).</li>
<li>It replaces the AST of the macro invocation with the AST returned by the macro.</li>
<li>It repeats semantic analysis of that region of the code.</li>
<li>If the AST returned by the macro contains other macro invocations, this process iterates.</li>
</ul>
<p>While macros enable advanced compile-time code transformations, they cannot change Nim's syntax.</p>
<p><strong>Style note:</strong> For code readability, it is best to use the least powerful programming construct that remains expressive. So the &quot;check list&quot; is:</p>
<ol class="simple"><li>Use an ordinary proc/iterator, if possible.</li>
<li>Else: Use a generic proc/iterator, if possible.</li>
<li>Else: Use a template, if possible.</li>
<li>Else: Use a macro.</li>
</ol>

<h2><a class="toc-backref" id="macros-debug-example" href="#macros-debug-example">Debug example</a></h2><p>The following example implements a powerful <tt class="docutils literal"><span class="pre"><span class="Identifier">debug</span></span></tt> command that accepts a variable number of arguments:</p>
<p><pre class="listing"><span class="Comment"># to work with Nim syntax trees, we need an API that is defined in the</span>
<span class="Comment"># `macros` module:</span>
<span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">macros</span>

<span class="Keyword">macro</span> <span class="Identifier">debug</span><span class="Punctuation">(</span><span class="Identifier">args</span><span class="Punctuation">:</span> <span class="Identifier">varargs</span><span class="Punctuation">[</span><span class="Identifier">untyped</span><span class="Punctuation">]</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">untyped</span> <span class="Operator">=</span>
  <span class="Comment"># `args` is a collection of `NimNode` values that each contain the</span>
  <span class="Comment"># AST for an argument of the macro. A macro always has to</span>
  <span class="Comment"># return a `NimNode`. A node of kind `nnkStmtList` is suitable for</span>
  <span class="Comment"># this use case.</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">nnkStmtList</span><span class="Operator">.</span><span class="Identifier">newTree</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
  <span class="Comment"># iterate over any argument that is passed to this macro:</span>
  <span class="Keyword">for</span> <span class="Identifier">n</span> <span class="Keyword">in</span> <span class="Identifier">args</span><span class="Punctuation">:</span>
    <span class="Comment"># add a call to the statement list that writes the expression;</span>
    <span class="Comment"># `toStrLit` converts an AST to its string representation:</span>
    <span class="Identifier">result</span><span class="Operator">.</span><span class="Identifier">add</span> <span class="Identifier">newCall</span><span class="Punctuation">(</span><span class="StringLit">&quot;write&quot;</span><span class="Punctuation">,</span> <span class="Identifier">newIdentNode</span><span class="Punctuation">(</span><span class="StringLit">&quot;stdout&quot;</span><span class="Punctuation">)</span><span class="Punctuation">,</span> <span class="Identifier">newLit</span><span class="Punctuation">(</span><span class="Identifier">n</span><span class="Operator">.</span><span class="Identifier">repr</span><span class="Punctuation">)</span><span class="Punctuation">)</span>
    <span class="Comment"># add a call to the statement list that writes &quot;: &quot;</span>
    <span class="Identifier">result</span><span class="Operator">.</span><span class="Identifier">add</span> <span class="Identifier">newCall</span><span class="Punctuation">(</span><span class="StringLit">&quot;write&quot;</span><span class="Punctuation">,</span> <span class="Identifier">newIdentNode</span><span class="Punctuation">(</span><span class="StringLit">&quot;stdout&quot;</span><span class="Punctuation">)</span><span class="Punctuation">,</span> <span class="Identifier">newLit</span><span class="Punctuation">(</span><span class="StringLit">&quot;: &quot;</span><span class="Punctuation">)</span><span class="Punctuation">)</span>
    <span class="Comment"># add a call to the statement list that writes the expressions value:</span>
    <span class="Identifier">result</span><span class="Operator">.</span><span class="Identifier">add</span> <span class="Identifier">newCall</span><span class="Punctuation">(</span><span class="StringLit">&quot;writeLine&quot;</span><span class="Punctuation">,</span> <span class="Identifier">newIdentNode</span><span class="Punctuation">(</span><span class="StringLit">&quot;stdout&quot;</span><span class="Punctuation">)</span><span class="Punctuation">,</span> <span class="Identifier">n</span><span class="Punctuation">)</span>

<span class="Keyword">var</span>
  <span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">array</span><span class="Punctuation">[</span><span class="FloatNumber">0.</span><span class="Operator">.</span><span class="DecNumber">10</span><span class="Punctuation">,</span> <span class="Identifier">int</span><span class="Punctuation">]</span>
  <span class="Identifier">x</span> <span class="Operator">=</span> <span class="StringLit">&quot;some string&quot;</span>
<span class="Identifier">a</span><span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="DecNumber">42</span>
<span class="Identifier">a</span><span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="DecNumber">45</span>

<span class="Identifier">debug</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">]</span><span class="Punctuation">,</span> <span class="Identifier">a</span><span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">]</span><span class="Punctuation">,</span> <span class="Identifier">x</span><span class="Punctuation">)</span></pre></p>
<p>The macro call expands to:</p>
<p><pre class="listing"><span class="Identifier">write</span><span class="Punctuation">(</span><span class="Identifier">stdout</span><span class="Punctuation">,</span> <span class="StringLit">&quot;a[0]&quot;</span><span class="Punctuation">)</span>
<span class="Identifier">write</span><span class="Punctuation">(</span><span class="Identifier">stdout</span><span class="Punctuation">,</span> <span class="StringLit">&quot;: &quot;</span><span class="Punctuation">)</span>
<span class="Identifier">writeLine</span><span class="Punctuation">(</span><span class="Identifier">stdout</span><span class="Punctuation">,</span> <span class="Identifier">a</span><span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">]</span><span class="Punctuation">)</span>

<span class="Identifier">write</span><span class="Punctuation">(</span><span class="Identifier">stdout</span><span class="Punctuation">,</span> <span class="StringLit">&quot;a[1]&quot;</span><span class="Punctuation">)</span>
<span class="Identifier">write</span><span class="Punctuation">(</span><span class="Identifier">stdout</span><span class="Punctuation">,</span> <span class="StringLit">&quot;: &quot;</span><span class="Punctuation">)</span>
<span class="Identifier">writeLine</span><span class="Punctuation">(</span><span class="Identifier">stdout</span><span class="Punctuation">,</span> <span class="Identifier">a</span><span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">]</span><span class="Punctuation">)</span>

<span class="Identifier">write</span><span class="Punctuation">(</span><span class="Identifier">stdout</span><span class="Punctuation">,</span> <span class="StringLit">&quot;x&quot;</span><span class="Punctuation">)</span>
<span class="Identifier">write</span><span class="Punctuation">(</span><span class="Identifier">stdout</span><span class="Punctuation">,</span> <span class="StringLit">&quot;: &quot;</span><span class="Punctuation">)</span>
<span class="Identifier">writeLine</span><span class="Punctuation">(</span><span class="Identifier">stdout</span><span class="Punctuation">,</span> <span class="Identifier">x</span><span class="Punctuation">)</span></pre></p>
<p>Arguments that are passed to a <tt class="docutils literal"><span class="pre"><span class="Identifier">varargs</span></span></tt> parameter are wrapped in an array constructor expression. This is why <tt class="docutils literal"><span class="pre"><span class="Identifier">debug</span></span></tt> iterates over all of <tt class="docutils literal"><span class="pre"><span class="Identifier">args</span></span></tt>'s children.</p>

<h2><a class="toc-backref" id="macros-bindsym" href="#macros-bindsym">bindSym</a></h2><p>The above <tt class="docutils literal"><span class="pre"><span class="Identifier">debug</span></span></tt> macro relies on the fact that <tt class="docutils literal"><span class="pre"><span class="Identifier">write</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Identifier">writeLine</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">stdout</span></span></tt> are declared in the system module and are thus visible in the instantiating context. There is a way to use bound identifiers (aka <span id="symbols_1">symbols</span>) instead of using unbound identifiers. The <tt class="docutils literal"><span class="pre"><span class="Identifier">bindSym</span></span></tt> builtin can be used for that:</p>
<p><pre class="listing"><span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">macros</span>

<span class="Keyword">macro</span> <span class="Identifier">debug</span><span class="Punctuation">(</span><span class="Identifier">n</span><span class="Punctuation">:</span> <span class="Identifier">varargs</span><span class="Punctuation">[</span><span class="Identifier">typed</span><span class="Punctuation">]</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">untyped</span> <span class="Operator">=</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">newNimNode</span><span class="Punctuation">(</span><span class="Identifier">nnkStmtList</span><span class="Punctuation">,</span> <span class="Identifier">n</span><span class="Punctuation">)</span>
  <span class="Keyword">for</span> <span class="Identifier">x</span> <span class="Keyword">in</span> <span class="Identifier">n</span><span class="Punctuation">:</span>
    <span class="Comment"># we can bind symbols in scope via 'bindSym':</span>
    <span class="Identifier">add</span><span class="Punctuation">(</span><span class="Identifier">result</span><span class="Punctuation">,</span> <span class="Identifier">newCall</span><span class="Punctuation">(</span><span class="RawData">bindSym&quot;write&quot;</span><span class="Punctuation">,</span> <span class="RawData">bindSym&quot;stdout&quot;</span><span class="Punctuation">,</span> <span class="Identifier">toStrLit</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span><span class="Punctuation">)</span><span class="Punctuation">)</span>
    <span class="Identifier">add</span><span class="Punctuation">(</span><span class="Identifier">result</span><span class="Punctuation">,</span> <span class="Identifier">newCall</span><span class="Punctuation">(</span><span class="RawData">bindSym&quot;write&quot;</span><span class="Punctuation">,</span> <span class="RawData">bindSym&quot;stdout&quot;</span><span class="Punctuation">,</span> <span class="Identifier">newStrLitNode</span><span class="Punctuation">(</span><span class="StringLit">&quot;: &quot;</span><span class="Punctuation">)</span><span class="Punctuation">)</span><span class="Punctuation">)</span>
    <span class="Identifier">add</span><span class="Punctuation">(</span><span class="Identifier">result</span><span class="Punctuation">,</span> <span class="Identifier">newCall</span><span class="Punctuation">(</span><span class="RawData">bindSym&quot;writeLine&quot;</span><span class="Punctuation">,</span> <span class="RawData">bindSym&quot;stdout&quot;</span><span class="Punctuation">,</span> <span class="Identifier">x</span><span class="Punctuation">)</span><span class="Punctuation">)</span>

<span class="Keyword">var</span>
  <span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">array</span><span class="Punctuation">[</span><span class="FloatNumber">0.</span><span class="Operator">.</span><span class="DecNumber">10</span><span class="Punctuation">,</span> <span class="Identifier">int</span><span class="Punctuation">]</span>
  <span class="Identifier">x</span> <span class="Operator">=</span> <span class="StringLit">&quot;some string&quot;</span>
<span class="Identifier">a</span><span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="DecNumber">42</span>
<span class="Identifier">a</span><span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="DecNumber">45</span>

<span class="Identifier">debug</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">]</span><span class="Punctuation">,</span> <span class="Identifier">a</span><span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">]</span><span class="Punctuation">,</span> <span class="Identifier">x</span><span class="Punctuation">)</span></pre></p>
<p>The macro call expands to:</p>
<p><pre class="listing"><span class="Identifier">write</span><span class="Punctuation">(</span><span class="Identifier">stdout</span><span class="Punctuation">,</span> <span class="StringLit">&quot;a[0]&quot;</span><span class="Punctuation">)</span>
<span class="Identifier">write</span><span class="Punctuation">(</span><span class="Identifier">stdout</span><span class="Punctuation">,</span> <span class="StringLit">&quot;: &quot;</span><span class="Punctuation">)</span>
<span class="Identifier">writeLine</span><span class="Punctuation">(</span><span class="Identifier">stdout</span><span class="Punctuation">,</span> <span class="Identifier">a</span><span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">]</span><span class="Punctuation">)</span>

<span class="Identifier">write</span><span class="Punctuation">(</span><span class="Identifier">stdout</span><span class="Punctuation">,</span> <span class="StringLit">&quot;a[1]&quot;</span><span class="Punctuation">)</span>
<span class="Identifier">write</span><span class="Punctuation">(</span><span class="Identifier">stdout</span><span class="Punctuation">,</span> <span class="StringLit">&quot;: &quot;</span><span class="Punctuation">)</span>
<span class="Identifier">writeLine</span><span class="Punctuation">(</span><span class="Identifier">stdout</span><span class="Punctuation">,</span> <span class="Identifier">a</span><span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">]</span><span class="Punctuation">)</span>

<span class="Identifier">write</span><span class="Punctuation">(</span><span class="Identifier">stdout</span><span class="Punctuation">,</span> <span class="StringLit">&quot;x&quot;</span><span class="Punctuation">)</span>
<span class="Identifier">write</span><span class="Punctuation">(</span><span class="Identifier">stdout</span><span class="Punctuation">,</span> <span class="StringLit">&quot;: &quot;</span><span class="Punctuation">)</span>
<span class="Identifier">writeLine</span><span class="Punctuation">(</span><span class="Identifier">stdout</span><span class="Punctuation">,</span> <span class="Identifier">x</span><span class="Punctuation">)</span></pre></p>
<p>In this version of <tt class="docutils literal"><span class="pre"><span class="Identifier">debug</span></span></tt>, the symbols <tt class="docutils literal"><span class="pre"><span class="Identifier">write</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Identifier">writeLine</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">stdout</span></span></tt> are already bound and are not looked up again. As the example shows, <tt class="docutils literal"><span class="pre"><span class="Identifier">bindSym</span></span></tt> does work with overloaded symbols implicitly.</p>
<p>Note that the symbol names passed to <tt class="docutils literal"><span class="pre"><span class="Identifier">bindSym</span></span></tt> have to be constant. The experimental feature <tt class="docutils literal"><span class="pre"><span class="Identifier">dynamicBindSym</span></span></tt> (<a class="reference external" href=" manual_experimental.html#dynamic-arguments-for-bindsym">experimental manual</a>) allows this value to be computed dynamically.</p>

<h2><a class="toc-backref" id="macros-postminusstatement-blocks" href="#macros-postminusstatement-blocks">Post-statement blocks</a></h2><p>Macros can receive <tt class="docutils literal"><span class="pre"><span class="Keyword">of</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">elif</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">else</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">except</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">finally</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Keyword">do</span></span></tt> blocks (including their different forms such as <tt class="docutils literal"><span class="pre"><span class="Keyword">do</span></span></tt> with routine parameters) as arguments if called in statement form.</p>
<p><pre class="listing"><span class="Keyword">macro</span> <span class="Identifier">performWithUndo</span><span class="Punctuation">(</span><span class="Identifier">task</span><span class="Punctuation">,</span> <span class="Identifier">undo</span><span class="Punctuation">:</span> <span class="Identifier">untyped</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Operator">...</span>

<span class="Identifier">performWithUndo</span> <span class="Keyword">do</span><span class="Punctuation">:</span>
  <span class="Comment"># multiple-line block of code</span>
  <span class="Comment"># to perform the task</span>
<span class="Keyword">do</span><span class="Punctuation">:</span>
  <span class="Comment"># code to undo it</span>

<span class="Keyword">let</span> <span class="Identifier">num</span> <span class="Operator">=</span> <span class="DecNumber">12</span>
<span class="Comment"># a single colon may be used if there is no initial block</span>
<span class="Identifier">match</span> <span class="Punctuation">(</span><span class="Identifier">num</span> <span class="Keyword">mod</span> <span class="DecNumber">3</span><span class="Punctuation">,</span> <span class="Identifier">num</span> <span class="Keyword">mod</span> <span class="DecNumber">5</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
<span class="Keyword">of</span> <span class="Punctuation">(</span><span class="DecNumber">0</span><span class="Punctuation">,</span> <span class="DecNumber">0</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;FizzBuzz&quot;</span>
<span class="Keyword">of</span> <span class="Punctuation">(</span><span class="DecNumber">0</span><span class="Punctuation">,</span> <span class="Identifier">_</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;Fizz&quot;</span>
<span class="Keyword">of</span> <span class="Punctuation">(</span><span class="Identifier">_</span><span class="Punctuation">,</span> <span class="DecNumber">0</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;Buzz&quot;</span>
<span class="Keyword">else</span><span class="Punctuation">:</span>
  <span class="Identifier">echo</span> <span class="Identifier">num</span></pre></p>

<h2><a class="toc-backref" id="macros-for-loop-macro" href="#macros-for-loop-macro">For loop macro</a></h2><p>A macro that takes as its only input parameter an expression of the special type <tt class="docutils literal"><span class="pre"><span class="Identifier">system</span><span class="Operator">.</span><span class="Identifier">ForLoopStmt</span></span></tt> can rewrite the entirety of a <tt class="docutils literal"><span class="pre"><span class="Keyword">for</span></span></tt> loop:</p>
<p><pre class="listing"><span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">macros</span>

<span class="Keyword">macro</span> <span class="Identifier">example</span><span class="Punctuation">(</span><span class="Identifier">loop</span><span class="Punctuation">:</span> <span class="Identifier">ForLoopStmt</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">newTree</span><span class="Punctuation">(</span><span class="Identifier">nnkForStmt</span><span class="Punctuation">)</span>    <span class="Comment"># Create a new For loop.</span>
  <span class="Identifier">result</span><span class="Operator">.</span><span class="Identifier">add</span> <span class="Identifier">loop</span><span class="Punctuation">[</span><span class="Operator">^</span><span class="DecNumber">3</span><span class="Punctuation">]</span>             <span class="Comment"># This is &quot;item&quot;.</span>
  <span class="Identifier">result</span><span class="Operator">.</span><span class="Identifier">add</span> <span class="Identifier">loop</span><span class="Punctuation">[</span><span class="Operator">^</span><span class="DecNumber">2</span><span class="Punctuation">]</span><span class="Punctuation">[</span><span class="Operator">^</span><span class="DecNumber">1</span><span class="Punctuation">]</span>         <span class="Comment"># This is &quot;[1, 2, 3]&quot;.</span>
  <span class="Identifier">result</span><span class="Operator">.</span><span class="Identifier">add</span> <span class="Identifier">newCall</span><span class="Punctuation">(</span><span class="RawData">bindSym&quot;echo&quot;</span><span class="Punctuation">,</span> <span class="Identifier">loop</span><span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">]</span><span class="Punctuation">)</span>

<span class="Keyword">for</span> <span class="Identifier">item</span> <span class="Keyword">in</span> <span class="Identifier">example</span><span class="Punctuation">(</span><span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="DecNumber">2</span><span class="Punctuation">,</span> <span class="DecNumber">3</span><span class="Punctuation">]</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Keyword">discard</span></pre></p>
<p>Expands to:</p>
<p><pre class="listing"><span class="Keyword">for</span> <span class="Identifier">item</span> <span class="Keyword">in</span> <span class="Identifier">items</span><span class="Punctuation">(</span><span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="DecNumber">2</span><span class="Punctuation">,</span> <span class="DecNumber">3</span><span class="Punctuation">]</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
  <span class="Identifier">echo</span> <span class="Identifier">item</span></pre></p>
<p>Another example:</p>
<p><pre class="listing"><span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">macros</span>

<span class="Keyword">macro</span> <span class="Identifier">enumerate</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">ForLoopStmt</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">untyped</span> <span class="Operator">=</span>
  <span class="Identifier">expectKind</span> <span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">nnkForStmt</span>
  <span class="Comment"># check if the starting count is specified:</span>
  <span class="Keyword">var</span> <span class="Identifier">countStart</span> <span class="Operator">=</span> <span class="Keyword">if</span> <span class="Identifier">x</span><span class="Punctuation">[</span><span class="Operator">^</span><span class="DecNumber">2</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Identifier">len</span> <span class="Operator">==</span> <span class="DecNumber">2</span><span class="Punctuation">:</span> <span class="Identifier">newLit</span><span class="Punctuation">(</span><span class="DecNumber">0</span><span class="Punctuation">)</span> <span class="Keyword">else</span><span class="Punctuation">:</span> <span class="Identifier">x</span><span class="Punctuation">[</span><span class="Operator">^</span><span class="DecNumber">2</span><span class="Punctuation">]</span><span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">]</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">newStmtList</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
  <span class="Comment"># we strip off the first for loop variable and use it as an integer counter:</span>
  <span class="Identifier">result</span><span class="Operator">.</span><span class="Identifier">add</span> <span class="Identifier">newVarStmt</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">]</span><span class="Punctuation">,</span> <span class="Identifier">countStart</span><span class="Punctuation">)</span>
  <span class="Keyword">var</span> <span class="Identifier">body</span> <span class="Operator">=</span> <span class="Identifier">x</span><span class="Punctuation">[</span><span class="Operator">^</span><span class="DecNumber">1</span><span class="Punctuation">]</span>
  <span class="Keyword">if</span> <span class="Identifier">body</span><span class="Operator">.</span><span class="Identifier">kind</span> <span class="Operator">!=</span> <span class="Identifier">nnkStmtList</span><span class="Punctuation">:</span>
    <span class="Identifier">body</span> <span class="Operator">=</span> <span class="Identifier">newTree</span><span class="Punctuation">(</span><span class="Identifier">nnkStmtList</span><span class="Punctuation">,</span> <span class="Identifier">body</span><span class="Punctuation">)</span>
  <span class="Identifier">body</span><span class="Operator">.</span><span class="Identifier">add</span> <span class="Identifier">newCall</span><span class="Punctuation">(</span><span class="RawData">bindSym&quot;inc&quot;</span><span class="Punctuation">,</span> <span class="Identifier">x</span><span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">]</span><span class="Punctuation">)</span>
  <span class="Keyword">var</span> <span class="Identifier">newFor</span> <span class="Operator">=</span> <span class="Identifier">newTree</span><span class="Punctuation">(</span><span class="Identifier">nnkForStmt</span><span class="Punctuation">)</span>
  <span class="Keyword">for</span> <span class="Identifier">i</span> <span class="Keyword">in</span> <span class="FloatNumber">1.</span><span class="Operator">.</span><span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">len</span><span class="Operator">-</span><span class="DecNumber">3</span><span class="Punctuation">:</span>
    <span class="Identifier">newFor</span><span class="Operator">.</span><span class="Identifier">add</span> <span class="Identifier">x</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span>
  <span class="Comment"># transform enumerate(X) to 'X'</span>
  <span class="Identifier">newFor</span><span class="Operator">.</span><span class="Identifier">add</span> <span class="Identifier">x</span><span class="Punctuation">[</span><span class="Operator">^</span><span class="DecNumber">2</span><span class="Punctuation">]</span><span class="Punctuation">[</span><span class="Operator">^</span><span class="DecNumber">1</span><span class="Punctuation">]</span>
  <span class="Identifier">newFor</span><span class="Operator">.</span><span class="Identifier">add</span> <span class="Identifier">body</span>
  <span class="Identifier">result</span><span class="Operator">.</span><span class="Identifier">add</span> <span class="Identifier">newFor</span>
  <span class="Comment"># now wrap the whole macro in a block to create a new scope</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">quote</span> <span class="Keyword">do</span><span class="Punctuation">:</span>
    <span class="Keyword">block</span><span class="Punctuation">:</span> <span class="Punctuation">`</span><span class="Identifier">result</span><span class="Punctuation">`</span>

<span class="Keyword">for</span> <span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span> <span class="Keyword">in</span> <span class="Identifier">enumerate</span><span class="Punctuation">(</span><span class="Identifier">items</span><span class="Punctuation">(</span><span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="DecNumber">2</span><span class="Punctuation">,</span> <span class="DecNumber">3</span><span class="Punctuation">]</span><span class="Punctuation">)</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
  <span class="Identifier">echo</span> <span class="Identifier">a</span><span class="Punctuation">,</span> <span class="StringLit">&quot; &quot;</span><span class="Punctuation">,</span> <span class="Identifier">b</span>

<span class="Comment"># without wrapping the macro in a block, we'd need to choose different</span>
<span class="Comment"># names for `a` and `b` here to avoid redefinition errors</span>
<span class="Keyword">for</span> <span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span> <span class="Keyword">in</span> <span class="Identifier">enumerate</span><span class="Punctuation">(</span><span class="DecNumber">10</span><span class="Punctuation">,</span> <span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="DecNumber">2</span><span class="Punctuation">,</span> <span class="DecNumber">3</span><span class="Punctuation">,</span> <span class="DecNumber">5</span><span class="Punctuation">]</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
  <span class="Identifier">echo</span> <span class="Identifier">a</span><span class="Punctuation">,</span> <span class="StringLit">&quot; &quot;</span><span class="Punctuation">,</span> <span class="Identifier">b</span></pre></p>

<h2><a class="toc-backref" id="macros-case-statement-macros" href="#macros-case-statement-macros">Case statement macros</a></h2><p>Macros named `` <tt class="docutils literal"><span class="pre"><span class="Keyword">case</span></span></tt> `` can provide implementations of <tt class="docutils literal"><span class="pre"><span class="Keyword">case</span></span></tt> statements for certain types. The following is an example of such an implementation for tuples, leveraging the existing equality operator for tuples (as provided in <tt class="docutils literal"><span class="pre"><span class="Identifier">system</span><span class="Operator">.==</span></span></tt>):</p>
<p><pre class="listing"><span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">macros</span>

<span class="Keyword">macro</span> <span class="Punctuation">`</span><span class="Keyword">case</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">n</span><span class="Punctuation">:</span> <span class="Keyword">tuple</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">untyped</span> <span class="Operator">=</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">newTree</span><span class="Punctuation">(</span><span class="Identifier">nnkIfStmt</span><span class="Punctuation">)</span>
  <span class="Keyword">let</span> <span class="Identifier">selector</span> <span class="Operator">=</span> <span class="Identifier">n</span><span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">]</span>
  <span class="Keyword">for</span> <span class="Identifier">i</span> <span class="Keyword">in</span> <span class="DecNumber">1</span> <span class="Operator">..&lt;</span> <span class="Identifier">n</span><span class="Operator">.</span><span class="Identifier">len</span><span class="Punctuation">:</span>
    <span class="Keyword">let</span> <span class="Identifier">it</span> <span class="Operator">=</span> <span class="Identifier">n</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span>
    <span class="Keyword">case</span> <span class="Identifier">it</span><span class="Operator">.</span><span class="Identifier">kind</span>
    <span class="Keyword">of</span> <span class="Identifier">nnkElse</span><span class="Punctuation">,</span> <span class="Identifier">nnkElifBranch</span><span class="Punctuation">,</span> <span class="Identifier">nnkElifExpr</span><span class="Punctuation">,</span> <span class="Identifier">nnkElseExpr</span><span class="Punctuation">:</span>
      <span class="Identifier">result</span><span class="Operator">.</span><span class="Identifier">add</span> <span class="Identifier">it</span>
    <span class="Keyword">of</span> <span class="Identifier">nnkOfBranch</span><span class="Punctuation">:</span>
      <span class="Keyword">for</span> <span class="Identifier">j</span> <span class="Keyword">in</span> <span class="FloatNumber">0.</span><span class="Operator">.</span><span class="Identifier">it</span><span class="Operator">.</span><span class="Identifier">len</span><span class="Operator">-</span><span class="DecNumber">2</span><span class="Punctuation">:</span>
        <span class="Keyword">let</span> <span class="Identifier">cond</span> <span class="Operator">=</span> <span class="Identifier">newCall</span><span class="Punctuation">(</span><span class="StringLit">&quot;==&quot;</span><span class="Punctuation">,</span> <span class="Identifier">selector</span><span class="Punctuation">,</span> <span class="Identifier">it</span><span class="Punctuation">[</span><span class="Identifier">j</span><span class="Punctuation">]</span><span class="Punctuation">)</span>
        <span class="Identifier">result</span><span class="Operator">.</span><span class="Identifier">add</span> <span class="Identifier">newTree</span><span class="Punctuation">(</span><span class="Identifier">nnkElifBranch</span><span class="Punctuation">,</span> <span class="Identifier">cond</span><span class="Punctuation">,</span> <span class="Identifier">it</span><span class="Punctuation">[</span><span class="Operator">^</span><span class="DecNumber">1</span><span class="Punctuation">]</span><span class="Punctuation">)</span>
    <span class="Keyword">else</span><span class="Punctuation">:</span>
      <span class="Identifier">error</span> <span class="StringLit">&quot;custom 'case' for tuple cannot handle this node&quot;</span><span class="Punctuation">,</span> <span class="Identifier">it</span>

<span class="Keyword">case</span> <span class="Punctuation">(</span><span class="StringLit">&quot;foo&quot;</span><span class="Punctuation">,</span> <span class="DecNumber">78</span><span class="Punctuation">)</span>
<span class="Keyword">of</span> <span class="Punctuation">(</span><span class="StringLit">&quot;foo&quot;</span><span class="Punctuation">,</span> <span class="DecNumber">78</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">echo</span> <span class="StringLit">&quot;yes&quot;</span>
<span class="Keyword">of</span> <span class="Punctuation">(</span><span class="StringLit">&quot;bar&quot;</span><span class="Punctuation">,</span> <span class="DecNumber">88</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">echo</span> <span class="StringLit">&quot;no&quot;</span>
<span class="Keyword">else</span><span class="Punctuation">:</span> <span class="Keyword">discard</span></pre></p>
<p><tt class="docutils literal"><span class="pre"><span class="Keyword">case</span></span></tt> macros are subject to overload resolution. The type of the <tt class="docutils literal"><span class="pre"><span class="Keyword">case</span></span></tt> statement's selector expression is matched against the type of the first argument of the <tt class="docutils literal"><span class="pre"><span class="Keyword">case</span></span></tt> macro. Then the complete <tt class="docutils literal"><span class="pre"><span class="Keyword">case</span></span></tt> statement is passed in place of the argument and the macro is evaluated.</p>
<p>In other words, the macro needs to transform the full <tt class="docutils literal"><span class="pre"><span class="Keyword">case</span></span></tt> statement but only the statement's selector expression is used to determine which macro to call.</p>

<h1><a class="toc-backref" id="special-types" href="#special-types">Special Types</a></h1>
<h2><a class="toc-backref" id="special-types-static-t" href="#special-types-static-t">static[T]</a></h2><p>As their name suggests, static parameters must be constant expressions:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">precompiledRegex</span><span class="Punctuation">(</span><span class="Identifier">pattern</span><span class="Punctuation">:</span> <span class="Keyword">static</span> <span class="Identifier">string</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">RegEx</span> <span class="Operator">=</span>
  <span class="Keyword">var</span> <span class="Identifier">res</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">global</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Identifier">re</span><span class="Punctuation">(</span><span class="Identifier">pattern</span><span class="Punctuation">)</span>
  <span class="Keyword">return</span> <span class="Identifier">res</span>

<span class="Identifier">precompiledRegex</span><span class="Punctuation">(</span><span class="StringLit">&quot;/d+&quot;</span><span class="Punctuation">)</span> <span class="Comment"># Replaces the call with a precompiled</span>
                        <span class="Comment"># regex, stored in a global variable</span>

<span class="Identifier">precompiledRegex</span><span class="Punctuation">(</span><span class="Identifier">paramStr</span><span class="Punctuation">(</span><span class="DecNumber">1</span><span class="Punctuation">)</span><span class="Punctuation">)</span> <span class="Comment"># Error, command-line options</span>
                              <span class="Comment"># are not constant expressions</span></pre></p>
<p>For the purposes of code generation, all static parameters are treated as generic parameters - the proc will be compiled separately for each unique supplied value (or combination of values).</p>
<p>Static parameters can also appear in the signatures of generic types:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">Matrix</span><span class="Punctuation">[</span><span class="Identifier">M</span><span class="Punctuation">,</span><span class="Identifier">N</span><span class="Punctuation">:</span> <span class="Keyword">static</span> <span class="Identifier">int</span><span class="Punctuation">;</span> <span class="Identifier">T</span><span class="Punctuation">:</span> <span class="Identifier">Number</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Identifier">array</span><span class="Punctuation">[</span><span class="FloatNumber">0.</span><span class="Operator">.</span><span class="Punctuation">(</span><span class="Identifier">M</span><span class="Operator">*</span><span class="Identifier">N</span> <span class="Operator">-</span> <span class="DecNumber">1</span><span class="Punctuation">)</span><span class="Punctuation">,</span> <span class="Identifier">T</span><span class="Punctuation">]</span>
    <span class="Comment"># Note how `Number` is just a type constraint here, while</span>
    <span class="Comment"># `static int` requires us to supply an int value</span>
  
  <span class="Identifier">AffineTransform2D</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Identifier">Matrix</span><span class="Punctuation">[</span><span class="DecNumber">3</span><span class="Punctuation">,</span> <span class="DecNumber">3</span><span class="Punctuation">,</span> <span class="Identifier">T</span><span class="Punctuation">]</span>
  <span class="Identifier">AffineTransform3D</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Identifier">Matrix</span><span class="Punctuation">[</span><span class="DecNumber">4</span><span class="Punctuation">,</span> <span class="DecNumber">4</span><span class="Punctuation">,</span> <span class="Identifier">T</span><span class="Punctuation">]</span>

<span class="Keyword">var</span> <span class="Identifier">m1</span><span class="Punctuation">:</span> <span class="Identifier">AffineTransform3D</span><span class="Punctuation">[</span><span class="Identifier">float</span><span class="Punctuation">]</span>  <span class="Comment"># OK</span>
<span class="Keyword">var</span> <span class="Identifier">m2</span><span class="Punctuation">:</span> <span class="Identifier">AffineTransform2D</span><span class="Punctuation">[</span><span class="Identifier">string</span><span class="Punctuation">]</span> <span class="Comment"># Error, `string` is not a `Number`</span></pre></p>
<p>Please note that <tt class="docutils literal"><span class="pre"><span class="Keyword">static</span> <span class="Identifier">T</span></span></tt> is just a syntactic convenience for the underlying generic type <tt class="docutils literal"><span class="pre"><span class="Keyword">static</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span></span></tt>. The type parameter can be omitted to obtain the type class of all constant expressions. A more specific type class can be created by instantiating <tt class="docutils literal"><span class="pre"><span class="Keyword">static</span></span></tt> with another type class.</p>
<p>One can force an expression to be evaluated at compile time as a constant expression by coercing it to a corresponding <tt class="docutils literal"><span class="pre"><span class="Keyword">static</span></span></tt> type:</p>
<p><pre class="listing"><span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">math</span>

<span class="Identifier">echo</span> <span class="Keyword">static</span><span class="Punctuation">(</span><span class="Identifier">fac</span><span class="Punctuation">(</span><span class="DecNumber">5</span><span class="Punctuation">)</span><span class="Punctuation">)</span><span class="Punctuation">,</span> <span class="StringLit">&quot; &quot;</span><span class="Punctuation">,</span> <span class="Keyword">static</span><span class="Punctuation">[</span><span class="Identifier">bool</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="FloatNumber">16.</span><span class="Identifier">isPowerOfTwo</span><span class="Punctuation">)</span></pre></p>
<p>The compiler will report any failure to evaluate the expression or a possible type mismatch error.</p>

<h2><a class="toc-backref" id="special-types-typedesc-t" href="#special-types-typedesc-t">typedesc[T]</a></h2><p>In many contexts, Nim treats the names of types as regular values. These values exist only during the compilation phase, but since all values must have a type, <tt class="docutils literal"><span class="pre"><span class="Identifier">typedesc</span></span></tt> is considered their special type.</p>
<p><tt class="docutils literal"><span class="pre"><span class="Identifier">typedesc</span></span></tt> acts as a generic type. For instance, the type of the symbol <tt class="docutils literal"><span class="pre"><span class="Identifier">int</span></span></tt> is <tt class="docutils literal"><span class="pre"><span class="Identifier">typedesc</span><span class="Punctuation">[</span><span class="Identifier">int</span><span class="Punctuation">]</span></span></tt>. Just like with regular generic types, when the generic parameter is omitted, <tt class="docutils literal"><span class="pre"><span class="Identifier">typedesc</span></span></tt> denotes the type class of all types. As a syntactic convenience, one can also use <tt class="docutils literal"><span class="pre"><span class="Identifier">typedesc</span></span></tt> as a modifier.</p>
<p>Procs featuring <tt class="docutils literal"><span class="pre"><span class="Identifier">typedesc</span></span></tt> parameters are considered implicitly generic. They will be instantiated for each unique combination of supplied types, and within the body of the proc, the name of each parameter will refer to the bound concrete type:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">new</span><span class="Punctuation">(</span><span class="Identifier">T</span><span class="Punctuation">:</span> <span class="Identifier">typedesc</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Keyword">ref</span> <span class="Identifier">T</span> <span class="Operator">=</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;allocating &quot;</span><span class="Punctuation">,</span> <span class="Identifier">T</span><span class="Operator">.</span><span class="Identifier">name</span>
  <span class="Identifier">new</span><span class="Punctuation">(</span><span class="Identifier">result</span><span class="Punctuation">)</span>

<span class="Keyword">var</span> <span class="Identifier">n</span> <span class="Operator">=</span> <span class="Identifier">Node</span><span class="Operator">.</span><span class="Identifier">new</span>
<span class="Keyword">var</span> <span class="Identifier">tree</span> <span class="Operator">=</span> <span class="Identifier">new</span><span class="Punctuation">(</span><span class="Identifier">BinaryTree</span><span class="Punctuation">[</span><span class="Identifier">int</span><span class="Punctuation">]</span><span class="Punctuation">)</span></pre></p>
<p>When multiple type parameters are present, they will bind freely to different types. To force a bind-once behavior, one can use an explicit generic parameter:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">acceptOnlyTypePairs</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">,</span> <span class="Identifier">U</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">A</span><span class="Punctuation">,</span> <span class="Identifier">B</span><span class="Punctuation">:</span> <span class="Identifier">typedesc</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">;</span> <span class="Identifier">C</span><span class="Punctuation">,</span> <span class="Identifier">D</span><span class="Punctuation">:</span> <span class="Identifier">typedesc</span><span class="Punctuation">[</span><span class="Identifier">U</span><span class="Punctuation">]</span><span class="Punctuation">)</span></pre></p>
<p>Once bound, type parameters can appear in the rest of the proc signature:</p>
<p><pre class="listing"><span class="Keyword">template</span> <span class="Identifier">declareVariableWithType</span><span class="Punctuation">(</span><span class="Identifier">T</span><span class="Punctuation">:</span> <span class="Identifier">typedesc</span><span class="Punctuation">,</span> <span class="Identifier">value</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">var</span> <span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">T</span> <span class="Operator">=</span> <span class="Identifier">value</span>

<span class="Identifier">declareVariableWithType</span> <span class="Identifier">int</span><span class="Punctuation">,</span> <span class="DecNumber">42</span></pre></p>
<p>Overload resolution can be further influenced by constraining the set of types that will match the type parameter. This works in practice by attaching attributes to types via templates. The constraint can be a concrete type or a type class.</p>
<p><pre class="listing"><span class="Keyword">template</span> <span class="Identifier">maxval</span><span class="Punctuation">(</span><span class="Identifier">T</span><span class="Punctuation">:</span> <span class="Identifier">typedesc</span><span class="Punctuation">[</span><span class="Identifier">int</span><span class="Punctuation">]</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span> <span class="Identifier">high</span><span class="Punctuation">(</span><span class="Identifier">int</span><span class="Punctuation">)</span>
<span class="Keyword">template</span> <span class="Identifier">maxval</span><span class="Punctuation">(</span><span class="Identifier">T</span><span class="Punctuation">:</span> <span class="Identifier">typedesc</span><span class="Punctuation">[</span><span class="Identifier">float</span><span class="Punctuation">]</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">float</span> <span class="Operator">=</span> <span class="Identifier">Inf</span>

<span class="Keyword">var</span> <span class="Identifier">i</span> <span class="Operator">=</span> <span class="Identifier">int</span><span class="Operator">.</span><span class="Identifier">maxval</span>
<span class="Keyword">var</span> <span class="Identifier">f</span> <span class="Operator">=</span> <span class="Identifier">float</span><span class="Operator">.</span><span class="Identifier">maxval</span>
<span class="Keyword">when</span> <span class="Identifier">false</span><span class="Punctuation">:</span>
  <span class="Keyword">var</span> <span class="Identifier">s</span> <span class="Operator">=</span> <span class="Identifier">string</span><span class="Operator">.</span><span class="Identifier">maxval</span> <span class="Comment"># error, maxval is not implemented for string</span>

<span class="Keyword">template</span> <span class="Identifier">isNumber</span><span class="Punctuation">(</span><span class="Identifier">t</span><span class="Punctuation">:</span> <span class="Identifier">typedesc</span><span class="Punctuation">[</span><span class="Keyword">object</span><span class="Punctuation">]</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">string</span> <span class="Operator">=</span> <span class="StringLit">&quot;Don't think so.&quot;</span>
<span class="Keyword">template</span> <span class="Identifier">isNumber</span><span class="Punctuation">(</span><span class="Identifier">t</span><span class="Punctuation">:</span> <span class="Identifier">typedesc</span><span class="Punctuation">[</span><span class="Identifier">SomeInteger</span><span class="Punctuation">]</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">string</span> <span class="Operator">=</span> <span class="StringLit">&quot;Yes!&quot;</span>
<span class="Keyword">template</span> <span class="Identifier">isNumber</span><span class="Punctuation">(</span><span class="Identifier">t</span><span class="Punctuation">:</span> <span class="Identifier">typedesc</span><span class="Punctuation">[</span><span class="Identifier">SomeFloat</span><span class="Punctuation">]</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">string</span> <span class="Operator">=</span> <span class="StringLit">&quot;Maybe, could be NaN.&quot;</span>

<span class="Identifier">echo</span> <span class="StringLit">&quot;is int a number? &quot;</span><span class="Punctuation">,</span> <span class="Identifier">isNumber</span><span class="Punctuation">(</span><span class="Identifier">int</span><span class="Punctuation">)</span>
<span class="Identifier">echo</span> <span class="StringLit">&quot;is float a number? &quot;</span><span class="Punctuation">,</span> <span class="Identifier">isNumber</span><span class="Punctuation">(</span><span class="Identifier">float</span><span class="Punctuation">)</span>
<span class="Identifier">echo</span> <span class="StringLit">&quot;is RootObj a number? &quot;</span><span class="Punctuation">,</span> <span class="Identifier">isNumber</span><span class="Punctuation">(</span><span class="Identifier">RootObj</span><span class="Punctuation">)</span></pre></p>
<p>Passing <tt class="docutils literal"><span class="pre"><span class="Identifier">typedesc</span></span></tt> is almost identical, just with the difference that the macro is not instantiated generically. The type expression is simply passed as a <tt class="docutils literal"><span class="pre"><span class="Identifier">NimNode</span></span></tt> to the macro, like everything else.</p>
<p><pre class="listing"><span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">macros</span>

<span class="Keyword">macro</span> <span class="Identifier">forwardType</span><span class="Punctuation">(</span><span class="Identifier">arg</span><span class="Punctuation">:</span> <span class="Identifier">typedesc</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">typedesc</span> <span class="Operator">=</span>
  <span class="Comment"># `arg` is of type `NimNode`</span>
  <span class="Keyword">let</span> <span class="Identifier">tmp</span><span class="Punctuation">:</span> <span class="Identifier">NimNode</span> <span class="Operator">=</span> <span class="Identifier">arg</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">tmp</span>

<span class="Keyword">var</span> <span class="Identifier">tmp</span><span class="Punctuation">:</span> <span class="Identifier">forwardType</span><span class="Punctuation">(</span><span class="Identifier">int</span><span class="Punctuation">)</span></pre></p>

<h2><a class="toc-backref" id="special-types-typeof-operator" href="#special-types-typeof-operator">typeof operator</a></h2><p><strong>Note</strong>: <tt class="docutils literal"><span class="pre"><span class="Identifier">typeof</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span></span></tt> can for historical reasons also be written as <tt class="docutils literal"><span class="pre"><span class="Keyword">type</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span></span></tt> but <tt class="docutils literal"><span class="pre"><span class="Keyword">type</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span></span></tt> is discouraged.</p>
<p>One can obtain the type of a given expression by constructing a <tt class="docutils literal"><span class="pre"><span class="Identifier">typeof</span></span></tt> value from it (in many other languages this is known as the <span id="typeof_1">typeof</span> operator):</p>
<p><pre class="listing"><span class="Keyword">var</span> <span class="Identifier">x</span> <span class="Operator">=</span> <span class="DecNumber">0</span>
<span class="Keyword">var</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">typeof</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span> <span class="Comment"># y has type int</span></pre></p>
<p>If <tt class="docutils literal"><span class="pre"><span class="Identifier">typeof</span></span></tt> is used to determine the result type of a proc/iterator/converter call <tt class="docutils literal"><span class="pre"><span class="Identifier">c</span><span class="Punctuation">(</span><span class="Identifier">X</span><span class="Punctuation">)</span></span></tt> (where <tt class="docutils literal"><span class="pre"><span class="Identifier">X</span></span></tt> stands for a possibly empty list of arguments), the interpretation, where <tt class="docutils literal"><span class="pre"><span class="Identifier">c</span></span></tt> is an iterator, is preferred over the other interpretations, but this behavior can be changed by passing <tt class="docutils literal"><span class="pre"><span class="Identifier">typeOfProc</span></span></tt> as the second argument to <tt class="docutils literal"><span class="pre"><span class="Identifier">typeof</span></span></tt>:</p>
<p><pre class="listing"><span class="Keyword">iterator</span> <span class="Identifier">split</span><span class="Punctuation">(</span><span class="Identifier">s</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">string</span> <span class="Operator">=</span> <span class="Keyword">discard</span>
<span class="Keyword">proc</span> <span class="Identifier">split</span><span class="Punctuation">(</span><span class="Identifier">s</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">string</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Keyword">discard</span>

<span class="Comment"># since an iterator is the preferred interpretation, this has the type `string`:</span>
<span class="Identifier">assert</span> <span class="Identifier">typeof</span><span class="Punctuation">(</span><span class="StringLit">&quot;a b c&quot;</span><span class="Operator">.</span><span class="Identifier">split</span><span class="Punctuation">)</span> <span class="Keyword">is</span> <span class="Identifier">string</span>

<span class="Identifier">assert</span> <span class="Identifier">typeof</span><span class="Punctuation">(</span><span class="StringLit">&quot;a b c&quot;</span><span class="Operator">.</span><span class="Identifier">split</span><span class="Punctuation">,</span> <span class="Identifier">typeOfProc</span><span class="Punctuation">)</span> <span class="Keyword">is</span> <span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">string</span><span class="Punctuation">]</span></pre></p>

<h1><a class="toc-backref" id="modules" href="#modules">Modules</a></h1><p>Nim supports splitting a program into pieces by a module concept. Each module needs to be in its own file and has its own <span id="namespace_1">namespace</span>. Modules enable <span id="information-hiding_1">information hiding</span> and <span id="separate-compilation_1">separate compilation</span>. A module may gain access to the symbols of another module by the <span id="import_1">import</span> statement. <span id="recursive-module-dependencies_1">Recursive module dependencies</span> are allowed, but are slightly subtle. Only top-level symbols that are marked with an asterisk (<tt class="docutils literal"><span class="pre"><span class="Operator">*</span></span></tt>) are exported. A valid module name can only be a valid Nim identifier (and thus its filename is <tt class="docutils literal"><span class="pre">identifier.nim</span></tt>).</p>
<p>The algorithm for compiling modules is:</p>
<ul class="simple"><li>Compile the whole module as usual, following import statements recursively.</li>
<li>If there is a cycle, only import the already parsed symbols (that are exported); if an unknown identifier occurs then abort.</li>
</ul>
<p>This is best illustrated by an example:</p>
<p><pre class="listing"><span class="Comment"># Module A</span>
<span class="Keyword">type</span>
  <span class="Identifier">T1</span><span class="Operator">*</span> <span class="Operator">=</span> <span class="Identifier">int</span>  <span class="Comment"># Module A exports the type `T1`</span>
<span class="Keyword">import</span> <span class="Identifier">B</span>     <span class="Comment"># the compiler starts parsing B</span>

<span class="Keyword">proc</span> <span class="Identifier">main</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">var</span> <span class="Identifier">i</span> <span class="Operator">=</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="DecNumber">3</span><span class="Punctuation">)</span> <span class="Comment"># works because B has been parsed completely here</span>

<span class="Identifier">main</span><span class="Punctuation">(</span><span class="Punctuation">)</span></pre></p>
<p><pre class="listing"><span class="Comment"># Module B</span>
<span class="Keyword">import</span> <span class="Identifier">A</span>  <span class="Comment"># A is not parsed here! Only the already known symbols</span>
          <span class="Comment"># of A are imported.</span>

<span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">A</span><span class="Operator">.</span><span class="Identifier">T1</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">A</span><span class="Operator">.</span><span class="Identifier">T1</span> <span class="Operator">=</span>
  <span class="Comment"># this works because the compiler has already</span>
  <span class="Comment"># added T1 to A's interface symbol table</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">x</span> <span class="Operator">+</span> <span class="DecNumber">1</span></pre></p>

<h2><a class="toc-backref" id="modules-import-statement" href="#modules-import-statement">Import statement</a></h2><p>After the <tt class="docutils literal"><span class="pre"><span class="Keyword">import</span></span></tt> keyword, a list of module names can follow or a single module name followed by an <tt class="docutils literal"><span class="pre"><span class="Keyword">except</span></span></tt> list to prevent some symbols from being imported:</p>
<p><pre class="listing"><span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">strutils</span> <span class="Keyword">except</span> <span class="Punctuation">`</span><span class="Operator">%</span><span class="Punctuation">`</span><span class="Punctuation">,</span> <span class="Identifier">toUpperAscii</span>

<span class="Comment"># doesn't work then:</span>
<span class="Identifier">echo</span> <span class="StringLit">&quot;$1&quot;</span> <span class="Operator">%</span> <span class="StringLit">&quot;abc&quot;</span><span class="Operator">.</span><span class="Identifier">toUpperAscii</span></pre></p>
<p>It is not checked that the <tt class="docutils literal"><span class="pre"><span class="Keyword">except</span></span></tt> list is really exported from the module. This feature allows us to compile against different versions of the module, even when one version does not export some of these identifiers.</p>
<p>The <tt class="docutils literal"><span class="pre"><span class="Keyword">import</span></span></tt> statement is only allowed at the top level.</p>
<p>String literals can be used for import/include statements. The compiler performs <a class="reference external" href="nimc.html#compiler-usage-commandminusline-switches">path substitution</a> when used.</p>

<h2><a class="toc-backref" id="modules-include-statement" href="#modules-include-statement">Include statement</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Keyword">include</span></span></tt> statement does something fundamentally different than importing a module: it merely includes the contents of a file. The <tt class="docutils literal"><span class="pre"><span class="Keyword">include</span></span></tt> statement is useful to split up a large module into several files:</p>
<p><pre class="listing"><span class="Keyword">include</span> <span class="Identifier">fileA</span><span class="Punctuation">,</span> <span class="Identifier">fileB</span><span class="Punctuation">,</span> <span class="Identifier">fileC</span></pre></p>
<p>The <tt class="docutils literal"><span class="pre"><span class="Keyword">include</span></span></tt> statement can be used outside the top level, as such:</p>
<p><pre class="listing"><span class="Comment"># Module A</span>
<span class="Identifier">echo</span> <span class="StringLit">&quot;Hello World!&quot;</span></pre></p>
<p><pre class="listing"><span class="Comment"># Module B</span>
<span class="Keyword">proc</span> <span class="Identifier">main</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">include</span> <span class="Identifier">A</span>

<span class="Identifier">main</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Comment"># =&gt; Hello World!</span></pre></p>

<h2><a class="toc-backref" id="modules-module-names-in-imports" href="#modules-module-names-in-imports">Module names in imports</a></h2><p>A module alias can be introduced via the <tt class="docutils literal"><span class="pre"><span class="Keyword">as</span></span></tt> keyword, after which the original module name is inaccessible:</p>
<p><pre class="listing"><span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">strutils</span> <span class="Keyword">as</span> <span class="Identifier">su</span><span class="Punctuation">,</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">sequtils</span> <span class="Keyword">as</span> <span class="Identifier">qu</span>

<span class="Identifier">echo</span> <span class="Identifier">su</span><span class="Operator">.</span><span class="Identifier">format</span><span class="Punctuation">(</span><span class="StringLit">&quot;$1&quot;</span><span class="Punctuation">,</span> <span class="StringLit">&quot;lalelu&quot;</span><span class="Punctuation">)</span></pre></p>
<p>The notations <tt class="docutils literal"><span class="pre"><span class="Identifier">path</span><span class="Operator">/</span><span class="Identifier">to</span><span class="Operator">/</span><span class="Identifier">module</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="StringLit">&quot;path/to/module&quot;</span></span></tt> can be used to refer to a module in subdirectories:</p>
<p><pre class="listing"><span class="Keyword">import</span> <span class="Identifier">lib</span><span class="Operator">/</span><span class="Identifier">pure</span><span class="Operator">/</span><span class="Identifier">os</span><span class="Punctuation">,</span> <span class="StringLit">&quot;lib/pure/times&quot;</span></pre></p>
<p>Note that the module name is still <tt class="docutils literal"><span class="pre"><span class="Identifier">strutils</span></span></tt> and not <tt class="docutils literal"><span class="pre"><span class="Identifier">lib</span><span class="Operator">/</span><span class="Identifier">pure</span><span class="Operator">/</span><span class="Identifier">strutils</span></span></tt>, thus one <strong>cannot</strong> do:</p>
<p><pre class="listing"><span class="Keyword">import</span> <span class="Identifier">lib</span><span class="Operator">/</span><span class="Identifier">pure</span><span class="Operator">/</span><span class="Identifier">strutils</span>
<span class="Identifier">echo</span> <span class="Identifier">lib</span><span class="Operator">/</span><span class="Identifier">pure</span><span class="Operator">/</span><span class="Identifier">strutils</span><span class="Operator">.</span><span class="Identifier">toUpperAscii</span><span class="Punctuation">(</span><span class="StringLit">&quot;abc&quot;</span><span class="Punctuation">)</span></pre></p>
<p>Likewise, the following does not make sense as the name is <tt class="docutils literal"><span class="pre"><span class="Identifier">strutils</span></span></tt> already:</p>
<p><pre class="listing"><span class="Keyword">import</span> <span class="Identifier">lib</span><span class="Operator">/</span><span class="Identifier">pure</span><span class="Operator">/</span><span class="Identifier">strutils</span> <span class="Keyword">as</span> <span class="Identifier">strutils</span></pre></p>

<h2><a class="toc-backref" id="modules-collective-imports-from-a-directory" href="#modules-collective-imports-from-a-directory">Collective imports from a directory</a></h2><p>The syntax <tt class="docutils literal"><span class="pre"><span class="Keyword">import</span> <span class="Identifier">dir</span> <span class="Operator">/</span> <span class="Punctuation">[</span><span class="Identifier">moduleA</span><span class="Punctuation">,</span> <span class="Identifier">moduleB</span><span class="Punctuation">]</span></span></tt> can be used to import multiple modules from the same directory.</p>
<p>Path names are syntactically either Nim identifiers or string literals. If the path name is not a valid Nim identifier it needs to be a string literal:</p>
<p><pre class="listing"><span class="Keyword">import</span> <span class="StringLit">&quot;gfx/3d/somemodule&quot;</span> <span class="Comment"># in quotes because '3d' is not a valid Nim identifier</span></pre></p>

<h2><a class="toc-backref" id="modules-pseudo-importslashinclude-paths" href="#modules-pseudo-importslashinclude-paths">Pseudo import/include paths</a></h2><p>A directory can also be a so-called &quot;pseudo directory&quot;. They can be used to avoid ambiguity when there are multiple modules with the same path.</p>
<p>There are two pseudo directories:</p>
<ol class="simple"><li><tt class="docutils literal"><span class="pre"><span class="Identifier">std</span></span></tt>: The <tt class="docutils literal"><span class="pre"><span class="Identifier">std</span></span></tt> pseudo directory is the abstract location of Nim's standard library. For example, the syntax <tt class="docutils literal"><span class="pre"><span class="Keyword">import</span> <span class="Identifier">std</span> <span class="Operator">/</span> <span class="Identifier">strutils</span></span></tt> is used to unambiguously refer to the standard library's <tt class="docutils literal"><span class="pre"><span class="Identifier">strutils</span></span></tt> module.</li>
<li><tt class="docutils literal"><span class="pre"><span class="Identifier">pkg</span></span></tt>: The <tt class="docutils literal"><span class="pre"><span class="Identifier">pkg</span></span></tt> pseudo directory is used to unambiguously refer to a Nimble package. However, for technical details that lie outside the scope of this document, its semantics are: <em>Use the search path to look for module name but ignore the standard library locations</em>. In other words, it is the opposite of <tt class="docutils literal"><span class="pre"><span class="Identifier">std</span></span></tt>.</li>
</ol>
<p>It is recommended and preferred but not currently enforced that all stdlib module imports include the std/ &quot;pseudo directory&quot; as part of the import name.</p>

<h2><a class="toc-backref" id="modules-from-import-statement" href="#modules-from-import-statement">From import statement</a></h2><p>After the <tt class="docutils literal"><span class="pre"><span class="Keyword">from</span></span></tt> keyword, a module name followed by an <tt class="docutils literal"><span class="pre"><span class="Keyword">import</span></span></tt> to list the symbols one likes to use without explicit full qualification:</p>
<p><pre class="listing"><span class="Keyword">from</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">strutils</span> <span class="Keyword">import</span> <span class="Punctuation">`</span><span class="Operator">%</span><span class="Punctuation">`</span>

<span class="Identifier">echo</span> <span class="StringLit">&quot;$1&quot;</span> <span class="Operator">%</span> <span class="StringLit">&quot;abc&quot;</span>
<span class="Comment"># always possible: full qualification:</span>
<span class="Identifier">echo</span> <span class="Identifier">strutils</span><span class="Operator">.</span><span class="Identifier">replace</span><span class="Punctuation">(</span><span class="StringLit">&quot;abc&quot;</span><span class="Punctuation">,</span> <span class="StringLit">&quot;a&quot;</span><span class="Punctuation">,</span> <span class="StringLit">&quot;z&quot;</span><span class="Punctuation">)</span></pre></p>
<p>It's also possible to use <tt class="docutils literal"><span class="pre"><span class="Keyword">from</span> <span class="Identifier">module</span> <span class="Keyword">import</span> <span class="Keyword">nil</span></span></tt> if one wants to import the module but wants to enforce fully qualified access to every symbol in <tt class="docutils literal"><span class="pre"><span class="Identifier">module</span></span></tt>.</p>

<h2><a class="toc-backref" id="modules-export-statement" href="#modules-export-statement">Export statement</a></h2><p>An <tt class="docutils literal"><span class="pre"><span class="Keyword">export</span></span></tt> statement can be used for symbol forwarding so that client modules don't need to import a module's dependencies:</p>
<p><pre class="listing"><span class="Comment"># module B</span>
<span class="Keyword">type</span> <span class="Identifier">MyObject</span><span class="Operator">*</span> <span class="Operator">=</span> <span class="Keyword">object</span></pre></p>
<p><pre class="listing"><span class="Comment"># module A</span>
<span class="Keyword">import</span> <span class="Identifier">B</span>
<span class="Keyword">export</span> <span class="Identifier">B</span><span class="Operator">.</span><span class="Identifier">MyObject</span>

<span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">$</span><span class="Punctuation">`</span><span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">MyObject</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">string</span> <span class="Operator">=</span> <span class="StringLit">&quot;my object&quot;</span></pre></p>
<p><pre class="listing"><span class="Comment"># module C</span>
<span class="Keyword">import</span> <span class="Identifier">A</span>

<span class="Comment"># B.MyObject has been imported implicitly here:</span>
<span class="Keyword">var</span> <span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">MyObject</span>
<span class="Identifier">echo</span> <span class="Operator">$</span><span class="Identifier">x</span></pre></p>
<p>When the exported symbol is another module, all of its definitions will be forwarded. One can use an <tt class="docutils literal"><span class="pre"><span class="Keyword">except</span></span></tt> list to exclude some of the symbols.</p>
<p>Notice that when exporting, one needs to specify only the module name:</p>
<p><pre class="listing"><span class="Keyword">import</span> <span class="Identifier">foo</span><span class="Operator">/</span><span class="Identifier">bar</span><span class="Operator">/</span><span class="Identifier">baz</span>
<span class="Keyword">export</span> <span class="Identifier">baz</span></pre></p>

<h2><a class="toc-backref" id="modules-scope-rules" href="#modules-scope-rules">Scope rules</a></h2><p>Identifiers are valid from the point of their declaration until the end of the block in which the declaration occurred. The range where the identifier is known is the scope of the identifier. The exact scope of an identifier depends on the way it was declared.</p>

<h3><a class="toc-backref" id="scope-rules-block-scope" href="#scope-rules-block-scope">Block scope</a></h3><p>The <em>scope</em> of a variable declared in the declaration part of a block is valid from the point of declaration until the end of the block. If a block contains a second block, in which the identifier is redeclared, then inside this block, the second declaration will be valid. Upon leaving the inner block, the first declaration is valid again. An identifier cannot be redefined in the same block, except if valid for procedure or iterator overloading purposes.</p>

<h3><a class="toc-backref" id="scope-rules-tuple-or-object-scope" href="#scope-rules-tuple-or-object-scope">Tuple or object scope</a></h3><p>The field identifiers inside a tuple or object definition are valid in the following places:</p>
<ul class="simple"><li>To the end of the tuple/object definition.</li>
<li>Field designators of a variable of the given tuple/object type.</li>
<li>In all descendant types of the object type.</li>
</ul>

<h3><a class="toc-backref" id="scope-rules-module-scope" href="#scope-rules-module-scope">Module scope</a></h3><p>All identifiers of a module are valid from the point of declaration until the end of the module. Identifiers from indirectly dependent modules are <em>not</em> available. The <span id="system_1">system</span> module is automatically imported in every module.</p>
<p>If a module imports the same identifier from two different modules, the identifier is considered ambiguous, which can be resolved in the following ways:</p>
<ul class="simple"><li>Qualifying the identifier as <tt class="docutils literal"><span class="pre"><span class="Identifier">module</span><span class="Operator">.</span><span class="Identifier">identifier</span></span></tt> resolves ambiguity between modules. (See below for the case that the module name itself is ambiguous.)</li>
<li>Calling the identifier as a routine makes overload resolution take place, which resolves ambiguity in the case that one overload matches stronger than the others.</li>
<li><p>Using the identifier in a context where the compiler can infer the type of the identifier resolves ambiguity in the case that one definition matches the type stronger than the others.</p>
<p><pre class="listing"><span class="Comment"># Module A</span>
<span class="Keyword">var</span> <span class="Identifier">x</span><span class="Operator">*:</span> <span class="Identifier">string</span>
<span class="Keyword">proc</span> <span class="Identifier">foo</span><span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;A: &quot;</span><span class="Punctuation">,</span> <span class="Identifier">a</span></pre></p>
<p><pre class="listing"><span class="Comment"># Module B</span>
<span class="Keyword">var</span> <span class="Identifier">x</span><span class="Operator">*:</span> <span class="Identifier">int</span>
<span class="Keyword">proc</span> <span class="Identifier">foo</span><span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;B: &quot;</span><span class="Punctuation">,</span> <span class="Identifier">b</span></pre></p>
<p><pre class="listing"><span class="Comment"># Module C</span>
<span class="Keyword">import</span> <span class="Identifier">A</span><span class="Punctuation">,</span> <span class="Identifier">B</span>

<span class="Identifier">foo</span><span class="Punctuation">(</span><span class="StringLit">&quot;abc&quot;</span><span class="Punctuation">)</span> <span class="Comment"># A: abc</span>
<span class="Identifier">foo</span><span class="Punctuation">(</span><span class="DecNumber">123</span><span class="Punctuation">)</span> <span class="Comment"># B: 123</span>
<span class="Keyword">let</span> <span class="Identifier">inferred</span><span class="Punctuation">:</span> <span class="Keyword">proc</span> <span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Identifier">foo</span>
<span class="Identifier">foo</span><span class="Punctuation">(</span><span class="StringLit">&quot;def&quot;</span><span class="Punctuation">)</span> <span class="Comment"># A: def</span>

<span class="Identifier">write</span><span class="Punctuation">(</span><span class="Identifier">stdout</span><span class="Punctuation">,</span> <span class="Identifier">x</span><span class="Punctuation">)</span> <span class="Comment"># error: x is ambiguous</span>
<span class="Identifier">write</span><span class="Punctuation">(</span><span class="Identifier">stdout</span><span class="Punctuation">,</span> <span class="Identifier">A</span><span class="Operator">.</span><span class="Identifier">x</span><span class="Punctuation">)</span> <span class="Comment"># no error: qualifier used</span>

<span class="Keyword">proc</span> <span class="Identifier">bar</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span> <span class="Identifier">a</span> <span class="Operator">+</span> <span class="DecNumber">1</span>
<span class="Identifier">assert</span> <span class="Identifier">bar</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span> <span class="Operator">==</span> <span class="Identifier">x</span> <span class="Operator">+</span> <span class="DecNumber">1</span> <span class="Comment"># no error: only A.x of type int matches</span>

<span class="Keyword">var</span> <span class="Identifier">x</span> <span class="Operator">=</span> <span class="DecNumber">4</span>
<span class="Identifier">write</span><span class="Punctuation">(</span><span class="Identifier">stdout</span><span class="Punctuation">,</span> <span class="Identifier">x</span><span class="Punctuation">)</span> <span class="Comment"># not ambiguous: uses the module C's x</span></pre></p>
</li>
</ul>
<p>Modules can share their name, however, when trying to qualify an identifier with the module name the compiler will fail with ambiguous identifier error. One can qualify the identifier by aliasing the module.</p>
<p><pre class="listing"><span class="Comment"># Module A/C</span>
<span class="Keyword">proc</span> <span class="Identifier">fb</span><span class="Operator">*</span> <span class="Operator">=</span> <span class="Identifier">echo</span> <span class="StringLit">&quot;fizz&quot;</span></pre></p>
<p><pre class="listing"><span class="Comment"># Module B/C</span>
<span class="Keyword">proc</span> <span class="Identifier">fb</span><span class="Operator">*</span> <span class="Operator">=</span> <span class="Identifier">echo</span> <span class="StringLit">&quot;buzz&quot;</span></pre></p>
<p><pre class="listing"><span class="Keyword">import</span> <span class="Identifier">A</span><span class="Operator">/</span><span class="Identifier">C</span>
<span class="Keyword">import</span> <span class="Identifier">B</span><span class="Operator">/</span><span class="Identifier">C</span>

<span class="Identifier">C</span><span class="Operator">.</span><span class="Identifier">fb</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Comment"># Error: ambiguous identifier: 'C'</span></pre></p>
<p><pre class="listing"><span class="Keyword">import</span> <span class="Identifier">A</span><span class="Operator">/</span><span class="Identifier">C</span> <span class="Keyword">as</span> <span class="Identifier">fizz</span>
<span class="Keyword">import</span> <span class="Identifier">B</span><span class="Operator">/</span><span class="Identifier">C</span>

<span class="Identifier">fizz</span><span class="Operator">.</span><span class="Identifier">fb</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Comment"># Works</span></pre></p>

<h2><a class="toc-backref" id="modules-packages" href="#modules-packages">Packages</a></h2><p>A collection of modules in a file tree with an <tt class="docutils literal"><span class="pre">identifier.nimble</span></tt> file in the root of the tree is called a Nimble package. A valid package name can only be a valid Nim identifier and thus its filename is <tt class="docutils literal"><span class="pre">identifier.nimble</span></tt> where <tt class="docutils literal"><span class="pre">identifier</span></tt> is the desired package name. A module without a <tt class="docutils literal"><span class="pre">.nimble</span></tt> file is assigned the package identifier: <tt class="docutils literal"><span class="pre"><span class="Identifier">unknown</span></span></tt>.</p>
<p>The distinction between packages allows diagnostic compiler messages to be scoped to the current project's package vs foreign packages.</p>

<h1><a class="toc-backref" id="compiler-messages" href="#compiler-messages">Compiler Messages</a></h1><p>The Nim compiler emits different kinds of messages: <span id="hint_1">hint</span>, <span id="warning_1">warning</span>, and <span id="error_1">error</span> messages. An <em>error</em> message is emitted if the compiler encounters any static error.</p>

<h1><a class="toc-backref" id="pragmas" href="#pragmas">Pragmas</a></h1><p>Pragmas are Nim's method to give the compiler additional information / commands without introducing a massive number of new keywords. Pragmas are processed on the fly during semantic checking. Pragmas are enclosed in the special <tt class="docutils literal"><span class="pre"><span class="Punctuation">{</span><span class="Operator">.</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Operator">.</span><span class="Punctuation">}</span></span></tt> curly brackets. Pragmas are also often used as a first implementation to play with a language feature before a nicer syntax to access the feature becomes available.</p>

<h2><a class="toc-backref" id="pragmas-deprecated-pragma" href="#pragmas-deprecated-pragma">deprecated pragma</a></h2><p>The deprecated pragma is used to mark a symbol as deprecated:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">deprecated</span><span class="Operator">.</span><span class="Punctuation">}</span>
<span class="Keyword">var</span> <span class="Identifier">x</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">deprecated</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span> <span class="Identifier">char</span></pre></p>
<p>This pragma can also take in an optional warning string to relay to developers.</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">thing</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">bool</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">deprecated</span><span class="Punctuation">:</span> <span class="StringLit">&quot;use thong instead&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>

<h2><a class="toc-backref" id="pragmas-compiletime-pragma" href="#pragmas-compiletime-pragma">compileTime pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">compileTime</span></span></tt> pragma is used to mark a proc or variable to be used only during compile-time execution. No code will be generated for it. Compile-time procs are useful as helpers for macros. Since version 0.12.0 of the language, a proc that uses <tt class="docutils literal"><span class="pre"><span class="Identifier">system</span><span class="Operator">.</span><span class="Identifier">NimNode</span></span></tt> within its parameter types is implicitly declared <tt class="docutils literal"><span class="pre"><span class="Identifier">compileTime</span></span></tt>:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">astHelper</span><span class="Punctuation">(</span><span class="Identifier">n</span><span class="Punctuation">:</span> <span class="Identifier">NimNode</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">NimNode</span> <span class="Operator">=</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">n</span></pre></p>
<p>Is the same as:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">astHelper</span><span class="Punctuation">(</span><span class="Identifier">n</span><span class="Punctuation">:</span> <span class="Identifier">NimNode</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">NimNode</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">compileTime</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">n</span></pre></p>
<p><tt class="docutils literal"><span class="pre"><span class="Identifier">compileTime</span></span></tt> variables are available at runtime too. This simplifies certain idioms where variables are filled at compile-time (for example, lookup tables) but accessed at runtime:</p>
<p><pre class="listing"><span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">macros</span>

<span class="Keyword">var</span> <span class="Identifier">nameToProc</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">compileTime</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span> <span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Punctuation">(</span><span class="Identifier">string</span><span class="Punctuation">,</span> <span class="Keyword">proc</span> <span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">string</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">nimcall</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">)</span><span class="Punctuation">]</span>

<span class="Keyword">macro</span> <span class="Identifier">registerProc</span><span class="Punctuation">(</span><span class="Identifier">p</span><span class="Punctuation">:</span> <span class="Identifier">untyped</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">untyped</span> <span class="Operator">=</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">newTree</span><span class="Punctuation">(</span><span class="Identifier">nnkStmtList</span><span class="Punctuation">,</span> <span class="Identifier">p</span><span class="Punctuation">)</span>
  
  <span class="Keyword">let</span> <span class="Identifier">procName</span> <span class="Operator">=</span> <span class="Identifier">p</span><span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">]</span>
  <span class="Keyword">let</span> <span class="Identifier">procNameAsStr</span> <span class="Operator">=</span> <span class="Operator">$</span><span class="Identifier">p</span><span class="Punctuation">[</span><span class="DecNumber">0</span><span class="Punctuation">]</span>
  <span class="Identifier">result</span><span class="Operator">.</span><span class="Identifier">add</span> <span class="Identifier">quote</span> <span class="Keyword">do</span><span class="Punctuation">:</span>
    <span class="Identifier">nameToProc</span><span class="Operator">.</span><span class="Identifier">add</span><span class="Punctuation">(</span><span class="Punctuation">(</span><span class="Punctuation">`</span><span class="Identifier">procNameAsStr</span><span class="Punctuation">`</span><span class="Punctuation">,</span> <span class="Punctuation">`</span><span class="Identifier">procName</span><span class="Punctuation">`</span><span class="Punctuation">)</span><span class="Punctuation">)</span>

<span class="Keyword">proc</span> <span class="Identifier">foo</span><span class="Punctuation">:</span> <span class="Identifier">string</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">registerProc</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="StringLit">&quot;foo&quot;</span>
<span class="Keyword">proc</span> <span class="Identifier">bar</span><span class="Punctuation">:</span> <span class="Identifier">string</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">registerProc</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="StringLit">&quot;bar&quot;</span>
<span class="Keyword">proc</span> <span class="Identifier">baz</span><span class="Punctuation">:</span> <span class="Identifier">string</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">registerProc</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="StringLit">&quot;baz&quot;</span>

<span class="Identifier">doAssert</span> <span class="Identifier">nameToProc</span><span class="Punctuation">[</span><span class="DecNumber">2</span><span class="Punctuation">]</span><span class="Punctuation">[</span><span class="DecNumber">1</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Operator">==</span> <span class="StringLit">&quot;baz&quot;</span></pre></p>

<h2><a class="toc-backref" id="pragmas-noreturn-pragma" href="#pragmas-noreturn-pragma">noreturn pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">noreturn</span></span></tt> pragma is used to mark a proc that never returns.</p>

<h2><a class="toc-backref" id="pragmas-acyclic-pragma" href="#pragmas-acyclic-pragma">acyclic pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">acyclic</span></span></tt> pragma can be used for object types to mark them as acyclic even though they seem to be cyclic. This is an <strong>optimization</strong> for the garbage collector to not consider objects of this type as part of a cycle:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">Node</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Identifier">NodeObj</span>
  <span class="Identifier">NodeObj</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">acyclic</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">object</span>
    <span class="Identifier">left</span><span class="Punctuation">,</span> <span class="Identifier">right</span><span class="Punctuation">:</span> <span class="Identifier">Node</span>
    <span class="Identifier">data</span><span class="Punctuation">:</span> <span class="Identifier">string</span></pre></p>
<p>Or if we directly use a ref object:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">Node</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">acyclic</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Keyword">object</span>
    <span class="Identifier">left</span><span class="Punctuation">,</span> <span class="Identifier">right</span><span class="Punctuation">:</span> <span class="Identifier">Node</span>
    <span class="Identifier">data</span><span class="Punctuation">:</span> <span class="Identifier">string</span></pre></p>
<p>In the example, a tree structure is declared with the <tt class="docutils literal"><span class="pre"><span class="Identifier">Node</span></span></tt> type. Note that the type definition is recursive and the GC has to assume that objects of this type may form a cyclic graph. The <tt class="docutils literal"><span class="pre"><span class="Identifier">acyclic</span></span></tt> pragma passes the information that this cannot happen to the GC. If the programmer uses the <tt class="docutils literal"><span class="pre"><span class="Identifier">acyclic</span></span></tt> pragma for data types that are in reality cyclic, this may result in memory leaks, but memory safety is preserved.</p>

<h2><a class="toc-backref" id="pragmas-final-pragma" href="#pragmas-final-pragma">final pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">final</span></span></tt> pragma can be used for an object type to specify that it cannot be inherited from. Note that inheritance is only available for objects that inherit from an existing object (via the <tt class="docutils literal"><span class="pre"><span class="Keyword">object</span> <span class="Keyword">of</span> <span class="Identifier">SuperType</span></span></tt> syntax) or that have been marked as <tt class="docutils literal"><span class="pre"><span class="Identifier">inheritable</span></span></tt>.</p>

<h2><a class="toc-backref" id="pragmas-shallow-pragma" href="#pragmas-shallow-pragma">shallow pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">shallow</span></span></tt> pragma affects the semantics of a type: The compiler is allowed to make a shallow copy. This can cause serious semantic issues and break memory safety! However, it can speed up assignments considerably, because the semantics of Nim require deep copying of sequences and strings. This can be expensive, especially if sequences are used to build a tree structure:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">NodeKind</span> <span class="Operator">=</span> <span class="Keyword">enum</span> <span class="Identifier">nkLeaf</span><span class="Punctuation">,</span> <span class="Identifier">nkInner</span>
  <span class="Identifier">Node</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">shallow</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">object</span>
    <span class="Keyword">case</span> <span class="Identifier">kind</span><span class="Punctuation">:</span> <span class="Identifier">NodeKind</span>
    <span class="Keyword">of</span> <span class="Identifier">nkLeaf</span><span class="Punctuation">:</span>
      <span class="Identifier">strVal</span><span class="Punctuation">:</span> <span class="Identifier">string</span>
    <span class="Keyword">of</span> <span class="Identifier">nkInner</span><span class="Punctuation">:</span>
      <span class="Identifier">children</span><span class="Punctuation">:</span> <span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">Node</span><span class="Punctuation">]</span></pre></p>

<h2><a class="toc-backref" id="pragmas-pure-pragma" href="#pragmas-pure-pragma">pure pragma</a></h2><p>An object type can be marked with the <tt class="docutils literal"><span class="pre"><span class="Identifier">pure</span></span></tt> pragma so that its type field which is used for runtime type identification is omitted. This used to be necessary for binary compatibility with other compiled languages.</p>
<p>An enum type can be marked as <tt class="docutils literal"><span class="pre"><span class="Identifier">pure</span></span></tt>. Then access of its fields always requires full qualification.</p>

<h2><a class="toc-backref" id="pragmas-asmnostackframe-pragma" href="#pragmas-asmnostackframe-pragma">asmNoStackFrame pragma</a></h2><p>A proc can be marked with the <tt class="docutils literal"><span class="pre"><span class="Identifier">asmNoStackFrame</span></span></tt> pragma to tell the compiler it should not generate a stack frame for the proc. There are also no exit statements like <tt class="docutils literal"><span class="pre"><span class="Keyword">return</span> <span class="Identifier">result</span><span class="Punctuation">;</span></span></tt> generated and the generated C function is declared as <tt class="docutils literal"><span class="pre"><span class="Identifier">__declspec</span><span class="Punctuation">(</span><span class="Identifier">naked</span><span class="Punctuation">)</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Identifier">__attribute__</span><span class="Punctuation">(</span><span class="Punctuation">(</span><span class="Identifier">naked</span><span class="Punctuation">)</span><span class="Punctuation">)</span></span></tt> (depending on the used C compiler).</p>
<p><strong>Note</strong>: This pragma should only be used by procs which consist solely of assembler statements.</p>

<h2><a class="toc-backref" id="pragmas-error-pragma" href="#pragmas-error-pragma">error pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">error</span></span></tt> pragma is used to make the compiler output an error message with the given content. The compilation does not necessarily abort after an error though.</p>
<p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">error</span></span></tt> pragma can also be used to annotate a symbol (like an iterator or proc). The <em>usage</em> of the symbol then triggers a static error. This is especially useful to rule out that some operation is valid due to overloading and type conversions:</p>
<p><pre class="listing"><span class="Comment">## check that underlying int values are compared and not the pointers:</span>
<span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Operator">==</span><span class="Punctuation">`</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Keyword">ptr</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">bool</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">error</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>

<h2><a class="toc-backref" id="pragmas-fatal-pragma" href="#pragmas-fatal-pragma">fatal pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">fatal</span></span></tt> pragma is used to make the compiler output an error message with the given content. In contrast to the <tt class="docutils literal"><span class="pre"><span class="Identifier">error</span></span></tt> pragma, the compilation is guaranteed to be aborted by this pragma. Example:</p>
<p><pre class="listing"><span class="Keyword">when</span> <span class="Keyword">not</span> <span class="Identifier">defined</span><span class="Punctuation">(</span><span class="Identifier">objc</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
  <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">fatal</span><span class="Punctuation">:</span> <span class="StringLit">&quot;Compile this program with the objc command!&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>

<h2><a class="toc-backref" id="pragmas-warning-pragma" href="#pragmas-warning-pragma">warning pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">warning</span></span></tt> pragma is used to make the compiler output a warning message with the given content. Compilation continues after the warning.</p>

<h2><a class="toc-backref" id="pragmas-hint-pragma" href="#pragmas-hint-pragma">hint pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">hint</span></span></tt> pragma is used to make the compiler output a hint message with the given content. Compilation continues after the hint.</p>

<h2><a class="toc-backref" id="pragmas-line-pragma" href="#pragmas-line-pragma">line pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">line</span></span></tt> pragma can be used to affect line information of the annotated statement, as seen in stack backtraces:</p>
<p><pre class="listing"><span class="Keyword">template</span> <span class="Identifier">myassert</span><span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">cond</span><span class="Punctuation">:</span> <span class="Identifier">untyped</span><span class="Punctuation">,</span> <span class="Identifier">msg</span> <span class="Operator">=</span> <span class="StringLit">&quot;&quot;</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">if</span> <span class="Keyword">not</span> <span class="Identifier">cond</span><span class="Punctuation">:</span>
    <span class="Comment"># change run-time line information of the 'raise' statement:</span>
    <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">line</span><span class="Punctuation">:</span> <span class="Identifier">instantiationInfo</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span>
      <span class="Keyword">raise</span> <span class="Identifier">newException</span><span class="Punctuation">(</span><span class="Identifier">AssertionDefect</span><span class="Punctuation">,</span> <span class="Identifier">msg</span><span class="Punctuation">)</span></pre></p>
<p>If the <tt class="docutils literal"><span class="pre"><span class="Identifier">line</span></span></tt> pragma is used with a parameter, the parameter needs to be a <tt class="docutils literal"><span class="pre"><span class="Keyword">tuple</span><span class="Punctuation">[</span><span class="Identifier">filename</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">,</span> <span class="Identifier">line</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">]</span></span></tt>. If it is used without a parameter, <tt class="docutils literal"><span class="pre"><span class="Identifier">system</span><span class="Operator">.</span><span class="Identifier">instantiationInfo</span><span class="Punctuation">(</span><span class="Punctuation">)</span></span></tt> is used.</p>

<h2><a class="toc-backref" id="pragmas-linearscanend-pragma" href="#pragmas-linearscanend-pragma">linearScanEnd pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">linearScanEnd</span></span></tt> pragma can be used to tell the compiler how to compile a Nim <span id="case_1">case</span> statement. Syntactically it has to be used as a statement:</p>
<p><pre class="listing"><span class="Keyword">case</span> <span class="Identifier">myInt</span>
<span class="Keyword">of</span> <span class="DecNumber">0</span><span class="Punctuation">:</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;most common case&quot;</span>
<span class="Keyword">of</span> <span class="DecNumber">1</span><span class="Punctuation">:</span>
  <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">linearScanEnd</span><span class="Operator">.</span><span class="Punctuation">}</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;second most common case&quot;</span>
<span class="Keyword">of</span> <span class="DecNumber">2</span><span class="Punctuation">:</span> <span class="Identifier">echo</span> <span class="StringLit">&quot;unlikely: use branch table&quot;</span>
<span class="Keyword">else</span><span class="Punctuation">:</span> <span class="Identifier">echo</span> <span class="StringLit">&quot;unlikely too: use branch table for &quot;</span><span class="Punctuation">,</span> <span class="Identifier">myInt</span></pre></p>
<p>In the example, the case branches <tt class="docutils literal"><span class="pre"><span class="DecNumber">0</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="DecNumber">1</span></span></tt> are much more common than the other cases. Therefore, the generated assembler code should test for these values first so that the CPU's branch predictor has a good chance to succeed (avoiding an expensive CPU pipeline stall). The other cases might be put into a jump table for O(1) overhead but at the cost of a (very likely) pipeline stall.</p>
<p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">linearScanEnd</span></span></tt> pragma should be put into the last branch that should be tested against via linear scanning. If put into the last branch of the whole <tt class="docutils literal"><span class="pre"><span class="Keyword">case</span></span></tt> statement, the whole <tt class="docutils literal"><span class="pre"><span class="Keyword">case</span></span></tt> statement uses linear scanning.</p>

<h2><a class="toc-backref" id="pragmas-computedgoto-pragma" href="#pragmas-computedgoto-pragma">computedGoto pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">computedGoto</span></span></tt> pragma can be used to tell the compiler how to compile a Nim <span id="case_2">case</span> in a <tt class="docutils literal"><span class="pre"><span class="Keyword">while</span> <span class="Identifier">true</span></span></tt> statement. Syntactically it has to be used as a statement inside the loop:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">MyEnum</span> <span class="Operator">=</span> <span class="Keyword">enum</span>
    <span class="Identifier">enumA</span><span class="Punctuation">,</span> <span class="Identifier">enumB</span><span class="Punctuation">,</span> <span class="Identifier">enumC</span><span class="Punctuation">,</span> <span class="Identifier">enumD</span><span class="Punctuation">,</span> <span class="Identifier">enumE</span>

<span class="Keyword">proc</span> <span class="Identifier">vm</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">var</span> <span class="Identifier">instructions</span><span class="Punctuation">:</span> <span class="Identifier">array</span><span class="Punctuation">[</span><span class="FloatNumber">0.</span><span class="Operator">.</span><span class="DecNumber">100</span><span class="Punctuation">,</span> <span class="Identifier">MyEnum</span><span class="Punctuation">]</span>
  <span class="Identifier">instructions</span><span class="Punctuation">[</span><span class="DecNumber">2</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Identifier">enumC</span>
  <span class="Identifier">instructions</span><span class="Punctuation">[</span><span class="DecNumber">3</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Identifier">enumD</span>
  <span class="Identifier">instructions</span><span class="Punctuation">[</span><span class="DecNumber">4</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Identifier">enumA</span>
  <span class="Identifier">instructions</span><span class="Punctuation">[</span><span class="DecNumber">5</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Identifier">enumD</span>
  <span class="Identifier">instructions</span><span class="Punctuation">[</span><span class="DecNumber">6</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Identifier">enumC</span>
  <span class="Identifier">instructions</span><span class="Punctuation">[</span><span class="DecNumber">7</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Identifier">enumA</span>
  <span class="Identifier">instructions</span><span class="Punctuation">[</span><span class="DecNumber">8</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Identifier">enumB</span>
  
  <span class="Identifier">instructions</span><span class="Punctuation">[</span><span class="DecNumber">12</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Identifier">enumE</span>
  <span class="Keyword">var</span> <span class="Identifier">pc</span> <span class="Operator">=</span> <span class="DecNumber">0</span>
  <span class="Keyword">while</span> <span class="Identifier">true</span><span class="Punctuation">:</span>
    <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">computedGoto</span><span class="Operator">.</span><span class="Punctuation">}</span>
    <span class="Keyword">let</span> <span class="Identifier">instr</span> <span class="Operator">=</span> <span class="Identifier">instructions</span><span class="Punctuation">[</span><span class="Identifier">pc</span><span class="Punctuation">]</span>
    <span class="Keyword">case</span> <span class="Identifier">instr</span>
    <span class="Keyword">of</span> <span class="Identifier">enumA</span><span class="Punctuation">:</span>
      <span class="Identifier">echo</span> <span class="StringLit">&quot;yeah A&quot;</span>
    <span class="Keyword">of</span> <span class="Identifier">enumC</span><span class="Punctuation">,</span> <span class="Identifier">enumD</span><span class="Punctuation">:</span>
      <span class="Identifier">echo</span> <span class="StringLit">&quot;yeah CD&quot;</span>
    <span class="Keyword">of</span> <span class="Identifier">enumB</span><span class="Punctuation">:</span>
      <span class="Identifier">echo</span> <span class="StringLit">&quot;yeah B&quot;</span>
    <span class="Keyword">of</span> <span class="Identifier">enumE</span><span class="Punctuation">:</span>
      <span class="Keyword">break</span>
    <span class="Identifier">inc</span><span class="Punctuation">(</span><span class="Identifier">pc</span><span class="Punctuation">)</span>

<span class="Identifier">vm</span><span class="Punctuation">(</span><span class="Punctuation">)</span></pre></p>
<p>As the example shows, <tt class="docutils literal"><span class="pre"><span class="Identifier">computedGoto</span></span></tt> is mostly useful for interpreters. If the underlying backend (C compiler) does not support the computed goto extension the pragma is simply ignored.</p>

<h2><a class="toc-backref" id="pragmas-immediate-pragma" href="#pragmas-immediate-pragma">immediate pragma</a></h2><p>The immediate pragma is obsolete. See <a class="reference internal" href="#templates-typed-vs-untyped-parameters">Typed vs untyped parameters</a>.</p>

<h2><a class="toc-backref" id="pragmas-redefine-pragma" href="#pragmas-redefine-pragma">redefine pragma</a></h2><p>Redefinition of template symbols with the same signature is allowed. This can be made explicit with the <tt class="docutils literal"><span class="pre"><span class="Identifier">redefine</span></span></tt> pragma:</p>
<p><pre class="listing"><span class="Keyword">template</span> <span class="Identifier">foo</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span> <span class="DecNumber">1</span>
<span class="Identifier">echo</span> <span class="Identifier">foo</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Comment"># 1</span>
<span class="Keyword">template</span> <span class="Identifier">foo</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">redefine</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="DecNumber">2</span>
<span class="Identifier">echo</span> <span class="Identifier">foo</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Comment"># 2</span>
<span class="Comment"># warning: implicit redefinition of template</span>
<span class="Keyword">template</span> <span class="Identifier">foo</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span> <span class="DecNumber">3</span></pre></p>
<p>This is mostly intended for macro generated code.</p>

<h2><a class="toc-backref" id="pragmas-compilation-option-pragmas" href="#pragmas-compilation-option-pragmas">compilation option pragmas</a></h2><p>The listed pragmas here can be used to override the code generation options for a proc/method/converter.</p>
<p>The implementation currently provides the following possible options (various others may be added later).</p>
<table border="1" class="docutils"><tr><th>pragma</th><th>allowed values</th><th>description</th></tr>
<tr><td>checks</td><td>on|off </td><td>Turns the code generation for all runtime checks on or off.</td></tr>
<tr><td>boundChecks</td><td>on|off </td><td>Turns the code generation for array bound checks on or off.</td></tr>
<tr><td>overflowChecks</td><td>on|off </td><td>Turns the code generation for over- or underflow checks on or off.</td></tr>
<tr><td>nilChecks</td><td>on|off </td><td>Turns the code generation for nil pointer checks on or off.</td></tr>
<tr><td>assertions</td><td>on|off </td><td>Turns the code generation for assertions on or off.</td></tr>
<tr><td>warnings</td><td>on|off </td><td>Turns the warning messages of the compiler on or off.</td></tr>
<tr><td>hints</td><td>on|off </td><td>Turns the hint messages of the compiler on or off.</td></tr>
<tr><td>optimization</td><td>none|speed|size </td><td>Optimize the code for speed or size, or disable optimization.</td></tr>
<tr><td>patterns</td><td>on|off </td><td>Turns the term rewriting templates/macros on or off.</td></tr>
<tr><td>callconv</td><td>cdecl|...</td><td>Specifies the default calling convention for all procedures (and procedure types) that follow.</td></tr>
</table><p>Example:</p>
<p><pre class="listing"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">checks</span><span class="Punctuation">:</span> <span class="Identifier">off</span><span class="Punctuation">,</span> <span class="Identifier">optimization</span><span class="Punctuation">:</span> <span class="Identifier">speed</span><span class="Operator">.</span><span class="Punctuation">}</span>
<span class="Comment"># compile without runtime checks and optimize for speed</span></pre></p>

<h2><a class="toc-backref" id="pragmas-push-and-pop-pragmas" href="#pragmas-push-and-pop-pragmas">push and pop pragmas</a></h2><p>The <span id="pushslashpop_1">push/pop</span> pragmas are very similar to the option directive, but are used to override the settings temporarily. Example:</p>
<p><pre class="listing"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">push</span> <span class="Identifier">checks</span><span class="Punctuation">:</span> <span class="Identifier">off</span><span class="Operator">.</span><span class="Punctuation">}</span>
<span class="Comment"># compile this section without runtime checks as it is</span>
<span class="Comment"># speed critical</span>
<span class="Comment"># ... some code ...</span>
<span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">pop</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Comment"># restore old settings</span></pre></p>
<p><span id="pushslashpop_2">push/pop</span> can switch on/off some standard library pragmas, example:</p>
<p><pre class="listing"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">push</span> <span class="Identifier">inline</span><span class="Operator">.</span><span class="Punctuation">}</span>
<span class="Keyword">proc</span> <span class="Identifier">thisIsInlined</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span> <span class="DecNumber">42</span>
<span class="Keyword">func</span> <span class="Identifier">willBeInlined</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">float</span> <span class="Operator">=</span> <span class="FloatNumber">42.0</span>
<span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">pop</span><span class="Operator">.</span><span class="Punctuation">}</span>
<span class="Keyword">proc</span> <span class="Identifier">notInlined</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span> <span class="DecNumber">9</span>

<span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">push</span> <span class="Identifier">discardable</span><span class="Punctuation">,</span> <span class="Identifier">boundChecks</span><span class="Punctuation">:</span> <span class="Identifier">off</span><span class="Punctuation">,</span> <span class="Identifier">compileTime</span><span class="Punctuation">,</span> <span class="Identifier">noSideEffect</span><span class="Punctuation">,</span> <span class="Identifier">experimental</span><span class="Operator">.</span><span class="Punctuation">}</span>
<span class="Keyword">template</span> <span class="Identifier">example</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">string</span> <span class="Operator">=</span> <span class="StringLit">&quot;https://nim-lang.org&quot;</span>
<span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">pop</span><span class="Operator">.</span><span class="Punctuation">}</span>

<span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">push</span> <span class="Identifier">deprecated</span><span class="Punctuation">,</span> <span class="Identifier">used</span><span class="Punctuation">,</span> <span class="Identifier">stackTrace</span><span class="Punctuation">:</span> <span class="Identifier">off</span><span class="Operator">.</span><span class="Punctuation">}</span>
<span class="Keyword">proc</span> <span class="Identifier">sample</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">bool</span> <span class="Operator">=</span> <span class="Identifier">true</span>
<span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">pop</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>
<p>For third party pragmas, it depends on its implementation but uses the same syntax.</p>

<h2><a class="toc-backref" id="pragmas-register-pragma" href="#pragmas-register-pragma">register pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">register</span></span></tt> pragma is for variables only. It declares the variable as <tt class="docutils literal"><span class="pre"><span class="Identifier">register</span></span></tt>, giving the compiler a hint that the variable should be placed in a hardware register for faster access. C compilers usually ignore this though and for good reasons: Often they do a better job without it anyway.</p>
<p>However, in highly specific cases (a dispatch loop of a bytecode interpreter for example) it may provide benefits.</p>

<h2><a class="toc-backref" id="pragmas-global-pragma" href="#pragmas-global-pragma">global pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">global</span></span></tt> pragma can be applied to a variable within a proc to instruct the compiler to store it in a global location and initialize it once at program startup.</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">isHexNumber</span><span class="Punctuation">(</span><span class="Identifier">s</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">bool</span> <span class="Operator">=</span>
  <span class="Keyword">var</span> <span class="Identifier">pattern</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">global</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="RawData">re&quot;[0-9a-fA-F]+&quot;</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">s</span><span class="Operator">.</span><span class="Identifier">match</span><span class="Punctuation">(</span><span class="Identifier">pattern</span><span class="Punctuation">)</span></pre></p>
<p>When used within a generic proc, a separate unique global variable will be created for each instantiation of the proc. The order of initialization of the created global variables within a module is not defined, but all of them will be initialized after any top-level variables in their originating module and before any variable in a module that imports it.</p>

<h2><a class="toc-backref" id="pragmas-disabling-certain-messages" href="#pragmas-disabling-certain-messages">Disabling certain messages</a></h2><p>Nim generates some warnings and hints that may annoy the user. A mechanism for disabling certain messages is provided: Each hint and warning message is associated with a symbol. This is the message's identifier, which can be used to enable or disable the message by putting it in brackets following the pragma:</p>
<p><pre class="listing"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">hint</span><span class="Punctuation">[</span><span class="Identifier">XDeclaredButNotUsed</span><span class="Punctuation">]</span><span class="Punctuation">:</span> <span class="Identifier">off</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Comment"># Turn off the hint about declared but not used symbols.</span></pre></p>
<p>This is often better than disabling all warnings at once.</p>

<h2><a class="toc-backref" id="pragmas-used-pragma" href="#pragmas-used-pragma">used pragma</a></h2><p>Nim produces a warning for symbols that are not exported and not used either. The <tt class="docutils literal"><span class="pre"><span class="Identifier">used</span></span></tt> pragma can be attached to a symbol to suppress this warning. This is particularly useful when the symbol was generated by a macro:</p>
<p><pre class="listing"><span class="Keyword">template</span> <span class="Identifier">implementArithOps</span><span class="Punctuation">(</span><span class="Identifier">T</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">proc</span> <span class="Identifier">echoAdd</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">used</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
    <span class="Identifier">echo</span> <span class="Identifier">a</span> <span class="Operator">+</span> <span class="Identifier">b</span>
  <span class="Keyword">proc</span> <span class="Identifier">echoSub</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">used</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
    <span class="Identifier">echo</span> <span class="Identifier">a</span> <span class="Operator">-</span> <span class="Identifier">b</span>

<span class="Comment"># no warning produced for the unused 'echoSub'</span>
<span class="Identifier">implementArithOps</span><span class="Punctuation">(</span><span class="Identifier">int</span><span class="Punctuation">)</span>
<span class="Identifier">echoAdd</span> <span class="DecNumber">3</span><span class="Punctuation">,</span> <span class="DecNumber">5</span></pre></p>
<p><tt class="docutils literal"><span class="pre"><span class="Identifier">used</span></span></tt> can also be used as a top-level statement to mark a module as &quot;used&quot;. This prevents the &quot;Unused import&quot; warning:</p>
<p><pre class="listing"><span class="Comment"># module: debughelper.nim</span>
<span class="Keyword">when</span> <span class="Identifier">defined</span><span class="Punctuation">(</span><span class="Identifier">nimHasUsed</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
  <span class="Comment"># 'import debughelper' is so useful for debugging</span>
  <span class="Comment"># that Nim shouldn't produce a warning for that import,</span>
  <span class="Comment"># even if currently unused:</span>
  <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">used</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>

<h2><a class="toc-backref" id="pragmas-experimental-pragma" href="#pragmas-experimental-pragma">experimental pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">experimental</span></span></tt> pragma enables experimental language features. Depending on the concrete feature, this means that the feature is either considered too unstable for an otherwise stable release or that the future of the feature is uncertain (it may be removed at any time). See the <a class="reference external" href="manual_experimental.html">experimental manual</a> for more details.</p>
<p>Example:</p>
<p><pre class="listing"><span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">threadpool</span>
<span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">experimental</span><span class="Punctuation">:</span> <span class="StringLit">&quot;parallel&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span>

<span class="Keyword">proc</span> <span class="Identifier">threadedEcho</span><span class="Punctuation">(</span><span class="Identifier">s</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">,</span> <span class="Identifier">i</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Identifier">echo</span><span class="Punctuation">(</span><span class="Identifier">s</span><span class="Punctuation">,</span> <span class="StringLit">&quot; &quot;</span><span class="Punctuation">,</span> <span class="Operator">$</span><span class="Identifier">i</span><span class="Punctuation">)</span>

<span class="Keyword">proc</span> <span class="Identifier">useParallel</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Identifier">parallel</span><span class="Punctuation">:</span>
    <span class="Keyword">for</span> <span class="Identifier">i</span> <span class="Keyword">in</span> <span class="FloatNumber">0.</span><span class="Operator">.</span><span class="DecNumber">4</span><span class="Punctuation">:</span>
      <span class="Identifier">spawn</span> <span class="Identifier">threadedEcho</span><span class="Punctuation">(</span><span class="StringLit">&quot;echo in parallel&quot;</span><span class="Punctuation">,</span> <span class="Identifier">i</span><span class="Punctuation">)</span>

<span class="Identifier">useParallel</span><span class="Punctuation">(</span><span class="Punctuation">)</span></pre></p>
<p>As a top-level statement, the experimental pragma enables a feature for the rest of the module it's enabled in. This is problematic for macro and generic instantiations that cross a module scope. Currently, these usages have to be put into a <tt class="docutils literal"><span class="pre"><span class="Operator">.</span><span class="Identifier">push</span><span class="Operator">/</span><span class="Identifier">pop</span></span></tt> environment:</p>
<p><pre class="listing"><span class="Comment"># client.nim</span>
<span class="Keyword">proc</span> <span class="Identifier">useParallel</span><span class="Operator">*</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">unused</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Comment"># use a generic T here to show the problem.</span>
  <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">push</span> <span class="Identifier">experimental</span><span class="Punctuation">:</span> <span class="StringLit">&quot;parallel&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span>
  <span class="Identifier">parallel</span><span class="Punctuation">:</span>
    <span class="Keyword">for</span> <span class="Identifier">i</span> <span class="Keyword">in</span> <span class="FloatNumber">0.</span><span class="Operator">.</span><span class="DecNumber">4</span><span class="Punctuation">:</span>
      <span class="Identifier">echo</span> <span class="StringLit">&quot;echo in parallel&quot;</span>
  
  <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">pop</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>
<p><pre class="listing"><span class="Keyword">import</span> <span class="Identifier">client</span>
<span class="Identifier">useParallel</span><span class="Punctuation">(</span><span class="DecNumber">1</span><span class="Punctuation">)</span></pre></p>

<h1><a class="toc-backref" id="implementation-specific-pragmas" href="#implementation-specific-pragmas">Implementation Specific Pragmas</a></h1><p>This section describes additional pragmas that the current Nim implementation supports but which should not be seen as part of the language specification.</p>

<h2><a class="toc-backref" id="implementation-specific-pragmas-bitsize-pragma" href="#implementation-specific-pragmas-bitsize-pragma">Bitsize pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">bitsize</span></span></tt> pragma is for object field members. It declares the field as a bitfield in C/C++.</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">mybitfield</span> <span class="Operator">=</span> <span class="Keyword">object</span>
    <span class="Identifier">flag</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">bitsize</span><span class="Punctuation">:</span><span class="FloatNumber">1.</span><span class="Punctuation">}</span><span class="Punctuation">:</span> <span class="Identifier">cuint</span></pre></p>
<p>generates:</p>
<p><pre class="listing"><span class="Keyword">struct</span> <span class="Identifier">mybitfield</span> <span class="Punctuation">{</span>
  <span class="Keyword">unsigned</span> <span class="Keyword">int</span> <span class="Identifier">flag</span><span class="Punctuation">:</span><span class="DecNumber">1</span><span class="Punctuation">;</span>
<span class="Punctuation">}</span><span class="Punctuation">;</span></pre></p>

<h2><a class="toc-backref" id="implementation-specific-pragmas-size-pragma" href="#implementation-specific-pragmas-size-pragma">size pragma</a></h2><p>Nim automatically determines the size of an enum. But when wrapping a C enum type, it needs to be of a specific size. The <tt class="docutils literal"><span class="pre"><span class="Identifier">size</span> <span class="Identifier">pragma</span></span></tt> allows specifying the size of the enum type.</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">EventType</span><span class="Operator">*</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">size</span><span class="Punctuation">:</span> <span class="Identifier">sizeof</span><span class="Punctuation">(</span><span class="Identifier">uint32</span><span class="Punctuation">)</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">enum</span>
    <span class="Identifier">QuitEvent</span><span class="Punctuation">,</span>
    <span class="Identifier">AppTerminating</span><span class="Punctuation">,</span>
    <span class="Identifier">AppLowMemory</span>

<span class="Identifier">doAssert</span> <span class="Identifier">sizeof</span><span class="Punctuation">(</span><span class="Identifier">EventType</span><span class="Punctuation">)</span> <span class="Operator">==</span> <span class="Identifier">sizeof</span><span class="Punctuation">(</span><span class="Identifier">uint32</span><span class="Punctuation">)</span></pre></p>
<p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">size</span> <span class="Identifier">pragma</span></span></tt> can also specify the size of an <tt class="docutils literal"><span class="pre"><span class="Identifier">importc</span></span></tt> incomplete object type so that one can get the size of it at compile time even if it was declared without fields.</p>
<p><pre class="listing">  <span class="Keyword">type</span>
    <span class="Identifier">AtomicFlag</span><span class="Operator">*</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importc</span><span class="Punctuation">:</span> <span class="StringLit">&quot;atomic_flag&quot;</span><span class="Punctuation">,</span> <span class="Identifier">header</span><span class="Punctuation">:</span> <span class="StringLit">&quot;&lt;stdatomic.h&gt;&quot;</span><span class="Punctuation">,</span> <span class="Identifier">size</span><span class="Punctuation">:</span> <span class="FloatNumber">1.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">object</span>
  
  <span class="Keyword">static</span><span class="Punctuation">:</span>
    <span class="Comment"># if AtomicFlag didn't have the size pragma, this code would result in a compile time error.</span>
    <span class="Identifier">echo</span> <span class="Identifier">sizeof</span><span class="Punctuation">(</span><span class="Identifier">AtomicFlag</span><span class="Punctuation">)</span></pre></p>
<p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">size</span> <span class="Identifier">pragma</span></span></tt> accepts only the values 1, 2, 4 or 8.</p>

<h2><a class="toc-backref" id="implementation-specific-pragmas-align-pragma" href="#implementation-specific-pragmas-align-pragma">Align pragma</a></h2><p>The <span id="align_1">align</span> pragma is for variables and object field members. It modifies the alignment requirement of the entity being declared. The argument must be a constant power of 2. Valid non-zero alignments that are weaker than other align pragmas on the same declaration are ignored. Alignments that are weaker than the alignment requirement of the type are ignored.</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">sseType</span> <span class="Operator">=</span> <span class="Keyword">object</span>
    <span class="Identifier">sseData</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">align</span><span class="Punctuation">(</span><span class="DecNumber">16</span><span class="Punctuation">)</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span> <span class="Identifier">array</span><span class="Punctuation">[</span><span class="DecNumber">4</span><span class="Punctuation">,</span> <span class="Identifier">float32</span><span class="Punctuation">]</span>
  
  <span class="Comment"># every object will be aligned to 128-byte boundary</span>
  <span class="Identifier">Data</span> <span class="Operator">=</span> <span class="Keyword">object</span>
    <span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">char</span>
    <span class="Identifier">cacheline</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">align</span><span class="Punctuation">(</span><span class="DecNumber">128</span><span class="Punctuation">)</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span> <span class="Identifier">array</span><span class="Punctuation">[</span><span class="DecNumber">128</span><span class="Punctuation">,</span> <span class="Identifier">char</span><span class="Punctuation">]</span> <span class="Comment"># over-aligned array of char,</span>

<span class="Keyword">proc</span> <span class="Identifier">main</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;sizeof(Data) = &quot;</span><span class="Punctuation">,</span> <span class="Identifier">sizeof</span><span class="Punctuation">(</span><span class="Identifier">Data</span><span class="Punctuation">)</span><span class="Punctuation">,</span> <span class="StringLit">&quot; (1 byte + 127 bytes padding + 128-byte array)&quot;</span>
  <span class="Comment"># output: sizeof(Data) = 256 (1 byte + 127 bytes padding + 128-byte array)</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;alignment of sseType is &quot;</span><span class="Punctuation">,</span> <span class="Identifier">alignof</span><span class="Punctuation">(</span><span class="Identifier">sseType</span><span class="Punctuation">)</span>
  <span class="Comment"># output: alignment of sseType is 16</span>
  <span class="Keyword">var</span> <span class="Identifier">d</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">align</span><span class="Punctuation">(</span><span class="DecNumber">2048</span><span class="Punctuation">)</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span> <span class="Identifier">Data</span> <span class="Comment"># this instance of data is aligned even stricter</span>

<span class="Identifier">main</span><span class="Punctuation">(</span><span class="Punctuation">)</span></pre></p>
<p>This pragma has no effect on the JS backend.</p>

<h2><a class="toc-backref" id="implementation-specific-pragmas-noalias-pragma" href="#implementation-specific-pragmas-noalias-pragma">Noalias pragma</a></h2><p>Since version 1.4 of the Nim compiler, there is a <tt class="docutils literal"><span class="pre"><span class="Operator">.</span><span class="Identifier">noalias</span></span></tt> annotation for variables and parameters. It is mapped directly to C/C++'s <tt class="docutils literal"><span class="pre"><span class="Keyword">restrict</span></span></tt> keyword and means that the underlying pointer is pointing to a unique location in memory, no other aliases to this location exist. It is <em>unchecked</em> that this alias restriction is followed. If the restriction is violated, the backend optimizer is free to miscompile the code. This is an <strong>unsafe</strong> language feature.</p>
<p>Ideally in later versions of the language, the restriction will be enforced at compile time. (This is also why the name <tt class="docutils literal"><span class="pre"><span class="Identifier">noalias</span></span></tt> was chosen instead of a more verbose name like <tt class="docutils literal"><span class="pre"><span class="Identifier">unsafeAssumeNoAlias</span></span></tt>.)</p>

<h2><a class="toc-backref" id="implementation-specific-pragmas-volatile-pragma" href="#implementation-specific-pragmas-volatile-pragma">Volatile pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">volatile</span></span></tt> pragma is for variables only. It declares the variable as <tt class="docutils literal"><span class="pre"><span class="Keyword">volatile</span></span></tt>, whatever that means in C/C++ (its semantics are not well-defined in C/C++).</p>
<p><strong>Note</strong>: This pragma will not exist for the LLVM backend.</p>

<h2><a class="toc-backref" id="implementation-specific-pragmas-nodecl-pragma" href="#implementation-specific-pragmas-nodecl-pragma">nodecl pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">nodecl</span></span></tt> pragma can be applied to almost any symbol (variable, proc, type, etc.) and is sometimes useful for interoperability with C: It tells Nim that it should not generate a declaration for the symbol in the C code. For example:</p>
<p><pre class="listing"><span class="Keyword">var</span>
  <span class="Identifier">EACCES</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importc</span><span class="Punctuation">,</span> <span class="Identifier">nodecl</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span> <span class="Identifier">cint</span> <span class="Comment"># pretend EACCES was a variable, as</span>
                                   <span class="Comment"># Nim does not know its value</span></pre></p>
<p>However, the <tt class="docutils literal"><span class="pre"><span class="Identifier">header</span></span></tt> pragma is often the better alternative.</p>
<p><strong>Note</strong>: This will not work for the LLVM backend.</p>

<h2><a class="toc-backref" id="implementation-specific-pragmas-header-pragma" href="#implementation-specific-pragmas-header-pragma">Header pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">header</span></span></tt> pragma is very similar to the <tt class="docutils literal"><span class="pre"><span class="Identifier">nodecl</span></span></tt> pragma: It can be applied to almost any symbol and specifies that it should not be declared and instead, the generated code should contain an <tt class="docutils literal"><span class="pre"><span class="Preprocessor">#include</span></span></tt>:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">PFile</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importc</span><span class="Punctuation">:</span> <span class="StringLit">&quot;FILE*&quot;</span><span class="Punctuation">,</span> <span class="Identifier">header</span><span class="Punctuation">:</span> <span class="StringLit">&quot;&lt;stdio.h&gt;&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">distinct</span> <span class="Identifier">pointer</span>
    <span class="Comment"># import C's FILE* type; Nim will treat it as a new pointer type</span></pre></p>
<p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">header</span></span></tt> pragma always expects a string constant. The string constant contains the header file: As usual for C, a system header file is enclosed in angle brackets: <tt class="docutils literal"><span class="pre"><span class="Operator">&lt;&gt;</span></span></tt>. If no angle brackets are given, Nim encloses the header file in <tt class="docutils literal"><span class="pre"><span class="StringLit">&quot;&quot;</span></span></tt> in the generated C code.</p>
<p><strong>Note</strong>: This will not work for the LLVM backend.</p>

<h2><a class="toc-backref" id="implementation-specific-pragmas-incompletestruct-pragma" href="#implementation-specific-pragmas-incompletestruct-pragma">IncompleteStruct pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">incompleteStruct</span></span></tt> pragma tells the compiler to not use the underlying C <tt class="docutils literal"><span class="pre"><span class="Keyword">struct</span></span></tt> in a <tt class="docutils literal"><span class="pre"><span class="Identifier">sizeof</span></span></tt> expression:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">DIR</span><span class="Operator">*</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importc</span><span class="Punctuation">:</span> <span class="StringLit">&quot;DIR&quot;</span><span class="Punctuation">,</span> <span class="Identifier">header</span><span class="Punctuation">:</span> <span class="StringLit">&quot;&lt;dirent.h&gt;&quot;</span><span class="Punctuation">,</span>
         <span class="Identifier">pure</span><span class="Punctuation">,</span> <span class="Identifier">incompleteStruct</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">object</span></pre></p>

<h2><a class="toc-backref" id="implementation-specific-pragmas-compile-pragma" href="#implementation-specific-pragmas-compile-pragma">Compile pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">compile</span></span></tt> pragma can be used to compile and link a C/C++ source file with the project:</p>
<p>This pragma can take three forms. The first is a simple file input:</p>
<p><pre class="listing"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">compile</span><span class="Punctuation">:</span> <span class="StringLit">&quot;myfile.cpp&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>
<p>The second form is a tuple where the second arg is the output name strutils formatter:</p>
<p><pre class="listing"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">compile</span><span class="Punctuation">:</span> <span class="Punctuation">(</span><span class="StringLit">&quot;file.c&quot;</span><span class="Punctuation">,</span> <span class="StringLit">&quot;$1.o&quot;</span><span class="Punctuation">)</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>
<p><strong>Note</strong>: Nim computes a SHA1 checksum and only recompiles the file if it has changed. One can use the <tt class="docutils literal"><span class="pre option">-f</span></tt> command-line option to force the recompilation of the file.</p>
<p>Since 1.4 the <tt class="docutils literal"><span class="pre"><span class="Identifier">compile</span></span></tt> pragma is also available with this syntax:</p>
<p><pre class="listing"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">compile</span><span class="Punctuation">(</span><span class="StringLit">&quot;myfile.cpp&quot;</span><span class="Punctuation">,</span> <span class="StringLit">&quot;--custom flags here&quot;</span><span class="Punctuation">)</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>
<p>As can be seen in the example, this new variant allows for custom flags that are passed to the C compiler when the file is recompiled.</p>

<h2><a class="toc-backref" id="implementation-specific-pragmas-link-pragma" href="#implementation-specific-pragmas-link-pragma">Link pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">link</span></span></tt> pragma can be used to link an additional file with the project:</p>
<p><pre class="listing"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">link</span><span class="Punctuation">:</span> <span class="StringLit">&quot;myfile.o&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>

<h2><a class="toc-backref" id="implementation-specific-pragmas-passc-pragma" href="#implementation-specific-pragmas-passc-pragma">passc pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">passc</span></span></tt> pragma can be used to pass additional parameters to the C compiler like one would use the command-line switch <tt class="docutils literal"><span class="pre option">--passc</span></tt>:</p>
<p><pre class="listing"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">passc</span><span class="Punctuation">:</span> <span class="StringLit">&quot;-Wall -Werror&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>
<p>Note that one can use <tt class="docutils literal"><span class="pre"><span class="Identifier">gorge</span></span></tt> from the <a class="reference external" href="system.html">system module</a> to embed parameters from an external command that will be executed during semantic analysis:</p>
<p><pre class="listing"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">passc</span><span class="Punctuation">:</span> <span class="Identifier">gorge</span><span class="Punctuation">(</span><span class="StringLit">&quot;pkg-config --cflags sdl&quot;</span><span class="Punctuation">)</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>

<h2><a class="toc-backref" id="implementation-specific-pragmas-localpassc-pragma" href="#implementation-specific-pragmas-localpassc-pragma">localPassC pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">localPassC</span></span></tt> pragma can be used to pass additional parameters to the C compiler, but only for the C/C++ file that is produced from the Nim module the pragma resides in:</p>
<p><pre class="listing"><span class="Comment"># Module A.nim</span>
<span class="Comment"># Produces: A.nim.cpp</span>
<span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">localPassC</span><span class="Punctuation">:</span> <span class="StringLit">&quot;-Wall -Werror&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Comment"># Passed when compiling A.nim.cpp</span></pre></p>

<h2><a class="toc-backref" id="implementation-specific-pragmas-passl-pragma" href="#implementation-specific-pragmas-passl-pragma">passl pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">passl</span></span></tt> pragma can be used to pass additional parameters to the linker like one would be using the command-line switch <tt class="docutils literal"><span class="pre option">--passl</span></tt>:</p>
<p><pre class="listing"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">passl</span><span class="Punctuation">:</span> <span class="StringLit">&quot;-lSDLmain -lSDL&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>
<p>Note that one can use <tt class="docutils literal"><span class="pre"><span class="Identifier">gorge</span></span></tt> from the <a class="reference external" href="system.html">system module</a> to embed parameters from an external command that will be executed during semantic analysis:</p>
<p><pre class="listing"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">passl</span><span class="Punctuation">:</span> <span class="Identifier">gorge</span><span class="Punctuation">(</span><span class="StringLit">&quot;pkg-config --libs sdl&quot;</span><span class="Punctuation">)</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>

<h2><a class="toc-backref" id="implementation-specific-pragmas-emit-pragma" href="#implementation-specific-pragmas-emit-pragma">Emit pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">emit</span></span></tt> pragma can be used to directly affect the output of the compiler's code generator. The code is then unportable to other code generators/backends. Its usage is highly discouraged! However, it can be extremely useful for interfacing with <span id="cplusplus_1">C++</span> or <span id="objective-c_1">Objective C</span> code.</p>
<p>Example:</p>
<p><pre class="listing"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">emit</span><span class="Punctuation">:</span> <span class="LongStringLit">&quot;&quot;&quot;
static int cvariable = 420;
&quot;&quot;&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span>

<span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">push</span> <span class="Identifier">stackTrace</span><span class="Punctuation">:</span><span class="Identifier">off</span><span class="Operator">.</span><span class="Punctuation">}</span>
<span class="Keyword">proc</span> <span class="Identifier">embedsC</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">var</span> <span class="Identifier">nimVar</span> <span class="Operator">=</span> <span class="DecNumber">89</span>
  <span class="Comment"># access Nim symbols within an emit section outside of string literals:</span>
  <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">emit</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="LongStringLit">&quot;&quot;&quot;fprintf(stdout, &quot;%d\n&quot;, cvariable + (int)&quot;&quot;&quot;</span><span class="Punctuation">,</span> <span class="Identifier">nimVar</span><span class="Punctuation">,</span> <span class="StringLit">&quot;);&quot;</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Punctuation">}</span>
<span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">pop</span><span class="Operator">.</span><span class="Punctuation">}</span>

<span class="Identifier">embedsC</span><span class="Punctuation">(</span><span class="Punctuation">)</span></pre></p>
<p><tt class="docutils literal"><span class="pre">nimbase.h</span></tt> defines <tt class="docutils literal"><span class="pre"><span class="Identifier">NIM_EXTERNC</span></span></tt> C macro that can be used for <tt class="docutils literal"><span class="pre"><span class="Keyword">extern</span> <span class="StringLit">&quot;C&quot;</span></span></tt> code to work with both <tt class="docutils literal"><span class="pre"><span class="program">nim</span> <span class="option">c</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="program">nim</span> <span class="option">cpp</span></span></tt>, e.g.:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">foobar</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importc</span><span class="Punctuation">:</span><span class="StringLit">&quot;$1&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span>
<span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">emit</span><span class="Punctuation">:</span> <span class="LongStringLit">&quot;&quot;&quot;
#include &lt;stdio.h&gt;
NIM_EXTERNC
void fun(){}
&quot;&quot;&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>
<div class="admonition admonition-info"><span class="admonition-info-text"><b>Note:</b></span>
For backward compatibility, if the argument to the <tt class="docutils literal"><span class="pre"><span class="Identifier">emit</span></span></tt> statement is a single string literal, Nim symbols can be referred to via backticks. This usage is however deprecated.</div>
<p>For a top-level emit statement, the section where in the generated C/C++ file the code should be emitted can be influenced via the prefixes <tt class="docutils literal"><span class="pre"><span class="LongComment">/*TYPESECTION*/</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="LongComment">/*VARSECTION*/</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="LongComment">/*INCLUDESECTION*/</span></span></tt>:</p>
<p><pre class="listing"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">emit</span><span class="Punctuation">:</span> <span class="LongStringLit">&quot;&quot;&quot;/*TYPESECTION*/
struct Vector3 {
public:
  Vector3(): x(5) {}
  Vector3(float x_): x(x_) {}
  float x;
};
&quot;&quot;&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span>

<span class="Keyword">type</span> <span class="Identifier">Vector3</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importcpp</span><span class="Punctuation">:</span> <span class="StringLit">&quot;Vector3&quot;</span><span class="Punctuation">,</span> <span class="Identifier">nodecl</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">object</span>
  <span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">cfloat</span>

<span class="Keyword">proc</span> <span class="Identifier">constructVector3</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">cfloat</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">Vector3</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importcpp</span><span class="Punctuation">:</span> <span class="StringLit">&quot;Vector3(@)&quot;</span><span class="Punctuation">,</span> <span class="Identifier">nodecl</span><span class="Punctuation">}</span></pre></p>

<h2><a class="toc-backref" id="implementation-specific-pragmas-importcpp-pragma" href="#implementation-specific-pragmas-importcpp-pragma">ImportCpp pragma</a></h2><p><strong>Note</strong>: <a class="reference external" href="https://github.com/nim-lang/c2nim/blob/master/doc/c2nim.rst">c2nim</a> can parse a large subset of C++ and knows about the <tt class="docutils literal"><span class="pre"><span class="Identifier">importcpp</span></span></tt> pragma pattern language. It is not necessary to know all the details described here.</p>
<p>Similar to the <a class="reference internal" href="#foreign-function-interface-importc-pragma">importc pragma</a> for C, the <tt class="docutils literal"><span class="pre"><span class="Identifier">importcpp</span></span></tt> pragma can be used to import <span id="cplusplus_2">C++</span> methods or C++ symbols in general. The generated code then uses the C++ method calling syntax: <tt class="docutils literal"><span class="pre"><span class="Identifier">obj</span><span class="Operator">-&gt;</span><span class="Identifier">method</span><span class="Punctuation">(</span><span class="Identifier">arg</span><span class="Punctuation">)</span></span></tt>. In combination with the <tt class="docutils literal"><span class="pre"><span class="Identifier">header</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">emit</span></span></tt> pragmas this allows <em>sloppy</em> interfacing with libraries written in C++:</p>
<p><pre class="listing"><span class="Comment"># Horrible example of how to interface with a C++ engine ... ;-)</span>

<span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">link</span><span class="Punctuation">:</span> <span class="StringLit">&quot;/usr/lib/libIrrlicht.so&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span>

<span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">emit</span><span class="Punctuation">:</span> <span class="LongStringLit">&quot;&quot;&quot;
using namespace irr;
using namespace core;
using namespace scene;
using namespace video;
using namespace io;
using namespace gui;
&quot;&quot;&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span>

<span class="Keyword">const</span>
  <span class="Identifier">irr</span> <span class="Operator">=</span> <span class="StringLit">&quot;&lt;irrlicht/irrlicht.h&gt;&quot;</span>

<span class="Keyword">type</span>
  <span class="Identifier">IrrlichtDeviceObj</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">header</span><span class="Punctuation">:</span> <span class="Identifier">irr</span><span class="Punctuation">,</span>
                      <span class="Identifier">importcpp</span><span class="Punctuation">:</span> <span class="StringLit">&quot;IrrlichtDevice&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">object</span>
  <span class="Identifier">IrrlichtDevice</span> <span class="Operator">=</span> <span class="Keyword">ptr</span> <span class="Identifier">IrrlichtDeviceObj</span>

<span class="Keyword">proc</span> <span class="Identifier">createDevice</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">IrrlichtDevice</span> <span class="Punctuation">{</span><span class="Operator">.</span>
  <span class="Identifier">header</span><span class="Punctuation">:</span> <span class="Identifier">irr</span><span class="Punctuation">,</span> <span class="Identifier">importcpp</span><span class="Punctuation">:</span> <span class="StringLit">&quot;createDevice(@)&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span>
<span class="Keyword">proc</span> <span class="Identifier">run</span><span class="Punctuation">(</span><span class="Identifier">device</span><span class="Punctuation">:</span> <span class="Identifier">IrrlichtDevice</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">bool</span> <span class="Punctuation">{</span><span class="Operator">.</span>
  <span class="Identifier">header</span><span class="Punctuation">:</span> <span class="Identifier">irr</span><span class="Punctuation">,</span> <span class="Identifier">importcpp</span><span class="Punctuation">:</span> <span class="StringLit">&quot;#.run(@)&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>
<p>The compiler needs to be told to generate C++ (command <tt class="docutils literal"><span class="pre option">cpp</span></tt>) for this to work. The conditional symbol <tt class="docutils literal"><span class="pre"><span class="Identifier">cpp</span></span></tt> is defined when the compiler emits C++ code.</p>

<h3><a class="toc-backref" id="importcpp-pragma-namespaces" href="#importcpp-pragma-namespaces">Namespaces</a></h3><p>The <em>sloppy interfacing</em> example uses <tt class="docutils literal"><span class="pre"><span class="Operator">.</span><span class="Identifier">emit</span></span></tt> to produce <tt class="docutils literal"><span class="pre"><span class="Identifier">using</span> <span class="Identifier">namespace</span></span></tt> declarations. It is usually much better to instead refer to the imported name via the <tt class="docutils literal"><span class="pre"><span class="Identifier">namespace</span><span class="Punctuation">:</span><span class="Punctuation">:</span><span class="Identifier">identifier</span></span></tt> notation:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">IrrlichtDeviceObj</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">header</span><span class="Punctuation">:</span> <span class="Identifier">irr</span><span class="Punctuation">,</span>
                      <span class="Identifier">importcpp</span><span class="Punctuation">:</span> <span class="StringLit">&quot;irr::IrrlichtDevice&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">object</span></pre></p>

<h3><a class="toc-backref" id="importcpp-pragma-importcpp-for-enums" href="#importcpp-pragma-importcpp-for-enums">Importcpp for enums</a></h3><p>When <tt class="docutils literal"><span class="pre"><span class="Identifier">importcpp</span></span></tt> is applied to an enum type the numerical enum values are annotated with the C++ enum type, like in this example: <tt class="docutils literal"><span class="pre"><span class="Punctuation">(</span><span class="Punctuation">(</span><span class="Identifier">TheCppEnum</span><span class="Punctuation">)</span><span class="Punctuation">(</span><span class="DecNumber">3</span><span class="Punctuation">)</span><span class="Punctuation">)</span></span></tt>. (This turned out to be the simplest way to implement it.)</p>

<h3><a class="toc-backref" id="importcpp-pragma-importcpp-for-procs" href="#importcpp-pragma-importcpp-for-procs">Importcpp for procs</a></h3><p>Note that the <tt class="docutils literal"><span class="pre"><span class="Identifier">importcpp</span></span></tt> variant for procs uses a somewhat cryptic pattern language for maximum flexibility:</p>
<ul class="simple"><li>A hash <tt class="docutils literal"><span class="pre">#</span></tt> symbol is replaced by the first or next argument.</li>
<li>A dot following the hash <tt class="docutils literal"><span class="pre">#.</span></tt> indicates that the call should use C++'s dot or arrow notation.</li>
<li>An at symbol <tt class="docutils literal"><span class="pre">@</span></tt> is replaced by the remaining arguments, separated by commas.</li>
</ul>
<p>For example:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">cppMethod</span><span class="Punctuation">(</span><span class="Identifier">this</span><span class="Punctuation">:</span> <span class="Identifier">CppObj</span><span class="Punctuation">,</span> <span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">,</span> <span class="Identifier">c</span><span class="Punctuation">:</span> <span class="Identifier">cint</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importcpp</span><span class="Punctuation">:</span> <span class="StringLit">&quot;#.CppMethod(@)&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span>
<span class="Keyword">var</span> <span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Keyword">ptr</span> <span class="Identifier">CppObj</span>
<span class="Identifier">cppMethod</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Punctuation">,</span> <span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="DecNumber">2</span><span class="Punctuation">,</span> <span class="DecNumber">3</span><span class="Punctuation">)</span></pre></p>
<p>Produces:</p>
<p><pre class="listing"><span class="Identifier">x</span><span class="Operator">-&gt;</span><span class="Identifier">CppMethod</span><span class="Punctuation">(</span><span class="DecNumber">1</span><span class="Punctuation">,</span> <span class="DecNumber">2</span><span class="Punctuation">,</span> <span class="DecNumber">3</span><span class="Punctuation">)</span></pre></p>
<p>As a special rule to keep backward compatibility with older versions of the <tt class="docutils literal"><span class="pre"><span class="Identifier">importcpp</span></span></tt> pragma, if there is no special pattern character (any of <tt class="docutils literal"><span class="pre"># ' @</span></tt>) at all, C++'s dot or arrow notation is assumed, so the above example can also be written as:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">cppMethod</span><span class="Punctuation">(</span><span class="Identifier">this</span><span class="Punctuation">:</span> <span class="Identifier">CppObj</span><span class="Punctuation">,</span> <span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">,</span> <span class="Identifier">c</span><span class="Punctuation">:</span> <span class="Identifier">cint</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importcpp</span><span class="Punctuation">:</span> <span class="StringLit">&quot;CppMethod&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>
<p>Note that the pattern language naturally also covers C++'s operator overloading capabilities:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">vectorAddition</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">Vec3</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">Vec3</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importcpp</span><span class="Punctuation">:</span> <span class="StringLit">&quot;# + #&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span>
<span class="Keyword">proc</span> <span class="Identifier">dictLookup</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">Dict</span><span class="Punctuation">,</span> <span class="Identifier">k</span><span class="Punctuation">:</span> <span class="Identifier">Key</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">Value</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importcpp</span><span class="Punctuation">:</span> <span class="StringLit">&quot;#[#]&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>
<ul class="simple"><li>An apostrophe <tt class="docutils literal"><span class="pre">'</span></tt> followed by an integer <tt class="docutils literal"><span class="pre">i</span></tt> in the range 0..9 is replaced by the i'th parameter <em>type</em>. The 0th position is the result type. This can be used to pass types to C++ function templates. Between the <tt class="docutils literal"><span class="pre">'</span></tt> and the digit, an asterisk can be used to get to the base type of the type. (So it &quot;takes away a star&quot; from the type; <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span><span class="Operator">*</span></span></tt> becomes <tt class="docutils literal"><span class="pre"><span class="Identifier">T</span></span></tt>.) Two stars can be used to get to the element type of the element type etc.</li>
</ul>
<p>For example:</p>
<p><pre class="listing"><span class="Keyword">type</span> <span class="Identifier">Input</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importcpp</span><span class="Punctuation">:</span> <span class="StringLit">&quot;System::Input&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">object</span>
<span class="Keyword">proc</span> <span class="Identifier">getSubsystem</span><span class="Operator">*</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Keyword">ptr</span> <span class="Identifier">T</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importcpp</span><span class="Punctuation">:</span> <span class="StringLit">&quot;SystemManager::getSubsystem&lt;'*0&gt;()&quot;</span><span class="Punctuation">,</span> <span class="Identifier">nodecl</span><span class="Operator">.</span><span class="Punctuation">}</span>

<span class="Keyword">let</span> <span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Keyword">ptr</span> <span class="Identifier">Input</span> <span class="Operator">=</span> <span class="Identifier">getSubsystem</span><span class="Punctuation">[</span><span class="Identifier">Input</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Punctuation">)</span></pre></p>
<p>Produces:</p>
<p><pre class="listing"><span class="Identifier">x</span> <span class="Operator">=</span> <span class="Identifier">SystemManager</span><span class="Punctuation">:</span><span class="Punctuation">:</span><span class="Identifier">getSubsystem</span><span class="Operator">&lt;</span><span class="Identifier">System</span><span class="Punctuation">:</span><span class="Punctuation">:</span><span class="Identifier">Input</span><span class="Operator">&gt;</span><span class="Punctuation">(</span><span class="Punctuation">)</span></pre></p>
<ul class="simple"><li><tt class="docutils literal"><span class="pre">#@</span></tt> is a special case to support a <tt class="docutils literal"><span class="pre"><span class="Identifier">cnew</span></span></tt> operation. It is required so that the call expression is inlined directly, without going through a temporary location. This is only required to circumvent a limitation of the current code generator.</li>
</ul>
<p>For example C++'s <tt class="docutils literal"><span class="pre"><span class="Keyword">new</span></span></tt> operator can be &quot;imported&quot; like this:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">cnew</span><span class="Operator">*</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Keyword">ptr</span> <span class="Identifier">T</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importcpp</span><span class="Punctuation">:</span> <span class="StringLit">&quot;(new '*0#@)&quot;</span><span class="Punctuation">,</span> <span class="Identifier">nodecl</span><span class="Operator">.</span><span class="Punctuation">}</span>

<span class="Comment"># constructor of 'Foo':</span>
<span class="Keyword">proc</span> <span class="Identifier">constructFoo</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">cint</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">Foo</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importcpp</span><span class="Punctuation">:</span> <span class="StringLit">&quot;Foo(@)&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span>

<span class="Keyword">let</span> <span class="Identifier">x</span> <span class="Operator">=</span> <span class="Identifier">cnew</span> <span class="Identifier">constructFoo</span><span class="Punctuation">(</span><span class="DecNumber">3</span><span class="Punctuation">,</span> <span class="DecNumber">4</span><span class="Punctuation">)</span></pre></p>
<p>Produces:</p>
<p><pre class="listing"><span class="Identifier">x</span> <span class="Operator">=</span> <span class="Identifier">new</span> <span class="Identifier">Foo</span><span class="Punctuation">(</span><span class="DecNumber">3</span><span class="Punctuation">,</span> <span class="DecNumber">4</span><span class="Punctuation">)</span></pre></p>
<p>However, depending on the use case <tt class="docutils literal"><span class="pre"><span class="Keyword">new</span> <span class="Identifier">Foo</span></span></tt> can also be wrapped like this instead:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">newFoo</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">cint</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Keyword">ptr</span> <span class="Identifier">Foo</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importcpp</span><span class="Punctuation">:</span> <span class="StringLit">&quot;new Foo(@)&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span>

<span class="Keyword">let</span> <span class="Identifier">x</span> <span class="Operator">=</span> <span class="Identifier">newFoo</span><span class="Punctuation">(</span><span class="DecNumber">3</span><span class="Punctuation">,</span> <span class="DecNumber">4</span><span class="Punctuation">)</span></pre></p>

<h3><a class="toc-backref" id="importcpp-pragma-wrapping-constructors" href="#importcpp-pragma-wrapping-constructors">Wrapping constructors</a></h3><p>Sometimes a C++ class has a private copy constructor and so code like <tt class="docutils literal"><span class="pre"><span class="Identifier">Class</span> <span class="Identifier">c</span> <span class="Operator">=</span> <span class="Identifier">Class</span><span class="Punctuation">(</span><span class="DecNumber">1</span><span class="Punctuation">,</span><span class="DecNumber">2</span><span class="Punctuation">)</span><span class="Punctuation">;</span></span></tt> must not be generated but instead <tt class="docutils literal"><span class="pre"><span class="Identifier">Class</span> <span class="Identifier">c</span><span class="Punctuation">(</span><span class="DecNumber">1</span><span class="Punctuation">,</span><span class="DecNumber">2</span><span class="Punctuation">)</span><span class="Punctuation">;</span></span></tt>. For this purpose the Nim proc that wraps a C++ constructor needs to be annotated with the <span id="constructor_1">constructor</span> pragma. This pragma also helps to generate faster C++ code since construction then doesn't invoke the copy constructor:</p>
<p><pre class="listing"><span class="Comment"># a better constructor of 'Foo':</span>
<span class="Keyword">proc</span> <span class="Identifier">constructFoo</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">cint</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">Foo</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importcpp</span><span class="Punctuation">:</span> <span class="StringLit">&quot;Foo(@)&quot;</span><span class="Punctuation">,</span> <span class="Identifier">constructor</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>

<h3><a class="toc-backref" id="importcpp-pragma-wrapping-destructors" href="#importcpp-pragma-wrapping-destructors">Wrapping destructors</a></h3><p>Since Nim generates C++ directly, any destructor is called implicitly by the C++ compiler at the scope exits. This means that often one can get away with not wrapping the destructor at all! However, when it needs to be invoked explicitly, it needs to be wrapped. The pattern language provides everything that is required:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">destroyFoo</span><span class="Punctuation">(</span><span class="Identifier">this</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">Foo</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importcpp</span><span class="Punctuation">:</span> <span class="StringLit">&quot;#.~Foo()&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>

<h3><a class="toc-backref" id="importcpp-pragma-importcpp-for-objects" href="#importcpp-pragma-importcpp-for-objects">Importcpp for objects</a></h3><p>Generic <tt class="docutils literal"><span class="pre"><span class="Identifier">importcpp</span></span></tt>'ed objects are mapped to C++ templates. This means that one can import C++'s templates rather easily without the need for a pattern language for object types:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">StdMap</span><span class="Punctuation">[</span><span class="Identifier">K</span><span class="Punctuation">,</span> <span class="Identifier">V</span><span class="Punctuation">]</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importcpp</span><span class="Punctuation">:</span> <span class="StringLit">&quot;std::map&quot;</span><span class="Punctuation">,</span> <span class="Identifier">header</span><span class="Punctuation">:</span> <span class="StringLit">&quot;&lt;map&gt;&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">object</span>
<span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Operator">=</span><span class="Punctuation">`</span><span class="Punctuation">[</span><span class="Identifier">K</span><span class="Punctuation">,</span> <span class="Identifier">V</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">this</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">StdMap</span><span class="Punctuation">[</span><span class="Identifier">K</span><span class="Punctuation">,</span> <span class="Identifier">V</span><span class="Punctuation">]</span><span class="Punctuation">;</span> <span class="Identifier">key</span><span class="Punctuation">:</span> <span class="Identifier">K</span><span class="Punctuation">;</span> <span class="Identifier">val</span><span class="Punctuation">:</span> <span class="Identifier">V</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span>
  <span class="Identifier">importcpp</span><span class="Punctuation">:</span> <span class="StringLit">&quot;#[#] = #&quot;</span><span class="Punctuation">,</span> <span class="Identifier">header</span><span class="Punctuation">:</span> <span class="StringLit">&quot;&lt;map&gt;&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span>

<span class="Keyword">var</span> <span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">StdMap</span><span class="Punctuation">[</span><span class="Identifier">cint</span><span class="Punctuation">,</span> <span class="Identifier">cdouble</span><span class="Punctuation">]</span>
<span class="Identifier">x</span><span class="Punctuation">[</span><span class="DecNumber">6</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="FloatNumber">91.4</span></pre></p>
<p>Produces:</p>
<p><pre class="listing"><span class="Identifier">std</span><span class="Punctuation">:</span><span class="Punctuation">:</span><span class="Identifier">map</span><span class="Operator">&lt;</span><span class="Keyword">int</span><span class="Punctuation">,</span> <span class="Keyword">double</span><span class="Operator">&gt;</span> <span class="Identifier">x</span><span class="Punctuation">;</span>
<span class="Identifier">x</span><span class="Punctuation">[</span><span class="DecNumber">6</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="FloatNumber">91.4</span><span class="Punctuation">;</span></pre></p>
<ul class="simple"><li><p>If more precise control is needed, the apostrophe <tt class="docutils literal"><span class="pre"><span class="CharLit">'</span></span></tt> can be used in the supplied pattern to denote the concrete type parameters of the generic type. See the usage of the apostrophe operator in proc patterns for more details.</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">VectorIterator</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importcpp</span><span class="Punctuation">:</span> <span class="StringLit">&quot;std::vector&lt;'0&gt;::iterator&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">object</span>

<span class="Keyword">var</span> <span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">VectorIterator</span><span class="Punctuation">[</span><span class="Identifier">cint</span><span class="Punctuation">]</span></pre></p>
<p>Produces:</p>
<p><pre class="listing">
<span class="Identifier">std</span><span class="Punctuation">:</span><span class="Punctuation">:</span><span class="Identifier">vector</span><span class="Operator">&lt;</span><span class="Keyword">int</span><span class="Operator">&gt;::</span><span class="Identifier">iterator</span> <span class="Identifier">x</span><span class="Punctuation">;</span></pre></p>
</li>
</ul>

<h2><a class="toc-backref" id="implementation-specific-pragmas-importjs-pragma" href="#implementation-specific-pragmas-importjs-pragma">ImportJs pragma</a></h2><p>Similar to the <a class="reference internal" href="#implementation-specific-pragmas-importcpp-pragma">importcpp pragma</a> for C++, the <tt class="docutils literal"><span class="pre"><span class="Identifier">importjs</span></span></tt> pragma can be used to import Javascript methods or symbols in general. The generated code then uses the Javascript method calling syntax: <tt class="docutils literal"><span class="pre">obj.method(arg)</span></tt>.</p>

<h2><a class="toc-backref" id="implementation-specific-pragmas-importobjc-pragma" href="#implementation-specific-pragmas-importobjc-pragma">ImportObjC pragma</a></h2><p>Similar to the <a class="reference internal" href="#foreign-function-interface-importc-pragma">importc pragma</a> for C, the <tt class="docutils literal"><span class="pre"><span class="Identifier">importobjc</span></span></tt> pragma can be used to import <span id="objective-c_2">Objective C</span> methods. The generated code then uses the Objective C method calling syntax: <tt class="docutils literal"><span class="pre">[obj method param1: arg]</span></tt>. In addition with the <tt class="docutils literal"><span class="pre"><span class="Identifier">header</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">emit</span></span></tt> pragmas this allows <em>sloppy</em> interfacing with libraries written in Objective C:</p>
<p><pre class="listing"><span class="Comment"># horrible example of how to interface with GNUStep ...</span>

<span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">passl</span><span class="Punctuation">:</span> <span class="StringLit">&quot;-lobjc&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span>
<span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">emit</span><span class="Punctuation">:</span> <span class="LongStringLit">&quot;&quot;&quot;
#include &lt;objc/Object.h&gt;
@interface Greeter:Object
{
}

- (void)greet:(long)x y:(long)dummy;
@end

#include &lt;stdio.h&gt;
@implementation Greeter

- (void)greet:(long)x y:(long)dummy
{
  printf(&quot;Hello, World!\n&quot;);
}
@end

#include &lt;stdlib.h&gt;
&quot;&quot;&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span>

<span class="Keyword">type</span>
  <span class="Identifier">Id</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importc</span><span class="Punctuation">:</span> <span class="StringLit">&quot;id&quot;</span><span class="Punctuation">,</span> <span class="Identifier">header</span><span class="Punctuation">:</span> <span class="StringLit">&quot;&lt;objc/Object.h&gt;&quot;</span><span class="Punctuation">,</span> <span class="Identifier">final</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">distinct</span> <span class="Identifier">int</span>

<span class="Keyword">proc</span> <span class="Identifier">newGreeter</span><span class="Punctuation">:</span> <span class="Identifier">Id</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importobjc</span><span class="Punctuation">:</span> <span class="StringLit">&quot;Greeter new&quot;</span><span class="Punctuation">,</span> <span class="Identifier">nodecl</span><span class="Operator">.</span><span class="Punctuation">}</span>
<span class="Keyword">proc</span> <span class="Identifier">greet</span><span class="Punctuation">(</span><span class="Identifier">self</span><span class="Punctuation">:</span> <span class="Identifier">Id</span><span class="Punctuation">,</span> <span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importobjc</span><span class="Punctuation">:</span> <span class="StringLit">&quot;greet&quot;</span><span class="Punctuation">,</span> <span class="Identifier">nodecl</span><span class="Operator">.</span><span class="Punctuation">}</span>
<span class="Keyword">proc</span> <span class="Identifier">free</span><span class="Punctuation">(</span><span class="Identifier">self</span><span class="Punctuation">:</span> <span class="Identifier">Id</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importobjc</span><span class="Punctuation">:</span> <span class="StringLit">&quot;free&quot;</span><span class="Punctuation">,</span> <span class="Identifier">nodecl</span><span class="Operator">.</span><span class="Punctuation">}</span>

<span class="Keyword">var</span> <span class="Identifier">g</span> <span class="Operator">=</span> <span class="Identifier">newGreeter</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
<span class="Identifier">g</span><span class="Operator">.</span><span class="Identifier">greet</span><span class="Punctuation">(</span><span class="DecNumber">12</span><span class="Punctuation">,</span> <span class="DecNumber">34</span><span class="Punctuation">)</span>
<span class="Identifier">g</span><span class="Operator">.</span><span class="Identifier">free</span><span class="Punctuation">(</span><span class="Punctuation">)</span></pre></p>
<p>The compiler needs to be told to generate Objective C (command <tt class="docutils literal"><span class="pre option">objc</span></tt>) for this to work. The conditional symbol <tt class="docutils literal"><span class="pre">objc</span></tt> is defined when the compiler emits Objective C code.</p>

<h2><a class="toc-backref" id="implementation-specific-pragmas-codegendecl-pragma" href="#implementation-specific-pragmas-codegendecl-pragma">CodegenDecl pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">codegenDecl</span></span></tt> pragma can be used to directly influence Nim's code generator. It receives a format string that determines how the variable, proc or object type is declared in the generated code.</p>
<p>For variables, $1 in the format string represents the type of the variable, $2 is the name of the variable, and each appearance of $# represents $1/$2 respectively according to its position.</p>
<p>The following Nim code:</p>
<p><pre class="listing"><span class="Keyword">var</span>
  <span class="Identifier">a</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">codegenDecl</span><span class="Punctuation">:</span> <span class="StringLit">&quot;$# progmem $#&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span> <span class="Identifier">int</span></pre></p>
<p>will generate this C code:</p>
<p><pre class="listing"><span class="Keyword">int</span> <span class="Identifier">progmem</span> <span class="Identifier">a</span></pre></p>
<p>For procedures, $1 is the return type of the procedure, $2 is the name of the procedure, $3 is the parameter list, and each appearance of $# represents $1/$2/$3 respectively according to its position.</p>
<p>The following nim code:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">myinterrupt</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">codegenDecl</span><span class="Punctuation">:</span> <span class="StringLit">&quot;__interrupt $# $#$#&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
  <span class="Identifier">echo</span> <span class="StringLit">&quot;realistic interrupt handler&quot;</span></pre></p>
<p>will generate this code:</p>
<p><pre class="listing"><span class="Identifier">__interrupt</span> <span class="Keyword">void</span> <span class="Identifier">myinterrupt</span><span class="Punctuation">(</span><span class="Punctuation">)</span></pre></p>
<p>For object types, the $1 represents the name of the object type, $2 is the list of fields and $3 is the base type.</p>
<p><pre class="listing">
<span class="Keyword">const</span> <span class="Identifier">strTemplate</span> <span class="Operator">=</span> <span class="LongStringLit">&quot;&quot;&quot;
  struct $1 {
    $2
  };
&quot;&quot;&quot;</span>
<span class="Keyword">type</span> <span class="Identifier">Foo</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">codegenDecl</span><span class="Punctuation">:</span><span class="Identifier">strTemplate</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">object</span>
  <span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">int</span></pre></p>
<p>will generate this code:</p>
<p><pre class="listing"><span class="Keyword">struct</span> <span class="Identifier">Foo</span> <span class="Punctuation">{</span>
  <span class="Identifier">NI</span> <span class="Identifier">a</span><span class="Punctuation">;</span>
  <span class="Identifier">NI</span> <span class="Identifier">b</span><span class="Punctuation">;</span>
<span class="Punctuation">}</span><span class="Punctuation">;</span></pre></p>

<h2><a class="toc-backref" id="implementation-specific-pragmas-nimcppnonpod-pragma" href="#implementation-specific-pragmas-nimcppnonpod-pragma"><tt class="docutils literal"><span class="pre"><span class="Identifier">cppNonPod</span></span></tt> pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">cppNonPod</span></span></tt> pragma should be used for non-POD <tt class="docutils literal"><span class="pre"><span class="Identifier">importcpp</span></span></tt> types so that they work properly (in particular regarding constructor and destructor) for <tt class="docutils literal"><span class="pre"><span class="Identifier">threadvar</span></span></tt> variables. This requires <tt class="docutils literal"><span class="pre option">--tlsEmulation:off</span></tt>.</p>
<p><pre class="listing"><span class="Keyword">type</span> <span class="Identifier">Foo</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">cppNonPod</span><span class="Punctuation">,</span> <span class="Identifier">importcpp</span><span class="Punctuation">,</span> <span class="Identifier">header</span><span class="Punctuation">:</span> <span class="StringLit">&quot;funs.h&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">object</span>
  <span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">cint</span>
<span class="Keyword">proc</span> <span class="Identifier">main</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Operator">=</span>
  <span class="Keyword">var</span> <span class="Identifier">a</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">threadvar</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span> <span class="Identifier">Foo</span></pre></p>

<h2><a class="toc-backref" id="implementation-specific-pragmas-compileminustime-define-pragmas" href="#implementation-specific-pragmas-compileminustime-define-pragmas">compile-time define pragmas</a></h2><p>The pragmas listed here can be used to optionally accept values from the <tt class="docutils literal"><span class="pre option">-d/--define</span></tt> option at compile time.</p>
<p>The implementation currently provides the following possible options (various others may be added later).</p>
<table border="1" class="docutils"><tr><th>pragma</th><th>description</th></tr>
<tr><td><span id="intdefine_1">intdefine</span></td><td>Reads in a build-time define as an integer</td></tr>
<tr><td><span id="strdefine_1">strdefine</span></td><td>Reads in a build-time define as a string</td></tr>
<tr><td><span id="booldefine_1">booldefine</span></td><td>Reads in a build-time define as a bool</td></tr>
</table><p><pre class="listing"><span class="Keyword">const</span> <span class="Identifier">FooBar</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">intdefine</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span> <span class="DecNumber">5</span>
<span class="Identifier">echo</span> <span class="Identifier">FooBar</span></pre></p>
<p><pre class="listing"><span class="program">nim</span> <span class="option">c</span> <span class="option">-d:FooBar=42</span> <span class="Identifier">foobar.nim</span></pre></p>
<p>In the above example, providing the <tt class="docutils literal"><span class="pre option">-d</span></tt> flag causes the symbol <tt class="docutils literal"><span class="pre"><span class="Identifier">FooBar</span></span></tt> to be overwritten at compile-time, printing out 42. If the <tt class="docutils literal"><span class="pre option">-d:FooBar=42</span></tt> were to be omitted, the default value of 5 would be used. To see if a value was provided, <tt class="docutils literal"><span class="pre"><span class="Identifier">defined</span><span class="Punctuation">(</span><span class="Identifier">FooBar</span><span class="Punctuation">)</span></span></tt> can be used.</p>
<p>The syntax <tt class="docutils literal"><span class="pre option">-d:flag</span></tt> is actually just a shortcut for <tt class="docutils literal"><span class="pre option">-d:flag=true</span></tt>.</p>
<p>These pragmas also accept an optional string argument for qualified define names.</p>
<p><pre class="listing"><span class="Keyword">const</span> <span class="Identifier">FooBar</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">intdefine</span><span class="Punctuation">:</span> <span class="StringLit">&quot;package.FooBar&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span> <span class="DecNumber">5</span>
<span class="Identifier">echo</span> <span class="Identifier">FooBar</span></pre></p>
<p><pre class="listing"><span class="program">nim</span> <span class="option">c</span> <span class="Identifier">-d:package.FooBar=42</span> <span class="Identifier">foobar.nim</span></pre></p>
<p>This helps disambiguate define names in different packages.</p>
<p>See also the <a class="reference external" href="manual_experimental.html#generic-nimdefine-pragma">generic `define` pragma</a> for a version of these pragmas that detects the type of the define based on the constant value.</p>

<h1><a class="toc-backref" id="userminusdefined-pragmas" href="#userminusdefined-pragmas">User-defined pragmas</a></h1>
<h2><a class="toc-backref" id="userminusdefined-pragmas-pragma-pragma" href="#userminusdefined-pragmas-pragma-pragma">pragma pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">pragma</span></span></tt> pragma can be used to declare user-defined pragmas. This is useful because Nim's templates and macros do not affect pragmas. User-defined pragmas are in a different module-wide scope than all other symbols. They cannot be imported from a module.</p>
<p>Example:</p>
<p><pre class="listing"><span class="Keyword">when</span> <span class="Identifier">appType</span> <span class="Operator">==</span> <span class="StringLit">&quot;lib&quot;</span><span class="Punctuation">:</span>
  <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">pragma</span><span class="Punctuation">:</span> <span class="Identifier">rtl</span><span class="Punctuation">,</span> <span class="Identifier">exportc</span><span class="Punctuation">,</span> <span class="Identifier">dynlib</span><span class="Punctuation">,</span> <span class="Identifier">cdecl</span><span class="Operator">.</span><span class="Punctuation">}</span>
<span class="Keyword">else</span><span class="Punctuation">:</span>
  <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">pragma</span><span class="Punctuation">:</span> <span class="Identifier">rtl</span><span class="Punctuation">,</span> <span class="Identifier">importc</span><span class="Punctuation">,</span> <span class="Identifier">dynlib</span><span class="Punctuation">:</span> <span class="StringLit">&quot;client.dll&quot;</span><span class="Punctuation">,</span> <span class="Identifier">cdecl</span><span class="Operator">.</span><span class="Punctuation">}</span>

<span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">rtl</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">a</span> <span class="Operator">+</span> <span class="Identifier">b</span></pre></p>
<p>In the example, a new pragma named <tt class="docutils literal"><span class="pre"><span class="Identifier">rtl</span></span></tt> is introduced that either imports a symbol from a dynamic library or exports the symbol for dynamic library generation.</p>

<h2><a class="toc-backref" id="userminusdefined-pragmas-custom-annotations" href="#userminusdefined-pragmas-custom-annotations">Custom annotations</a></h2><p>It is possible to define custom typed pragmas. Custom pragmas do not affect code generation directly, but their presence can be detected by macros. Custom pragmas are defined using templates annotated with pragma <tt class="docutils literal"><span class="pre"><span class="Identifier">pragma</span></span></tt>:</p>
<p><pre class="listing"><span class="Keyword">template</span> <span class="Identifier">dbTable</span><span class="Punctuation">(</span><span class="Identifier">name</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">,</span> <span class="Identifier">table_space</span><span class="Punctuation">:</span> <span class="Identifier">string</span> <span class="Operator">=</span> <span class="StringLit">&quot;&quot;</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">pragma</span><span class="Operator">.</span><span class="Punctuation">}</span>
<span class="Keyword">template</span> <span class="Identifier">dbKey</span><span class="Punctuation">(</span><span class="Identifier">name</span><span class="Punctuation">:</span> <span class="Identifier">string</span> <span class="Operator">=</span> <span class="StringLit">&quot;&quot;</span><span class="Punctuation">,</span> <span class="Identifier">primary_key</span><span class="Punctuation">:</span> <span class="Identifier">bool</span> <span class="Operator">=</span> <span class="Identifier">false</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">pragma</span><span class="Operator">.</span><span class="Punctuation">}</span>
<span class="Keyword">template</span> <span class="Identifier">dbForeignKey</span><span class="Punctuation">(</span><span class="Identifier">t</span><span class="Punctuation">:</span> <span class="Identifier">typedesc</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">pragma</span><span class="Operator">.</span><span class="Punctuation">}</span>
<span class="Keyword">template</span> <span class="Identifier">dbIgnore</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">pragma</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>
<p>Consider this stylized example of a possible Object Relation Mapping (ORM) implementation:</p>
<p><pre class="listing"><span class="Keyword">const</span> <span class="Identifier">tblspace</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">strdefine</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="StringLit">&quot;dev&quot;</span> <span class="Comment"># switch for dev, test and prod environments</span>

<span class="Keyword">type</span>
  <span class="Identifier">User</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">dbTable</span><span class="Punctuation">(</span><span class="StringLit">&quot;users&quot;</span><span class="Punctuation">,</span> <span class="Identifier">tblspace</span><span class="Punctuation">)</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">object</span>
    <span class="Identifier">id</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">dbKey</span><span class="Punctuation">(</span><span class="Identifier">primary_key</span> <span class="Operator">=</span> <span class="Identifier">true</span><span class="Punctuation">)</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span> <span class="Identifier">int</span>
    <span class="Identifier">name</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="RawData">dbKey&quot;full_name&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span> <span class="Identifier">string</span>
    <span class="Identifier">is_cached</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">dbIgnore</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span> <span class="Identifier">bool</span>
    <span class="Identifier">age</span><span class="Punctuation">:</span> <span class="Identifier">int</span>
  
  <span class="Identifier">UserProfile</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">dbTable</span><span class="Punctuation">(</span><span class="StringLit">&quot;profiles&quot;</span><span class="Punctuation">,</span> <span class="Identifier">tblspace</span><span class="Punctuation">)</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">object</span>
    <span class="Identifier">id</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">dbKey</span><span class="Punctuation">(</span><span class="Identifier">primary_key</span> <span class="Operator">=</span> <span class="Identifier">true</span><span class="Punctuation">)</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span> <span class="Identifier">int</span>
    <span class="Identifier">user_id</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">dbForeignKey</span><span class="Punctuation">:</span> <span class="Identifier">User</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span> <span class="Identifier">int</span>
    <span class="Identifier">read_access</span><span class="Punctuation">:</span> <span class="Identifier">bool</span>
    <span class="Identifier">write_access</span><span class="Punctuation">:</span> <span class="Identifier">bool</span>
    <span class="Identifier">admin_access</span><span class="Punctuation">:</span> <span class="Identifier">bool</span></pre></p>
<p>In this example, custom pragmas are used to describe how Nim objects are mapped to the schema of the relational database. Custom pragmas can have zero or more arguments. In order to pass multiple arguments use one of template call syntaxes. All arguments are typed and follow standard overload resolution rules for templates. Therefore, it is possible to have default values for arguments, pass by name, varargs, etc.</p>
<p>Custom pragmas can be used in all locations where ordinary pragmas can be specified. It is possible to annotate procs, templates, type and variable definitions, statements, etc.</p>
<p>The macros module includes helpers which can be used to simplify custom pragma access <tt class="docutils literal"><span class="pre"><span class="Identifier">hasCustomPragma</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Identifier">getCustomPragmaVal</span></span></tt>. Please consult the <a class="reference external" href="macros.html">macros</a> module documentation for details. These macros are not magic, everything they do can also be achieved by walking the AST of the object representation.</p>
<p>More examples with custom pragmas:</p>
<ul class="simple"><li><p>Better serialization/deserialization control:</p>
<p><pre class="listing"><span class="Keyword">type</span> <span class="Identifier">MyObj</span> <span class="Operator">=</span> <span class="Keyword">object</span>
  <span class="Identifier">a</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">dontSerialize</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span> <span class="Identifier">int</span>
  <span class="Identifier">b</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">defaultDeserialize</span><span class="Punctuation">:</span> <span class="FloatNumber">5.</span><span class="Punctuation">}</span><span class="Punctuation">:</span> <span class="Identifier">int</span>
  <span class="Identifier">c</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">serializationKey</span><span class="Punctuation">:</span> <span class="StringLit">&quot;_c&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span> <span class="Identifier">string</span></pre></p>
</li>
<li><p>Adopting type for gui inspector in a game engine:</p>
<p><pre class="listing"><span class="Keyword">type</span> <span class="Identifier">MyComponent</span> <span class="Operator">=</span> <span class="Keyword">object</span>
  <span class="Identifier">position</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">editable</span><span class="Punctuation">,</span> <span class="Identifier">animatable</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span> <span class="Identifier">Vector3</span>
  <span class="Identifier">alpha</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">editRange</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="FloatNumber">0.0</span><span class="Operator">..</span><span class="FloatNumber">1.0</span><span class="Punctuation">]</span><span class="Punctuation">,</span> <span class="Identifier">animatable</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span> <span class="Identifier">float32</span></pre></p>
</li>
</ul>

<h2><a class="toc-backref" id="userminusdefined-pragmas-macro-pragmas" href="#userminusdefined-pragmas-macro-pragmas">Macro pragmas</a></h2><p>Macros and templates can sometimes be called with the pragma syntax. Cases where this is possible include when attached to routine (procs, iterators, etc.) declarations or routine type expressions. The compiler will perform the following simple syntactic transformations:</p>
<p><pre class="listing"><span class="Keyword">template</span> <span class="Identifier">command</span><span class="Punctuation">(</span><span class="Identifier">name</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">,</span> <span class="Identifier">def</span><span class="Punctuation">:</span> <span class="Identifier">untyped</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Keyword">discard</span>

<span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">command</span><span class="Punctuation">(</span><span class="StringLit">&quot;print&quot;</span><span class="Punctuation">)</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">discard</span></pre></p>
<p>This is translated to:</p>
<p><pre class="listing"><span class="Identifier">command</span><span class="Punctuation">(</span><span class="StringLit">&quot;print&quot;</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
  <span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Keyword">discard</span></pre></p>
<hr />
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">AsyncEventHandler</span> <span class="Operator">=</span> <span class="Keyword">proc</span> <span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">Event</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">async</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>
<p>This is translated to:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">AsyncEventHandler</span> <span class="Operator">=</span> <span class="Identifier">async</span><span class="Punctuation">(</span><span class="Keyword">proc</span> <span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">Event</span><span class="Punctuation">)</span><span class="Punctuation">)</span></pre></p>
<hr />
<p>When multiple macro pragmas are applied to the same definition, the first one from left to right will be evaluated. This macro can then choose to keep the remaining macro pragmas in its output, and those will be evaluated in the same way.</p>
<p>There are a few more applications of macro pragmas, such as in type, variable and constant declarations, but this behavior is considered to be experimental and is documented in the <a class="reference external" href=" manual_experimental.html#extended-macro-pragmas">experimental manual</a> instead.</p>

<h1><a class="toc-backref" id="foreign-function-interface" href="#foreign-function-interface">Foreign function interface</a></h1><p>Nim's <span id="ffi_1">FFI</span> (foreign function interface) is extensive and only the parts that scale to other future backends (like the LLVM/JavaScript backends) are documented here.</p>

<h2><a class="toc-backref" id="foreign-function-interface-importc-pragma" href="#foreign-function-interface-importc-pragma">Importc pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">importc</span></span></tt> pragma provides a means to import a proc or a variable from C. The optional argument is a string containing the C identifier. If the argument is missing, the C name is the Nim identifier <em>exactly as spelled</em>:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">printf</span><span class="Punctuation">(</span><span class="Identifier">formatstr</span><span class="Punctuation">:</span> <span class="Identifier">cstring</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">header</span><span class="Punctuation">:</span> <span class="StringLit">&quot;&lt;stdio.h&gt;&quot;</span><span class="Punctuation">,</span> <span class="Identifier">importc</span><span class="Punctuation">:</span> <span class="StringLit">&quot;printf&quot;</span><span class="Punctuation">,</span> <span class="Identifier">varargs</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>
<p>When <tt class="docutils literal"><span class="pre"><span class="Identifier">importc</span></span></tt> is applied to a <tt class="docutils literal"><span class="pre"><span class="Keyword">let</span></span></tt> statement it can omit its value which will then be expected to come from C. This can be used to import a C <tt class="docutils literal"><span class="pre"><span class="Keyword">const</span></span></tt>:</p>
<p><pre class="listing"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">emit</span><span class="Punctuation">:</span> <span class="StringLit">&quot;const int cconst = 42;&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span>

<span class="Keyword">let</span> <span class="Identifier">cconst</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importc</span><span class="Punctuation">,</span> <span class="Identifier">nodecl</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span> <span class="Identifier">cint</span>

<span class="Identifier">assert</span> <span class="Identifier">cconst</span> <span class="Operator">==</span> <span class="DecNumber">42</span></pre></p>
<p>Note that this pragma has been abused in the past to also work in the JS backend for JS objects and functions. Other backends do provide the same feature under the same name. Also, when the target language is not set to C, other pragmas are available:</p>
<ul class="simple"><li><a class="reference internal" href="#implementation-specific-pragmas-importcpp-pragma">importcpp</a></li>
<li><a class="reference internal" href="#implementation-specific-pragmas-importobjc-pragma">importobjc</a></li>
<li><a class="reference internal" href="#implementation-specific-pragmas-importjs-pragma">importjs</a></li>
</ul>
<p>The string literal passed to <tt class="docutils literal"><span class="pre"><span class="Identifier">importc</span></span></tt> can be a format string:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Identifier">s</span><span class="Punctuation">:</span> <span class="Identifier">cstring</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importc</span><span class="Punctuation">:</span> <span class="StringLit">&quot;prefix$1&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>
<p>In the example, the external name of <tt class="docutils literal"><span class="pre"><span class="Identifier">p</span></span></tt> is set to <tt class="docutils literal"><span class="pre"><span class="Identifier">prefixp</span></span></tt>. Only <tt class="docutils literal"><span class="pre">$1</span></tt> is available and a literal dollar sign must be written as <tt class="docutils literal"><span class="pre">$$</span></tt>.</p>

<h2><a class="toc-backref" id="foreign-function-interface-exportc-pragma" href="#foreign-function-interface-exportc-pragma">Exportc pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">exportc</span></span></tt> pragma provides a means to export a type, a variable, or a procedure to C. Enums and constants can't be exported. The optional argument is a string containing the C identifier. If the argument is missing, the C name is the Nim identifier <em>exactly as spelled</em>:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">callme</span><span class="Punctuation">(</span><span class="Identifier">formatstr</span><span class="Punctuation">:</span> <span class="Identifier">cstring</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">exportc</span><span class="Punctuation">:</span> <span class="StringLit">&quot;callMe&quot;</span><span class="Punctuation">,</span> <span class="Identifier">varargs</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>
<p>Note that this pragma is somewhat of a misnomer: Other backends do provide the same feature under the same name.</p>
<p>The string literal passed to <tt class="docutils literal"><span class="pre"><span class="Identifier">exportc</span></span></tt> can be a format string:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Identifier">s</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">exportc</span><span class="Punctuation">:</span> <span class="StringLit">&quot;prefix$1&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
  <span class="Identifier">echo</span> <span class="Identifier">s</span></pre></p>
<p>In the example, the external name of <tt class="docutils literal"><span class="pre"><span class="Identifier">p</span></span></tt> is set to <tt class="docutils literal"><span class="pre"><span class="Identifier">prefixp</span></span></tt>. Only <tt class="docutils literal"><span class="pre">$1</span></tt> is available and a literal dollar sign must be written as <tt class="docutils literal"><span class="pre">$$</span></tt>.</p>
<p>If the symbol should also be exported to a dynamic library, the <tt class="docutils literal"><span class="pre"><span class="Identifier">dynlib</span></span></tt> pragma should be used in addition to the <tt class="docutils literal"><span class="pre"><span class="Identifier">exportc</span></span></tt> pragma. See <a class="reference internal" href="#foreign-function-interface-dynlib-pragma-for-export">Dynlib pragma for export</a>.</p>

<h2><a class="toc-backref" id="foreign-function-interface-exportcpp-pragma" href="#foreign-function-interface-exportcpp-pragma">Exportcpp pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">exportcpp</span></span></tt> pragma works like the <tt class="docutils literal"><span class="pre"><span class="Identifier">exportc</span></span></tt> pragma but it requires the <tt class="docutils literal"><span class="pre"><span class="Identifier">cpp</span></span></tt> backend. When compiled with the <tt class="docutils literal"><span class="pre"><span class="Identifier">cpp</span></span></tt> backend, the <tt class="docutils literal"><span class="pre"><span class="Identifier">exportc</span></span></tt> pragma adds <tt class="docutils literal"><span class="pre"><span class="Keyword">export</span> <span class="StringLit">&quot;C&quot;</span></span></tt> to the declaration in the generated code so that it can be called from both C and C++ code. <tt class="docutils literal"><span class="pre"><span class="Identifier">exportcpp</span></span></tt> pragma doesn't add <tt class="docutils literal"><span class="pre"><span class="Keyword">export</span> <span class="StringLit">&quot;C&quot;</span></span></tt>.</p>

<h2><a class="toc-backref" id="foreign-function-interface-extern-pragma" href="#foreign-function-interface-extern-pragma">Extern pragma</a></h2><p>Like <tt class="docutils literal"><span class="pre"><span class="Identifier">exportc</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Identifier">importc</span></span></tt>, the <tt class="docutils literal"><span class="pre"><span class="Identifier">extern</span></span></tt> pragma affects name mangling. The string literal passed to <tt class="docutils literal"><span class="pre"><span class="Identifier">extern</span></span></tt> can be a format string:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Identifier">s</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">extern</span><span class="Punctuation">:</span> <span class="StringLit">&quot;prefix$1&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
  <span class="Identifier">echo</span> <span class="Identifier">s</span></pre></p>
<p>In the example, the external name of <tt class="docutils literal"><span class="pre"><span class="Identifier">p</span></span></tt> is set to <tt class="docutils literal"><span class="pre"><span class="Identifier">prefixp</span></span></tt>. Only <tt class="docutils literal"><span class="pre">$1</span></tt> is available and a literal dollar sign must be written as <tt class="docutils literal"><span class="pre">$$</span></tt>.</p>

<h2><a class="toc-backref" id="foreign-function-interface-bycopy-pragma" href="#foreign-function-interface-bycopy-pragma">Bycopy pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">bycopy</span></span></tt> pragma can be applied to an object or tuple type or a proc param. It instructs the compiler to pass the type by value to procs:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">Vector</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">bycopy</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">object</span>
    <span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">,</span> <span class="Identifier">z</span><span class="Punctuation">:</span> <span class="Identifier">float</span></pre></p>
<p>The Nim compiler automatically determines whether a parameter is passed by value or by reference based on the parameter type's size. If a parameter must be passed by value or by reference, (such as when interfacing with a C library) use the bycopy or byref pragmas. Notice params marked as <tt class="docutils literal"><span class="pre"><span class="Identifier">byref</span></span></tt> takes precedence over types marked as <tt class="docutils literal"><span class="pre"><span class="Identifier">bycopy</span></span></tt>.</p>

<h2><a class="toc-backref" id="foreign-function-interface-byref-pragma" href="#foreign-function-interface-byref-pragma">Byref pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">byref</span></span></tt> pragma can be applied to an object or tuple type or a proc param. When applied to a type it instructs the compiler to pass the type by reference (hidden pointer) to procs. When applied to a param it will take precedence, even if the the type was marked as <tt class="docutils literal"><span class="pre"><span class="Identifier">bycopy</span></span></tt>. When an <tt class="docutils literal"><span class="pre"><span class="Identifier">importc</span></span></tt> type has a <tt class="docutils literal"><span class="pre"><span class="Identifier">byref</span></span></tt> pragma or parameters are marked as <tt class="docutils literal"><span class="pre"><span class="Identifier">byref</span></span></tt> in an <tt class="docutils literal"><span class="pre"><span class="Identifier">importc</span></span></tt> proc, these params translate to pointers. When an <tt class="docutils literal"><span class="pre"><span class="Identifier">importcpp</span></span></tt> type has a <tt class="docutils literal"><span class="pre"><span class="Identifier">byref</span></span></tt> pragma, these params translate to C++ references <tt class="docutils literal"><span class="pre"><span class="Operator">&amp;</span></span></tt>.</p>
<p><pre class="listing"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">emit</span><span class="Punctuation">:</span> <span class="LongStringLit">&quot;&quot;&quot;/*TYPESECTION*/
typedef struct {
  int x;
} CStruct;
&quot;&quot;&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span>

<span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">emit</span><span class="Punctuation">:</span> <span class="LongStringLit">&quot;&quot;&quot;
#ifdef __cplusplus
extern &quot;C&quot;
#endif
int takesCStruct(CStruct* x) {
  return x-&gt;x;
}
&quot;&quot;&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span>

<span class="Keyword">type</span>
  <span class="Identifier">CStruct</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importc</span><span class="Punctuation">,</span> <span class="Identifier">byref</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">object</span>
    <span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">cint</span>

<span class="Keyword">proc</span> <span class="Identifier">takesCStruct</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">CStruct</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">cint</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importc</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>
<p>or</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">CStruct</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importc</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">object</span>
    <span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">cint</span>

<span class="Keyword">proc</span> <span class="Identifier">takesCStruct</span><span class="Punctuation">(</span><span class="Identifier">x</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">byref</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span> <span class="Identifier">CStruct</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">cint</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importc</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>
<p><pre class="listing"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">emit</span><span class="Punctuation">:</span> <span class="LongStringLit">&quot;&quot;&quot;/*TYPESECTION*/
struct CppStruct {
  int x;
  
  int takesCppStruct(CppStruct&amp; y) {
    return x + y.x;
  }
};
&quot;&quot;&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span>

<span class="Keyword">type</span>
  <span class="Identifier">CppStruct</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importcpp</span><span class="Punctuation">,</span> <span class="Identifier">byref</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">object</span>
    <span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">cint</span>

<span class="Keyword">proc</span> <span class="Identifier">takesCppStruct</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Identifier">CppStruct</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">cint</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importcpp</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>

<h2><a class="toc-backref" id="foreign-function-interface-varargs-pragma" href="#foreign-function-interface-varargs-pragma">Varargs pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">varargs</span></span></tt> pragma can be applied to procedures only (and procedure types). It tells Nim that the proc can take a variable number of parameters after the last specified parameter. Nim string values will be converted to C strings automatically:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">printf</span><span class="Punctuation">(</span><span class="Identifier">formatstr</span><span class="Punctuation">:</span> <span class="Identifier">cstring</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">header</span><span class="Punctuation">:</span> <span class="StringLit">&quot;&lt;stdio.h&gt;&quot;</span><span class="Punctuation">,</span> <span class="Identifier">varargs</span><span class="Operator">.</span><span class="Punctuation">}</span>

<span class="Identifier">printf</span><span class="Punctuation">(</span><span class="StringLit">&quot;hallo %s&quot;</span><span class="Punctuation">,</span> <span class="StringLit">&quot;world&quot;</span><span class="Punctuation">)</span> <span class="Comment"># &quot;world&quot; will be passed as C string</span></pre></p>

<h2><a class="toc-backref" id="foreign-function-interface-union-pragma" href="#foreign-function-interface-union-pragma">Union pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">union</span></span></tt> pragma can be applied to any <tt class="docutils literal"><span class="pre"><span class="Keyword">object</span></span></tt> type. It means all of an object's fields are overlaid in memory. This produces a <tt class="docutils literal"><span class="pre"><span class="Keyword">union</span></span></tt> instead of a <tt class="docutils literal"><span class="pre"><span class="Keyword">struct</span></span></tt> in the generated C/C++ code. The object declaration then must not use inheritance or any GC'ed memory but this is currently not checked.</p>
<p><strong>Future directions</strong>: GC'ed memory should be allowed in unions and the GC should scan unions conservatively.</p>

<h2><a class="toc-backref" id="foreign-function-interface-packed-pragma" href="#foreign-function-interface-packed-pragma">Packed pragma</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">packed</span></span></tt> pragma can be applied to any <tt class="docutils literal"><span class="pre"><span class="Keyword">object</span></span></tt> type. It ensures that the fields of an object are packed back-to-back in memory. It is useful to store packets or messages from/to network or hardware drivers, and for interoperability with C. Combining packed pragma with inheritance is not defined, and it should not be used with GC'ed memory (ref's).</p>
<p><strong>Future directions</strong>: Using GC'ed memory in packed pragma will result in a static error. Usage with inheritance should be defined and documented.</p>

<h2><a class="toc-backref" id="foreign-function-interface-dynlib-pragma-for-import" href="#foreign-function-interface-dynlib-pragma-for-import">Dynlib pragma for import</a></h2><p>With the <tt class="docutils literal"><span class="pre"><span class="Identifier">dynlib</span></span></tt> pragma, a procedure or a variable can be imported from a dynamic library (<tt class="docutils literal"><span class="pre">.dll</span></tt> files for Windows, <tt class="docutils literal"><span class="pre">lib*.so</span></tt> files for UNIX). The non-optional argument has to be the name of the dynamic library:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">gtk_image_new</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">PGtkWidget</span>
  <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">cdecl</span><span class="Punctuation">,</span> <span class="Identifier">dynlib</span><span class="Punctuation">:</span> <span class="StringLit">&quot;libgtk-x11-2.0.so&quot;</span><span class="Punctuation">,</span> <span class="Identifier">importc</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>
<p>In general, importing a dynamic library does not require any special linker options or linking with import libraries. This also implies that no <em>devel</em> packages need to be installed.</p>
<p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">dynlib</span></span></tt> import mechanism supports a versioning scheme:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">Tcl_Eval</span><span class="Punctuation">(</span><span class="Identifier">interp</span><span class="Punctuation">:</span> <span class="Identifier">pTcl_Interp</span><span class="Punctuation">,</span> <span class="Identifier">script</span><span class="Punctuation">:</span> <span class="Identifier">cstring</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">cdecl</span><span class="Punctuation">,</span>
  <span class="Identifier">importc</span><span class="Punctuation">,</span> <span class="Identifier">dynlib</span><span class="Punctuation">:</span> <span class="StringLit">&quot;libtcl(|8.5|8.4|8.3).so.(1|0)&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>
<p>At runtime, the dynamic library is searched for (in this order):</p>
<pre>libtcl.so.1
libtcl.so.0
libtcl8.5.so.1
libtcl8.5.so.0
libtcl8.4.so.1
libtcl8.4.so.0
libtcl8.3.so.1
libtcl8.3.so.0</pre>
<p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">dynlib</span></span></tt> pragma supports not only constant strings as an argument but also string expressions in general:</p>
<p><pre class="listing"><span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">os</span>

<span class="Keyword">proc</span> <span class="Identifier">getDllName</span><span class="Punctuation">:</span> <span class="Identifier">string</span> <span class="Operator">=</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="StringLit">&quot;mylib.dll&quot;</span>
  <span class="Keyword">if</span> <span class="Identifier">fileExists</span><span class="Punctuation">(</span><span class="Identifier">result</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Keyword">return</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="StringLit">&quot;mylib2.dll&quot;</span>
  <span class="Keyword">if</span> <span class="Identifier">fileExists</span><span class="Punctuation">(</span><span class="Identifier">result</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Keyword">return</span>
  <span class="Identifier">quit</span><span class="Punctuation">(</span><span class="StringLit">&quot;could not load dynamic library&quot;</span><span class="Punctuation">)</span>

<span class="Keyword">proc</span> <span class="Identifier">myImport</span><span class="Punctuation">(</span><span class="Identifier">s</span><span class="Punctuation">:</span> <span class="Identifier">cstring</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">cdecl</span><span class="Punctuation">,</span> <span class="Identifier">importc</span><span class="Punctuation">,</span> <span class="Identifier">dynlib</span><span class="Punctuation">:</span> <span class="Identifier">getDllName</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>
<p><strong>Note</strong>: Patterns like <tt class="docutils literal"><span class="pre">libtcl(|8.5|8.4).so</span></tt> are only supported in constant strings, because they are precompiled.</p>
<p><strong>Note</strong>: Passing variables to the <tt class="docutils literal"><span class="pre"><span class="Identifier">dynlib</span></span></tt> pragma will fail at runtime because of order of initialization problems.</p>
<p><strong>Note</strong>: A <tt class="docutils literal"><span class="pre"><span class="Identifier">dynlib</span></span></tt> import can be overridden with the <tt class="docutils literal"><span class="pre option">--dynlibOverride:name</span></tt> command-line option. The <a class="reference external" href="nimc.html">Compiler User Guide</a> contains further information.</p>

<h2><a class="toc-backref" id="foreign-function-interface-dynlib-pragma-for-export" href="#foreign-function-interface-dynlib-pragma-for-export">Dynlib pragma for export</a></h2><p>With the <tt class="docutils literal"><span class="pre"><span class="Identifier">dynlib</span></span></tt> pragma, a procedure can also be exported to a dynamic library. The pragma then has no argument and has to be used in conjunction with the <tt class="docutils literal"><span class="pre"><span class="Identifier">exportc</span></span></tt> pragma:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">exportme</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">cdecl</span><span class="Punctuation">,</span> <span class="Identifier">exportc</span><span class="Punctuation">,</span> <span class="Identifier">dynlib</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>
<p>This is only useful if the program is compiled as a dynamic library via the <tt class="docutils literal"><span class="pre option">--app:lib</span></tt> command-line option.</p>

<h1><a class="toc-backref" id="threads" href="#threads">Threads</a></h1><p>The <tt class="docutils literal"><span class="pre option">--threads:on</span></tt> command-line switch is enabled by default. The <a class="reference external" href="typedthreads.html">typedthreads module</a> module then contains several threading primitives. See <a class="reference external" href="manual_experimental.html#parallel-amp-spawn">spawn</a> for further details.</p>
<p>The only ways to create a thread is via <tt class="docutils literal"><span class="pre"><span class="Identifier">spawn</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Identifier">createThread</span></span></tt>.</p>

<h2><a class="toc-backref" id="threads-thread-pragma" href="#threads-thread-pragma">Thread pragma</a></h2><p>A proc that is executed as a new thread of execution should be marked by the <tt class="docutils literal"><span class="pre"><span class="Identifier">thread</span></span></tt> pragma for reasons of readability. The compiler checks for violations of the <span id="no-heap-sharing-restriction_1">no heap sharing restriction</span>: This restriction implies that it is invalid to construct a data structure that consists of memory allocated from different (thread-local) heaps.</p>
<p>A thread proc can be passed to <tt class="docutils literal"><span class="pre"><span class="Identifier">createThread</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Identifier">spawn</span></span></tt>.</p>

<h2><a class="toc-backref" id="threads-threadvar-pragma" href="#threads-threadvar-pragma">Threadvar pragma</a></h2><p>A variable can be marked with the <tt class="docutils literal"><span class="pre"><span class="Identifier">threadvar</span></span></tt> pragma, which makes it a <span id="threadminuslocal_1">thread-local</span> variable; Additionally, this implies all the effects of the <tt class="docutils literal"><span class="pre"><span class="Identifier">global</span></span></tt> pragma.</p>
<p><pre class="listing"><span class="Keyword">var</span> <span class="Identifier">checkpoints</span><span class="Operator">*</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">threadvar</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span> <span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">string</span><span class="Punctuation">]</span></pre></p>
<p>Due to implementation restrictions, thread-local variables cannot be initialized within the <tt class="docutils literal"><span class="pre"><span class="Keyword">var</span></span></tt> section. (Every thread-local variable needs to be replicated at thread creation.)</p>

<h2><a class="toc-backref" id="threads-threads-and-exceptions" href="#threads-threads-and-exceptions">Threads and exceptions</a></h2><p>The interaction between threads and exceptions is simple: A <em>handled</em> exception in one thread cannot affect any other thread. However, an <em>unhandled</em> exception in one thread terminates the whole <em>process</em>.</p>

<h1><a class="toc-backref" id="guards-and-locks" href="#guards-and-locks">Guards and locks</a></h1><p>Nim provides common low level concurrency mechanisms like locks, atomic intrinsics or condition variables.</p>
<p>Nim significantly improves on the safety of these features via additional pragmas:</p>
<ol class="simple"><li>A <span id="guard_1">guard</span> annotation is introduced to prevent data races.</li>
<li>Every access of a guarded memory location needs to happen in an appropriate <span id="locks_1">locks</span> statement.</li>
</ol>

<h2><a class="toc-backref" id="guards-and-locks-guards-and-locks-sections" href="#guards-and-locks-guards-and-locks-sections">Guards and locks sections</a></h2>
<h3><a class="toc-backref" id="guards-and-locks-sections-protecting-global-variables" href="#guards-and-locks-sections-protecting-global-variables">Protecting global variables</a></h3><p>Object fields and global variables can be annotated via a <tt class="docutils literal"><span class="pre"><span class="Identifier">guard</span></span></tt> pragma:</p>
<p><pre class="listing"><span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">locks</span>

<span class="Keyword">var</span> <span class="Identifier">glock</span><span class="Punctuation">:</span> <span class="Identifier">Lock</span>
<span class="Keyword">var</span> <span class="Identifier">gdata</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">guard</span><span class="Punctuation">:</span> <span class="Identifier">glock</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span> <span class="Identifier">int</span></pre></p>
<p>The compiler then ensures that every access of <tt class="docutils literal"><span class="pre"><span class="Identifier">gdata</span></span></tt> is within a <tt class="docutils literal"><span class="pre"><span class="Identifier">locks</span></span></tt> section:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">invalid</span> <span class="Operator">=</span>
  <span class="Comment"># invalid: unguarded access:</span>
  <span class="Identifier">echo</span> <span class="Identifier">gdata</span>

<span class="Keyword">proc</span> <span class="Identifier">valid</span> <span class="Operator">=</span>
  <span class="Comment"># valid access:</span>
  <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">locks</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Identifier">glock</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span>
    <span class="Identifier">echo</span> <span class="Identifier">gdata</span></pre></p>
<p>Top level accesses to <tt class="docutils literal"><span class="pre"><span class="Identifier">gdata</span></span></tt> are always allowed so that it can be initialized conveniently. It is <em>assumed</em> (but not enforced) that every top level statement is executed before any concurrent action happens.</p>
<p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">locks</span></span></tt> section deliberately looks ugly because it has no runtime semantics and should not be used directly! It should only be used in templates that also implement some form of locking at runtime:</p>
<p><pre class="listing"><span class="Keyword">template</span> <span class="Identifier">lock</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">Lock</span><span class="Punctuation">;</span> <span class="Identifier">body</span><span class="Punctuation">:</span> <span class="Identifier">untyped</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Identifier">pthread_mutex_lock</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">)</span>
  <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">locks</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Identifier">a</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span>
    <span class="Keyword">try</span><span class="Punctuation">:</span>
      <span class="Identifier">body</span>
    <span class="Keyword">finally</span><span class="Punctuation">:</span>
      <span class="Identifier">pthread_mutex_unlock</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">)</span></pre></p>
<p>The guard does not need to be of any particular type. It is flexible enough to model low level lockfree mechanisms:</p>
<p><pre class="listing"><span class="Keyword">var</span> <span class="Identifier">dummyLock</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">compileTime</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span> <span class="Identifier">int</span>
<span class="Keyword">var</span> <span class="Identifier">atomicCounter</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">guard</span><span class="Punctuation">:</span> <span class="Identifier">dummyLock</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span> <span class="Identifier">int</span>

<span class="Keyword">template</span> <span class="Identifier">atomicRead</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">untyped</span> <span class="Operator">=</span>
  <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">locks</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Identifier">dummyLock</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span>
    <span class="Identifier">memoryReadBarrier</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
    <span class="Identifier">x</span>

<span class="Identifier">echo</span> <span class="Identifier">atomicRead</span><span class="Punctuation">(</span><span class="Identifier">atomicCounter</span><span class="Punctuation">)</span></pre></p>
<p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">locks</span></span></tt> pragma takes a list of lock expressions <tt class="docutils literal"><span class="pre"><span class="Identifier">locks</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">,</span> <span class="Operator">...</span><span class="Punctuation">]</span></span></tt> in order to support <em>multi lock</em> statements.</p>

<h3><a class="toc-backref" id="guards-and-locks-sections-protecting-general-locations" href="#guards-and-locks-sections-protecting-general-locations">Protecting general locations</a></h3><p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">guard</span></span></tt> annotation can also be used to protect fields within an object. The guard then needs to be another field within the same object or a global variable.</p>
<p>Since objects can reside on the heap or on the stack, this greatly enhances the expressiveness of the language:</p>
<p><pre class="listing"><span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">locks</span>

<span class="Keyword">type</span>
  <span class="Identifier">ProtectedCounter</span> <span class="Operator">=</span> <span class="Keyword">object</span>
    <span class="Identifier">v</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">guard</span><span class="Punctuation">:</span> <span class="Identifier">L</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span> <span class="Identifier">int</span>
    <span class="Identifier">L</span><span class="Punctuation">:</span> <span class="Identifier">Lock</span>

<span class="Keyword">proc</span> <span class="Identifier">incCounters</span><span class="Punctuation">(</span><span class="Identifier">counters</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">openArray</span><span class="Punctuation">[</span><span class="Identifier">ProtectedCounter</span><span class="Punctuation">]</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">for</span> <span class="Identifier">i</span> <span class="Keyword">in</span> <span class="FloatNumber">0.</span><span class="Operator">.</span><span class="Identifier">counters</span><span class="Operator">.</span><span class="Identifier">high</span><span class="Punctuation">:</span>
    <span class="Identifier">lock</span> <span class="Identifier">counters</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Identifier">L</span><span class="Punctuation">:</span>
      <span class="Identifier">inc</span> <span class="Identifier">counters</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Identifier">v</span></pre></p>
<p>The access to field <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">v</span></span></tt> is allowed since its guard <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">L</span></span></tt>  is active. After template expansion, this amounts to:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">incCounters</span><span class="Punctuation">(</span><span class="Identifier">counters</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">openArray</span><span class="Punctuation">[</span><span class="Identifier">ProtectedCounter</span><span class="Punctuation">]</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">for</span> <span class="Identifier">i</span> <span class="Keyword">in</span> <span class="FloatNumber">0.</span><span class="Operator">.</span><span class="Identifier">counters</span><span class="Operator">.</span><span class="Identifier">high</span><span class="Punctuation">:</span>
    <span class="Identifier">pthread_mutex_lock</span><span class="Punctuation">(</span><span class="Identifier">counters</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Identifier">L</span><span class="Punctuation">)</span>
    <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">locks</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Identifier">counters</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Identifier">L</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span>
      <span class="Keyword">try</span><span class="Punctuation">:</span>
        <span class="Identifier">inc</span> <span class="Identifier">counters</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Identifier">v</span>
      <span class="Keyword">finally</span><span class="Punctuation">:</span>
        <span class="Identifier">pthread_mutex_unlock</span><span class="Punctuation">(</span><span class="Identifier">counters</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Identifier">L</span><span class="Punctuation">)</span></pre></p>
<p>There is an analysis that checks that <tt class="docutils literal"><span class="pre"><span class="Identifier">counters</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Identifier">L</span></span></tt> is the lock that corresponds to the protected location <tt class="docutils literal"><span class="pre"><span class="Identifier">counters</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Identifier">v</span></span></tt>. This analysis is called <span id="path-analysis_1">path analysis</span> because it deals with paths to locations like <tt class="docutils literal"><span class="pre"><span class="Identifier">obj</span><span class="Operator">.</span><span class="Identifier">field</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Identifier">fieldB</span><span class="Punctuation">[</span><span class="Identifier">j</span><span class="Punctuation">]</span></span></tt>.</p>
<p>The path analysis is <strong>currently unsound</strong>, but that doesn't make it useless. Two paths are considered equivalent if they are syntactically the same.</p>
<p>This means the following compiles (for now) even though it really should not:</p>
<p><pre class="listing"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">locks</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Identifier">a</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Identifier">L</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Punctuation">}</span><span class="Punctuation">:</span>
  <span class="Identifier">inc</span> <span class="Identifier">i</span>
  <span class="Identifier">access</span> <span class="Identifier">a</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Identifier">v</span></pre></p>

<h1><a class="toc-backref" id="strict-definitions-and-nimout-parameters" href="#strict-definitions-and-nimout-parameters">Strict definitions and <tt class="docutils literal"><span class="pre"><span class="Keyword">out</span></span></tt> parameters</a></h1><p><em>every</em> local variable must be initialized explicitly before it can be used:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">test</span> <span class="Operator">=</span>
  <span class="Keyword">var</span> <span class="Identifier">s</span><span class="Punctuation">:</span> <span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">string</span><span class="Punctuation">]</span>
  <span class="Identifier">s</span><span class="Operator">.</span><span class="Identifier">add</span> <span class="StringLit">&quot;abc&quot;</span> <span class="Comment"># invalid!</span></pre></p>
<p>Needs to be written as:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">test</span> <span class="Operator">=</span>
  <span class="Keyword">var</span> <span class="Identifier">s</span><span class="Punctuation">:</span> <span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">string</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Operator">@</span><span class="Punctuation">[</span><span class="Punctuation">]</span>
  <span class="Identifier">s</span><span class="Operator">.</span><span class="Identifier">add</span> <span class="StringLit">&quot;abc&quot;</span> <span class="Comment"># valid!</span></pre></p>
<p>A control flow analysis is performed in order to prove that a variable has been written to before it is used. Thus the following is valid:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">test</span><span class="Punctuation">(</span><span class="Identifier">cond</span><span class="Punctuation">:</span> <span class="Identifier">bool</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">var</span> <span class="Identifier">s</span><span class="Punctuation">:</span> <span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">string</span><span class="Punctuation">]</span>
  <span class="Keyword">if</span> <span class="Identifier">cond</span><span class="Punctuation">:</span>
    <span class="Identifier">s</span> <span class="Operator">=</span> <span class="Operator">@</span><span class="Punctuation">[</span><span class="StringLit">&quot;y&quot;</span><span class="Punctuation">]</span>
  <span class="Keyword">else</span><span class="Punctuation">:</span>
    <span class="Identifier">s</span> <span class="Operator">=</span> <span class="Operator">@</span><span class="Punctuation">[</span><span class="Punctuation">]</span>
  <span class="Identifier">s</span><span class="Operator">.</span><span class="Identifier">add</span> <span class="StringLit">&quot;abc&quot;</span> <span class="Comment"># valid!</span></pre></p>
<p>In this example every path does set <tt class="docutils literal"><span class="pre"><span class="Identifier">s</span></span></tt> to a value before it is used.</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">test</span><span class="Punctuation">(</span><span class="Identifier">cond</span><span class="Punctuation">:</span> <span class="Identifier">bool</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Keyword">let</span> <span class="Identifier">s</span><span class="Punctuation">:</span> <span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">string</span><span class="Punctuation">]</span>
  <span class="Keyword">if</span> <span class="Identifier">cond</span><span class="Punctuation">:</span>
    <span class="Identifier">s</span> <span class="Operator">=</span> <span class="Operator">@</span><span class="Punctuation">[</span><span class="StringLit">&quot;y&quot;</span><span class="Punctuation">]</span>
  <span class="Keyword">else</span><span class="Punctuation">:</span>
    <span class="Identifier">s</span> <span class="Operator">=</span> <span class="Operator">@</span><span class="Punctuation">[</span><span class="Punctuation">]</span></pre></p>
<p><tt class="docutils literal"><span class="pre"><span class="Keyword">let</span></span></tt> statements are allowed to not have an initial value, but every path should set <tt class="docutils literal"><span class="pre"><span class="Identifier">s</span></span></tt> to a value before it is used.</p>

<h2><a class="toc-backref" id="strict-definitions-and-nimout-parameters-nimout-parameters" href="#strict-definitions-and-nimout-parameters-nimout-parameters"><tt class="docutils literal"><span class="pre"><span class="Keyword">out</span></span></tt> parameters</a></h2><p>An <tt class="docutils literal"><span class="pre"><span class="Keyword">out</span></span></tt> parameter is like a <tt class="docutils literal"><span class="pre"><span class="Keyword">var</span></span></tt> parameter but it must be written to before it can be used:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">myopen</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">:</span> <span class="Keyword">out</span> <span class="Identifier">File</span><span class="Punctuation">;</span> <span class="Identifier">name</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">bool</span> <span class="Operator">=</span>
  <span class="Identifier">f</span> <span class="Operator">=</span> <span class="Identifier">default</span><span class="Punctuation">(</span><span class="Identifier">File</span><span class="Punctuation">)</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">open</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">,</span> <span class="Identifier">name</span><span class="Punctuation">)</span></pre></p>
<p>While it is usually the better style to use the return type in order to return results API and ABI considerations might make this infeasible. Like for <tt class="docutils literal"><span class="pre"><span class="Keyword">var</span> <span class="Identifier">T</span></span></tt> Nim maps <tt class="docutils literal"><span class="pre"><span class="Keyword">out</span> <span class="Identifier">T</span></span></tt> to a hidden pointer. For example POSIX's <tt class="docutils literal"><span class="pre"><span class="Identifier">stat</span></span></tt> routine can be wrapped as:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">stat</span><span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">a1</span><span class="Punctuation">:</span> <span class="Identifier">cstring</span><span class="Punctuation">,</span> <span class="Identifier">a2</span><span class="Punctuation">:</span> <span class="Keyword">out</span> <span class="Identifier">Stat</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">cint</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">importc</span><span class="Punctuation">,</span> <span class="Identifier">header</span><span class="Punctuation">:</span> <span class="StringLit">&quot;&lt;sys/stat.h&gt;&quot;</span><span class="Operator">.</span><span class="Punctuation">}</span></pre></p>
<p>When the implementation of a routine with output parameters is analysed, the compiler checks that every path before the (implicit or explicit) return does set every output parameter:</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Keyword">out</span> <span class="Identifier">int</span><span class="Punctuation">;</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Keyword">out</span> <span class="Identifier">string</span><span class="Punctuation">;</span> <span class="Identifier">cond</span><span class="Punctuation">:</span> <span class="Identifier">bool</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Identifier">x</span> <span class="Operator">=</span> <span class="DecNumber">4</span>
  <span class="Keyword">if</span> <span class="Identifier">cond</span><span class="Punctuation">:</span>
    <span class="Identifier">y</span> <span class="Operator">=</span> <span class="StringLit">&quot;abc&quot;</span>
  <span class="Comment"># error: not every path initializes 'y'</span></pre></p>

<h2><a class="toc-backref" id="strict-definitions-and-nimout-parameters-out-parameters-and-exception-handling" href="#strict-definitions-and-nimout-parameters-out-parameters-and-exception-handling">Out parameters and exception handling</a></h2><p>The analysis should take exceptions into account (but currently does not):</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">p</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Keyword">out</span> <span class="Identifier">int</span><span class="Punctuation">;</span> <span class="Identifier">y</span><span class="Punctuation">:</span> <span class="Keyword">out</span> <span class="Identifier">string</span><span class="Punctuation">;</span> <span class="Identifier">cond</span><span class="Punctuation">:</span> <span class="Identifier">bool</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Identifier">x</span> <span class="Operator">=</span> <span class="Identifier">canRaise</span><span class="Punctuation">(</span><span class="DecNumber">45</span><span class="Punctuation">)</span>
  <span class="Identifier">y</span> <span class="Operator">=</span> <span class="StringLit">&quot;abc&quot;</span> <span class="Comment"># &lt;-- error: not every path initializes 'y'</span></pre></p>
<p>Once the implementation takes exceptions into account it is easy enough to use <tt class="docutils literal"><span class="pre"><span class="Identifier">outParam</span> <span class="Operator">=</span> <span class="Identifier">default</span><span class="Punctuation">(</span><span class="Identifier">typeof</span><span class="Punctuation">(</span><span class="Identifier">outParam</span><span class="Punctuation">)</span><span class="Punctuation">)</span></span></tt> in the beginning of the proc body.</p>

<h2><a class="toc-backref" id="strict-definitions-and-nimout-parameters-out-parameters-and-inheritance" href="#strict-definitions-and-nimout-parameters-out-parameters-and-inheritance">Out parameters and inheritance</a></h2><p>It is not valid to pass an lvalue of a supertype to an <tt class="docutils literal"><span class="pre"><span class="Keyword">out</span> <span class="Identifier">T</span></span></tt> parameter:</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">Superclass</span> <span class="Operator">=</span> <span class="Keyword">object</span> <span class="Keyword">of</span> <span class="Identifier">RootObj</span>
    <span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">int</span>
  <span class="Identifier">Subclass</span> <span class="Operator">=</span> <span class="Keyword">object</span> <span class="Keyword">of</span> <span class="Identifier">Superclass</span>
    <span class="Identifier">s</span><span class="Punctuation">:</span> <span class="Identifier">string</span>

<span class="Keyword">proc</span> <span class="Identifier">init</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Keyword">out</span> <span class="Identifier">Superclass</span><span class="Punctuation">)</span> <span class="Operator">=</span>
  <span class="Identifier">x</span> <span class="Operator">=</span> <span class="Identifier">Superclass</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="DecNumber">8</span><span class="Punctuation">)</span>

<span class="Keyword">var</span> <span class="Identifier">v</span><span class="Punctuation">:</span> <span class="Identifier">Subclass</span>
<span class="Identifier">init</span> <span class="Identifier">v</span>
<span class="Identifier">use</span> <span class="Identifier">v</span><span class="Operator">.</span><span class="Identifier">s</span> <span class="Comment"># the 's' field was never initialized!</span></pre></p>
<p>However, in the future this could be allowed and provide a better way to write object constructors that take inheritance into account.</p>
</p>
    
  </div>
</div>

      <div class="twelve-columns footer">
        <span class="nim-sprite"></span>
        <br>
        <small style="color: var(--hint);">Made with Nim. Generated: 2025-01-09 12:00:01 UTC</small>
      </div>
    </div>
  </div>
      <script defer data-domain="nim-lang.org" src="https://plausible.io/js/plausible.js"></script>
    
</body>
</html>