ref.tex 255 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314231523162317231823192320232123222323232423252326232723282329233023312332233323342335233623372338233923402341234223432344234523462347234823492350235123522353235423552356235723582359236023612362236323642365236623672368236923702371237223732374237523762377237823792380238123822383238423852386238723882389239023912392239323942395239623972398239924002401240224032404240524062407240824092410241124122413241424152416241724182419242024212422242324242425242624272428242924302431243224332434243524362437243824392440244124422443244424452446244724482449245024512452245324542455245624572458245924602461246224632464246524662467246824692470247124722473247424752476247724782479248024812482248324842485248624872488248924902491249224932494249524962497249824992500250125022503250425052506250725082509251025112512251325142515251625172518251925202521252225232524252525262527252825292530253125322533253425352536253725382539254025412542254325442545254625472548254925502551255225532554255525562557255825592560256125622563256425652566256725682569257025712572257325742575257625772578257925802581258225832584258525862587258825892590259125922593259425952596259725982599260026012602260326042605260626072608260926102611261226132614261526162617261826192620262126222623262426252626262726282629263026312632263326342635263626372638263926402641264226432644264526462647264826492650265126522653265426552656265726582659266026612662266326642665266626672668266926702671267226732674267526762677267826792680268126822683268426852686268726882689269026912692269326942695269626972698269927002701270227032704270527062707270827092710271127122713271427152716271727182719272027212722272327242725272627272728272927302731273227332734273527362737273827392740274127422743274427452746274727482749275027512752275327542755275627572758275927602761276227632764276527662767276827692770277127722773277427752776277727782779278027812782278327842785278627872788278927902791279227932794279527962797279827992800280128022803280428052806280728082809281028112812281328142815281628172818281928202821282228232824282528262827282828292830283128322833283428352836283728382839284028412842284328442845284628472848284928502851285228532854285528562857285828592860286128622863286428652866286728682869287028712872287328742875287628772878287928802881288228832884288528862887288828892890289128922893289428952896289728982899290029012902290329042905290629072908290929102911291229132914291529162917291829192920292129222923292429252926292729282929293029312932293329342935293629372938293929402941294229432944294529462947294829492950295129522953295429552956295729582959296029612962296329642965296629672968296929702971297229732974297529762977297829792980298129822983298429852986298729882989299029912992299329942995299629972998299930003001300230033004300530063007300830093010301130123013301430153016301730183019302030213022302330243025302630273028302930303031303230333034303530363037303830393040304130423043304430453046304730483049305030513052305330543055305630573058305930603061306230633064306530663067306830693070307130723073307430753076307730783079308030813082308330843085308630873088308930903091309230933094309530963097309830993100310131023103310431053106310731083109311031113112311331143115311631173118311931203121312231233124312531263127312831293130313131323133313431353136313731383139314031413142314331443145314631473148314931503151315231533154315531563157315831593160316131623163316431653166316731683169317031713172317331743175317631773178317931803181318231833184318531863187318831893190319131923193319431953196319731983199320032013202320332043205320632073208320932103211321232133214321532163217321832193220322132223223322432253226322732283229323032313232323332343235323632373238323932403241324232433244324532463247324832493250325132523253325432553256325732583259326032613262326332643265326632673268326932703271327232733274327532763277327832793280328132823283328432853286328732883289329032913292329332943295329632973298329933003301330233033304330533063307330833093310331133123313331433153316331733183319332033213322332333243325332633273328332933303331333233333334333533363337333833393340334133423343334433453346334733483349335033513352335333543355335633573358335933603361336233633364336533663367336833693370337133723373337433753376337733783379338033813382338333843385338633873388338933903391339233933394339533963397339833993400340134023403340434053406340734083409341034113412341334143415341634173418341934203421342234233424342534263427342834293430343134323433343434353436343734383439344034413442344334443445344634473448344934503451345234533454345534563457345834593460346134623463346434653466346734683469347034713472347334743475347634773478347934803481348234833484348534863487348834893490349134923493349434953496349734983499350035013502350335043505350635073508350935103511351235133514351535163517351835193520352135223523352435253526352735283529353035313532353335343535353635373538353935403541354235433544354535463547354835493550355135523553355435553556355735583559356035613562356335643565356635673568356935703571357235733574357535763577357835793580358135823583358435853586358735883589359035913592359335943595359635973598359936003601360236033604360536063607360836093610361136123613361436153616361736183619362036213622362336243625362636273628362936303631363236333634363536363637363836393640364136423643364436453646364736483649365036513652365336543655365636573658365936603661366236633664366536663667366836693670367136723673367436753676367736783679368036813682368336843685368636873688368936903691369236933694369536963697369836993700370137023703370437053706370737083709371037113712371337143715371637173718371937203721372237233724372537263727372837293730373137323733373437353736373737383739374037413742374337443745374637473748374937503751375237533754375537563757375837593760376137623763376437653766376737683769377037713772377337743775377637773778377937803781378237833784378537863787378837893790379137923793379437953796379737983799380038013802380338043805380638073808380938103811381238133814381538163817381838193820382138223823382438253826382738283829383038313832383338343835383638373838383938403841384238433844384538463847384838493850385138523853385438553856385738583859386038613862386338643865386638673868386938703871387238733874387538763877387838793880388138823883388438853886388738883889389038913892389338943895389638973898389939003901390239033904390539063907390839093910391139123913391439153916391739183919392039213922392339243925392639273928392939303931393239333934393539363937393839393940394139423943394439453946394739483949395039513952395339543955395639573958395939603961396239633964396539663967396839693970397139723973397439753976397739783979398039813982398339843985398639873988398939903991399239933994399539963997399839994000400140024003400440054006400740084009401040114012401340144015401640174018401940204021402240234024402540264027402840294030403140324033403440354036403740384039404040414042404340444045404640474048404940504051405240534054405540564057405840594060406140624063406440654066406740684069407040714072407340744075407640774078407940804081408240834084408540864087408840894090409140924093409440954096409740984099410041014102410341044105410641074108410941104111411241134114411541164117411841194120412141224123412441254126412741284129413041314132413341344135413641374138413941404141414241434144414541464147414841494150415141524153415441554156415741584159416041614162416341644165416641674168416941704171417241734174417541764177417841794180418141824183418441854186418741884189419041914192419341944195419641974198419942004201420242034204420542064207420842094210421142124213421442154216421742184219422042214222422342244225422642274228422942304231423242334234423542364237423842394240424142424243424442454246424742484249425042514252425342544255425642574258425942604261426242634264426542664267426842694270427142724273427442754276427742784279428042814282428342844285428642874288428942904291429242934294429542964297429842994300430143024303430443054306430743084309431043114312431343144315431643174318431943204321432243234324432543264327432843294330433143324333433443354336433743384339434043414342434343444345434643474348434943504351435243534354435543564357435843594360436143624363436443654366436743684369437043714372437343744375437643774378437943804381438243834384438543864387438843894390439143924393439443954396439743984399440044014402440344044405440644074408440944104411441244134414441544164417441844194420442144224423442444254426442744284429443044314432443344344435443644374438443944404441444244434444444544464447444844494450445144524453445444554456445744584459446044614462446344644465446644674468446944704471447244734474447544764477447844794480448144824483448444854486448744884489449044914492449344944495449644974498449945004501450245034504450545064507450845094510451145124513451445154516451745184519452045214522452345244525452645274528452945304531453245334534453545364537453845394540454145424543454445454546454745484549455045514552455345544555455645574558455945604561456245634564456545664567456845694570457145724573457445754576457745784579458045814582458345844585458645874588458945904591459245934594459545964597459845994600460146024603460446054606460746084609461046114612461346144615461646174618461946204621462246234624462546264627462846294630463146324633463446354636463746384639464046414642464346444645464646474648464946504651465246534654465546564657465846594660466146624663466446654666466746684669467046714672467346744675467646774678467946804681468246834684468546864687468846894690469146924693469446954696469746984699470047014702470347044705470647074708470947104711471247134714471547164717471847194720472147224723472447254726472747284729473047314732473347344735473647374738473947404741474247434744474547464747474847494750475147524753475447554756475747584759476047614762476347644765476647674768476947704771477247734774477547764777477847794780478147824783478447854786478747884789479047914792479347944795479647974798479948004801480248034804480548064807480848094810481148124813481448154816481748184819482048214822482348244825482648274828482948304831483248334834483548364837483848394840484148424843484448454846484748484849485048514852485348544855485648574858485948604861486248634864486548664867486848694870487148724873487448754876487748784879488048814882488348844885488648874888488948904891489248934894489548964897489848994900490149024903490449054906490749084909491049114912491349144915491649174918491949204921492249234924492549264927492849294930493149324933493449354936493749384939494049414942494349444945494649474948494949504951495249534954495549564957495849594960496149624963496449654966496749684969497049714972497349744975497649774978497949804981498249834984498549864987498849894990499149924993499449954996499749984999500050015002500350045005500650075008500950105011501250135014501550165017501850195020502150225023502450255026502750285029503050315032503350345035503650375038503950405041504250435044504550465047504850495050505150525053505450555056505750585059506050615062506350645065506650675068506950705071507250735074507550765077507850795080508150825083508450855086508750885089509050915092509350945095509650975098509951005101510251035104510551065107510851095110511151125113511451155116511751185119512051215122512351245125512651275128512951305131513251335134513551365137513851395140514151425143514451455146514751485149515051515152515351545155515651575158515951605161516251635164516551665167516851695170517151725173517451755176517751785179518051815182518351845185518651875188518951905191519251935194519551965197519851995200520152025203520452055206520752085209521052115212521352145215521652175218521952205221522252235224522552265227522852295230523152325233523452355236523752385239524052415242524352445245524652475248524952505251525252535254525552565257525852595260526152625263526452655266526752685269527052715272527352745275527652775278527952805281528252835284528552865287528852895290529152925293529452955296529752985299530053015302530353045305530653075308530953105311531253135314531553165317531853195320532153225323532453255326532753285329533053315332533353345335533653375338533953405341534253435344534553465347534853495350535153525353535453555356535753585359536053615362536353645365536653675368536953705371537253735374537553765377537853795380538153825383538453855386538753885389539053915392539353945395539653975398539954005401540254035404540554065407540854095410541154125413541454155416541754185419542054215422542354245425542654275428542954305431543254335434543554365437543854395440544154425443544454455446544754485449545054515452545354545455545654575458545954605461546254635464546554665467546854695470547154725473547454755476547754785479548054815482548354845485548654875488548954905491549254935494549554965497549854995500550155025503550455055506550755085509551055115512551355145515551655175518551955205521552255235524552555265527552855295530553155325533553455355536553755385539554055415542554355445545554655475548554955505551555255535554555555565557555855595560556155625563556455655566556755685569557055715572557355745575557655775578557955805581558255835584558555865587558855895590559155925593559455955596559755985599560056015602560356045605560656075608560956105611561256135614561556165617561856195620562156225623562456255626562756285629563056315632563356345635563656375638563956405641564256435644564556465647564856495650565156525653565456555656565756585659566056615662566356645665566656675668566956705671567256735674567556765677567856795680568156825683568456855686568756885689569056915692569356945695569656975698569957005701570257035704570557065707570857095710571157125713571457155716571757185719572057215722572357245725572657275728572957305731573257335734573557365737573857395740574157425743574457455746574757485749575057515752575357545755575657575758575957605761576257635764576557665767576857695770577157725773577457755776577757785779578057815782578357845785578657875788578957905791579257935794579557965797579857995800580158025803580458055806580758085809581058115812581358145815581658175818581958205821582258235824582558265827582858295830583158325833583458355836583758385839584058415842584358445845584658475848584958505851585258535854585558565857585858595860586158625863586458655866586758685869587058715872587358745875587658775878587958805881588258835884588558865887588858895890589158925893589458955896589758985899590059015902590359045905590659075908590959105911591259135914591559165917591859195920592159225923592459255926592759285929593059315932593359345935593659375938593959405941594259435944594559465947594859495950595159525953595459555956595759585959596059615962596359645965596659675968596959705971597259735974597559765977597859795980598159825983598459855986598759885989599059915992599359945995599659975998599960006001600260036004600560066007600860096010601160126013601460156016601760186019602060216022602360246025602660276028602960306031603260336034603560366037603860396040604160426043604460456046604760486049605060516052605360546055605660576058605960606061606260636064606560666067606860696070607160726073607460756076607760786079608060816082608360846085608660876088608960906091609260936094609560966097609860996100610161026103610461056106610761086109611061116112611361146115611661176118611961206121612261236124612561266127612861296130613161326133613461356136613761386139614061416142614361446145614661476148614961506151615261536154615561566157615861596160616161626163616461656166616761686169617061716172617361746175617661776178617961806181618261836184618561866187618861896190619161926193619461956196619761986199620062016202620362046205620662076208620962106211621262136214621562166217621862196220622162226223622462256226622762286229623062316232623362346235623662376238623962406241624262436244624562466247624862496250625162526253625462556256625762586259626062616262626362646265626662676268626962706271627262736274627562766277627862796280628162826283628462856286628762886289629062916292629362946295629662976298629963006301630263036304630563066307630863096310631163126313631463156316631763186319632063216322632363246325632663276328632963306331633263336334633563366337633863396340634163426343634463456346634763486349635063516352635363546355635663576358635963606361636263636364636563666367636863696370637163726373637463756376637763786379638063816382638363846385638663876388638963906391639263936394639563966397639863996400640164026403640464056406640764086409641064116412641364146415641664176418641964206421642264236424642564266427642864296430643164326433643464356436643764386439644064416442644364446445644664476448644964506451645264536454645564566457645864596460646164626463646464656466646764686469647064716472647364746475647664776478647964806481648264836484648564866487648864896490649164926493649464956496649764986499650065016502650365046505650665076508650965106511651265136514651565166517651865196520652165226523652465256526652765286529653065316532653365346535653665376538653965406541654265436544654565466547654865496550655165526553655465556556655765586559656065616562656365646565656665676568656965706571657265736574657565766577657865796580658165826583658465856586658765886589659065916592659365946595659665976598659966006601660266036604660566066607660866096610661166126613661466156616661766186619662066216622662366246625662666276628662966306631663266336634663566366637663866396640664166426643664466456646664766486649665066516652665366546655665666576658665966606661666266636664666566666667666866696670667166726673667466756676667766786679668066816682668366846685668666876688668966906691669266936694669566966697669866996700670167026703670467056706670767086709671067116712671367146715671667176718671967206721672267236724672567266727672867296730673167326733673467356736673767386739674067416742674367446745674667476748674967506751675267536754675567566757675867596760676167626763676467656766676767686769677067716772677367746775677667776778677967806781678267836784678567866787678867896790679167926793679467956796679767986799680068016802680368046805680668076808680968106811681268136814681568166817681868196820682168226823682468256826682768286829683068316832683368346835683668376838683968406841684268436844684568466847684868496850685168526853685468556856685768586859686068616862686368646865686668676868686968706871687268736874687568766877687868796880688168826883688468856886688768886889689068916892689368946895689668976898689969006901690269036904690569066907690869096910691169126913691469156916691769186919692069216922692369246925692669276928692969306931693269336934693569366937693869396940694169426943694469456946694769486949695069516952695369546955695669576958695969606961696269636964696569666967696869696970697169726973697469756976697769786979698069816982698369846985698669876988698969906991699269936994699569966997699869997000700170027003700470057006700770087009701070117012701370147015701670177018701970207021702270237024702570267027702870297030703170327033703470357036703770387039704070417042704370447045704670477048704970507051705270537054705570567057705870597060706170627063706470657066706770687069707070717072707370747075707670777078707970807081708270837084708570867087708870897090709170927093709470957096709770987099710071017102710371047105710671077108710971107111711271137114711571167117711871197120712171227123712471257126712771287129713071317132713371347135713671377138713971407141714271437144714571467147714871497150715171527153715471557156715771587159716071617162716371647165716671677168716971707171717271737174717571767177717871797180718171827183718471857186718771887189719071917192719371947195719671977198719972007201720272037204720572067207720872097210721172127213721472157216721772187219722072217222722372247225722672277228722972307231723272337234723572367237723872397240724172427243724472457246724772487249725072517252725372547255725672577258725972607261726272637264726572667267726872697270727172727273727472757276727772787279728072817282728372847285728672877288728972907291729272937294729572967297729872997300730173027303730473057306730773087309731073117312731373147315731673177318731973207321732273237324732573267327732873297330733173327333733473357336733773387339734073417342734373447345734673477348734973507351735273537354735573567357735873597360736173627363736473657366736773687369737073717372737373747375737673777378737973807381738273837384738573867387738873897390739173927393739473957396739773987399740074017402740374047405740674077408740974107411741274137414741574167417741874197420742174227423742474257426742774287429743074317432743374347435743674377438743974407441744274437444744574467447744874497450745174527453745474557456745774587459746074617462746374647465746674677468746974707471747274737474747574767477747874797480748174827483748474857486748774887489749074917492749374947495749674977498749975007501750275037504750575067507750875097510751175127513751475157516751775187519752075217522752375247525752675277528752975307531753275337534753575367537753875397540754175427543754475457546754775487549755075517552755375547555755675577558755975607561756275637564756575667567756875697570757175727573757475757576757775787579758075817582758375847585758675877588758975907591759275937594759575967597759875997600760176027603760476057606760776087609761076117612761376147615761676177618761976207621762276237624
  1. %
  2. % $Id$
  3. % This file is part of the FPC documentation.
  4. % Copyright (C) 1997, by Michael Van Canneyt
  5. %
  6. % The FPC documentation is free text; you can redistribute it and/or
  7. % modify it under the terms of the GNU Library General Public License as
  8. % published by the Free Software Foundation; either version 2 of the
  9. % License, or (at your option) any later version.
  10. %
  11. % The FPC Documentation is distributed in the hope that it will be useful,
  12. % but WITHOUT ANY WARRANTY; without even the implied warranty of
  13. % MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  14. % Library General Public License for more details.
  15. %
  16. % You should have received a copy of the GNU Library General Public
  17. % License along with the FPC documentation; see the file COPYING.LIB. If not,
  18. % write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  19. % Boston, MA 02111-1307, USA.
  20. %
  21. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  22. % Preamble.
  23. \input{preamble.inc}
  24. \latex{%
  25. \ifpdf
  26. \pdfinfo{/Author(Michael Van Canneyt)
  27. /Title(Standard units Reference Guide)
  28. /Subject(Free Pascal Reference guide)
  29. /Keywords(Free Pascal, Language, System Unit)
  30. }
  31. \fi}
  32. %
  33. % Settings
  34. %
  35. \makeindex
  36. %
  37. % Syntax style
  38. %
  39. \usepackage{syntax}
  40. \input{syntax/diagram.tex}
  41. %
  42. % Start of document.
  43. %
  44. \begin{document}
  45. \title{Free Pascal :\\ Reference guide.}
  46. \docdescription{Reference guide for Free Pascal, version \fpcversion}
  47. \docversion{1.9}
  48. \input{date.inc}
  49. \author{Micha\"el Van Canneyt}
  50. \maketitle
  51. \tableofcontents
  52. \newpage
  53. \listoftables
  54. \newpage
  55. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  56. % Introduction
  57. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  58. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  59. % About this guide
  60. \section*{About this guide}
  61. This document describes all constants, types, variables, functions and
  62. procedures as they are declared in the system unit.
  63. Furthermore, it describes all pascal constructs supported by \fpc, and lists
  64. all supported data types. It does not, however, give a detailed explanation
  65. of the pascal language. The aim is to list which Pascal constructs are
  66. supported, and to show where the \fpc implementation differs from the
  67. Turbo Pascal implementation.
  68. \subsection*{Notations}
  69. Throughout this document, we will refer to functions, types and variables
  70. with \var{typewriter} font. Functions and procedures have their own
  71. subsections, and for each function or procedure we have the following
  72. topics:
  73. \begin{description}
  74. \item [Declaration] The exact declaration of the function.
  75. \item [Description] What does the procedure exactly do ?
  76. \item [Errors] What errors can occur.
  77. \item [See Also] Cross references to other related functions/commands.
  78. \end{description}
  79. The cross-references come in two flavours:
  80. \begin{itemize}
  81. \item References to other functions in this manual. In the printed copy, a
  82. number will appear after this reference. It refers to the page where this
  83. function is explained. In the on-line help pages, this is a hyperlink,
  84. which can be clicked to jump to the declaration.
  85. \item References to Unix manual pages. (For linux and unix related things only) they
  86. are printed in \var{typewriter} font, and the number after it is the Unix
  87. manual section.
  88. \end{itemize}
  89. \subsection*{Syntax diagrams}
  90. All elements of the pascal language are explained in syntax diagrams.
  91. Syntax diagrams are like flow charts. Reading a syntax diagram means getting
  92. from the left side to the right side, following the arrows.
  93. When the right side of a syntax diagram is reached, and it ends with a single
  94. arrow, this means the syntax diagram is continued on the next line. If
  95. the line ends on 2 arrows pointing to each other, then the diagram is
  96. ended.
  97. Syntactical elements are written like this
  98. \begin{mysyntdiag}
  99. \synt{syntactical\ elements\ are\ like\ this}
  100. \end{mysyntdiag}
  101. Keywords which must be typed exactly as in the diagram:
  102. \begin{mysyntdiag}
  103. \lit*{keywords\ are\ like\ this}
  104. \end{mysyntdiag}
  105. When something can be repeated, there is an arrow around it:
  106. \begin{mysyntdiag}
  107. \<[b] \synt{this\ can\ be\ repeated} \\ \>
  108. \end{mysyntdiag}
  109. When there are different possibilities, they are listed in columns:
  110. \begin{mysyntdiag}
  111. \(
  112. \synt{First\ possibility} \\
  113. \synt{Second\ possibility}
  114. \)
  115. \end{mysyntdiag}
  116. Note, that one of the possibilities can be empty:
  117. \begin{mysyntdiag}
  118. \[
  119. \synt{First\ possibility} \\
  120. \synt{Second\ possibility}
  121. \]
  122. \end{mysyntdiag}
  123. This means that both the first or second possibility are optional.
  124. Of course, all these elements can be combined and nested.
  125. \part{The Pascal language}
  126. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  127. % The Pascal language
  128. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  129. \chapter{Pascal Tokens}
  130. In this chapter we describe all the pascal reserved words, as well as the
  131. various ways to denote strings, numbers, identifiers etc.
  132. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  133. % Symbols
  134. \section{Symbols}
  135. Free Pascal allows all characters, digits and some special ASCII symbols
  136. in a Pascal source file.
  137. \input{syntax/symbol.syn}
  138. The following characters have a special meaning:
  139. \begin{verbatim}
  140. + - * / = < > [ ] . , ( ) : ^ @ { } $ #
  141. \end{verbatim}
  142. and the following character pairs too:
  143. \begin{verbatim}
  144. <= >= := += -= *= /= (* *) (. .) //
  145. \end{verbatim}
  146. When used in a range specifier, the character pair \var{(.} is equivalent to
  147. the left square bracket \var{[}. Likewise, the character pair \var{.)} is
  148. equivalent to the right square bracket \var{]}.
  149. When used for comment delimiters, the character pair \var{(*} is equivalent
  150. to the left brace \var{\{} and the character pair \var{*)} is equivalent
  151. to the right brace \var{\}}.
  152. These character pairs retain their normal meaning in string expressions.
  153. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  154. % Comments
  155. \section{Comments}
  156. \fpc supports the use of nested comments. The following constructs are valid
  157. comments:
  158. \begin{verbatim}
  159. (* This is an old style comment *)
  160. { This is a Turbo Pascal comment }
  161. // This is a Delphi comment. All is ignored till the end of the line.
  162. \end{verbatim}
  163. The following are valid ways of nesting comments:
  164. \begin{verbatim}
  165. { Comment 1 (* comment 2 *) }
  166. (* Comment 1 { comment 2 } *)
  167. { comment 1 // Comment 2 }
  168. (* comment 1 // Comment 2 *)
  169. // comment 1 (* comment 2 *)
  170. // comment 1 { comment 2 }
  171. \end{verbatim}
  172. The last two comments {\em must} be on one line. The following two will give
  173. errors:
  174. \begin{verbatim}
  175. // Valid comment { No longer valid comment !!
  176. }
  177. \end{verbatim}
  178. and
  179. \begin{verbatim}
  180. // Valid comment (* No longer valid comment !!
  181. *)
  182. \end{verbatim}
  183. The compiler will react with a 'invalid character' error when it encounters
  184. such constructs, regardless of the \var{-So} switch.
  185. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  186. % Reserved words
  187. \section{Reserved words}
  188. Reserved words are part of the Pascal language, and cannot be redefined.
  189. They will be denoted as {\sffamily\bfseries this} throughout the syntax
  190. diagrams. Reserved words can be typed regardless of case, i.e. Pascal is
  191. case insensitive.
  192. We make a distinction between Turbo Pascal and Delphi reserved words, since
  193. with the \var{-So} switch, only the Turbo Pascal reserved words are
  194. recognised, and the Delphi ones can be redefined. By default, \fpc
  195. recognises the Delphi reserved words.
  196. \subsection{Turbo Pascal reserved words}
  197. The following keywords exist in Turbo Pascal mode
  198. \begin{multicols}{4}
  199. \begin{verbatim}
  200. absolute
  201. and
  202. array
  203. asm
  204. begin
  205. break
  206. case
  207. const
  208. constructor
  209. continue
  210. destructor
  211. div
  212. do
  213. downto
  214. else
  215. end
  216. file
  217. for
  218. function
  219. goto
  220. if
  221. implementation
  222. in
  223. inherited
  224. inline
  225. interface
  226. label
  227. mod
  228. nil
  229. not
  230. object
  231. of
  232. on
  233. operator
  234. or
  235. packed
  236. procedure
  237. program
  238. record
  239. repeat
  240. self
  241. set
  242. shl
  243. shr
  244. string
  245. then
  246. to
  247. type
  248. unit
  249. until
  250. uses
  251. var
  252. while
  253. with
  254. xor
  255. \end{verbatim}
  256. \end{multicols}
  257. \subsection{Delphi reserved words}
  258. The Delphi (II) reserved words are the same as the pascal ones, plus the
  259. following ones:
  260. \begin{multicols}{4}
  261. \begin{verbatim}
  262. as
  263. class
  264. except
  265. exports
  266. finalization
  267. finally
  268. initialization
  269. is
  270. library
  271. on
  272. property
  273. raise
  274. try
  275. \end{verbatim}
  276. \end{multicols}
  277. \subsection{\fpc reserved words}
  278. On top of the Turbo Pascal and Delphi reserved words, \fpc also considers
  279. the following as reserved words:
  280. \begin{multicols}{4}
  281. \begin{verbatim}
  282. dispose
  283. exit
  284. false
  285. new
  286. true
  287. \end{verbatim}
  288. \end{multicols}
  289. \subsection{Modifiers}
  290. The following is a list of all modifiers. Contrary to Delphi, \fpc doesn't
  291. allow the programmer to redefine these modifiers.
  292. \begin{multicols}{4}
  293. \begin{verbatim}
  294. absolute
  295. abstract
  296. alias
  297. assembler
  298. cdecl
  299. default
  300. export
  301. external
  302. far
  303. forward
  304. index
  305. name
  306. near
  307. override
  308. pascal
  309. popstack
  310. private
  311. protected
  312. public
  313. published
  314. read
  315. register
  316. saveregisters
  317. stdcall
  318. virtual
  319. write
  320. \end{verbatim}
  321. \end{multicols}
  322. \begin{remark}
  323. Predefined types such as \var{Byte}, \var{Boolean} and constants
  324. such as \var{maxint} are {\em not} reserved words. They are
  325. identifiers, declared in the system unit. This means that these types
  326. can be redefined in other units. The programmer is, however, not
  327. encouraged to do this, as it will cause a lot of confusion.
  328. \end{remark}
  329. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  330. % Identifiers
  331. \section{Identifiers}
  332. Identifiers denote constants, types, variables, procedures and functions,
  333. units, and programs. All names of things that are defined are identifiers.
  334. An identifier consists of 255 significant characters (letters, digits and
  335. the underscore character), from which the first must be an alphanumeric
  336. character, or an underscore (\var{\_})
  337. The following diagram gives the basic syntax for identifiers.
  338. \input{syntax/identifier.syn}
  339. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  340. % Numbers
  341. \section{Numbers}
  342. Numbers are by default denoted in decimal notation.
  343. Real (or decimal) numbers are written using engineering or scientific
  344. notation (e.g. \var{0.314E1}).
  345. For integer type constants, \fpc supports 4 formats:
  346. \begin{enumerate}
  347. \item Normal, decimal format (base 10). This is the standard format.
  348. \item Hexadecimal format (base 16), in the same way as Turbo Pascal does.
  349. To specify a constant value in hexadecimal format, prepend it with a dollar
  350. sign (\var{\$}). Thus, the hexadecimal \var{\$FF} equals 255 decimal.
  351. Note that case is insignificant when using hexadecimal constants.
  352. \item As of version 1.0.7, Octal format (base 8) is also supported.
  353. To specify a constant in octal format, prepend it with a ampersand (\&).
  354. For instance 15 is specified in octal notation as \var{\&17}.
  355. \item Binary notation (base 2). A binary number can be specified
  356. by preceding it with a percent sign (\var{\%}). Thus, \var{255} can be
  357. specified in binary notation as \var{\%11111111}.
  358. \end{enumerate}
  359. The following diagrams show the syntax for numbers.
  360. \input{syntax/numbers.syn}
  361. %%% !!!!!!!!!!!!
  362. %%% For 2.0, the range has changed, and constants within
  363. %%% a 64bit range are parsed as int64. and no longer
  364. %%% as reals (except if they don't fit in int64!) !!!! - carl
  365. \begin{remark}
  366. It is to note that all decimal constants which do no fit within
  367. the -2147483648..2147483647 range, are silently and automatically
  368. parsed as real-type constants.
  369. \end{remark}
  370. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  371. % Labels
  372. \section{Labels}
  373. Labels can be digit sequences or identifiers.
  374. \input{syntax/label.syn}
  375. \begin{remark}
  376. Note that the \var{-Sg} switch must be specified before labels can be used.
  377. By default, \fpc doesn't support \var{label} and \var{goto} statements.
  378. \end{remark}
  379. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  380. % Character strings
  381. \section{Character strings}
  382. A character string (or string for short) is a sequence of zero or more
  383. characters from the ASCII character set, enclosed by single quotes, and on 1
  384. line of the program source.
  385. A character set with nothing between the quotes (\var{'{}'}) is an empty
  386. string.
  387. \input{syntax/string.syn}
  388. \chapter{Constants}
  389. Just as in Turbo Pascal, \fpc supports both normal and typed constants.
  390. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  391. % Ordinary constants
  392. \section{Ordinary constants}
  393. Ordinary constants declarations are not different from the Turbo Pascal or
  394. Delphi implementation.
  395. \input{syntax/const.syn}
  396. The compiler must be able to evaluate the expression in a constant
  397. declaration at compile time. This means that most of the functions
  398. in the Run-Time library cannot be used in a constant declaration.
  399. Operators such as \var{+, -, *, /, not, and, or, div, mod, ord, chr,
  400. sizeof, pi, int, trunc, round, frac, odd} can be used, however. For more
  401. information on expressions, see \seec{Expressions}.
  402. Only constants of the following types can be declared: \var{Ordinal types},
  403. \var{Real types}, \var{Char}, and \var{String}.
  404. The following are all valid constant declarations:
  405. \begin{verbatim}
  406. Const
  407. e = 2.7182818; { Real type constant. }
  408. a = 2; { Ordinal (Integer) type constant. }
  409. c = '4'; { Character type constant. }
  410. s = 'This is a constant string'; {String type constant.}
  411. s = chr(32)
  412. ls = SizeOf(Longint);
  413. \end{verbatim}
  414. Assigning a value to an ordinary constant is not permitted.
  415. Thus, given the previous declaration, the following will result
  416. in a compiler error:
  417. \begin{verbatim}
  418. s := 'some other string';
  419. \end{verbatim}
  420. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  421. % Typed constants
  422. \section{Typed constants}
  423. Typed constants serve to provide a program with initialised variables.
  424. Contrary to ordinary constants, they may be assigned to at run-time.
  425. The difference with normal variables is that their value is initialised
  426. when the program starts, whereas normal variables must be initialised
  427. explicitly.
  428. \input{syntax/tconst.syn}
  429. Given the declaration:
  430. \begin{verbatim}
  431. Const
  432. S : String = 'This is a typed constant string';
  433. \end{verbatim}
  434. The following is a valid assignment:
  435. \begin{verbatim}
  436. S := 'Result : '+Func;
  437. \end{verbatim}
  438. Where \var{Func} is a function that returns a \var{String}.
  439. Typed constants are often used to initialize arrays and records. For arrays,
  440. the initial elements must be specified, surrounded by round brackets, and
  441. separated by commas. The number of elements must be exactly the same as
  442. the number of elements in the declaration of the type.
  443. As an example:
  444. \begin{verbatim}
  445. Const
  446. tt : array [1..3] of string[20] = ('ikke', 'gij', 'hij');
  447. ti : array [1..3] of Longint = (1,2,3);
  448. \end{verbatim}
  449. For constant records, each element of the record should be specified, in
  450. the form \var{Field : Value}, separated by commas, and surrounded by round
  451. brackets.
  452. As an example:
  453. \begin{verbatim}
  454. Type
  455. Point = record
  456. X,Y : Real
  457. end;
  458. Const
  459. Origin : Point = (X:0.0; Y:0.0);
  460. \end{verbatim}
  461. The order of the fields in a constant record needs to be the same as in the type declaration,
  462. otherwise a compile-time error will occur.
  463. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  464. % resource strings
  465. \section{Resource strings}
  466. \label{se:resourcestring}
  467. A special kind of constant declaration part is the \var{Resourestring}
  468. part. This part is like a \var{Const} section, but it only allows
  469. to declare constant of type string. This part is only available in the
  470. \var{Delphi} or \var{objfpc} mode.
  471. The following is an example of a resourcestring definition:
  472. \begin{verbatim}
  473. Resourcestring
  474. FileMenu = '&File...';
  475. EditMenu = '&Edit...';
  476. \end{verbatim}
  477. All string constants defined in the resourcestring section are stored
  478. in special tables, allowing to manipulate the values of the strings
  479. at runtime with some special mechanisms.
  480. Semantically, the strings are like constants; Values can not be assigned to
  481. them, except through the special mechanisms in the objpas unit. However,
  482. they can be used in assignments or expressions as normal constants.
  483. The main use of the resourcestring section is to provide an easy means
  484. of internationalization.
  485. More on the subject of resourcestrings can be found in the \progref, and
  486. in the chapter on the \file{objpas} later in this manual.
  487. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  488. % Types
  489. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  490. \chapter{Types}
  491. All variables have a type. \fpc supports the same basic types as Turbo
  492. Pascal, with some extra types from Delphi.
  493. The programmer can declare his own types, which is in essence defining an identifier
  494. that can be used to denote this custom type when declaring variables further
  495. in the source code.
  496. \input{syntax/typedecl.syn}
  497. There are 7 major type classes :
  498. \input{syntax/type.syn}
  499. The last class, {\sffamily type identifier}, is just a means to give another
  500. name to a type. This presents a way to make types platform independent, by
  501. only using these types, and then defining these types for each platform
  502. individually. The programmer that uses these units doesn't have to worry
  503. about type size and so on. It also allows to use shortcut names for
  504. fully qualified type names. e.g. define \var{system.longint} as
  505. \var{Olongint} and then redefine \var{longint}.
  506. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  507. % Base types
  508. \section{Base types}
  509. The base or simple types of \fpc are the Delphi types.
  510. We will discuss each separate.
  511. \input{syntax/typesim.syn}
  512. \subsection{Ordinal types}
  513. With the exception of \var{int64}, \var{qword} and Real types,
  514. all base types are ordinal types. Ordinal types have the following
  515. characteristics:
  516. \begin{enumerate}
  517. \item Ordinal types are countable and ordered, i.e. it is, in principle,
  518. possible to start counting them one bye one, in a specified order.
  519. This property allows the operation of functions as \seep{Inc}, \seef{Ord},
  520. \seep{Dec}
  521. on ordinal types to be defined.
  522. \item Ordinal values have a smallest possible value. Trying to apply the
  523. \seef{Pred} function on the smallest possible value will generate a range
  524. check error if range checking is enabled.
  525. \item Ordinal values have a largest possible value. Trying to apply the
  526. \seef{Succ} function on the largest possible value will generate a range
  527. check error if range checking is enabled.
  528. \end{enumerate}
  529. \subsubsection{Integers}
  530. A list of pre-defined integer types is presented in \seet{integerstyp}
  531. \begin{FPCltable}{l}{Predefined integer types}{integerstyp}
  532. Name\\ \hline
  533. Integer \\
  534. Shortint \\
  535. SmallInt \\
  536. Longint \\
  537. Longword \\
  538. Int64 \\
  539. Byte \\
  540. Word \\
  541. Cardinal \\
  542. QWord \\
  543. Boolean \\
  544. ByteBool \\
  545. LongBool \\
  546. Char \\ \hline
  547. \end{FPCltable}
  548. The integer types, and their ranges and sizes, that are predefined in
  549. \fpc are listed in \seet{integersranges}. It is to note that
  550. the \var{qword} and \var{int64} types are not true ordinals, so
  551. some pascal constructs will not work with these two integer types.
  552. \begin{FPCltable}{lcr}{Predefined integer types}{integersranges}
  553. Type & Range & Size in bytes \\ \hline
  554. Byte & 0 .. 255 & 1 \\
  555. Shortint & -128 .. 127 & 1\\
  556. Smallint & -32768 .. 32767 & 2\\
  557. Word & 0 .. 65535 & 2 \\
  558. Integer & either smallint, longint or int64 & size 2,4 or 8 \\
  559. Cardinal & either word, longword or qword & size 2,4 or 8 \\
  560. Longint & -2147483648 .. 2147483647 & 4\\
  561. Longword & 0..4294967295 & 4 \\
  562. Int64 & -9223372036854775808 .. 9223372036854775807 & 8 \\
  563. QWord & 0 .. 18446744073709551615 & 8 \\ \hline
  564. \end{FPCltable}
  565. The \var{integer} type maps to the smallint type in the default
  566. \fpc mode. It maps to either a longint or int64 in either Delphi or ObjFPC
  567. mode. The \var{cardinal} type is currently always mapped to the
  568. longword type.
  569. % This IS NOT TRUE, this is a 32-bit compiler, so the integer type
  570. % will always be the same independently the CPU type.
  571. %This is summarized in \seet{integer32type} for 32-bit processors
  572. %(such as Intel 80x86, Motorola 680x0, PowerPC 32-bit, SPARC v7, MIPS32), and
  573. %in \seet{integer64type} for 64-bit processors (such as Alpha AXP,
  574. %SPARC v9 or later, Intel Itanium, MIPS64).
  575. %\begin{FPCltable}{lcr}{\var{Integer} type mapping for 32-bit processors}{integer32type}
  576. %Compiler mode & Range & Size in bytes \\ \hline
  577. %<default> & -32768 .. 32767 & 2\\
  578. %tp & -32768 .. 32767 & 2\\
  579. %Delphi & -2147483648 .. 2147483647 & 4\\
  580. %ObjFPC & -2147483648 .. 2147483647 & 4\\
  581. %\end{FPCltable}
  582. %\begin{FPCltable}{lcr}{\var{Integer} type mapping for 64-bit processors}{integer64type}
  583. %Compiler mode & Range & Size in bytes \\ \hline
  584. %<default> & -32768 .. 32767 & 2\\
  585. %tp & -32768 .. 32767 & 2\\
  586. %Delphi & -9223372036854775808 .. 9223372036854775807 & 8 \\
  587. %ObjFPC & -9223372036854775808 .. 9223372036854775807 & 8 \\
  588. %\end{FPCltable}
  589. \fpc does automatic type conversion in expressions where different kinds of
  590. integer types are used.
  591. \subsubsection{Boolean types}
  592. \fpc supports the \var{Boolean} type, with its two pre-defined possible
  593. values \var{True} and \var{False}. It also supports the \var{ByteBool},
  594. \var{WordBool} and \var{LongBool} types. These are the only two values that can be
  595. assigned to a \var{Boolean} type. Of course, any expression that resolves
  596. to a \var{boolean} value, can also be assigned to a boolean type.
  597. \begin{FPCltable}{lll}{Boolean types}{booleantypes}
  598. Name & Size & Ord(True) \\ \hline
  599. Boolean & 1 & 1 \\
  600. ByteBool & 1 & Any nonzero value \\
  601. WordBool & 2 & Any nonzero value \\
  602. LongBool & 4 & Any nonzero value \\ \hline
  603. \end{FPCltable}
  604. Assuming \var{B} to be of type \var{Boolean}, the following are valid
  605. assignments:
  606. \begin{verbatim}
  607. B := True;
  608. B := False;
  609. B := 1<>2; { Results in B := True }
  610. \end{verbatim}
  611. Boolean expressions are also used in conditions.
  612. \begin{remark}
  613. In \fpc, boolean expressions are always evaluated in such a
  614. way that when the result is known, the rest of the expression will no longer
  615. be evaluated (Called short-cut evaluation). In the following example, the function \var{Func} will never
  616. be called, which may have strange side-effects.
  617. \begin{verbatim}
  618. ...
  619. B := False;
  620. A := B and Func;
  621. \end{verbatim}
  622. Here \var{Func} is a function which returns a \var{Boolean} type.
  623. \end{remark}
  624. \subsubsection{Enumeration types}
  625. Enumeration types are supported in \fpc. On top of the Turbo Pascal
  626. implementation, \fpc allows also a C-style extension of the
  627. enumeration type, where a value is assigned to a particular element of
  628. the enumeration list.
  629. \input{syntax/typeenum.syn}
  630. (see \seec{Expressions} for how to use expressions)
  631. When using assigned enumerated types, the assigned elements must be in
  632. ascending numerical order in the list, or the compiler will complain.
  633. The expressions used in assigned enumerated elements must be known at
  634. compile time.
  635. So the following is a correct enumerated type declaration:
  636. \begin{verbatim}
  637. Type
  638. Direction = ( North, East, South, West );
  639. \end{verbatim}
  640. The C style enumeration type looks as follows:
  641. \begin{verbatim}
  642. Type
  643. EnumType = (one, two, three, forty := 40,fortyone);
  644. \end{verbatim}
  645. As a result, the ordinal number of \var{forty} is \var{40}, and not \var{3},
  646. as it would be when the \var{':= 40'} wasn't present.
  647. The ordinal value of \var{fortyone} is then {41}, and not \var{4}, as it
  648. would be when the assignment wasn't present. After an assignment in an
  649. enumerated definition the compiler adds 1 to the assigned value to assign to
  650. the next enumerated value.
  651. When specifying such an enumeration type, it is important to keep in mind
  652. that the enumerated elements should be kept in ascending order. The
  653. following will produce a compiler error:
  654. \begin{verbatim}
  655. Type
  656. EnumType = (one, two, three, forty := 40, thirty := 30);
  657. \end{verbatim}
  658. It is necessary to keep \var{forty} and \var{thirty} in the correct order.
  659. When using enumeration types it is important to keep the following points
  660. in mind:
  661. \begin{enumerate}
  662. \item The \var{Pred} and \var{Succ} functions cannot be used on
  663. this kind of enumeration types. Trying to do this anyhow will result in a
  664. compiler error.
  665. \item Enumeration types stored using a default size. This behaviour can be changed
  666. with the \var{\{\$PACKENUM n\}} compiler directive, which
  667. tells the compiler the minimal number of bytes to be used for enumeration
  668. types.
  669. For instance
  670. \begin{verbatim}
  671. Type
  672. {$PACKENUM 4}
  673. LargeEnum = ( BigOne, BigTwo, BigThree );
  674. {$PACKENUM 1}
  675. SmallEnum = ( one, two, three );
  676. Var S : SmallEnum;
  677. L : LargeEnum;
  678. begin
  679. WriteLn ('Small enum : ',SizeOf(S));
  680. WriteLn ('Large enum : ',SizeOf(L));
  681. end.
  682. \end{verbatim}
  683. will, when run, print the following:
  684. \begin{verbatim}
  685. Small enum : 1
  686. Large enum : 4
  687. \end{verbatim}
  688. \end{enumerate}
  689. More information can be found in the \progref, in the compiler directives
  690. section.
  691. \subsubsection{Subrange types}
  692. A subrange type is a range of values from an ordinal type (the {\em host}
  693. type). To define a subrange type, one must specify it's limiting values: the
  694. highest and lowest value of the type.
  695. \input{syntax/typesubr.syn}
  696. Some of the predefined \var{integer} types are defined as subrange types:
  697. \begin{verbatim}
  698. Type
  699. Longint = $80000000..$7fffffff;
  700. Integer = -32768..32767;
  701. shortint = -128..127;
  702. byte = 0..255;
  703. Word = 0..65535;
  704. \end{verbatim}
  705. Subrange types of enumeration types can also be defined:
  706. \begin{verbatim}
  707. Type
  708. Days = (monday,tuesday,wednesday,thursday,friday,
  709. saturday,sunday);
  710. WorkDays = monday .. friday;
  711. WeekEnd = Saturday .. Sunday;
  712. \end{verbatim}
  713. \subsection{Real types}
  714. \fpc uses the math coprocessor (or emulation) for all its floating-point
  715. calculations. The Real native type is processor dependant,
  716. but it is either Single or Double. Only the IEEE floating point types are
  717. supported, and these depend on the target processor and emulation options.
  718. The true Turbo Pascal compatible types are listed in
  719. \seet{Reals}.
  720. \begin{FPCltable}{lccr}{Supported Real types}{Reals}
  721. Type & Range & Significant digits & Size \\ \hline
  722. Real & platform dependant & ??? & 4 or 8 \\
  723. Single & 1.5E-45 .. 3.4E38 & 7-8 & 4 \\
  724. Double & 5.0E-324 .. 1.7E308 & 15-16 & 8 \\
  725. Extended & 1.9E-4951 .. 1.1E4932 & 19-20 & 10\\
  726. Comp & -2E64+1 .. 2E63-1 & 19-20 & 8 \\
  727. \end{FPCltable}
  728. The \var{Comp} type is, in effect, a 64-bit integer and is not available
  729. on all target platforms. To get more information on the supported types
  730. for each platform, refer to the \progref.
  731. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  732. % Character types
  733. \section{Character types}
  734. \subsection{Char}
  735. \fpc supports the type \var{Char}. A \var{Char} is exactly 1 byte in
  736. size, and contains one character.
  737. A character constant can be specified by enclosing the character in single
  738. quotes, as follows : 'a' or 'A' are both character constants.
  739. A character can also be specified by its ASCII
  740. value, by preceding the ASCII value with the number symbol (\#). For example
  741. specifying \var{\#65} would be the same as \var{'A'}.
  742. Also, the caret character (\verb+^+) can be used in combination with a letter to
  743. specify a character with ASCII value less than 27. Thus \verb+^G+ equals
  744. \var{\#7} (G is the seventh letter in the alphabet.)
  745. When the single quote character must be represented, it should be typed
  746. two times successively, thus \var{''''} represents the single quote character.
  747. \subsection{Strings}
  748. \fpc supports the \var{String} type as it is defined in Turbo Pascal
  749. (A sequence of characters with a specified length) and it
  750. supports ansistrings as in Delphi.
  751. To declare a variable as a string, use the following type specification:
  752. \input{syntax/sstring.syn}
  753. The meaning of a string declaration statement is interpreted differently
  754. depending on the \var{\{\$H\}} switch. The above declaration can declare an
  755. ansistrng or a short string.
  756. Whatever the actual type, ansistrings and short strings can be used
  757. interchangeably. The compiler always takes care of the necessary type
  758. conversions. Note, however, that the result of an expression that contains
  759. ansistrings and short strings will always be an ansistring.
  760. \subsection{Short strings}
  761. A string declaration declares a short string in the following cases:
  762. \begin{enumerate}
  763. \item If the switch is off: \var{\{\$H-\}}, the string declaration
  764. will always be a short string declaration.
  765. \item If the switch is on \var{\{\$H+\}}, and there is a length
  766. specifier, the declaration is a short string declaration.
  767. \end{enumerate}
  768. The predefined type \var{ShortString} is defined as a string of length 255:
  769. \begin{verbatim}
  770. ShortString = String[255];
  771. \end{verbatim}
  772. If the size of the string is not specified, \var{255} is taken as a
  773. default. The length of the string can be obtained with the \seef{Length}
  774. standard runtime routine.
  775. For example in
  776. \begin{verbatim}
  777. {$H-}
  778. Type
  779. NameString = String[10];
  780. StreetString = String;
  781. \end{verbatim}
  782. \var{NameString} can contain a maximum of 10 characters. While
  783. \var{StreetString} can contain up to 255 characters.
  784. \subsection{Ansistrings}
  785. If the \var{\{\$H\}} switch is on, then a string definition that doesn't
  786. contain a length specifier, will be regarded as an ansistring.
  787. Ansistrings are strings that have no length limit. They are reference
  788. counted. Internally, an ansistring is treated as a pointer.
  789. If the string is empty (\var{''}), then the pointer is nil.
  790. If the string is not empty, then the pointer points to a structure in
  791. heap memory.
  792. It is possible to typecast an ansistring to a pchar.
  793. If the string is empty (so the pointer is nil) then the compiler
  794. makes sure that the typecasted pchar will point to a null byte. AnsiStrings
  795. can be unlimited in length.
  796. Assigning one ansistring to another doesn't involve moving the actual
  797. string. A statement
  798. \begin{verbatim}
  799. S2:=S1;
  800. \end{verbatim}
  801. results in the reference count of \var{S2} being decreased by one,
  802. The referece count of \var{S1} is increased by one, and finally \var{S1}
  803. (as a pointer) is copied to \var{S2}. This is a significant speed-up in
  804. the code.
  805. If a reference count reaches zero, then the memory occupied by the
  806. string is deallocated automatically, so no memory leaks arise.
  807. When an ansistring is declared, the \fpc compiler initially
  808. allocates just memory for a pointer, not more. This pointer is guaranteed
  809. to be nil, meaning that the string is initially empty. This is
  810. true for local, global or part of a structure (arrays, records or objects).
  811. This does introduce an overhead. For instance, declaring
  812. \begin{verbatim}
  813. Var
  814. A : Array[1..100000] of string;
  815. \end{verbatim}
  816. Will copy 100,000 times \var{nil} into \var{A}. When \var{A} goes out of scope, then
  817. the 100,000 strings will be dereferenced one by one. All this happens
  818. invisibly for the programmer, but when considering performance issues,
  819. this is important.
  820. Memory will be allocated only when the string is assigned a value.
  821. If the string goes out of scope, then it is automatically dereferenced.
  822. If a value is assigned to a character of a string that has a reference count
  823. greater than 1, such as in the following
  824. statements:
  825. \begin{verbatim}
  826. S:=T; { reference count for S and T is now 2 }
  827. S[I]:='@';
  828. \end{verbatim}
  829. then a copy of the string is created before the assignment. This is known
  830. as {\em copy-on-write} semantics.
  831. The \seef{Length} function must be used to get the length of an
  832. ansistring.
  833. To set the length of an ansistring, the \seep{SetLength} function must be used.
  834. Constant ansistrings have a reference count of -1 and are treated specially.
  835. Ansistrings are converted to short strings by the compiler if needed,
  836. this means that the use of ansistrings and short strings can be mixed
  837. without problems.
  838. Ansistrings can be typecasted to \var{PChar} or \var{Pointer} types:
  839. \begin{verbatim}
  840. Var P : Pointer;
  841. PC : PChar;
  842. S : AnsiString;
  843. begin
  844. S :='This is an ansistring';
  845. PC:=Pchar(S);
  846. P :=Pointer(S);
  847. \end{verbatim}
  848. There is a difference between the two typecasts. When an empty
  849. ansistring is typecasted to a pointer, the pointer wil be \var{Nil}. If an
  850. empty ansistring is typecasted to a \var{PChar}, then the result will be a pointer to a
  851. zero byte (an empty string).
  852. The result of such a typecast must be used with care. In general, it is best
  853. to consider the result of such a typecast as read-only, i.e. suitable for
  854. passing to a procedure that needs a constant pchar argument.
  855. It is therefore NOT advisable to typecast one of the following:
  856. \begin{enumerate}
  857. \item expressions.
  858. \item strings that have reference count larger than 0.
  859. (call uniquestring to ensure a string has reference count 1)
  860. \end{enumerate}
  861. \subsection{Constant strings}
  862. To specify a constant string, it must be enclosed in single-quotes, just
  863. as a \var{Char} type, only now more than one character is allowed.
  864. Given that \var{S} is of type \var{String}, the following are valid assignments:
  865. \begin{verbatim}
  866. S := 'This is a string.';
  867. S := 'One'+', Two'+', Three';
  868. S := 'This isn''t difficult !';
  869. S := 'This is a weird character : '#145' !';
  870. \end{verbatim}
  871. As can be seen, the single quote character is represented by 2 single-quote
  872. characters next to each other. Strange characters can be specified by their
  873. ASCII value.
  874. The example shows also that two strings can be added. The resulting string is
  875. just the concatenation of the first with the second string, without spaces in
  876. between them. Strings can not be substracted, however.
  877. Whether the constant string is stored as an ansistring or a short string
  878. depends on the settings of the \var{\{\$H\}} switch.
  879. \subsection{PChar}
  880. \fpc supports the Delphi implementation of the \var{PChar} type. \var{PChar}
  881. is defined as a pointer to a \var{Char} type, but allows additional
  882. operations.
  883. The \var{PChar} type can be understood best as the Pascal equivalent of a
  884. C-style null-terminated string, i.e. a variable of type \var{PChar} is a
  885. pointer that points to an array of type \var{Char}, which is ended by a
  886. null-character (\var{\#0}).
  887. \fpc supports initializing of \var{PChar} typed constants, or a direct
  888. assignment. For example, the following pieces of code are equivalent:
  889. \begin{verbatim}
  890. program one;
  891. var p : PChar;
  892. begin
  893. P := 'This is a null-terminated string.';
  894. WriteLn (P);
  895. end.
  896. \end{verbatim}
  897. Results in the same as
  898. \begin{verbatim}
  899. program two;
  900. const P : PChar = 'This is a null-terminated string.'
  901. begin
  902. WriteLn (P);
  903. end.
  904. \end{verbatim}
  905. These examples also show that it is possible to write {\em the contents} of
  906. the string to a file of type \var{Text}.
  907. The \seestrings unit contains procedures and functions that manipulate the
  908. \var{PChar} type as in the standard C library.
  909. Since it is equivalent to a pointer to a type \var{Char} variable, it is
  910. also possible to do the following:
  911. \begin{verbatim}
  912. Program three;
  913. Var S : String[30];
  914. P : PChar;
  915. begin
  916. S := 'This is a null-terminated string.'#0;
  917. P := @S[1];
  918. WriteLn (P);
  919. end.
  920. \end{verbatim}
  921. This will have the same result as the previous two examples.
  922. Null-terminated strings cannot be added as normal Pascal
  923. strings. If two \var{PChar} strings mustt be concatenated; the functions from
  924. the unit \seestrings must be used.
  925. However, it is possible to do some pointer arithmetic. The
  926. operators \var{+} and \var{-} can be used to do operations on \var{PChar} pointers.
  927. In \seet{PCharMath}, \var{P} and \var{Q} are of type \var{PChar}, and
  928. \var{I} is of type \var{Longint}.
  929. \begin{FPCltable}{lr}{\var{PChar} pointer arithmetic}{PCharMath}
  930. Operation & Result \\ \hline
  931. \var{P + I} & Adds \var{I} to the address pointed to by \var{P}. \\
  932. \var{I + P} & Adds \var{I} to the address pointed to by \var{P}. \\
  933. \var{P - I} & Substracts \var{I} from the address pointed to by \var{P}. \\
  934. \var{P - Q} & Returns, as an integer, the distance between 2 addresses \\
  935. & (or the number of characters between \var{P} and \var{Q}) \\
  936. \hline
  937. \end{FPCltable}
  938. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  939. % Structured Types
  940. \section{Structured Types}
  941. A structured type is a type that can hold multiple values in one variable.
  942. Stuctured types can be nested to unlimited levels.
  943. \input{syntax/typestru.syn}
  944. Unlike Delphi, \fpc does not support the keyword \var{Packed} for all
  945. structured types, as can be seen in the syntax diagram. It will be mentioned
  946. when a type supports the \var{packed} keyword.
  947. In the following, each of the possible structured types is discussed.
  948. \subsection{Arrays}
  949. \fpc supports arrays as in Turbo Pascal, multi-dimensional arrays
  950. and packed arrays are also supported:
  951. \input{syntax/typearr.syn}
  952. The following is a valid array declaration:
  953. \begin{verbatim}
  954. Type
  955. RealArray = Array [1..100] of Real;
  956. \end{verbatim}
  957. As in Turbo Pascal, if the array component type is in itself an array, it is
  958. possible to combine the two arrays into one multi-dimensional array. The
  959. following declaration:
  960. \begin{verbatim}
  961. Type
  962. APoints = array[1..100] of Array[1..3] of Real;
  963. \end{verbatim}
  964. is equivalent to the following declaration:
  965. \begin{verbatim}
  966. Type
  967. APoints = array[1..100,1..3] of Real;
  968. \end{verbatim}
  969. The functions \seef{High} and \seef{Low} return the high and low bounds of
  970. the leftmost index type of the array. In the above case, this would be 100
  971. and 1.
  972. \subsection{Record types}
  973. \fpc supports fixed records and records with variant parts.
  974. The syntax diagram for a record type is
  975. \input{syntax/typerec.syn}
  976. So the following are valid record types declarations:
  977. \begin{verbatim}
  978. Type
  979. Point = Record
  980. X,Y,Z : Real;
  981. end;
  982. RPoint = Record
  983. Case Boolean of
  984. False : (X,Y,Z : Real);
  985. True : (R,theta,phi : Real);
  986. end;
  987. BetterRPoint = Record
  988. Case UsePolar : Boolean of
  989. False : (X,Y,Z : Real);
  990. True : (R,theta,phi : Real);
  991. end;
  992. \end{verbatim}
  993. The variant part must be last in the record. The optional identifier in the
  994. case statement serves to access the tag field value, which otherwise would
  995. be invisible to the programmer. It can be used to see which variant is
  996. active at a certain time. In effect, it introduces a new field in the
  997. record.
  998. \begin{remark}
  999. It is possible to nest variant parts, as in:
  1000. \begin{verbatim}
  1001. Type
  1002. MyRec = Record
  1003. X : Longint;
  1004. Case byte of
  1005. 2 : (Y : Longint;
  1006. case byte of
  1007. 3 : (Z : Longint);
  1008. );
  1009. end;
  1010. \end{verbatim}
  1011. \end{remark}
  1012. The size of a record is the sum of the sizes of its fields, each size of a
  1013. field is rounded up to a power of two. If the record contains a variant part, the size
  1014. of the variant part is the size of the biggest variant, plus the size of the
  1015. tag field type {\em if an identifier was declared for it}. Here also, the size of
  1016. each part is first rounded up to two. So in the above example,
  1017. \seef{SizeOf} would return 24 for \var{Point}, 24 for \var{RPoint} and
  1018. 26 for \var{BetterRPoint}. For \var{MyRec}, the value would be 12.
  1019. If a typed file with records, produced by a Turbo Pascal program, must be read,
  1020. then chances are that attempting to read that file correctly will fail.
  1021. The reason for this is that by default, elements of a record are aligned at
  1022. 2-byte boundaries, for performance reasons. This default behaviour can be
  1023. changed with the \var{\{\$PackRecords n\}} switch. Possible values for
  1024. \var{n} are 1, 2, 4, 16 or \var{Default}.
  1025. This switch tells the compiler to align elements of a record or object or
  1026. class that have size larger than \var{n} on \var{n} byte boundaries.
  1027. Elements that have size smaller or equal than \var{n} are aligned on
  1028. natural boundaries, i.e. to the first power of two that is larger than or
  1029. equal to the size of the record element.
  1030. The keyword \var{Default} selects the default value for the platform
  1031. that the code is compiled for (currently, this is 2 on all platforms)
  1032. Take a look at the following program:
  1033. \begin{verbatim}
  1034. Program PackRecordsDemo;
  1035. type
  1036. {$PackRecords 2}
  1037. Trec1 = Record
  1038. A : byte;
  1039. B : Word;
  1040. end;
  1041. {$PackRecords 1}
  1042. Trec2 = Record
  1043. A : Byte;
  1044. B : Word;
  1045. end;
  1046. {$PackRecords 2}
  1047. Trec3 = Record
  1048. A,B : byte;
  1049. end;
  1050. {$PackRecords 1}
  1051. Trec4 = Record
  1052. A,B : Byte;
  1053. end;
  1054. {$PackRecords 4}
  1055. Trec5 = Record
  1056. A : Byte;
  1057. B : Array[1..3] of byte;
  1058. C : byte;
  1059. end;
  1060. {$PackRecords 8}
  1061. Trec6 = Record
  1062. A : Byte;
  1063. B : Array[1..3] of byte;
  1064. C : byte;
  1065. end;
  1066. {$PackRecords 4}
  1067. Trec7 = Record
  1068. A : Byte;
  1069. B : Array[1..7] of byte;
  1070. C : byte;
  1071. end;
  1072. {$PackRecords 8}
  1073. Trec8 = Record
  1074. A : Byte;
  1075. B : Array[1..7] of byte;
  1076. C : byte;
  1077. end;
  1078. Var rec1 : Trec1;
  1079. rec2 : Trec2;
  1080. rec3 : TRec3;
  1081. rec4 : TRec4;
  1082. rec5 : Trec5;
  1083. rec6 : TRec6;
  1084. rec7 : TRec7;
  1085. rec8 : TRec8;
  1086. begin
  1087. Write ('Size Trec1 : ',SizeOf(Trec1));
  1088. Writeln (' Offset B : ',Longint(@rec1.B)-Longint(@rec1));
  1089. Write ('Size Trec2 : ',SizeOf(Trec2));
  1090. Writeln (' Offset B : ',Longint(@rec2.B)-Longint(@rec2));
  1091. Write ('Size Trec3 : ',SizeOf(Trec3));
  1092. Writeln (' Offset B : ',Longint(@rec3.B)-Longint(@rec3));
  1093. Write ('Size Trec4 : ',SizeOf(Trec4));
  1094. Writeln (' Offset B : ',Longint(@rec4.B)-Longint(@rec4));
  1095. Write ('Size Trec5 : ',SizeOf(Trec5));
  1096. Writeln (' Offset B : ',Longint(@rec5.B)-Longint(@rec5),
  1097. ' Offset C : ',Longint(@rec5.C)-Longint(@rec5));
  1098. Write ('Size Trec6 : ',SizeOf(Trec6));
  1099. Writeln (' Offset B : ',Longint(@rec6.B)-Longint(@rec6),
  1100. ' Offset C : ',Longint(@rec6.C)-Longint(@rec6));
  1101. Write ('Size Trec7 : ',SizeOf(Trec7));
  1102. Writeln (' Offset B : ',Longint(@rec7.B)-Longint(@rec7),
  1103. ' Offset C : ',Longint(@rec7.C)-Longint(@rec7));
  1104. Write ('Size Trec8 : ',SizeOf(Trec8));
  1105. Writeln (' Offset B : ',Longint(@rec8.B)-Longint(@rec8),
  1106. ' Offset C : ',Longint(@rec8.C)-Longint(@rec8));
  1107. end.
  1108. \end{verbatim}
  1109. The output of this program will be :
  1110. \begin{verbatim}
  1111. Size Trec1 : 4 Offset B : 2
  1112. Size Trec2 : 3 Offset B : 1
  1113. Size Trec3 : 2 Offset B : 1
  1114. Size Trec4 : 2 Offset B : 1
  1115. Size Trec5 : 8 Offset B : 4 Offset C : 7
  1116. Size Trec6 : 8 Offset B : 4 Offset C : 7
  1117. Size Trec7 : 12 Offset B : 4 Offset C : 11
  1118. Size Trec8 : 16 Offset B : 8 Offset C : 15
  1119. \end{verbatim}
  1120. And this is as expected. In \var{Trec1}, since \var{B} has size 2, it is
  1121. aligned on a 2 byte boundary, thus leaving an empty byte between \var{A}
  1122. and \var{B}, and making the total size 4. In \var{Trec2}, \var{B} is aligned
  1123. on a 1-byte boundary, right after \var{A}, hence, the total size of the
  1124. record is 3.
  1125. For \var{Trec3}, the sizes of \var{A,B} are 1, and hence they are aligned on 1
  1126. byte boundaries. The same is true for \var{Trec4}.
  1127. For \var{Trec5}, since the size of B -- 3 -- is smaller than 4, \var{B} will
  1128. be on a 4-byte boundary, as this is the first power of two that is
  1129. larger than it's size. The same holds for \var{Trec6}.
  1130. For \var{Trec7}, \var{B} is aligned on a 4 byte boundary, since it's size --
  1131. 7 -- is larger than 4. However, in \var{Trec8}, it is aligned on a 8-byte
  1132. boundary, since 8 is the first power of two that is greater than 7, thus
  1133. making the total size of the record 16.
  1134. \fpc supports also the 'packed record', this is a record where all the
  1135. elements are byte-aligned.
  1136. Thus the two following declarations are equivalent:
  1137. \begin{verbatim}
  1138. {$PackRecords 1}
  1139. Trec2 = Record
  1140. A : Byte;
  1141. B : Word;
  1142. end;
  1143. {$PackRecords 2}
  1144. \end{verbatim}
  1145. and
  1146. \begin{verbatim}
  1147. Trec2 = Packed Record
  1148. A : Byte;
  1149. B : Word;
  1150. end;
  1151. \end{verbatim}
  1152. Note the \var{\{\$PackRecords 2\}} after the first declaration !
  1153. \subsection{Set types}
  1154. \fpc supports the set types as in Turbo Pascal. The prototype of a set
  1155. declaration is:
  1156. \input{syntax/typeset.syn}
  1157. Each of the elements of \var{SetType} must be of type \var{TargetType}.
  1158. \var{TargetType} can be any ordinal type with a range between \var{0} and
  1159. \var{255}. A set can contain maximally \var{255} elements.
  1160. The following are valid set declaration:
  1161. \begin{verbatim}
  1162. Type
  1163. Junk = Set of Char;
  1164. Days = (Mon, Tue, Wed, Thu, Fri, Sat, Sun);
  1165. WorkDays : Set of days;
  1166. \end{verbatim}
  1167. Given this set declarations, the following assignment is legal:
  1168. \begin{verbatim}
  1169. WorkDays := [ Mon, Tue, Wed, Thu, Fri];
  1170. \end{verbatim}
  1171. The operators and functions for manipulations of sets are listed in
  1172. \seet{SetOps}.
  1173. \begin{FPCltable}{lr}{Set Manipulation operators}{SetOps}
  1174. Operation & Operator \\ \hline
  1175. Union & + \\
  1176. Difference & - \\
  1177. Intersection & * \\
  1178. Add element & \var{include} \\
  1179. Delete element & \var{exclude} \\ \hline
  1180. \end{FPCltable}
  1181. Two sets can be compared with the \var{<>} and \var{=} operators, but not
  1182. (yet) with the \var{<} and \var{>} operators.
  1183. The compiler stores small sets (less than 32 elements) in a Longint, if the
  1184. type range allows it. This allows for faster processing and decreases
  1185. program size. Otherwise, sets are stored in 32 bytes.
  1186. \subsection{File types}
  1187. File types are types that store a sequence of some base type, which can be
  1188. any type except another file type. It can contain (in principle) an infinite
  1189. number of elements.
  1190. File types are used commonly to store data on disk. Nothing prevents the programmer,
  1191. however, from writing a file driver that stores it's data in memory.
  1192. Here is the type declaration for a file type:
  1193. \input{syntax/typefil.syn}
  1194. If no type identifier is given, then the file is an untyped file; it can be
  1195. considered as equivalent to a file of bytes. Untyped files require special
  1196. commands to act on them (see \seep{Blockread}, \seep{Blockwrite}).
  1197. The following declaration declares a file of records:
  1198. \begin{verbatim}
  1199. Type
  1200. Point = Record
  1201. X,Y,Z : real;
  1202. end;
  1203. PointFile = File of Point;
  1204. \end{verbatim}
  1205. Internally, files are represented by the \var{FileRec} record, which is
  1206. declared in the DOS unit.
  1207. A special file type is the \var{Text} file type, represented by the
  1208. \var{TextRec} record. A file of type \var{Text} uses special input-output
  1209. routines.
  1210. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  1211. % Pointers
  1212. \section{Pointers}
  1213. \fpc supports the use of pointers. A variable of the pointer type
  1214. contains an address in memory, where the data of another variable may be
  1215. stored.
  1216. \input{syntax/typepoin.syn}
  1217. As can be seen from this diagram, pointers are typed, which means that
  1218. they point to a particular kind of data. The type of this data must be
  1219. known at compile time.
  1220. Dereferencing the pointer (denoted by adding \var{\^{}} after the variable
  1221. name) behaves then like a variable. This variable has the type declared in
  1222. the pointer declaration, and the variable is stored in the address that is
  1223. pointed to by the pointer variable.
  1224. Consider the following example:
  1225. \begin{verbatim}
  1226. Program pointers;
  1227. type
  1228. Buffer = String[255];
  1229. BufPtr = ^Buffer;
  1230. Var B : Buffer;
  1231. BP : BufPtr;
  1232. PP : Pointer;
  1233. etc..
  1234. \end{verbatim}
  1235. In this example, \var{BP} {\em is a pointer to} a \var{Buffer} type; while \var{B}
  1236. {\em is} a variable of type \var{Buffer}. \var{B} takes 256 bytes memory,
  1237. and \var{BP} only takes 4 bytes of memory (enough to keep an adress in
  1238. memory).
  1239. \begin{remark} \fpc treats pointers much the same way as C does. This means
  1240. that a pointer to some type can be treated as being an array of this type.
  1241. The pointer then points to the zeroeth element of this array. Thus the
  1242. following pointer declaration
  1243. \begin{verbatim}
  1244. Var p : ^Longint;
  1245. \end{verbatim}
  1246. Can be considered equivalent to the following array declaration:
  1247. \begin{verbatim}
  1248. Var p : array[0..Infinity] of Longint;
  1249. \end{verbatim}
  1250. The difference is that the former declaration allocates memory for the
  1251. pointer only (not for the array), and the second declaration allocates
  1252. memory for the entire array. If the former is used, the memory must be
  1253. allocated manually, using the \seep{Getmem} function.
  1254. The reference \var{P\^{}} is then the same as \var{p[0]}. The following program
  1255. illustrates this maybe more clear:
  1256. \begin{verbatim}
  1257. program PointerArray;
  1258. var i : Longint;
  1259. p : ^Longint;
  1260. pp : array[0..100] of Longint;
  1261. begin
  1262. for i := 0 to 100 do pp[i] := i; { Fill array }
  1263. p := @pp[0]; { Let p point to pp }
  1264. for i := 0 to 100 do
  1265. if p[i]<>pp[i] then
  1266. WriteLn ('Ohoh, problem !')
  1267. end.
  1268. \end{verbatim}
  1269. \end{remark}
  1270. \fpc supports pointer arithmetic as C does. This means that, if \var{P} is a
  1271. typed pointer, the instructions
  1272. \begin{verbatim}
  1273. Inc(P);
  1274. Dec(P);
  1275. \end{verbatim}
  1276. Will increase, respectively decrease the address the pointer points to
  1277. with the size of the type \var{P} is a pointer to. For example
  1278. \begin{verbatim}
  1279. Var P : ^Longint;
  1280. ...
  1281. Inc (p);
  1282. \end{verbatim}
  1283. will increase \var{P} with 4.
  1284. Normal arithmetic operators on pointers can also be used, that is, the
  1285. following are valid pointer arithmetic operations:
  1286. \begin{verbatim}
  1287. var p1,p2 : ^Longint;
  1288. L : Longint;
  1289. begin
  1290. P1 := @P2;
  1291. P2 := @L;
  1292. L := P1-P2;
  1293. P1 := P1-4;
  1294. P2 := P2+4;
  1295. end.
  1296. \end{verbatim}
  1297. Here, the value that is added or substracted {\em is } multiplied by the
  1298. size of the type the pointer points to. In the previous
  1299. example \var{P1} will be decremented by 16 bytes, and
  1300. \var{P2} will be incremented by 16.
  1301. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  1302. % Procedural types
  1303. \section{Procedural types}
  1304. \fpc has support for procedural types, although it differs a little from
  1305. the Turbo Pascal implementation of them. The type declaration remains the
  1306. same, as can be seen in the following syntax diagram:
  1307. \input{syntax/typeproc.syn}
  1308. For a description of formal parameter lists, see \seec{Procedures}.
  1309. The two following examples are valid type declarations:
  1310. \begin{verbatim}
  1311. Type TOneArg = Procedure (Var X : integer);
  1312. TNoArg = Function : Real;
  1313. var proc : TOneArg;
  1314. func : TNoArg;
  1315. \end{verbatim}
  1316. One can assign the following values to a procedural type variable:
  1317. \begin{enumerate}
  1318. \item \var{Nil}, for both normal procedure pointers and method pointers.
  1319. \item A variable reference of a procedural type, i.e. another variable of
  1320. the same type.
  1321. \item A global procedure or function address, with matching function or
  1322. procedure header and calling convention.
  1323. \item A method address.
  1324. \end{enumerate}
  1325. Given these declarations, the following assignments are valid:
  1326. \begin{verbatim}
  1327. Procedure printit (Var X : Integer);
  1328. begin
  1329. WriteLn (x);
  1330. end;
  1331. ...
  1332. Proc := @printit;
  1333. Func := @Pi;
  1334. \end{verbatim}
  1335. From this example, the difference with Turbo Pascal is clear: In Turbo
  1336. Pascal it isn't necessary to use the address operator (\var{@})
  1337. when assigning a procedural type variable, whereas in \fpc it is required
  1338. (unless the \var{-So} switch is used, in which case the address
  1339. operator can be dropped.)
  1340. \begin{remark} The modifiers concerning the calling conventions
  1341. must be the same as the declaration;
  1342. i.e. the following code would give an error:
  1343. \begin{verbatim}
  1344. Type TOneArgCcall = Procedure (Var X : integer);cdecl;
  1345. var proc : TOneArgCcall;
  1346. Procedure printit (Var X : Integer);
  1347. begin
  1348. WriteLn (x);
  1349. end;
  1350. begin
  1351. Proc := @printit;
  1352. end.
  1353. \end{verbatim}
  1354. Because the \var{TOneArgCcall} type is a procedure that uses the cdecl
  1355. calling convention.
  1356. \end{remark}
  1357. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  1358. % Objects
  1359. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  1360. \chapter{Objects}
  1361. \label{ch:Objects}
  1362. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  1363. % Declaration
  1364. \section{Declaration}
  1365. \fpc supports object oriented programming. In fact, most of the compiler is
  1366. written using objects. Here we present some technical questions regarding
  1367. object oriented programming in \fpc.
  1368. Objects should be treated as a special kind of record. The record contains
  1369. all the fields that are declared in the objects definition, and pointers
  1370. to the methods that are associated to the objects' type.
  1371. An object is declared just as a record would be declared; except that
  1372. now,procedures and functions can be declared as if they were part of the record.
  1373. Objects can ''inherit'' fields and methods from ''parent'' objects. This means
  1374. that these fields and methods can be used as if they were included in the
  1375. objects declared as a ''child'' object.
  1376. Furthermore, a concept of visibility is introduced: fields, procedures and functions
  1377. can be delcared as \var{public} or \var{private}. By default, fields and
  1378. methods are \var{public}, and are
  1379. exported outside the current unit. Fields or methods that are declared
  1380. \var{private} are only accessible in the current unit.
  1381. The prototype declaration of an object is as follows:
  1382. \input{syntax/typeobj.syn}
  1383. As can be seen, as many \var{private} and \var{public} blocks as needed can be
  1384. declared.
  1385. \var{Method definitions} are normal function or procedure declarations.
  1386. Fields cannot be declared after methods in the same block, i.e. the following
  1387. will generate an error when compiling:
  1388. \begin{verbatim}
  1389. Type MyObj = Object
  1390. Procedure Doit;
  1391. Field : Longint;
  1392. end;
  1393. \end{verbatim}
  1394. But the following will be accepted:
  1395. \begin{verbatim}
  1396. Type MyObj = Object
  1397. Public
  1398. Procedure Doit;
  1399. Private
  1400. Field : Longint;
  1401. end;
  1402. \end{verbatim}
  1403. because the field is in a different section.
  1404. \begin{remark}
  1405. \fpc also supports the packed object. This is the same as an object, only
  1406. the elements (fields) of the object are byte-aligned, just as in the packed
  1407. record.
  1408. The declaration of a packed object is similar to the declaration
  1409. of a packed record :
  1410. \begin{verbatim}
  1411. Type
  1412. TObj = packed object;
  1413. Constructor init;
  1414. ...
  1415. end;
  1416. Pobj = ^TObj;
  1417. Var PP : Pobj;
  1418. \end{verbatim}
  1419. Similarly, the \var{\{\$PackRecords \}} directive acts on objects as well.
  1420. \end{remark}
  1421. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  1422. % Fields
  1423. \section{Fields}
  1424. Object Fields are like record fields. They are accessed in the same way as
  1425. a record field would be accessed : by using a qualified identifier. Given the
  1426. following declaration:
  1427. \begin{verbatim}
  1428. Type TAnObject = Object
  1429. AField : Longint;
  1430. Procedure AMethod;
  1431. end;
  1432. Var AnObject : TAnObject;
  1433. \end{verbatim}
  1434. then the following would be a valid assignment:
  1435. \begin{verbatim}
  1436. AnObject.AField := 0;
  1437. \end{verbatim}
  1438. Inside methods, fields can be accessed using the short identifier:
  1439. \begin{verbatim}
  1440. Procedure TAnObject.AMethod;
  1441. begin
  1442. ...
  1443. AField := 0;
  1444. ...
  1445. end;
  1446. \end{verbatim}
  1447. Or, one can use the \var{self} identifier. The \var{self} identifier refers
  1448. to the current instance of the object:
  1449. \begin{verbatim}
  1450. Procedure TAnObject.AMethod;
  1451. begin
  1452. ...
  1453. Self.AField := 0;
  1454. ...
  1455. end;
  1456. \end{verbatim}
  1457. One cannot access fields that are in a private section of an object from
  1458. outside the objects' methods. If this is attempted anyway, the compiler will complain about
  1459. an unknown identifier.
  1460. It is also possible to use the \var{with} statement with an object instance:
  1461. \begin{verbatim}
  1462. With AnObject do
  1463. begin
  1464. Afield := 12;
  1465. AMethod;
  1466. end;
  1467. \end{verbatim}
  1468. In this example, between the \var{begin} and \var{end}, it is as if
  1469. \var{AnObject} was prepended to the \var{Afield} and \var{Amethod}
  1470. identifiers. More about this in \sees{With}
  1471. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  1472. % Constructors and destructors
  1473. \section{Constructors and destructors }
  1474. \label{se:constructdestruct}
  1475. As can be seen in the syntax diagram for an object declaration, \fpc supports
  1476. constructors and destructors. The programmer is responsible for calling the
  1477. constructor and the destructor explicitly when using objects.
  1478. The declaration of a constructor or destructor is as follows:
  1479. \input{syntax/construct.syn}
  1480. A constructor/destructor pair is {\em required} if the object uses virtual methods.
  1481. In the declaration of the object type, a simple identifier should be used
  1482. for the name of the constuctor or destructor. When the constructor or destructor
  1483. is implemented, A qualified method identifier should be used,
  1484. i.e. an identifier of the form \var{objectidentifier.methodidentifier}.
  1485. \fpc supports also the extended syntax of the \var{New} and \var{Dispose}
  1486. procedures. In case a dynamic variable of an object type must be allocated
  1487. the constructor's name can be specified in the call to \var{New}.
  1488. The \var{New} is implemented as a function which returns a pointer to the
  1489. instantiated object. Consider the following declarations:
  1490. \begin{verbatim}
  1491. Type
  1492. TObj = object;
  1493. Constructor init;
  1494. ...
  1495. end;
  1496. Pobj = ^TObj;
  1497. Var PP : Pobj;
  1498. \end{verbatim}
  1499. Then the following 3 calls are equivalent:
  1500. \begin{verbatim}
  1501. pp := new (Pobj,Init);
  1502. \end{verbatim}
  1503. and
  1504. \begin{verbatim}
  1505. new(pp,init);
  1506. \end{verbatim}
  1507. and also
  1508. \begin{verbatim}
  1509. new (pp);
  1510. pp^.init;
  1511. \end{verbatim}
  1512. In the last case, the compiler will issue a warning that the
  1513. extended syntax of \var{new} and \var{dispose} must be used to generate instances of an
  1514. object. It is possible to ignore this warning, but it's better programming practice to
  1515. use the extended syntax to create instances of an object.
  1516. Similarly, the \var{Dispose} procedure accepts the name of a destructor. The
  1517. destructor will then be called, before removing the object from the heap.
  1518. In view of the compiler warning remark, the following chapter presents the
  1519. Delphi approach to object-oriented programming, and may be considered a
  1520. more natural way of object-oriented programming.
  1521. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  1522. % Methods
  1523. \section{Methods}
  1524. Object methods are just like ordinary procedures or functions, only they
  1525. have an implicit extra parameter : \var{self}. Self points to the object
  1526. with which the method was invoked.
  1527. When implementing methods, the fully qualified identifier must be given
  1528. in the function header. When declaring methods, a normal identifier must be
  1529. given.
  1530. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  1531. % Method invocation
  1532. \section{Method invocation}
  1533. Methods are called just as normal procedures are called, only they have an
  1534. object instance identifier prepended to them (see also \seec{Statements}).
  1535. To determine which method is called, it is necessary to know the type of
  1536. the method. We treat the different types in what follows.
  1537. \subsubsection{Static methods}
  1538. Static methods are methods that have been declared without a \var{abstract}
  1539. or \var{virtual} keyword. When calling a static method, the declared (i.e.
  1540. compile time) method of the object is used.
  1541. For example, consider the following declarations:
  1542. \begin{verbatim}
  1543. Type
  1544. TParent = Object
  1545. ...
  1546. procedure Doit;
  1547. ...
  1548. end;
  1549. PParent = ^TParent;
  1550. TChild = Object(TParent)
  1551. ...
  1552. procedure Doit;
  1553. ...
  1554. end;
  1555. PChild = ^TChild;
  1556. \end{verbatim}
  1557. As it is visible, both the parent and child objects have a method called
  1558. \var{Doit}. Consider now the following declarations and calls:
  1559. \begin{verbatim}
  1560. Var ParentA,ParentB : PParent;
  1561. Child : PChild;
  1562. ParentA := New(PParent,Init);
  1563. ParentB := New(PChild,Init);
  1564. Child := New(PChild,Init);
  1565. ParentA^.Doit;
  1566. ParentB^.Doit;
  1567. Child^.Doit;
  1568. \end{verbatim}
  1569. Of the three invocations of \var{Doit}, only the last one will call
  1570. \var{TChild.Doit}, the other two calls will call \var{TParent.Doit}.
  1571. This is because for static methods, the compiler determines at compile
  1572. time which method should be called. Since \var{ParentB} is of type
  1573. \var{TParent}, the compiler decides that it must be called with
  1574. \var{TParent.Doit}, even though it will be created as a \var{TChild}.
  1575. There may be times when the method that is actually called should
  1576. depend on the actual type of the object at run-time. If so, the method
  1577. cannot be a static method, but must be a virtual method.
  1578. \subsubsection{Virtual methods}
  1579. To remedy the situation in the previous section, \var{virtual} methods are
  1580. created. This is simply done by appending the method declaration with the
  1581. \var{virtual} modifier.
  1582. Going back to the previous example, consider the following alternative
  1583. declaration:
  1584. \begin{verbatim}
  1585. Type
  1586. TParent = Object
  1587. ...
  1588. procedure Doit;virtual;
  1589. ...
  1590. end;
  1591. PParent = ^TParent;
  1592. TChild = Object(TParent)
  1593. ...
  1594. procedure Doit;virtual;
  1595. ...
  1596. end;
  1597. PChild = ^TChild;
  1598. \end{verbatim}
  1599. As it is visible, both the parent and child objects have a method called
  1600. \var{Doit}. Consider now the following declarations and calls :
  1601. \begin{verbatim}
  1602. Var ParentA,ParentB : PParent;
  1603. Child : PChild;
  1604. ParentA := New(PParent,Init);
  1605. ParentB := New(PChild,Init);
  1606. Child := New(PChild,Init);
  1607. ParentA^.Doit;
  1608. ParentB^.Doit;
  1609. Child^.Doit;
  1610. \end{verbatim}
  1611. Now, different methods will be called, depending on the actual run-time type
  1612. of the object. For \var{ParentA}, nothing changes, since it is created as
  1613. a \var{TParent} instance. For \var{Child}, the situation also doesn't
  1614. change: it is again created as an instance of \var{TChild}.
  1615. For \var{ParentB} however, the situation does change: Even though it was
  1616. declared as a \var{TParent}, it is created as an instance of \var{TChild}.
  1617. Now, when the program runs, before calling \var{Doit}, the program
  1618. checks what the actual type of \var{ParentB} is, and only then decides which
  1619. method must be called. Seeing that \var{ParentB} is of type \var{TChild},
  1620. \var{TChild.Doit} will be called.
  1621. The code for this run-time checking of the actual type of an object is
  1622. inserted by the compiler at compile time.
  1623. The \var{TChild.Doit} is said to {\em override} the \var{TParent.Doit}.
  1624. It is possible to acces the \var{TParent.Doit} from within the
  1625. var{TChild.Doit}, with the \var{inherited} keyword:
  1626. \begin{verbatim}
  1627. Procedure TChild.Doit;
  1628. begin
  1629. inherited Doit;
  1630. ...
  1631. end;
  1632. \end{verbatim}
  1633. In the above example, when \var{TChild.Doit} is called, the first thing it
  1634. does is call \var{TParent.Doit}. The inherited keyword cannot be used in
  1635. static methods, only on virtual methods.
  1636. \subsubsection{Abstract methods}
  1637. An abstract method is a special kind of virtual method. A method can not be
  1638. abstract if it is not virtual (this is not obvious from the syntax diagram).
  1639. An instance of an object that has an abstract method cannot be created directly.
  1640. The reason is obvious: there is no method where the compiler could jump to !
  1641. A method that is declared \var{abstract} does not have an implementation for
  1642. this method. It is up to inherited objects to override and implement this
  1643. method. Continuing our example, take a look at this:
  1644. \begin{verbatim}
  1645. Type
  1646. TParent = Object
  1647. ...
  1648. procedure Doit;virtual;abstract;
  1649. ...
  1650. end;
  1651. PParent=^TParent;
  1652. TChild = Object(TParent)
  1653. ...
  1654. procedure Doit;virtual;
  1655. ...
  1656. end;
  1657. PChild = ^TChild;
  1658. \end{verbatim}
  1659. As it is visible, both the parent and child objects have a method called
  1660. \var{Doit}. Consider now the following declarations and calls :
  1661. \begin{verbatim}
  1662. Var ParentA,ParentB : PParent;
  1663. Child : PChild;
  1664. ParentA := New(PParent,Init);
  1665. ParentB := New(PChild,Init);
  1666. Child := New(PChild,Init);
  1667. ParentA^.Doit;
  1668. ParentB^.Doit;
  1669. Child^.Doit;
  1670. \end{verbatim}
  1671. First of all, Line 3 will generate a compiler error, stating that one cannot
  1672. generate instances of objects with abstract methods: The compiler has
  1673. detected that \var{PParent} points to an object which has an abstract
  1674. method. Commenting line 3 would allow compilation of the program.
  1675. \begin{remark}
  1676. If an abstract method is overridden, The parent method cannot be called
  1677. with \var{inherited}, since there is no parent method; The compiler
  1678. will detect this, and complain about it, like this:
  1679. \begin{verbatim}
  1680. testo.pp(32,3) Error: Abstract methods can't be called directly
  1681. \end{verbatim}
  1682. If, through some mechanism, an abstract method is called at run-time,
  1683. then a run-time error will occur. (run-time error 211, to be precise)
  1684. \end{remark}
  1685. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  1686. % Visibility
  1687. \section{Visibility}
  1688. For objects, 3 visibility specifiers exist : \var{private}, \var{protected} and
  1689. \var{public}. If a visibility specifier is not specified, \var{public}
  1690. is assumed.
  1691. Both methods and fields can be hidden from a programmer by putting them
  1692. in a \var{private} section. The exact visibility rule is as follows:
  1693. \begin{description}
  1694. \item [Private\ ] All fields and methods that are in a \var{private} block,
  1695. can only be accessed in the module (i.e. unit or program) that contains
  1696. the object definition.
  1697. They can be accessed from inside the object's methods or from outside them
  1698. e.g. from other objects' methods, or global functions.
  1699. \item [Protected\ ] Is the same as \var{Private}, except that the members of
  1700. a \var{Protected} section are also accessible to descendent types, even if
  1701. they are implemented in other modules.
  1702. \item [Public\ ] sections are always accessible, from everywhere.
  1703. Fields and metods in a \var{public} section behave as though they were part
  1704. of an ordinary \var{record} type.
  1705. \end{description}
  1706. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  1707. % Classes
  1708. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  1709. \chapter{Classes}
  1710. \label{ch:Classes}
  1711. In the Delphi approach to Object Oriented Programming, everything revolves
  1712. around the concept of 'Classes'. A class can be seen as a pointer to an
  1713. object, or a pointer to a record.
  1714. \begin{remark}
  1715. In earlier versions of \fpc it was necessary, in order to use classes,
  1716. to put the \file{objpas} unit in the uses clause of a unit or program.
  1717. {\em This is no longer needed} as of version 0.99.12. As of version 0.99.12
  1718. the \file{system} unit contains the basic definitions of \var{TObject}
  1719. and \var{TClass}, as well as some auxiliary methods for using classes.
  1720. The \file{objpas} unit still exists, and contains some redefinitions of
  1721. basic types, so they coincide with Delphi types. The unit will be loaded
  1722. automatically when the \var{-S2} or \var{-Sd} options are specified.
  1723. \end{remark}
  1724. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  1725. % Class definitions
  1726. \section{Class definitions}
  1727. The prototype declaration of a class is as follows :
  1728. \input{syntax/typeclas.syn}
  1729. As many \var{private}, \var{protected}, \var{published}
  1730. and \var{public} blocks as needed can be repeated.
  1731. Methods are normal function or procedure declarations.
  1732. As can be seen, the declaration of a class is almost identical to the
  1733. declaration of an object. The real difference between objects and classes
  1734. is in the way they are created (see further in this chapter).
  1735. The visibility of the different sections is as follows:
  1736. \begin{description}
  1737. \item [Private\ ] All fields and methods that are in a \var{private} block, can
  1738. only be accessed in the module (i.e. unit) that contains the class definition.
  1739. They can be accessed from inside the classes' methods or from outside them
  1740. (e.g. from other classes' methods)
  1741. \item [Protected\ ] Is the same as \var{Private}, except that the members of
  1742. a \var{Protected} section are also accessible to descendent types, even if
  1743. they are implemented in other modules.
  1744. \item [Public\ ] sections are always accessible.
  1745. \item [Published\ ] Is the same as a \var{Public} section, but the compiler
  1746. generates also type information that is needed for automatic streaming of
  1747. these classes. Fields defined in a \var{published} section must be of class type.
  1748. Array peroperties cannot be in a \var{published} section.
  1749. \end{description}
  1750. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  1751. % Class instantiation
  1752. \section{Class instantiation}
  1753. Classes must be created using their constructor. Remember that a class is a
  1754. pointer to an object, so when a variable of some class is declared, the
  1755. compiler just allocates a pointer, not the entire object. The constructor of
  1756. a class returns a pointer to an initialized instance of the object.
  1757. So, to initialize an instance of some class, one would do the following :
  1758. \begin{verbatim}
  1759. ClassVar := ClassType.ConstructorName;
  1760. \end{verbatim}
  1761. The extended syntax of \var{new} and \var{dispose} can be used to
  1762. instantiate and destroy class instances.
  1763. That construct is reserved for use with objects only.
  1764. Calling the constructor will provoke a call to \var{getmem}, to allocate
  1765. enough space to hold the class instance data.
  1766. After that, the constuctor's code is executed.
  1767. The constructor has a pointer to it's data, in \var{self}.
  1768. \begin{remark}
  1769. \begin{itemize}
  1770. \item The \var{\{\$PackRecords \}} directive also affects classes.
  1771. i.e. the alignment in memory of the different fields depends on the
  1772. value of the \var{\{\$PackRecords \}} directive.
  1773. \item Just as for objects and records, a packed class can be declared.
  1774. This has the same effect as on an object, or record, namely that the
  1775. elements are aligned on 1-byte boundaries. i.e. as close as possible.
  1776. \item \var{SizeOf(class)} will return 4, since a class is but a pointer to
  1777. an object. To get the size of the class instance data, use the
  1778. \var{TObject.InstanceSize} method.
  1779. \end{itemize}
  1780. \end{remark}
  1781. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  1782. % Methods
  1783. \section{Methods}
  1784. \subsection{invocation}
  1785. Method invocation for classes is no different than for objects. The
  1786. following is a valid method invocation:
  1787. \begin{verbatim}
  1788. Var AnObject : TAnObject;
  1789. begin
  1790. AnObject := TAnObject.Create;
  1791. ANobject.AMethod;
  1792. \end{verbatim}
  1793. \subsection{Virtual methods}
  1794. Classes have virtual methods, just as objects do. There is however a
  1795. difference between the two. For objects, it is sufficient to redeclare the
  1796. same method in a descendent object with the keyword \var{virtual} to
  1797. override it. For classes, the situation is different:
  1798. virtual methods {\em must} be overridden with the \var{override} keyword. Failing to do so,
  1799. will start a {\em new} batch of virtual methods, hiding the previous
  1800. one. The \var{Inherited} keyword will not jump to the inherited method, if
  1801. virtual was used.
  1802. The following code is {\em wrong}:
  1803. \begin{verbatim}
  1804. Type ObjParent = Class
  1805. Procedure MyProc; virtual;
  1806. end;
  1807. ObjChild = Class(ObjPArent)
  1808. Procedure MyProc; virtual;
  1809. end;
  1810. \end{verbatim}
  1811. The compiler will produce a warning:
  1812. \begin{verbatim}
  1813. Warning: An inherited method is hidden by OBJCHILD.MYPROC
  1814. \end{verbatim}
  1815. The compiler will compile it, but using \var{Inherited} can
  1816. produce strange effects.
  1817. The correct declaration is as follows:
  1818. \begin{verbatim}
  1819. Type ObjParent = Class
  1820. Procedure MyProc; virtual;
  1821. end;
  1822. ObjChild = Class(ObjPArent)
  1823. Procedure MyProc; override;
  1824. end;
  1825. \end{verbatim}
  1826. This will compile and run without warnings or errors.
  1827. \subsection{Message methods}
  1828. New in classes are \var{message} methods. Pointers to message methods are
  1829. stored in a special table, together with the integer or string cnstant that
  1830. they were declared with. They are primarily intended to ease programming of
  1831. callback functions in several \var{GUI} toolkits, such as \var{Win32} or
  1832. \var{GTK}. In difference with Delphi, \fpc also accepts strings as message
  1833. identifiers.
  1834. Message methods that are declared with an integer constant can take only one
  1835. var argument (typed or not):
  1836. \begin{verbatim}
  1837. Procedure TMyObject.MyHandler(Var Msg); Message 1;
  1838. \end{verbatim}
  1839. The method implementation of a message function is no different from an
  1840. ordinary method. It is also possible to call a message method directly,
  1841. but this should not be done. Instead, the \var{TObject.Dispatch} method
  1842. should be used.
  1843. The \var{TOBject.Dispatch} method can be used to call a \var{message}
  1844. handler. It is declared in the \file{system} unit and will accept a var
  1845. parameter which must have at the first position a cardinal with the
  1846. message ID that should be called. For example:
  1847. \begin{verbatim}
  1848. Type
  1849. TMsg = Record
  1850. MSGID : Cardinal
  1851. Data : Pointer;
  1852. Var
  1853. Msg : TMSg;
  1854. MyObject.Dispatch (Msg);
  1855. \end{verbatim}
  1856. In this example, the \var{Dispatch} method will look at the object and all
  1857. it's ancestors (starting at the object, and searching up the class tree),
  1858. to see if a message method with message \var{MSGID} has been
  1859. declared. If such a method is found, it is called, and passed the
  1860. \var{Msg} parameter.
  1861. If no such method is found, \var{DefaultHandler} is called.
  1862. \var{DefaultHandler} is a virtual method of \var{TObject} that doesn't do
  1863. anything, but which can be overridden to provide any processing that might be
  1864. needed. \var{DefaultHandler} is declared as follows:
  1865. \begin{verbatim}
  1866. procedure defaulthandler(var message);virtual;
  1867. \end{verbatim}
  1868. In addition to the message method with a \var{Integer} identifier,
  1869. \fpc also supports a message method with a string identifier:
  1870. \begin{verbatim}
  1871. Procedure TMyObject.MyStrHandler(Var Msg); Message 'OnClick';
  1872. \end{verbatim}
  1873. The working of the string message handler is the same as the ordinary
  1874. integer message handler:
  1875. The \var{TOBject.DispatchStr} method can be used to call a \var{message}
  1876. handler. It is declared in the system unit and will accept one parameter
  1877. which must have at the first position a string with the message ID that
  1878. should be called. For example:
  1879. \begin{verbatim}
  1880. Type
  1881. TMsg = Record
  1882. MsgStr : String[10]; // Arbitrary length up to 255 characters.
  1883. Data : Pointer;
  1884. Var
  1885. Msg : TMSg;
  1886. MyObject.DispatchStr (Msg);
  1887. \end{verbatim}
  1888. In this example, the \var{DispatchStr} method will look at the object and
  1889. all it's ancestors (starting at the object, and searching up the class tree),
  1890. to see if a message method with message \var{MsgStr} has been
  1891. declared. If such a method is found, it is called, and passed the
  1892. \var{Msg} parameter.
  1893. If no such method is found, \var{DefaultHandlerStr} is called.
  1894. \var{DefaultHandlerStr} is a virtual method of \var{TObject} that doesn't do
  1895. anything, but which can be overridden to provide any processing that might be
  1896. needed. \var{DefaultHandlerStr} is declared as follows:
  1897. \begin{verbatim}
  1898. procedure DefaultHandlerStr(var message);virtual;
  1899. \end{verbatim}
  1900. In addition to this mechanism, a string message method accepts a \var{self}
  1901. parameter:
  1902. \begin{verbatim}
  1903. TMyObject.StrMsgHandler(Data : Pointer; Self : TMyObject);Message 'OnClick';
  1904. \end{verbatim}
  1905. When encountering such a method, the compiler will generate code that loads
  1906. the \var{Self} parameter into the object instance pointer. The result of
  1907. this is that it is possible to pass \var{Self} as a parameter to such a
  1908. method.
  1909. \begin{remark}
  1910. The type of the \var{Self} parameter must be of the same class
  1911. as the class the method is defined in.
  1912. \end{remark}
  1913. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  1914. % Properties
  1915. \section{Properties}
  1916. Classes can contain properties as part of their fields list. A property
  1917. acts like a normal field, i.e. its value can be retrieved or set, but it
  1918. allows to redirect the access of the field through functions and
  1919. procedures. They provide a means to associate an action with an assignment
  1920. of or a reading from a class 'field'. This allows for e.g. checking that a
  1921. value is valid when assigning, or, when reading, it allows to construct the
  1922. value on the fly. Moreover, properties can be read-only or write only.
  1923. The prototype declaration of a property is as follows:
  1924. \input{syntax/property.syn}
  1925. A \var{read specifier} is either the name of a field that contains the
  1926. property, or the name of a method function that has the same return type as
  1927. the property type. In the case of a simple type, this
  1928. function must not accept an argument. A \var{read specifier} is optional,
  1929. making the property write-only.
  1930. A \var{write specifier} is optional: If there is no \var{write specifier}, the
  1931. property is read-only. A write specifier is either the name of a field, or
  1932. the name of a method procedure that accepts as a sole argument a variable of
  1933. the same type as the property.
  1934. The section (\var{private}, \var{published}) in which the specified function or
  1935. procedure resides is irrelevant. Usually, however, this will be a protected
  1936. or private method.
  1937. Example:
  1938. Given the following declaration:
  1939. \begin{verbatim}
  1940. Type
  1941. MyClass = Class
  1942. Private
  1943. Field1 : Longint;
  1944. Field2 : Longint;
  1945. Field3 : Longint;
  1946. Procedure Sety (value : Longint);
  1947. Function Gety : Longint;
  1948. Function Getz : Longint;
  1949. Public
  1950. Property X : Longint Read Field1 write Field2;
  1951. Property Y : Longint Read GetY Write Sety;
  1952. Property Z : Longint Read GetZ;
  1953. end;
  1954. Var MyClass : TMyClass;
  1955. \end{verbatim}
  1956. The following are valid statements:
  1957. \begin{verbatim}
  1958. WriteLn ('X : ',MyClass.X);
  1959. WriteLn ('Y : ',MyClass.Y);
  1960. WriteLn ('Z : ',MyClass.Z);
  1961. MyClass.X := 0;
  1962. MyClass.Y := 0;
  1963. \end{verbatim}
  1964. But the following would generate an error:
  1965. \begin{verbatim}
  1966. MyClass.Z := 0;
  1967. \end{verbatim}
  1968. because Z is a read-only property.
  1969. What happens in the above statements is that when a value needs to be read,
  1970. the compiler inserts a call to the various \var{getNNN} methods of the
  1971. object, and the result of this call is used. When an assignment is made,
  1972. the compiler passes the value that must be assigned as a paramater to
  1973. the various \var{setNNN} methods.
  1974. Because of this mechanism, properties cannot be passed as var arguments to a
  1975. function or procedure, since there is no known address of the property (at
  1976. least, not always).
  1977. If the property definition contains an index, then the read and write
  1978. specifiers must be a function and a procedure. Moreover, these functions
  1979. require an additional parameter : An integer parameter. This allows to read
  1980. or write several properties with the same function. For this, the properties
  1981. must have the same type.
  1982. The following is an example of a property with an index:
  1983. \begin{verbatim}
  1984. {$mode objfpc}
  1985. Type TPoint = Class(TObject)
  1986. Private
  1987. FX,FY : Longint;
  1988. Function GetCoord (Index : Integer): Longint;
  1989. Procedure SetCoord (Index : Integer; Value : longint);
  1990. Public
  1991. Property X : Longint index 1 read GetCoord Write SetCoord;
  1992. Property Y : Longint index 2 read GetCoord Write SetCoord;
  1993. Property Coords[Index : Integer]:Longint Read GetCoord;
  1994. end;
  1995. Procedure TPoint.SetCoord (Index : Integer; Value : Longint);
  1996. begin
  1997. Case Index of
  1998. 1 : FX := Value;
  1999. 2 : FY := Value;
  2000. end;
  2001. end;
  2002. Function TPoint.GetCoord (INdex : Integer) : Longint;
  2003. begin
  2004. Case Index of
  2005. 1 : Result := FX;
  2006. 2 : Result := FY;
  2007. end;
  2008. end;
  2009. Var P : TPoint;
  2010. begin
  2011. P := TPoint.create;
  2012. P.X := 2;
  2013. P.Y := 3;
  2014. With P do
  2015. WriteLn ('X=',X,' Y=',Y);
  2016. end.
  2017. \end{verbatim}
  2018. When the compiler encounters an assignment to \var{X}, then \var{SetCoord}
  2019. is called with as first parameter the index (1 in the above case) and with
  2020. as a second parameter the value to be set.
  2021. Conversely, when reading the value of \var{X}, the compiler calls
  2022. \var{GetCoord} and passes it index 1.
  2023. Indexes can only be integer values.
  2024. Array propertie also exist. These are properties that accept an
  2025. index, just as an array does. Only now the index doesn't have to be an
  2026. ordinal type, but can be any type.
  2027. A \var{read specifier} for an array property is the name method function
  2028. that has the same return type as the property type.
  2029. The function must accept as a sole arguent a variable of the same type as
  2030. the index type. For an array property, one cannot specify fields as \var{read
  2031. specifiers}.
  2032. A \var{write specifier} for an array property is the name of a method
  2033. procedure that accepts two arguments: The first argument has the same
  2034. type as the index, and the second argument is a parameter of the same
  2035. type as the property type.
  2036. As an example, see the following declaration:
  2037. \begin{verbatim}
  2038. Type TIntList = Class
  2039. Private
  2040. Function GetInt (I : Longint) : longint;
  2041. Function GetAsString (A : String) : String;
  2042. Procedure SetInt (I : Longint; Value : Longint;);
  2043. Procedure SetAsString (A : String; Value : String);
  2044. Public
  2045. Property Items [i : Longint] : Longint Read GetInt
  2046. Write SetInt;
  2047. Property StrItems [S : String] : String Read GetAsString
  2048. Write SetAsstring;
  2049. end;
  2050. Var AIntList : TIntList;
  2051. \end{verbatim}
  2052. Then the following statements would be valid:
  2053. \begin{verbatim}
  2054. AIntList.Items[26] := 1;
  2055. AIntList.StrItems['twenty-five'] := 'zero';
  2056. WriteLn ('Item 26 : ',AIntList.Items[26]);
  2057. WriteLn ('Item 25 : ',AIntList.StrItems['twenty-five']);
  2058. \end{verbatim}
  2059. While the following statements would generate errors:
  2060. \begin{verbatim}
  2061. AIntList.Items['twenty-five'] := 1;
  2062. AIntList.StrItems[26] := 'zero';
  2063. \end{verbatim}
  2064. Because the index types are wrong.
  2065. Array properties can be declared as \var{default} properties. This means that
  2066. it is not necessary to specify the property name when assigning or reading
  2067. it. If, in the previous example, the definition of the items property would
  2068. have been
  2069. \begin{verbatim}
  2070. Property Items[i : Longint]: Longint Read GetInt
  2071. Write SetInt; Default;
  2072. \end{verbatim}
  2073. Then the assignment
  2074. \begin{verbatim}
  2075. AIntList.Items[26] := 1;
  2076. \end{verbatim}
  2077. Would be equivalent to the following abbreviation.
  2078. \begin{verbatim}
  2079. AIntList[26] := 1;
  2080. \end{verbatim}
  2081. Only one default property per class is allowed, and descendent classes
  2082. cannot redeclare the default property.
  2083. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2084. % Expressions
  2085. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2086. \chapter{Expressions}
  2087. \label{ch:Expressions}
  2088. Expressions occur in assignments or in tests. Expressions produce a value,
  2089. of a certain type.
  2090. Expressions are built with two components: Operators and their operands.
  2091. Usually an operator is binary, i.e. it requires 2 operands. Binary operators
  2092. occur always between the operands (as in \var{X/Y}). Sometimes an
  2093. operator is unary, i.e. it requires only one argument. A unary operator
  2094. occurs always before the operand, as in \var{-X}.
  2095. When using multiple operands in an expression, the precedence rules of
  2096. \seet{OperatorPrecedence} are used.
  2097. \begin{FPCltable}{lll}{Precedence of operators}{OperatorPrecedence}
  2098. Operator & Precedence & Category \\ \hline
  2099. \var{Not, @} & Highest (first) & Unary operators\\
  2100. \var{* / div mod and shl shr as} & Second & Multiplying operators\\
  2101. \var{+ - or xor} & Third & Adding operators \\
  2102. \var{< <> < > <= >= in is} & Lowest (Last) & relational operators \\
  2103. \hline
  2104. \end{FPCltable}
  2105. When determining the precedence, the compiler uses the following rules:
  2106. \begin{enumerate}
  2107. \item In operations with unequal precedences the operands belong to the
  2108. operater with the highest precedence. For example, in \var{5*3+7}, the
  2109. multiplication is higher in precedence than the addition, so it is
  2110. executed first. The result would be 22.
  2111. \item If parentheses are used in an expression, their contents is evaluated
  2112. first. Thus, \var {5*(3+7)} would result in 50.
  2113. \end{enumerate}
  2114. \begin{remark}
  2115. The order in which expressions of the same precedence are evaluated is not
  2116. guaranteed to be left-to-right. In general, no assumptions on which expression
  2117. is evaluated first should be made in such a case.
  2118. The compiler will decide which expression to evaluate first based on
  2119. optimization rules. Thus, in the following expression:
  2120. \begin{verbatim}
  2121. a := g(3) + f(2);
  2122. \end{verbatim}
  2123. \var{f(2)} may be executed before \var{g(3)}. This behaviour is distinctly
  2124. different from \delphi or \tp.
  2125. If one expression {\em must} be executed before the other, it is necessary
  2126. to split up the statement using temporary results:
  2127. \begin{verbatim}
  2128. e1 := g(3);
  2129. a := e1 + f(2);
  2130. \end{verbatim}
  2131. \end{remark}
  2132. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2133. % Expression syntax
  2134. \section{Expression syntax}
  2135. An expression applies relational operators to simple expressions. Simple
  2136. expressions are a series of terms (what a term is, is explained below), joined by
  2137. adding operators.
  2138. \input{syntax/expsimpl.syn}
  2139. The following are valid expressions:
  2140. \begin{verbatim}
  2141. GraphResult<>grError
  2142. (DoItToday=Yes) and (DoItTomorrow=No);
  2143. Day in Weekend
  2144. \end{verbatim}
  2145. And here are some simple expressions:
  2146. \begin{verbatim}
  2147. A + B
  2148. -Pi
  2149. ToBe or NotToBe
  2150. \end{verbatim}
  2151. Terms consist of factors, connected by multiplication operators.
  2152. \input{syntax/expterm.syn}
  2153. Here are some valid terms:
  2154. \begin{verbatim}
  2155. 2 * Pi
  2156. A Div B
  2157. (DoItToday=Yes) and (DoItTomorrow=No);
  2158. \end{verbatim}
  2159. Factors are all other constructions:
  2160. \input{syntax/expfact.syn}
  2161. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2162. % Function calls
  2163. \section{Function calls}
  2164. Function calls are part of expressions (although, using extended syntax,
  2165. they can be statements too). They are constructed as follows:
  2166. \input{syntax/fcall.syn}
  2167. The \synt{variable reference} must be a procedural type variable reference.
  2168. A method designator can only be used inside the method of an object. A
  2169. qualified method designator can be used outside object methods too.
  2170. The function that will get called is the function with a declared parameter
  2171. list that matches the actual parameter list. This means that
  2172. \begin{enumerate}
  2173. \item The number of actual parameters must equal the number of declared
  2174. parameters.
  2175. \item The types of the parameters must be compatible. For variable
  2176. reference parameters, the parameter types must be exactly the same.
  2177. \end{enumerate}
  2178. If no matching function is found, then the compiler will generate an error.
  2179. Depending on the fact of the function is overloaded (i.e. multiple functions
  2180. with the same name, but different parameter lists) the error will be
  2181. different.
  2182. There are cases when the compiler will not execute the function call in an
  2183. expression. This is the case when assigning a value to a procedural
  2184. type variable, as in the following example:
  2185. \begin{verbatim}
  2186. Type
  2187. FuncType = Function: Integer;
  2188. Var A : Integer;
  2189. Function AddOne : Integer;
  2190. begin
  2191. A := A+1;
  2192. AddOne := A;
  2193. end;
  2194. Var F : FuncType;
  2195. N : Integer;
  2196. begin
  2197. A := 0;
  2198. F := AddOne; { Assign AddOne to F, Don't call AddOne}
  2199. N := AddOne; { N := 1 !!}
  2200. end.
  2201. \end{verbatim}
  2202. In the above listing, the assigment to F will not cause the function AddOne
  2203. to be called. The assignment to N, however, will call AddOne.
  2204. A problem with this syntax is the following construction:
  2205. \begin{verbatim}
  2206. If F = AddOne Then
  2207. DoSomethingHorrible;
  2208. \end{verbatim}
  2209. Should the compiler compare the addresses of \var{F} and \var{AddOne},
  2210. or should it call both functions, and compare the result ? \fpc solves this
  2211. by deciding that a procedural variable is equivalent to a pointer. Thus the
  2212. compiler will give a type mismatch error, since AddOne is considered a
  2213. call to a function with integer result, and F is a pointer, Hence a type
  2214. mismatch occurs.
  2215. How then, should one compare whether \var{F} points to the function
  2216. \var{AddOne} ? To do this, one should use the address operator \var{@}:
  2217. \begin{verbatim}
  2218. If F = @AddOne Then
  2219. WriteLn ('Functions are equal');
  2220. \end{verbatim}
  2221. The left hand side of the boolean expression is an address. The right hand
  2222. side also, and so the compiler compares 2 addresses.
  2223. How to compare the values that both functions return ? By adding an empty
  2224. parameter list:
  2225. \begin{verbatim}
  2226. If F()=Addone then
  2227. WriteLn ('Functions return same values ');
  2228. \end{verbatim}
  2229. Remark that this behaviour is not compatible with Delphi syntax.
  2230. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2231. % Set constructors
  2232. \section{Set constructors}
  2233. When a set-type constant must be entered in an expression, a
  2234. set constructor must be given. In essence this is the same thing as when a
  2235. type is defined, only there is no identifier to identify the set with.
  2236. A set constructor is a comma separated list of expressions, enclosed in
  2237. square brackets.
  2238. \input{syntax/setconst.syn}
  2239. All set groups and set elements must be of the same ordinal type.
  2240. The empty set is denoted by \var{[]}, and it can be assigned to any type of
  2241. set. A set group with a range \var{[A..Z]} makes all values in the range a
  2242. set element. If the first range specifier has a bigger ordinal value than
  2243. the second the set is empty, e.g., \var{[Z..A]} denotes an empty set.
  2244. The following are valid set constructors:
  2245. \begin{verbatim}
  2246. [today,tomorrow]
  2247. [Monday..Friday,Sunday]
  2248. [ 2, 3*2, 6*2, 9*2 ]
  2249. ['A'..'Z','a'..'z','0'..'9']
  2250. \end{verbatim}
  2251. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2252. % Value typecasts
  2253. \section{Value typecasts}
  2254. Sometimes it is necessary to change the type of an expression, or a part of
  2255. the expression, to be able to be assignment compatible. This is done through
  2256. a value typecast. The syntax diagram for a value typecast is as follows:
  2257. \input{syntax/tcast.syn}
  2258. Value typecasts cannot be used on the left side of assignments, as variable
  2259. typecasts.
  2260. Here are some valid typecasts:
  2261. \begin{verbatim}
  2262. Byte('A')
  2263. Char(48)
  2264. boolean(1)
  2265. longint(@Buffer)
  2266. \end{verbatim}
  2267. The type size of the expression and the size of the type cast must be the
  2268. same. That is, the following doesn't work:
  2269. \begin{verbatim}
  2270. Integer('A')
  2271. Char(4875)
  2272. boolean(100)
  2273. Word(@Buffer)
  2274. \end{verbatim}
  2275. This is different from Delphi or Turbo Pascal behaviour.
  2276. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2277. % The @ operator
  2278. \section{The @ operator}
  2279. The address operator \var{@} returns the address of a variable, procedure
  2280. or function. It is used as follows:
  2281. \input{syntax/address.syn}
  2282. The \var{@} operator returns a typed pointer if the \var{\$T} switch is on.
  2283. If the \var{\$T} switch is off then the address operator returns an untyped
  2284. pointer, which is assigment compatible with all pointer types. The type of
  2285. the pointer is \var{\^{}T}, where \var{T} is the type of the variable
  2286. reference.
  2287. For example, the following will compile
  2288. \begin{verbatim}
  2289. Program tcast;
  2290. {$T-} { @ returns untyped pointer }
  2291. Type art = Array[1..100] of byte;
  2292. Var Buffer : longint;
  2293. PLargeBuffer : ^art;
  2294. begin
  2295. PLargeBuffer := @Buffer;
  2296. end.
  2297. \end{verbatim}
  2298. Changing the \var{\{\$T-\}} to \var{\{\$T+\}} will prevent the compiler from
  2299. compiling this. It will give a type mismatch error.
  2300. By default, the address operator returns an untyped pointer.
  2301. Applying the address operator to a function, method, or procedure identifier
  2302. will give a pointer to the entry point of that function. The result is an
  2303. untyped pointer.
  2304. By default, the address operator must be used if a value must be assigned
  2305. to a procedural type variable. This behaviour can be avoided by using the
  2306. \var{-So} or \var{-S2} switches, which result in a more compatible Delphi or
  2307. Turbo Pascal syntax.
  2308. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2309. % Operators
  2310. \section{Operators}
  2311. Operators can be classified according to the type of expression they
  2312. operate on. We will discuss them type by type.
  2313. \subsection{Arithmetic operators}
  2314. Arithmetic operators occur in arithmetic operations, i.e. in expressions
  2315. that contain integers or reals. There are 2 kinds of operators : Binary and
  2316. unary arithmetic operators.
  2317. Binary operators are listed in \seet{binaroperators}, unary operators are
  2318. listed in \seet{unaroperators}.
  2319. \begin{FPCltable}{ll}{Binary arithmetic operators}{binaroperators}
  2320. Operator & Operation \\ \hline
  2321. \var{+} & Addition\\
  2322. \var{-} & Subtraction\\
  2323. \var{*} & Multiplication \\
  2324. \var{/} & Division \\
  2325. \var{Div} & Integer division \\
  2326. \var{Mod} & Remainder \\ \hline
  2327. \end{FPCltable}
  2328. With the exception of \var{Div} and \var{Mod}, which accept only integer
  2329. expressions as operands, all operators accept real and integer expressions as
  2330. operands.
  2331. For binary operators, the result type will be integer if both operands are
  2332. integer type expressions. If one of the operands is a real type expression,
  2333. then the result is real.
  2334. As an exception : division (\var{/}) results always in real values.
  2335. \begin{FPCltable}{ll}{Unary arithmetic operators}{unaroperators}
  2336. Operator & Operation \\ \hline
  2337. \var{+} & Sign identity\\
  2338. \var{-} & Sign inversion \\ \hline
  2339. \end{FPCltable}
  2340. For unary operators, the result type is always equal to the expression type.
  2341. The division (\var{/}) and \var{Mod} operator will cause run-time errors if
  2342. the second argument is zero.
  2343. The sign of the result of a \var{Mod} operator is the same as the sign of
  2344. the left side operand of the \var{Mod} operator. In fact, the \var{Mod}
  2345. operator is equivalent to the following operation :
  2346. \begin{verbatim}
  2347. I mod J = I - (I div J) * J
  2348. \end{verbatim}
  2349. but it executes faster than the right hand side expression.
  2350. \subsection{Logical operators}
  2351. Logical operators act on the individual bits of ordinal expressions.
  2352. Logical operators require operands that are of an integer type, and produce
  2353. an integer type result. The possible logical operators are listed in
  2354. \seet{logicoperations}.
  2355. \begin{FPCltable}{ll}{Logical operators}{logicoperations}
  2356. Operator & Operation \\ \hline
  2357. \var{not} & Bitwise negation (unary) \\
  2358. \var{and} & Bitwise and \\
  2359. \var{or} & Bitwise or \\
  2360. \var{xor} & Bitwise xor \\
  2361. \var{shl} & Bitwise shift to the left \\
  2362. \var{shr} & Bitwise shift to the right \\ \hline
  2363. \end{FPCltable}
  2364. The following are valid logical expressions:
  2365. \begin{verbatim}
  2366. A shr 1 { same as A div 2, but faster}
  2367. Not 1 { equals -2 }
  2368. Not 0 { equals -1 }
  2369. Not -1 { equals 0 }
  2370. B shl 2 { same as B * 2 for integers }
  2371. 1 or 2 { equals 3 }
  2372. 3 xor 1 { equals 2 }
  2373. \end{verbatim}
  2374. \subsection{Boolean operators}
  2375. Boolean operators can be considered logical operations on a type with 1 bit
  2376. size. Therefore the \var{shl} and \var{shr} operations have little sense.
  2377. Boolean operators can only have boolean type operands, and the resulting
  2378. type is always boolean. The possible operators are listed in
  2379. \seet{booleanoperators}
  2380. \begin{FPCltable}{ll}{Boolean operators}{booleanoperators}
  2381. Operator & Operation \\ \hline
  2382. \var{not} & logical negation (unary) \\
  2383. \var{and} & logical and \\
  2384. \var{or} & logical or \\
  2385. \var{xor} & logical xor \\ \hline
  2386. \end{FPCltable}
  2387. \begin{remark} Boolean expressions are always evaluated with short-circuit
  2388. evaluation. This means that from the moment the result of the complete
  2389. expression is known, evaluation is stopped and the result is returned.
  2390. For instance, in the following expression:
  2391. \begin{verbatim}
  2392. B := True or MaybeTrue;
  2393. \end{verbatim}
  2394. The compiler will never look at the value of \var{MaybeTrue}, since it is
  2395. obvious that the expression will always be true. As a result of this
  2396. strategy, if \var{MaybeTrue} is a function, it will not get called !
  2397. (This can have surprising effects when used in conjunction with properties)
  2398. \end{remark}
  2399. \subsection{String operators}
  2400. There is only one string operator : \var{+}. It's action is to concatenate
  2401. the contents of the two strings (or characters) it stands between.
  2402. One cannot use \var{+} to concatenate null-terminated (\var{PChar}) strings.
  2403. The following are valid string operations:
  2404. \begin{verbatim}
  2405. 'This is ' + 'VERY ' + 'easy !'
  2406. Dirname+'\'
  2407. \end{verbatim}
  2408. The following is not:
  2409. \begin{verbatim}
  2410. Var Dirname = Pchar;
  2411. ...
  2412. Dirname := Dirname+'\';
  2413. \end{verbatim}
  2414. Because \var{Dirname} is a null-terminated string.
  2415. \subsection{Set operators}
  2416. The following operations on sets can be performed with operators:
  2417. Union, difference and intersection. The operators needed for this are listed
  2418. in \seet{setoperators}.
  2419. \begin{FPCltable}{ll}{Set operators}{setoperators}
  2420. Operator & Action \\ \hline
  2421. \var{+} & Union \\
  2422. \var{-} & Difference \\
  2423. \var{*} & Intersection \\ \hline
  2424. \end{FPCltable}
  2425. The set type of the operands must be the same, or an error will be
  2426. generated by the compiler.
  2427. \subsection{Relational operators}
  2428. The relational operators are listed in \seet{relationoperators}
  2429. \begin{FPCltable}{ll}{Relational operators}{relationoperators}
  2430. Operator & Action \\ \hline
  2431. \var{=} & Equal \\
  2432. \var{<>} & Not equal \\
  2433. \var{<} & Stricty less than\\
  2434. \var{>} & Strictly greater than\\
  2435. \var{<=} & Less than or equal \\
  2436. \var{>=} & Greater than or equal \\
  2437. \var{in} & Element of \\ \hline
  2438. \end{FPCltable}
  2439. Left and right operands must be of the same type. Only integer
  2440. and real types can be mixed in relational expressions.
  2441. Comparing strings is done on the basis of their ASCII code representation.
  2442. When comparing pointers, the addresses to which they point are compared.
  2443. This also is true for \var{PChar} type pointers. To compare the strings
  2444. the \var{Pchar} point to, the \var{StrComp} function
  2445. from the \file{strings} unit must be used.
  2446. The \var{in} returns \var{True} if the left operand (which must have the same
  2447. ordinal type as the set type, and which must be in the range 0..255) is an
  2448. element of the set which is the right operand, otherwise it returns \var{False}
  2449. \chapter{Statements}
  2450. \label{ch:Statements}
  2451. The heart of each algorithm are the actions it takes. These actions are
  2452. contained in the statements of a program or unit. Each statement can be
  2453. labeled and jumped to (within certain limits) with \var{Goto} statements.
  2454. This can be seen in the following syntax diagram:
  2455. \input{syntax/statement.syn}
  2456. A label can be an identifier or an integer digit.
  2457. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2458. % Simple statements
  2459. \section{Simple statements}
  2460. A simple statement cannot be decomposed in separate statements. There are
  2461. basically 4 kinds of simple statements:
  2462. \input{syntax/simstate.syn}
  2463. Of these statements, the {\em raise statement} will be explained in the
  2464. chapter on Exceptions (\seec{Exceptions})
  2465. \subsection{Assignments}
  2466. Assignments give a value to a variable, replacing any previous value the
  2467. variable might have had:
  2468. \input{syntax/assign.syn}
  2469. In addition to the standard Pascal assignment operator (\var{ := }), which
  2470. simply replaces the value of the varable with the value resulting from the
  2471. expression on the right of the { := } operator, \fpc
  2472. supports some c-style constructions. All available constructs are listed in
  2473. \seet{assignments}.
  2474. \begin{FPCltable}{lr}{Allowed C constructs in \fpc}{assignments}
  2475. Assignment & Result \\ \hline
  2476. a += b & Adds \var{b} to \var{a}, and stores the result in \var{a}.\\
  2477. a -= b & Substracts \var{b} from \var{a}, and stores the result in
  2478. \var{a}. \\
  2479. a *= b & Multiplies \var{a} with \var{b}, and stores the result in
  2480. \var{a}. \\
  2481. a /= b & Divides \var{a} through \var{b}, and stores the result in
  2482. \var{a}. \\ \hline
  2483. \end{FPCltable}
  2484. For these constructs to work, the \var{-Sc} command-line switch must
  2485. be specified.
  2486. \begin{remark}
  2487. These constructions are just for typing convenience, they
  2488. don't generate different code.
  2489. Here are some examples of valid assignment statements:
  2490. \begin{verbatim}
  2491. X := X+Y;
  2492. X+=Y; { Same as X := X+Y, needs -Sc command line switch}
  2493. X/=2; { Same as X := X/2, needs -Sc command line switch}
  2494. Done := False;
  2495. Weather := Good;
  2496. MyPi := 4* Tan(1);
  2497. \end{verbatim}
  2498. \end{remark}
  2499. \subsection{Procedure statements}
  2500. Procedure statements are calls to subroutines. There are
  2501. different possibilities for procedure calls: A normal procedure call, an
  2502. object method call (fully qualified or not), or even a call to a procedural
  2503. type variable. All types are present in the following diagram.
  2504. \input{syntax/procedure.syn}
  2505. The \fpc compiler will look for a procedure with the same name as given in
  2506. the procedure statement, and with a declared parameter list that matches the
  2507. actual parameter list.
  2508. The following are valid procedure statements:
  2509. \begin{verbatim}
  2510. Usage;
  2511. WriteLn('Pascal is an easy language !');
  2512. Doit();
  2513. \end{verbatim}
  2514. \subsection{Goto statements}
  2515. \fpc supports the \var{goto} jump statement. Its prototype syntax is
  2516. \input{syntax/goto.syn}
  2517. When using \var{goto} statements, the following must be kept in mind:
  2518. \begin{enumerate}
  2519. \item The jump label must be defined in the same block as the \var{Goto}
  2520. statement.
  2521. \item Jumping from outside a loop to the inside of a loop or vice versa can
  2522. have strange effects.
  2523. \item To be able to use the \var{Goto} statement, the \var{-Sg} compiler
  2524. switch must be used.
  2525. \end{enumerate}
  2526. \var{Goto} statements are considered bad practice and should be avoided as
  2527. much as possible. It is always possible to replace a \var{goto} statement by a
  2528. construction that doesn't need a \var{goto}, although this construction may
  2529. not be as clear as a goto statement.
  2530. For instance, the following is an allowed goto statement:
  2531. \begin{verbatim}
  2532. label
  2533. jumpto;
  2534. ...
  2535. Jumpto :
  2536. Statement;
  2537. ...
  2538. Goto jumpto;
  2539. ...
  2540. \end{verbatim}
  2541. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2542. % Structured statements
  2543. \section{Structured statements}
  2544. Structured statements can be broken into smaller simple statements, which
  2545. should be executed repeatedly, conditionally or sequentially:
  2546. \input{syntax/struct.syn}
  2547. Conditional statements come in 2 flavours :
  2548. \input{syntax/conditio.syn}
  2549. Repetitive statements come in 3 flavours:
  2550. \input{syntax/repetiti.syn}
  2551. The following sections deal with each of these statements.
  2552. \subsection{Compound statements}
  2553. Compound statements are a group of statements, separated by semicolons,
  2554. that are surrounded by the keywords \var{Begin} and \var{End}. The
  2555. Last statement doesn't need to be followed by a semicolon, although it is
  2556. allowed. A compound statement is a way of grouping statements together,
  2557. executing the statements sequentially. They are treated as one statement
  2558. in cases where Pascal syntax expects 1 statement, such as in
  2559. \var{if ... then} statements.
  2560. \input{syntax/compound.syn}
  2561. \subsection{The \var{Case} statement}
  2562. \fpc supports the \var{case} statement. Its syntax diagram is
  2563. \input{syntax/case.syn}
  2564. The constants appearing in the various case parts must be known at
  2565. compile-time, and can be of the following types : enumeration types,
  2566. Ordinal types (except boolean), and chars. The expression must be also of
  2567. this type, or a compiler error will occur. All case constants must
  2568. have the same type.
  2569. The compiler will evaluate the expression. If one of the case constants
  2570. values matches the value of the expression, the statement that follows
  2571. this constant is executed. After that, the program continues after the final
  2572. \var{end}.
  2573. If none of the case constants match the expression value, the statement
  2574. after the \var{else} keyword is executed. This can be an empty statement.
  2575. If no else part is present, and no case constant matches the expression
  2576. value, program flow continues after the final \var{end}.
  2577. The case statements can be compound statements
  2578. (i.e. a \var{begin..End} block).
  2579. \begin{remark}
  2580. Contrary to Turbo Pascal, duplicate case labels are not
  2581. allowed in \fpc, so the following code will generate an error when
  2582. compiling:
  2583. \begin{verbatim}
  2584. Var i : integer;
  2585. ...
  2586. Case i of
  2587. 3 : DoSomething;
  2588. 1..5 : DoSomethingElse;
  2589. end;
  2590. \end{verbatim}
  2591. The compiler will generate a \var{Duplicate case label} error when compiling
  2592. this, because the 3 also appears (implicitly) in the range \var{1..5}. This
  2593. is similar to Delphi syntax.
  2594. \end{remark}
  2595. The following are valid case statements:
  2596. \begin{verbatim}
  2597. Case C of
  2598. 'a' : WriteLn ('A pressed');
  2599. 'b' : WriteLn ('B pressed');
  2600. 'c' : WriteLn ('C pressed');
  2601. else
  2602. WriteLn ('unknown letter pressed : ',C);
  2603. end;
  2604. \end{verbatim}
  2605. Or
  2606. \begin{verbatim}
  2607. Case C of
  2608. 'a','e','i','o','u' : WriteLn ('vowel pressed');
  2609. 'y' : WriteLn ('This one depends on the language');
  2610. else
  2611. WriteLn ('Consonant pressed');
  2612. end;
  2613. \end{verbatim}
  2614. \begin{verbatim}
  2615. Case Number of
  2616. 1..10 : WriteLn ('Small number');
  2617. 11..100 : WriteLn ('Normal, medium number');
  2618. else
  2619. WriteLn ('HUGE number');
  2620. end;
  2621. \end{verbatim}
  2622. \subsection{The \var{If..then..else} statement}
  2623. The \var{If .. then .. else..} prototype syntax is
  2624. \input{syntax/ifthen.syn}
  2625. The expression between the \var{if} and \var{then} keywords must have a
  2626. boolean return type. If the expression evaluates to \var{True} then the
  2627. statement following \var{then} is executed.
  2628. If the expression evaluates to \var{False}, then the statement following
  2629. \var{else} is executed, if it is present.
  2630. Be aware of the fact that the boolean expression will be short-cut evaluated.
  2631. (Meaning that the evaluation will be stopped at the point where the
  2632. outcome is known with certainty)
  2633. Also, before the \var {else} keyword, no semicolon (\var{;}) is allowed,
  2634. but all statements can be compound statements.
  2635. In nested \var{If.. then .. else} constructs, some ambiguity may araise as
  2636. to which \var{else} statement pairs with which \var{if} statement. The rule
  2637. is that the \var{else } keyword matches the first \var{if} keyword not
  2638. already matched by an \var{else} keyword.
  2639. For example:
  2640. \begin{verbatim}
  2641. If exp1 Then
  2642. If exp2 then
  2643. Stat1
  2644. else
  2645. stat2;
  2646. \end{verbatim}
  2647. Despite it's appearance, the statement is syntactically equivalent to
  2648. \begin{verbatim}
  2649. If exp1 Then
  2650. begin
  2651. If exp2 then
  2652. Stat1
  2653. else
  2654. stat2
  2655. end;
  2656. \end{verbatim}
  2657. and not to
  2658. \begin{verbatim}
  2659. { NOT EQUIVALENT }
  2660. If exp1 Then
  2661. begin
  2662. If exp2 then
  2663. Stat1
  2664. end
  2665. else
  2666. stat2
  2667. \end{verbatim}
  2668. If it is this latter construct is needed, the \var{begin} and \var{end}
  2669. keywords must be present. When in doubt, it is better to add them.
  2670. The following is a valid statement:
  2671. \begin{verbatim}
  2672. If Today in [Monday..Friday] then
  2673. WriteLn ('Must work harder')
  2674. else
  2675. WriteLn ('Take a day off.');
  2676. \end{verbatim}
  2677. \subsection{The \var{For..to/downto..do} statement}
  2678. \fpc supports the \var{For} loop construction. A for loop is used in case
  2679. one wants to calculated something a fixed number of times.
  2680. The prototype syntax is as follows:
  2681. \input{syntax/for.syn}
  2682. \var{Statement} can be a compound statement.
  2683. When this statement is encountered, the control variable is initialized with
  2684. the initial value, and is compared with the final value.
  2685. What happens next depends on whether \var{to} or \var{downto} is used:
  2686. \begin{enumerate}
  2687. \item In the case \var{To} is used, if the initial value larger than the final
  2688. value then \var{Statement} will never be executed.
  2689. \item In the case \var{DownTo} is used, if the initial value larger than the final
  2690. value then \var{Statement} will never be executed.
  2691. \end{enumerate}
  2692. After this check, the statement after \var{Do} is executed. After the
  2693. execution of the statement, the control variable is increased or decreased
  2694. with 1, depending on whether \var{To} or \var{Downto} is used.
  2695. The control variable must be an ordinal type, no other
  2696. types can be used as counters in a loop.
  2697. \begin{remark}
  2698. Contrary to ANSI pascal specifications, \fpc first initializes
  2699. the counter variable, and only then calculates the upper bound.
  2700. \end{remark}
  2701. The following are valid loops:
  2702. \begin{verbatim}
  2703. For Day := Monday to Friday do Work;
  2704. For I := 100 downto 1 do
  2705. WriteLn ('Counting down : ',i);
  2706. For I := 1 to 7*dwarfs do KissDwarf(i);
  2707. \end{verbatim}
  2708. If the statement is a compound statement, then the \seep{Break} and
  2709. \seep{Continue} reserved words can be used to jump to the end or just
  2710. after the end of the \var{For} statement.
  2711. \subsection{The \var{Repeat..until} statement}
  2712. The \var{repeat} statement is used to execute a statement until a certain
  2713. condition is reached. The statement will be executed at least once.
  2714. The prototype syntax of the \var{Repeat..until} statement is
  2715. \input{syntax/repeat.syn}
  2716. This will execute the statements between \var{repeat} and \var{until} up to
  2717. the moment when \var{Expression} evaluates to \var{True}.
  2718. Since the \var{expression} is evaluated {\em after} the execution of the
  2719. statements, they are executed at least once.
  2720. Be aware of the fact that the boolean expression \var{Expression} will be
  2721. short-cut evaluated. (Meaning that the evaluation will be stopped at the
  2722. point where the outcome is known with certainty)
  2723. The following are valid \var{repeat} statements
  2724. \begin{verbatim}
  2725. repeat
  2726. WriteLn ('I =',i);
  2727. I := I+2;
  2728. until I>100;
  2729. repeat
  2730. X := X/2
  2731. until x<10e-3
  2732. \end{verbatim}
  2733. The \seep{Break} and \seep{Continue} reserved words can be used to jump to
  2734. the end or just after the end of the \var{repeat .. until } statement.
  2735. \subsection{The \var{While..do} statement}
  2736. A \var{while} statement is used to execute a statement as long as a certain
  2737. condition holds. This may imply that the statement is never executed.
  2738. The prototype syntax of the \var{While..do} statement is
  2739. \input{syntax/while.syn}
  2740. This will execute \var{Statement} as long as \var{Expression} evaluates to
  2741. \var{True}. Since \var{Expression} is evaluated {\em before} the execution
  2742. of \var{Statement}, it is possible that \var{Statement} isn't executed at
  2743. all. \var{Statement} can be a compound statement.
  2744. Be aware of the fact that the boolean expression \var{Expression} will be
  2745. short-cut evaluated. (Meaning that the evaluation will be stopped at the
  2746. point where the outcome is known with certainty)
  2747. The following are valid \var{while} statements:
  2748. \begin{verbatim}
  2749. I := I+2;
  2750. while i<=100 do
  2751. begin
  2752. WriteLn ('I =',i);
  2753. I := I+2;
  2754. end;
  2755. X := X/2;
  2756. while x>=10e-3 do
  2757. X := X/2;
  2758. \end{verbatim}
  2759. They correspond to the example loops for the \var{repeat} statements.
  2760. If the statement is a compound statement, then the \seep{Break} and
  2761. \seep{Continue} reserved words can be used to jump to the end or just
  2762. after the end of the \var{While} statement.
  2763. \subsection{The \var{With} statement}
  2764. \label{se:With}
  2765. The \var{with} statement serves to access the elements of a record
  2766. or object or class, without having to specify the name of the each time.
  2767. The syntax for a \var{with} statement is
  2768. \input{syntax/with.syn}
  2769. The variable reference must be a variable of a record, object or class type.
  2770. In the \var{with} statement, any variable reference, or method reference is
  2771. checked to see if it is a field or method of the record or object or class.
  2772. If so, then that field is accessed, or that method is called.
  2773. Given the declaration:
  2774. \begin{verbatim}
  2775. Type Passenger = Record
  2776. Name : String[30];
  2777. Flight : String[10];
  2778. end;
  2779. Var TheCustomer : Passenger;
  2780. \end{verbatim}
  2781. The following statements are completely equivalent:
  2782. \begin{verbatim}
  2783. TheCustomer.Name := 'Michael';
  2784. TheCustomer.Flight := 'PS901';
  2785. \end{verbatim}
  2786. and
  2787. \begin{verbatim}
  2788. With TheCustomer do
  2789. begin
  2790. Name := 'Michael';
  2791. Flight := 'PS901';
  2792. end;
  2793. \end{verbatim}
  2794. The statement
  2795. \begin{verbatim}
  2796. With A,B,C,D do Statement;
  2797. \end{verbatim}
  2798. is equivalent to
  2799. \begin{verbatim}
  2800. With A do
  2801. With B do
  2802. With C do
  2803. With D do Statement;
  2804. \end{verbatim}
  2805. This also is a clear example of the fact that the variables are tried {\em last
  2806. to first}, i.e., when the compiler encounters a variable reference, it will
  2807. first check if it is a field or method of the last variable. If not, then it
  2808. will check the last-but-one, and so on.
  2809. The following example shows this;
  2810. \begin{verbatim}
  2811. Program testw;
  2812. Type AR = record
  2813. X,Y : Longint;
  2814. end;
  2815. PAR = Record;
  2816. Var S,T : Ar;
  2817. begin
  2818. S.X := 1;S.Y := 1;
  2819. T.X := 2;T.Y := 2;
  2820. With S,T do
  2821. WriteLn (X,' ',Y);
  2822. end.
  2823. \end{verbatim}
  2824. The output of this program is
  2825. \begin{verbatim}
  2826. 2 2
  2827. \end{verbatim}
  2828. Showing thus that the \var{X,Y} in the \var{WriteLn} statement match the
  2829. \var{T} record variable.
  2830. \begin{remark}
  2831. When using a \var{With} statement with a pointer, or a class, it is not
  2832. permitted to change the pointer or the class in the \var{With} block.
  2833. With the definitions of the previous example, the following illustrates
  2834. what it is about:
  2835. \begin{verbatim}
  2836. Var p : PAR;
  2837. begin
  2838. With P^ do
  2839. begin
  2840. // Do some operations
  2841. P:=OtherP;
  2842. X:=0.0; // Wrong X will be used !!
  2843. end;
  2844. \end{verbatim}
  2845. The reason the pointer cannot be changed is that the address is stored
  2846. by the compiler in a temporary register. Changing the pointer won't change
  2847. the temporary address. The same is true for classes.
  2848. \end{remark}
  2849. \subsection{Exception Statements}
  2850. \fpc supports exceptions. Exceptions provide a convenient way to
  2851. program error and error-recovery mechanisms, and are
  2852. closely related to classes.
  2853. Exception support is explained in \seec{Exceptions}
  2854. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2855. % Assembler statements
  2856. \section{Assembler statements}
  2857. An assembler statement allows to insert assembler code right in the
  2858. pascal code.
  2859. \input{syntax/statasm.syn}
  2860. More information about assembler blocks can be found in the \progref.
  2861. The register list is used to indicate the registers that are modified by an
  2862. assembler statement in the assembler block. The compiler stores certain results in the
  2863. registers. If the registers are modified in an assembler statement, the compiler
  2864. should, sometimes, be told about it. The registers are denoted with their
  2865. Intel names for the I386 processor, i.e., \var{'EAX'}, \var{'ESI'} etc...
  2866. As an example, consider the following assembler code:
  2867. \begin{verbatim}
  2868. asm
  2869. Movl $1,%ebx
  2870. Movl $0,%eax
  2871. addl %eax,%ebx
  2872. end; ['EAX','EBX'];
  2873. \end{verbatim}
  2874. This will tell the compiler that it should save and restore the contents of
  2875. the \var{EAX} and \var{EBX} registers when it encounters this asm statement.
  2876. \fpc supports various styles of assembler syntax. By default, \var{AT\&T}
  2877. syntax is assumed for the 80386 and compatibles platform.
  2878. The default assembler style can be changed with the \var{\{\$asmmode xxx\}}
  2879. switch in the code, or the \var{-R} command-line option. More about this can
  2880. be found in the \progref.
  2881. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2882. % Using functions and procedures.
  2883. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2884. \chapter{Using functions and procedures}
  2885. \label{ch:Procedures}
  2886. \fpc supports the use of functions and procedures, but with some extras:
  2887. Function overloading is supported, as well as \var{Const} parameters and
  2888. open arrays.
  2889. \begin{remark} In many of the subsequent paragraphs the words \var{procedure}
  2890. and \var{function} will be used interchangeably. The statements made are
  2891. valid for both, except when indicated otherwise.
  2892. \end{remark}
  2893. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2894. % Procedure declaration
  2895. \section{Procedure declaration}
  2896. A procedure declaration defines an identifier and associates it with a
  2897. block of code. The procedure can then be called with a procedure statement.
  2898. \input{syntax/procedur.syn}
  2899. See \sees{Parameters} for the list of parameters.
  2900. A procedure declaration that is followed by a block implements the action of
  2901. the procedure in that block.
  2902. The following is a valid procedure :
  2903. \begin{verbatim}
  2904. Procedure DoSomething (Para : String);
  2905. begin
  2906. Writeln ('Got parameter : ',Para);
  2907. Writeln ('Parameter in upper case : ',Upper(Para));
  2908. end;
  2909. \end{verbatim}
  2910. Note that it is possible that a procedure calls itself.
  2911. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2912. % Function declaration
  2913. \section{Function declaration}
  2914. A function declaration defines an identifier and associates it with a
  2915. block of code. The block of code will return a result.
  2916. The function can then be called inside an expression, or with a procedure
  2917. statement, if extended syntax is on.
  2918. \input{syntax/function.syn}
  2919. The result type of a function can be any previously declared type.
  2920. contrary to Turbo pascal, where only simple types could be returned.
  2921. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2922. % Parameter lists
  2923. \section{Parameter lists}
  2924. \label{se:Parameters}
  2925. When arguments must be passed to a function or procedure, these parameters
  2926. must be declared in the formal parameter list of that function or procedure.
  2927. The parameter list is a declaration of identifiers that can be referred to
  2928. only in that procedure or function's block.
  2929. \input{syntax/params.syn}
  2930. Constant parameters and variable parameters can also be \var{untyped}
  2931. parameters if they have no type identifier.
  2932. \subsection{Value parameters}
  2933. Value parameters are declared as follows:
  2934. \input{syntax/paramval.syn}
  2935. When parameters are declared as value parameters, the procedure gets {\em
  2936. a copy} of the parameters that the calling block passes. Any modifications
  2937. to these parameters are purely local to the procedure's block, and do not
  2938. propagate back to the calling block.
  2939. A block that wishes to call a procedure with value parameters must pass
  2940. assignment compatible parameters to the procedure. This means that the types
  2941. should not match exactly, but can be converted (conversion code is inserted
  2942. by the compiler itself)
  2943. Care must be taken when using value parameters: Value parameters makes heavy
  2944. use of the stack, especially when using large parameters. The total size of
  2945. all parameters in the formal parameter list should be below 32K for
  2946. portability's sake (the Intel version limits this to 64K).
  2947. Open arrays can be passed as value parameters. See \sees{openarray} for
  2948. more information on using open arrays.
  2949. \subsection{Variable parameters}
  2950. \label{se:varparams}
  2951. Variable parameters are declared as follows:
  2952. \input{syntax/paramvar.syn}
  2953. When parameters are declared as variable parameters, the procedure or
  2954. function accesses immediatly the variable that the calling block passed in
  2955. its parameter list. The procedure gets a pointer to the variable that was
  2956. passed, and uses this pointer to access the variable's value.
  2957. From this, it follows that any changes made to the parameter, will
  2958. propagate back to the calling block. This mechanism can be used to pass
  2959. values back in procedures.
  2960. Because of this, the calling block must pass a parameter of {\em exactly}
  2961. the same type as the declared parameter's type. If it does not, the compiler
  2962. will generate an error.
  2963. Variable parameters can be untyped. In that case the variable has no type,
  2964. and hence is incompatible with all other types. However, the address operator
  2965. can be used on it, or it can be can passed to a function that has also an
  2966. untyped parameter. If an untyped parameter is used in an assigment,
  2967. or a value must be assigned to it, a typecast must be used.
  2968. File type variables must always be passed as variable parameters.
  2969. Open arrays can be passed as variable parameters. See \sees{openarray} for
  2970. more information on using open arrays.
  2971. \subsection{Constant parameters}
  2972. In addition to variable parameters and value parameters \fpc also supports
  2973. Constant parameters. A constant parameter as can be specified as follows:
  2974. \input{syntax/paramcon.syn}
  2975. A constant argument is passed by reference if it's size is larger than a
  2976. pointer. It is passed by value if the size is equal or is less then the
  2977. size of a native pointer.
  2978. This means that the function or procedure receives a pointer to the passed
  2979. argument, but it cannot be assigned to, this will result in a
  2980. compiler error. Furthermore a const parameter cannot be passed on to another
  2981. function that requires a variable parameter.
  2982. The main use for this is reducing the stack size, hence improving
  2983. performance, and still retaining the semantics of passing by value...
  2984. Constant parameters can also be untyped. See \sees{varparams} for more
  2985. information about untyped parameters.
  2986. Open arrays can be passed as constant parameters. See \sees{openarray} for
  2987. more information on using open arrays.
  2988. \subsection{Open array parameters}
  2989. \label{se:openarray}
  2990. \fpc supports the passing of open arrays, i.e. a procedure can be declared
  2991. with an array of unspecified length as a parameter, as in Delphi.
  2992. Open array parameters can be accessed in the procedure or function as an
  2993. array that is declared with starting index 0, and last element
  2994. index \var{High(paremeter)}.
  2995. For example, the parameter
  2996. \begin{verbatim}
  2997. Row : Array of Integer;
  2998. \end{verbatim}
  2999. would be equivalent to
  3000. \begin{verbatim}
  3001. Row : Array[0..N-1] of Integer;
  3002. \end{verbatim}
  3003. Where \var{N} would be the actual size of the array that is passed to the
  3004. function. \var{N-1} can be calculated as \var{High(Row)}.
  3005. Open parameters can be passed by value, by reference or as a constant
  3006. parameter. In the latter cases the procedure receives a pointer to the
  3007. actual array. In the former case, it receives a copy of the array.
  3008. In a function or procedure, open arrays can only be passed to functions which
  3009. are also declared with open arrays as parameters, {\em not} to functions or
  3010. procedures which accept arrays of fixed length.
  3011. The following is an example of a function using an open array:
  3012. \begin{verbatim}
  3013. Function Average (Row : Array of integer) : Real;
  3014. Var I : longint;
  3015. Temp : Real;
  3016. begin
  3017. Temp := Row[0];
  3018. For I := 1 to High(Row) do
  3019. Temp := Temp + Row[i];
  3020. Average := Temp / (High(Row)+1);
  3021. end;
  3022. \end{verbatim}
  3023. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  3024. % The array of const construct
  3025. \subsection{Array of const}
  3026. In Object Pascal or Delphi mode, \fpc supports the \var{Array of Const}
  3027. construction to pass parameters to a subroutine.
  3028. This is a special case of the \var{Open array} construction, where it is
  3029. allowed to pass any expression in an array to a function or procedure.
  3030. In the procedure, passed the arguments can be examined using a special
  3031. record:
  3032. \begin{verbatim}
  3033. Type
  3034. PVarRec = ^TVarRec;
  3035. TVarRec = record
  3036. case VType : Longint of
  3037. vtInteger : (VInteger: Longint);
  3038. vtBoolean : (VBoolean: Boolean);
  3039. vtChar : (VChar: Char);
  3040. vtExtended : (VExtended: PExtended);
  3041. vtString : (VString: PShortString);
  3042. vtPointer : (VPointer: Pointer);
  3043. vtPChar : (VPChar: PChar);
  3044. vtObject : (VObject: TObject);
  3045. vtClass : (VClass: TClass);
  3046. vtAnsiString : (VAnsiString: Pointer);
  3047. vtWideString : (VWideString: Pointer);
  3048. vtInt64 : (VInt64: PInt64);
  3049. end;
  3050. \end{verbatim}
  3051. Inside the procedure body, the array of const is equivalent to
  3052. an open array of TVarRec:
  3053. \begin{verbatim}
  3054. Procedure Testit (Args: Array of const);
  3055. Var I : longint;
  3056. begin
  3057. If High(Args)<0 then
  3058. begin
  3059. Writeln ('No aguments');
  3060. exit;
  3061. end;
  3062. Writeln ('Got ',High(Args)+1,' arguments :');
  3063. For i:=0 to High(Args) do
  3064. begin
  3065. write ('Argument ',i,' has type ');
  3066. case Args[i].vtype of
  3067. vtinteger :
  3068. Writeln ('Integer, Value :',args[i].vinteger);
  3069. vtboolean :
  3070. Writeln ('Boolean, Value :',args[i].vboolean);
  3071. vtchar :
  3072. Writeln ('Char, value : ',args[i].vchar);
  3073. vtextended :
  3074. Writeln ('Extended, value : ',args[i].VExtended^);
  3075. vtString :
  3076. Writeln ('ShortString, value :',args[i].VString^);
  3077. vtPointer :
  3078. Writeln ('Pointer, value : ',Longint(Args[i].VPointer));
  3079. vtPChar :
  3080. Writeln ('PCHar, value : ',Args[i].VPChar);
  3081. vtObject :
  3082. Writeln ('Object, name : ',Args[i].VObject.Classname);
  3083. vtClass :
  3084. Writeln ('Class reference, name :',Args[i].VClass.Classname);
  3085. vtAnsiString :
  3086. Writeln ('AnsiString, value :',AnsiString(Args[I].VAnsiStr
  3087. else
  3088. Writeln ('(Unknown) : ',args[i].vtype);
  3089. end;
  3090. end;
  3091. end;
  3092. \end{verbatim}
  3093. In code, it is possible to pass an arbitrary array of elements
  3094. to this procedure:
  3095. \begin{verbatim}
  3096. S:='Ansistring 1';
  3097. T:='AnsiString 2';
  3098. Testit ([]);
  3099. Testit ([1,2]);
  3100. Testit (['A','B']);
  3101. Testit ([TRUE,FALSE,TRUE]);
  3102. Testit (['String','Another string']);
  3103. Testit ([S,T]) ;
  3104. Testit ([P1,P2]);
  3105. Testit ([@testit,Nil]);
  3106. Testit ([ObjA,ObjB]);
  3107. Testit ([1.234,1.234]);
  3108. TestIt ([AClass]);
  3109. \end{verbatim}
  3110. If the procedure is declared with the \var{cdecl} modifier, then the
  3111. compiler will pass the array as a C compiler would pass it. This, in effect,
  3112. emulates the C construct of a variable number of arguments, as the following
  3113. example will show:
  3114. \begin{verbatim}
  3115. program testaocc;
  3116. {$mode objfpc}
  3117. Const
  3118. P : Pchar = 'example';
  3119. Fmt : PChar =
  3120. 'This %s uses printf to print numbers (%d) and strings.'#10;
  3121. // Declaration of standard C function printf:
  3122. procedure printf (fm : pchar; args : array of const);cdecl; external 'c';
  3123. begin
  3124. printf(Fmt,[P,123]);
  3125. end.
  3126. \end{verbatim}
  3127. Remark that this is not true for Delphi, so code relying on this feature
  3128. will not be portable.
  3129. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  3130. % Function overloading
  3131. \section{Function overloading}
  3132. Function overloading simply means that the same function is defined more
  3133. than once, but each time with a different formal parameter list.
  3134. The parameter lists must differ at least in one of it's elements type.
  3135. When the compiler encounters a function call, it will look at the function
  3136. parameters to decide which one of the defined functions it should call.
  3137. This can be useful when the same function must be defined for different
  3138. types. For example, in the RTL, the \var{Dec} procedure could be
  3139. defined as:
  3140. \begin{verbatim}
  3141. ...
  3142. Dec(Var I : Longint;decrement : Longint);
  3143. Dec(Var I : Longint);
  3144. Dec(Var I : Byte;decrement : Longint);
  3145. Dec(Var I : Byte);
  3146. ...
  3147. \end{verbatim}
  3148. When the compiler encounters a call to the dec function, it will first search
  3149. which function it should use. It therefore checks the parameters in a
  3150. function call, and looks if there is a function definition which matches the
  3151. specified parameter list. If the compiler finds such a function, a call is
  3152. inserted to that function. If no such function is found, a compiler error is
  3153. generated.
  3154. functions that have a \var{cdecl} modifier cannot be overloaded.
  3155. (Technically, because this modifier prevents the mangling of
  3156. the function name by the compiler).
  3157. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  3158. % forward defined functions
  3159. \section{Forward defined functions}
  3160. A function can be declared without having it followed by it's implementation,
  3161. by having it followed by the \var{forward} procedure. The effective
  3162. implementation of that function must follow later in the module.
  3163. The function can be used after a \var{forward} declaration as if it had been
  3164. implemented already.
  3165. The following is an example of a forward declaration.
  3166. \begin{verbatim}
  3167. Program testforward;
  3168. Procedure First (n : longint); forward;
  3169. Procedure Second;
  3170. begin
  3171. WriteLn ('In second. Calling first...');
  3172. First (1);
  3173. end;
  3174. Procedure First (n : longint);
  3175. begin
  3176. WriteLn ('First received : ',n);
  3177. end;
  3178. begin
  3179. Second;
  3180. end.
  3181. \end{verbatim}
  3182. A function can be defined as forward only once.
  3183. Likewise, in units, it is not allowed to have a forward declared function
  3184. of a function that has been declared in the interface part. The interface
  3185. declaration counts as a \var{forward} declaration.
  3186. The following unit will give an error when compiled:
  3187. \begin{verbatim}
  3188. Unit testforward;
  3189. interface
  3190. Procedure First (n : longint);
  3191. Procedure Second;
  3192. implementation
  3193. Procedure First (n : longint); forward;
  3194. Procedure Second;
  3195. begin
  3196. WriteLn ('In second. Calling first...');
  3197. First (1);
  3198. end;
  3199. Procedure First (n : longint);
  3200. begin
  3201. WriteLn ('First received : ',n);
  3202. end;
  3203. end.
  3204. \end{verbatim}
  3205. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  3206. % External functions
  3207. \section{External functions}
  3208. \label{se:external}
  3209. The \var{external} modifier can be used to declare a function that resides in
  3210. an external object file. It allows to use the function in some code, and at
  3211. linking time, the object file containing the implementation of the function
  3212. or procedure must be linked in.
  3213. \input{syntax/external.syn}
  3214. It replaces, in effect, the function or procedure code block.
  3215. As an example:
  3216. \begin{verbatim}
  3217. program CmodDemo;
  3218. {$Linklib c}
  3219. Const P : PChar = 'This is fun !';
  3220. Function strlen (P : PChar) : Longint; cdecl; external;
  3221. begin
  3222. WriteLn ('Length of (',p,') : ',strlen(p))
  3223. end.
  3224. \end{verbatim}
  3225. \begin{remark}
  3226. The parameters in our declaration of the \var{external} function
  3227. should match exactly the ones in the declaration in the object file.
  3228. \end{remark}
  3229. If the \var{external} modifier is followed by a string constant:
  3230. \begin{verbatim}
  3231. external 'lname';
  3232. \end{verbatim}
  3233. Then this tells the compiler that the function resides in library
  3234. 'lname'. The compiler will then automatically link this library to
  3235. the program.
  3236. The name that the function has in the library can also be specified:
  3237. \begin{verbatim}
  3238. external 'lname' name 'Fname';
  3239. \end{verbatim}
  3240. This tells the compiler that the function resides in library 'lname',
  3241. but with name 'Fname'.The compiler will then automatically link this
  3242. library to the program, and use the correct name for the function.
  3243. Under \windows and \ostwo, the following form can also be used:
  3244. \begin{verbatim}
  3245. external 'lname' Index Ind;
  3246. \end{verbatim}
  3247. This tells the compiler that the function resides in library 'lname',
  3248. but with index \var{Ind}. The compiler will then automatically
  3249. link this library to the program, and use the correct index for the
  3250. function.
  3251. Finally, the external directive can be used to specify the external name
  3252. of the function :
  3253. \begin{verbatim}
  3254. {$L myfunc.o}
  3255. external name 'Fname';
  3256. \end{verbatim}
  3257. This tells the compiler that the function has the name 'Fname'. The
  3258. correct library or object file (in this case myfunc.o) must still be linked.
  3259. so that the function 'Fname' is included in the linking stage.
  3260. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  3261. % Assembler functions
  3262. \section{Assembler functions}
  3263. Functions and procedures can be completely implemented in assembly
  3264. language. To indicate this, use the \var{assembler} keyword:
  3265. \input{syntax/asm.syn}
  3266. Contrary to Delphi, the assembler keyword must be present to indicate an
  3267. assembler function.
  3268. For more information about assembler functions, see the chapter on using
  3269. assembler in the \progref.
  3270. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  3271. % Modifiers
  3272. \section{Modifiers}
  3273. A function or procedure declaration can contain modifiers. Here we list the
  3274. various possibilities:
  3275. \input{syntax/modifiers.syn}
  3276. \fpc doesn't support all Turbo Pascal modifiers, but
  3277. does support a number of additional modifiers. They are used mainly for assembler and
  3278. reference to C object files.
  3279. \subsection{alias}
  3280. The \var{alias} modifier allows the programmer to specify a different name for a
  3281. procedure or function. This is mostly useful for referring to this procedure
  3282. from assembly language constructs or from another object file. As an example,
  3283. consider the following program:
  3284. \begin{verbatim}
  3285. Program Aliases;
  3286. Procedure Printit;alias : 'DOIT';
  3287. begin
  3288. WriteLn ('In Printit (alias : "DOIT")');
  3289. end;
  3290. begin
  3291. asm
  3292. call DOIT
  3293. end;
  3294. end.
  3295. \end{verbatim}
  3296. \begin{remark} the specified alias is inserted straight into the assembly
  3297. code, thus it is case sensitive.
  3298. \end{remark}
  3299. The \var{alias} modifier does not make the symbol public to other modules,
  3300. unless the routine is also declared in the interface part of a unit, or
  3301. the \var{public} modifier is used to force it as public. Consider the
  3302. following:
  3303. \begin{verbatim}
  3304. unit testalias;
  3305. interface
  3306. procedure testroutine;
  3307. implementation
  3308. procedure testroutine;alias:'ARoutine';
  3309. begin
  3310. WriteLn('Hello world');
  3311. end;
  3312. end.
  3313. \end{verbatim}
  3314. This will make the routine \var{testroutine} available publicly to
  3315. external object files uunder the label name \var{ARoutine}.
  3316. \subsection{cdecl}
  3317. \label{se:cdecl}
  3318. The \var{cdecl} modifier can be used to declare a function that uses a C
  3319. type calling convention. This must be used when accessing functions residing in
  3320. an object file generated by standard C compilers. It allows to use the function in
  3321. the code, and at linking time, the object file containing the
  3322. \var{C} implementation of the function or procedure must be linked in.
  3323. As an example:
  3324. \begin{verbatim}
  3325. program CmodDemo;
  3326. {$LINKLIB c}
  3327. Const P : PChar = 'This is fun !';
  3328. Function strlen (P : PChar) : Longint; cdecl; external name 'strlen';
  3329. begin
  3330. WriteLn ('Length of (',p,') : ',strlen(p))
  3331. end.
  3332. \end{verbatim}
  3333. When compiling this, and linking to the C-library, the \var{strlen} function
  3334. can be called throughout the program. The \var{external} directive tells
  3335. the compiler that the function resides in an external object filebrary
  3336. with the 'strlen' name (see \ref{se:external}).
  3337. \begin{remark}
  3338. The parameters in our declaration of the \var{C} function should
  3339. match exactly the ones in the declaration in \var{C}.
  3340. \end{remark}
  3341. \subsection{export}
  3342. The export modifier is used to export names when creating a shared library
  3343. or an executable program. This means that the symbol will be publicly
  3344. available, and can be imported from other programs. For more information
  3345. on this modifier, consult the section on Programming dynamic libraries
  3346. in the \progref.
  3347. \subsection{inline}
  3348. \label{se:inline}
  3349. Procedures that are declared inline are copied to the places where they
  3350. are called. This has the effect that there is no actual procedure call,
  3351. the code of the procedure is just copied to where the procedure is needed,
  3352. this results in faster execution speed if the function or procedure is
  3353. used a lot.
  3354. By default, \var{inline} procedures are not allowed. Inline code must be enabled
  3355. using the command-line switch \var{-Si} or \var{\{\$inline on\}}
  3356. directive.
  3357. \begin{enumerate}
  3358. \item Inline code is NOT exported from a unit. This means that when
  3359. calling an inline procedure from another unit, a normal procedure call will be
  3360. performed. Only inside units, \var{Inline} procedures are really inlined.
  3361. \item Recursive inline functions are not allowed. i.e. an inline function
  3362. that calls itself is not allowed.
  3363. \end{enumerate}
  3364. \subsection{interrupt}
  3365. \label{se:interrupt}
  3366. The \var{interrupt} keyword is used to declare a routine which will
  3367. be used as an interrupt handler. On entry to this routine, all the registers
  3368. will be saved and on exit, all registers will be restored
  3369. and an interrupt or trap return will be executed (instead of the normal return
  3370. from subroutine instruction).
  3371. On platforms where a return from interrupt does not exist, the normal exit
  3372. code of routines will be done instead. For more information on the generated
  3373. code, consult the \progref.
  3374. \subsection{pascal}
  3375. \label{se:pascal}
  3376. The \var{pascal} modifier can be used to declare a function that uses the
  3377. classic pascal type calling convention (passing parameters from left to right).
  3378. For more information on the pascal calling convention, consult the \progref.
  3379. \subsection{popstack}
  3380. \label{se:popstack}
  3381. Popstack does the same as \var{cdecl}, namely it tells the \fpc compiler
  3382. that a function uses the C calling convention. In difference with the
  3383. \var{cdecl} modifier, it still mangles the name of the function as it would
  3384. for a normal pascal function.
  3385. With \var{popstack}, functions can be called by their pascal names in a
  3386. library.
  3387. \subsection{public}
  3388. The \var{Public} keyword is used to declare a function globally in a unit.
  3389. This is useful if the function should not be accessible from the unit
  3390. file (i.e. another unit/program using the unit doesn't see the function),
  3391. but must be accessible from the object file. as an example:
  3392. \begin{verbatim}
  3393. Unit someunit;
  3394. interface
  3395. Function First : Real;
  3396. Implementation
  3397. Function First : Real;
  3398. begin
  3399. First := 0;
  3400. end;
  3401. Function Second : Real; [Public];
  3402. begin
  3403. Second := 1;
  3404. end;
  3405. end.
  3406. \end{verbatim}
  3407. If another program or unit uses this unit, it will not be able to use the
  3408. function \var{Second}, since it isn't declared in the interface part.
  3409. However, it will be possible to access the function \var{Second} at the
  3410. assembly-language level, by using it's mangled name (see the \progref).
  3411. \subsection{register}
  3412. \label{se:register}
  3413. The \var{register} keyword is used for compatibility with Delphi. In
  3414. version 1.0.x of the compiler, this directive has no effect on the
  3415. generated code.
  3416. \subsection{saveregisters}
  3417. If this modifier is specified after a procedure or function, then the
  3418. \fpc compiler will save all registers on procedure entry, and restore
  3419. them when the procedure exits (except for registers where return values
  3420. are stored).
  3421. This modifier is not used under normal circumstances, except maybe when
  3422. calling assembler code.
  3423. \subsection{safecall}
  3424. This modifier ressembles closely the \var{stdcall} modifier. It sends
  3425. parameters from right to left on the stack.
  3426. More information about this modifier can be found in the \progref, in the
  3427. section on the calling mechanism and the chapter on linking.
  3428. \subsection{stdcall}
  3429. This modifier pushes the parameters from right to left on the stack,
  3430. it also aligns all the parameters to a default alignment.
  3431. More information about this modifier can be found in the \progref, in the
  3432. section on the calling mechanism and the chapter on linking.
  3433. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  3434. % Unsupported Turbo Pascal modifiers
  3435. \section{Unsupported Turbo Pascal modifiers}
  3436. The modifiers that exist in Turbo pascal, but aren't supported by \fpc, are
  3437. listed in \seet{Modifs}.
  3438. \begin{FPCltable}{lr}{Unsupported modifiers}{Modifs}
  3439. Modifier & Why not supported ? \\ \hline
  3440. Near & \fpc is a 32-bit compiler.\\
  3441. Far & \fpc is a 32-bit compiler. \\
  3442. \end{FPCltable}
  3443. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  3444. % Operator overloading
  3445. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  3446. \chapter{Operator overloading}
  3447. \label{ch:operatoroverloading}
  3448. \section{Introduction}
  3449. \fpc supports operator overloading. This means that it is possible to
  3450. define the action of some operators on self-defined types, and thus allow
  3451. the use of these types in mathematical expressions.
  3452. Defining the action of an operator is much like the definition of a
  3453. function or procedure, only there are some restrictions on the possible
  3454. definitions, as will be shown in the subsequent.
  3455. Operator overloading is, in essence, a powerful notational tool;
  3456. but it is also not more than that, since the same results can be
  3457. obtained with regular function calls. When using operator overloading,
  3458. It is important to keep in mind that some implicit rules may produce
  3459. some unexpected results. This will be indicated.
  3460. \section{Operator declarations}
  3461. To define the action of an operator is much like defining a function:
  3462. \input{syntax/operator.syn}
  3463. The parameter list for a comparision operator or an arithmetic operator
  3464. must always contain 2 parameters. The result type of the comparision
  3465. operator must be \var{Boolean}.
  3466. \begin{remark}
  3467. When compiling in \var{Delphi} mode or \var{Objfpc} mode, the result
  3468. identifier may be dropped. The result can then be accessed through
  3469. the standard \var{Result} symbol.
  3470. If the result identifier is dropped and the compiler is not in one
  3471. of these modes, a syntax error will occur.
  3472. \end{remark}
  3473. The statement block contains the necessary statements to determine the
  3474. result of the operation. It can contain arbitrary large pieces of code;
  3475. it is executed whenever the operation is encountered in some expression.
  3476. The result of the statement block must always be defined; error conditions
  3477. are not checked by the compiler, and the code must take care of all possible
  3478. cases, throwing a run-time error if some error condition is encountered.
  3479. In the following, the three types of operator definitions will be examined.
  3480. As an example, throughout this chapter the following type will be used to
  3481. define overloaded operators on :
  3482. \begin{verbatim}
  3483. type
  3484. complex = record
  3485. re : real;
  3486. im : real;
  3487. end;
  3488. \end{verbatim}
  3489. this type will be used in all examples.
  3490. The sources of the Run-Time Library contain a unit \file{ucomplex},
  3491. which contains a complete calculus for complex numbers, based on
  3492. operator overloading.
  3493. \section{Assignment operators}
  3494. The assignment operator defines the action of a assignent of one type of
  3495. variable to another. The result type must match the type of the variable
  3496. at the left of the assignment statement, the single parameter to the
  3497. assignment operator must have the same type as the expression at the
  3498. right of the assignment operator.
  3499. This system can be used to declare a new type, and define an assignment for
  3500. that type. For instance, to be able to assign a newly defined type 'Complex'
  3501. \begin{verbatim}
  3502. Var
  3503. C,Z : Complex; // New type complex
  3504. begin
  3505. Z:=C; // assignments between complex types.
  3506. end;
  3507. \end{verbatim}
  3508. The following assignment operator would have to be defined:
  3509. \begin{verbatim}
  3510. Operator := (C : Complex) z : complex;
  3511. \end{verbatim}
  3512. To be able to assign a real type to a complex type as follows:
  3513. \begin{verbatim}
  3514. var
  3515. R : real;
  3516. C : complex;
  3517. begin
  3518. C:=R;
  3519. end;
  3520. \end{verbatim}
  3521. the following assignment operator must be defined:
  3522. \begin{verbatim}
  3523. Operator := (r : real) z : complex;
  3524. \end{verbatim}
  3525. As can be seen from this statement, it defines the action of the operator
  3526. \var{:=} with at the right a real expression, and at the left a complex
  3527. expression.
  3528. an example implementation of this could be as follows:
  3529. \begin{verbatim}
  3530. operator := (r : real) z : complex;
  3531. begin
  3532. z.re:=r;
  3533. z.im:=0.0;
  3534. end;
  3535. \end{verbatim}
  3536. As can be seen in the example, the result identifier (\var{z} in this case)
  3537. is used to store the result of the assignment. When compiling in Delphi mode
  3538. or objfpc mode, the use of the special identifier \var{Result} is also
  3539. allowed, and can be substituted for the \var{z}, so the above would be
  3540. equivalent to
  3541. \begin{verbatim}
  3542. operator := (r : real) z : complex;
  3543. begin
  3544. Result.re:=r;
  3545. Result.im:=0.0;
  3546. end;
  3547. \end{verbatim}
  3548. The assignment operator is also used to convert types from one type to
  3549. another. The compiler will consider all overloaded assignment operators
  3550. till it finds one that matches the types of the left hand and right hand
  3551. expressions. If no such operator is found, a 'type mismatch' error
  3552. is given.
  3553. \begin{remark}
  3554. The assignment operator is not commutative; the compiler will never reverse
  3555. the role of the two arguments. in other words, given the above definition of
  3556. the assignment operator, the following is {\em not} possible:
  3557. \begin{verbatim}
  3558. var
  3559. R : real;
  3560. C : complex;
  3561. begin
  3562. R:=C;
  3563. end;
  3564. \end{verbatim}
  3565. if the reverse assignment should be possible (this is not so for reals and
  3566. complex numbers) then the assigment operator must be defined for that as well.
  3567. \end{remark}
  3568. \begin{remark}
  3569. The assignment operator is also used in implicit type conversions. This can
  3570. have unwanted effects. Consider the following definitions:
  3571. \begin{verbatim}
  3572. operator := (r : real) z : complex;
  3573. function exp(c : complex) : complex;
  3574. \end{verbatim}
  3575. then the following assignment will give a type mismatch:
  3576. \begin{verbatim}
  3577. Var
  3578. r1,r2 : real;
  3579. begin
  3580. r1:=exp(r2);
  3581. end;
  3582. \end{verbatim}
  3583. because the compiler will encounter the definition of the \var{exp} function
  3584. with the complex argument. It implicitly converts r2 to a complex, so it can
  3585. use the above \var{exp} function. The result of this function is a complex,
  3586. which cannot be assigned to r1, so the compiler will give a 'type mismatch'
  3587. error. The compiler will not look further for another \var{exp} which has
  3588. the correct arguments.
  3589. It is possible to avoid this particular problem by specifying
  3590. \begin{verbatim}
  3591. r1:=system.exp(r2);
  3592. \end{verbatim}
  3593. An experimental solution for this problem exists in the compiler, but is
  3594. not enabled by default. Maybe someday it will be.
  3595. \end{remark}
  3596. \section{Arithmetic operators}
  3597. Arithmetic operators define the action of a binary operator. Possible
  3598. operations are:
  3599. \begin{description}
  3600. \item[multiplication] to multiply two types, the \var{*} multiplication
  3601. operator must be overloaded.
  3602. \item[division] to divide two types, the \var{/} division
  3603. operator must be overloaded.
  3604. \item[addition] to add two types, the \var{+} addition
  3605. operator must be overloaded.
  3606. \item[substraction] to substract two types, the \var{-} substraction
  3607. operator must be overloaded.
  3608. \item[exponentiation] to exponentiate two types, the \var{**} exponentiation
  3609. operator must be overloaded.
  3610. \end{description}
  3611. The definition of an arithmetic operator takes two parameters. The first
  3612. parameter must be of the type that occurs at the left of the operator,
  3613. the second parameter must be of the type that is at the right of the
  3614. arithmetic operator. The result type must match the type that results
  3615. after the arithmetic operation.
  3616. To compile an expression as
  3617. \begin{verbatim}
  3618. var
  3619. R : real;
  3620. C,Z : complex;
  3621. begin
  3622. C:=R*Z;
  3623. end;
  3624. \end{verbatim}
  3625. one needs a definition of the multiplication operator as:
  3626. \begin{verbatim}
  3627. Operator * (r : real; z1 : complex) z : complex;
  3628. begin
  3629. z.re := z1.re * r;
  3630. z.im := z1.im * r;
  3631. end;
  3632. \end{verbatim}
  3633. As can be seen, the first operator is a real, and the second is
  3634. a complex. The result type is complex.
  3635. Multiplication and addition of reals and complexes are commutative
  3636. operations. The compiler, however, has no notion of this fact so even
  3637. if a multiplication between a real and a complex is defined, the
  3638. compiler will not use that definition when it encounters a complex
  3639. and a real (in that order). It is necessary to define both operations.
  3640. So, given the above definition of the multiplication,
  3641. the compiler will not accept the following statement:
  3642. \begin{verbatim}
  3643. var
  3644. R : real;
  3645. C,Z : complex;
  3646. begin
  3647. C:=Z*R;
  3648. end;
  3649. \end{verbatim}
  3650. since the types of \var{Z} and \var{R} don't match the types in the
  3651. operator definition.
  3652. The reason for this behaviour is that it is possible that a multiplication
  3653. is not always commutative. e.g. the multiplication of a \var{(n,m)} with a
  3654. \var{(m,n)} matrix will result in a \var{(n,n)} matrix, while the
  3655. mutiplication of a \var{(m,n)} with a \var{(n,m)} matrix is a \var{(m,m)}
  3656. matrix, which needn't be the same in all cases.
  3657. \section{Comparision operator}
  3658. The comparision operator can be overloaded to compare two different types
  3659. or to compare two equal types that are not basic types. The result type of
  3660. a comparision operator is always a boolean.
  3661. The comparision operators that can be overloaded are:
  3662. \begin{description}
  3663. \item[equal to] (=) to determine if two variables are equal.
  3664. \item[less than] ($<$) to determine if one variable is less than another.
  3665. \item[greater than] ($>$) to determine if one variable is greater than another.
  3666. \item[greater than or equal to] ($>=$) to determine if one variable is greater than
  3667. or equal to another.
  3668. \item[less than or equal to] ($<=$) to determine if one variable is greater
  3669. than or equal to another.
  3670. \end{description}
  3671. There is no separate operator for {\em unequal to} ($<>$). To evaluate a
  3672. statement that contans the {\em unequal to} operator, the compiler uses the
  3673. {\em equal to} operator (=), and negates the result.
  3674. As an example, the following opetrator allows to compare two complex
  3675. numbers:
  3676. \begin{verbatim}
  3677. operator = (z1, z2 : complex) b : boolean;
  3678. \end{verbatim}
  3679. the above definition allows comparisions of the following form:
  3680. \begin{verbatim}
  3681. Var
  3682. C1,C2 : Complex;
  3683. begin
  3684. If C1=C2 then
  3685. Writeln('C1 and C2 are equal');
  3686. end;
  3687. \end{verbatim}
  3688. The comparision operator definition needs 2 parameters, with the types that
  3689. the operator is meant to compare. Here also, the compiler doesn't apply
  3690. commutativity; if the two types are different, then it necessary to
  3691. define 2 comparision operators.
  3692. In the case of complex numbers, it is, for instance necessary to define
  3693. 2 comparsions: one with the complex type first, and one with the real type
  3694. first.
  3695. Given the definitions
  3696. \begin{verbatim}
  3697. operator = (z1 : complex;r : real) b : boolean;
  3698. operator = (r : real; z1 : complex) b : boolean;
  3699. \end{verbatim}
  3700. the following two comparisions are possible:
  3701. \begin{verbatim}
  3702. Var
  3703. R,S : Real;
  3704. C : Complex;
  3705. begin
  3706. If (C=R) or (S=C) then
  3707. Writeln ('Ok');
  3708. end;
  3709. \end{verbatim}
  3710. Note that the order of the real and complex type in the two comparisions
  3711. is reversed.
  3712. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  3713. % Programs, Units, Blocks
  3714. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  3715. \chapter{Programs, units, blocks}
  3716. A Pascal program consists of modules called \var{units}. A unit can be used
  3717. to group pieces of code together, or to give someone code without giving
  3718. the sources.
  3719. Both programs and units consist of code blocks, which are mixtures of
  3720. statements, procedures, and variable or type declarations.
  3721. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  3722. % Programs
  3723. \section{Programs}
  3724. A pascal program consists of the program header, followed possibly by a
  3725. 'uses' clause, and a block.
  3726. \input{syntax/program.syn}
  3727. The program header is provided for backwards compatibility, and is ignored
  3728. by the compiler.
  3729. The uses clause serves to identify all units that are needed by the program.
  3730. The system unit doesn't have to be in this list, since it is always loaded
  3731. by the compiler.
  3732. The order in which the units appear is significant, it determines in
  3733. which order they are initialized. Units are initialized in the same order
  3734. as they appear in the uses clause. Identifiers are searched in the opposite
  3735. order, i.e. when the compiler searches for an identifier, then it looks
  3736. first in the last unit in the uses clause, then the last but one, and so on.
  3737. This is important in case two units declare different types with the same
  3738. identifier.
  3739. When the compiler looks for unit files, it adds the extension \file{.ppu}
  3740. (\file{.ppw} for Win32 platforms) to the name of the unit. On \linux and in
  3741. operating systems where filenames are case sensitive, when looking for a unit,
  3742. the unit name is first looked for in the original case, and when not found,
  3743. converted to all lowercase and searched for.
  3744. If a unit name is longer than 8 characters, the compiler will first look for
  3745. a unit name with this length, and then it will truncate the name to 8
  3746. characters and look for it again. For compatibility reasons, this is also
  3747. true on platforms that suport long file names.
  3748. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  3749. % Units
  3750. \section{Units}
  3751. A unit contains a set of declarations, procedures and functions that can be
  3752. used by a program or another unit.
  3753. The syntax for a unit is as follows:
  3754. \input{syntax/unit.syn}
  3755. The interface part declares all identifiers that must be exported from the
  3756. unit. This can be constant, type or variable identifiers, and also procedure
  3757. or function identifier declarations. Declarations inside the
  3758. implementation part are {\em not} accessible outside the unit. The
  3759. implementation must contain a function declaration for each function or
  3760. procedure that is declared in the interface part. If a function is declared
  3761. in the interface part, but no declaration of that function is present in the
  3762. implementation part, then the compiler will give an error.
  3763. When a program uses a unit (say \file{unitA}) and this units uses a second
  3764. unit, say \file{unitB}, then the program depends indirectly also on
  3765. \var{unitB}. This means that the compiler must have access to \file{unitB} when
  3766. trying to compile the program. If the unit is not present at compile time,
  3767. an error occurs.
  3768. Note that the identifiers from a unit on which a program depends indirectly,
  3769. are not accessible to the program. To have access to the identifiers of a
  3770. unit, the unit must be in the uses clause of the program or unit where the
  3771. identifiers are needed.
  3772. Units can be mutually dependent, that is, they can reference each other in
  3773. their uses clauses. This is allowed, on the condition that at least one of
  3774. the references is in the implementation section of the unit. This also holds
  3775. for indirect mutually dependent units.
  3776. If it is possible to start from one interface uses clause of a unit, and to return
  3777. there via uses clauses of interfaces only, then there is circular unit
  3778. dependence, and the compiler will generate an error.
  3779. As and example : the following is not allowed:
  3780. \begin{verbatim}
  3781. Unit UnitA;
  3782. interface
  3783. Uses UnitB;
  3784. implementation
  3785. end.
  3786. Unit UnitB
  3787. interface
  3788. Uses UnitA;
  3789. implementation
  3790. end.
  3791. \end{verbatim}
  3792. But this is allowed :
  3793. \begin{verbatim}
  3794. Unit UnitA;
  3795. interface
  3796. Uses UnitB;
  3797. implementation
  3798. end.
  3799. Unit UnitB
  3800. implementation
  3801. Uses UnitA;
  3802. end.
  3803. \end{verbatim}
  3804. Because \file{UnitB} uses \file{UnitA} only in it's implentation section.
  3805. In general, it is a bad idea to have circular unit dependencies, even if it is
  3806. only in implementation sections.
  3807. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  3808. % Blocks
  3809. \section{Blocks}
  3810. Units and programs are made of blocks. A block is made of declarations of
  3811. labels, constants, types variables and functions or procedures. Blocks can
  3812. be nested in certain ways, i.e., a procedure or function declaration can
  3813. have blocks in themselves.
  3814. A block looks like the following:
  3815. \input{syntax/block.syn}
  3816. Labels that can be used to identify statements in a block are declared in
  3817. the label declaration part of that block. Each label can only identify one
  3818. statement.
  3819. Constants that are to be used only in one block should be declared in that
  3820. block's constant declaration part.
  3821. Variables that are to be used only in one block should be declared in that
  3822. block's constant declaration part.
  3823. Types that are to be used only in one block should be declared in that
  3824. block's constant declaration part.
  3825. Lastly, functions and procedures that will be used in that block can be
  3826. declared in the procedure/function declaration part.
  3827. After the different declaration parts comes the statement part. This
  3828. contains any actions that the block should execute.
  3829. All identifiers declared before the statement part can be used in that
  3830. statement part.
  3831. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  3832. % Scope
  3833. \section{Scope}
  3834. Identifiers are valid from the point of their declaration until the end of
  3835. the block in which the declaration occurred. The range where the identifier
  3836. is known is the {\em scope} of the identifier. The exact scope of an
  3837. identifier depends on the way it was defined.
  3838. \subsection{Block scope}
  3839. The {\em scope} of a variable declared in the declaration part of a block,
  3840. is valid from the point of declaration until the end of the block.
  3841. If a block contains a second block, in which the identfier is
  3842. redeclared, then inside this block, the second declaration will be valid.
  3843. Upon leaving the inner block, the first declaration is valid again.
  3844. Consider the following example:
  3845. \begin{verbatim}
  3846. Program Demo;
  3847. Var X : Real;
  3848. { X is real variable }
  3849. Procedure NewDeclaration
  3850. Var X : Integer; { Redeclare X as integer}
  3851. begin
  3852. // X := 1.234; {would give an error when trying to compile}
  3853. X := 10; { Correct assigment}
  3854. end;
  3855. { From here on, X is Real again}
  3856. begin
  3857. X := 2.468;
  3858. end.
  3859. \end{verbatim}
  3860. In this example, inside the procedure, X denotes an integer variable.
  3861. It has it's own storage space, independent of the variable \var{X} outside
  3862. the procedure.
  3863. \subsection{Record scope}
  3864. The field identifiers inside a record definition are valid in the following
  3865. places:
  3866. \begin{enumerate}
  3867. \item to the end of the record definition.
  3868. \item field designators of a variable of the given record type.
  3869. \item identifiers inside a \var{With} statement that operates on a variable
  3870. of the given record type.
  3871. \end{enumerate}
  3872. \subsection{Class scope}
  3873. A component identifier is valid in the following places:
  3874. \begin{enumerate}
  3875. \item From the point of declaration to the end of the class definition.
  3876. \item In all descendent types of this class, unless it is in the private
  3877. part of the class declaration.
  3878. \item In all method declaration blocks of this class and descendent classes.
  3879. \item In a with statement that operators on a variable of the given class's
  3880. definition.
  3881. \end{enumerate}
  3882. Note that method designators are also considered identifiers.
  3883. \subsection{Unit scope}
  3884. All identifiers in the interface part of a unit are valid from the point of
  3885. declaration, until the end of the unit. Furthermore, the identifiers are
  3886. known in programs or units that have the unit in their uses clause.
  3887. Identifiers from indirectly dependent units are {\em not} available.
  3888. Identifiers declared in the implementation part of a unit are valid from the
  3889. point of declaration to the end of the unit.
  3890. The system unit is automatically used in all units and programs.
  3891. It's identifiers are therefore always known, in each pascal program, library
  3892. or unit.
  3893. The rules of unit scope imply that an identifier of a
  3894. unit can be redefined. To have access to an identifier of another unit that was redeclared in
  3895. the current unit, precede it with that other units name, as in the following
  3896. example:
  3897. \begin{verbatim}
  3898. unit unitA;
  3899. interface
  3900. Type
  3901. MyType = Real;
  3902. implementation
  3903. end.
  3904. Program prog;
  3905. Uses UnitA;
  3906. { Redeclaration of MyType}
  3907. Type MyType = Integer;
  3908. Var A : Mytype; { Will be Integer }
  3909. B : UnitA.MyType { Will be real }
  3910. begin
  3911. end.
  3912. \end{verbatim}
  3913. This is especially useful when redeclaring the system unit's identifiers.
  3914. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  3915. % Libraries
  3916. \section{Libraries}
  3917. \fpc supports making of dynamic libraries (DLLs under Win32 and \ostwo) trough
  3918. the use of the \var{Library} keyword.
  3919. A Library is just like a unit or a program:
  3920. \input{syntax/library.syn}
  3921. By default, functions and procedures that are declared and implemented in
  3922. library are not available to a programmer that wishes to use this library.
  3923. In order to make functions or procedures available from the library,
  3924. they must be exported in an export clause:
  3925. \input{syntax/exports.syn}
  3926. Under Win32, an index clause can be added to an exports entry.
  3927. an index entry must be a positive number larger or equal than 1.
  3928. Optionally, an exports entry can have a name specifier. If present, the name
  3929. specifier gives the exact name (case sensitive) of the function in the
  3930. library.
  3931. If neither of these constructs is present, the functions or procedures
  3932. are exported with the exact names as specified in the exports clause.
  3933. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  3934. % Exceptions
  3935. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  3936. \chapter{Exceptions}
  3937. \label{ch:Exceptions}
  3938. Exceptions provide a convenient way to program error and error-recovery
  3939. mechanisms, and are closely related to classes.
  3940. Exception support is based on 3 constructs:
  3941. \begin{description}
  3942. \item [Raise\ ] statements. To raise an exeption. This is usually done to signal an
  3943. error condition.
  3944. \item [Try ... Except\ ] blocks. These block serve to catch exceptions
  3945. raised within the scope of the block, and to provide exception-recovery
  3946. code.
  3947. \item [Try ... Finally\ ] blocks. These block serve to force code to be
  3948. executed irrespective of an exception occurrence or not. They generally
  3949. serve to clean up memory or close files in case an exception occurs.
  3950. The compiler generates many implicit \var{Try ... Finally} blocks around
  3951. procedure, to force memory consistence.
  3952. \end{description}
  3953. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  3954. % The raise statement
  3955. \section{The raise statement}
  3956. The \var{raise} statement is as follows:
  3957. \input{syntax/raise.syn}
  3958. This statement will raise an exception. If it is specified, the exception
  3959. instance must be an initialized instance of a class, which is the raise
  3960. type. The address exception is optional. If itis not specified, the compiler
  3961. will provide the address by itself.
  3962. If the exception instance is omitted, then the current exception is
  3963. re-raised. This construct can only be used in an exception handling
  3964. block (see further).
  3965. \begin{remark} Control {\em never} returns after an exception block. The
  3966. control is transferred to the first \var{try...finally} or
  3967. \var{try...except} statement that is encountered when unwinding the stack.
  3968. If no such statement is found, the \fpc Run-Time Library will generate a
  3969. run-time error 217 (see also \sees{exceptclasses}).
  3970. \end{remark}
  3971. As an example: The following division checks whether the denominator is
  3972. zero, and if so, raises an exception of type \var{EDivException}
  3973. \begin{verbatim}
  3974. Type EDivException = Class(Exception);
  3975. Function DoDiv (X,Y : Longint) : Integer;
  3976. begin
  3977. If Y=0 then
  3978. Raise EDivException.Create ('Division by Zero would occur');
  3979. Result := X Div Y;
  3980. end;
  3981. \end{verbatim}
  3982. The class \var{Exception} is defined in the \file{Sysutils} unit of the rtl.
  3983. (\sees{exceptclasses})
  3984. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  3985. % The try...except statement
  3986. \section{The try...except statement}
  3987. A \var{try...except} exception handling block is of the following form :
  3988. \input{syntax/try.syn}
  3989. If no exception is raised during the execution of the \var{statement list},
  3990. then all statements in the list will be executed sequentially, and the
  3991. except block will be skipped, transferring program flow to the statement
  3992. after the final \var{end}.
  3993. If an exception occurs during the execution of the \var{statement list}, the
  3994. program flow will be transferred to the except block. Statements in the
  3995. statement list between the place where the exception was raised and the
  3996. exception block are ignored.
  3997. In the exception handling block, the type of the exception is checked,
  3998. and if there is an exception handler where the class type matches the
  3999. exception object type, or is a parent type of
  4000. the exception object type, then the statement following the corresponding
  4001. \var{Do} will be executed. The first matching type is used. After the
  4002. \var{Do} block was executed, the program continues after the \var{End}
  4003. statement.
  4004. The identifier in an exception handling statement is optional, and declares
  4005. an exception object. It can be used to manipulate the exception object in
  4006. the exception handling code. The scope of this declaration is the statement
  4007. block foillowing the \var{Do} keyword.
  4008. If none of the \var{On} handlers matches the exception object type, then the
  4009. statement list after \var{else} is executed. If no such list is
  4010. found, then the exception is automatically re-raised. This process allows
  4011. to nest \var{try...except} blocks.
  4012. If, on the other hand, the exception was caught, then the exception object is
  4013. destroyed at the end of the exception handling block, before program flow
  4014. continues. The exception is destroyed through a call to the object's
  4015. \var{Destroy} destructor.
  4016. As an example, given the previous declaration of the \var{DoDiv} function,
  4017. consider the following
  4018. \begin{verbatim}
  4019. Try
  4020. Z := DoDiv (X,Y);
  4021. Except
  4022. On EDivException do Z := 0;
  4023. end;
  4024. \end{verbatim}
  4025. If \var{Y} happens to be zero, then the DoDiv function code will raise an
  4026. exception. When this happens, program flow is transferred to the except
  4027. statement, where the Exception handler will set the value of \var{Z} to
  4028. zero. If no exception is raised, then program flow continues past the last
  4029. \var{end} statement.
  4030. To allow error recovery, the \var{Try ... Finally} block is supported.
  4031. A \var{Try...Finally} block ensures that the statements following the
  4032. \var{Finally} keyword are guaranteed to be executed, even if an exception
  4033. occurs.
  4034. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  4035. % The try...finally statement
  4036. \section{The try...finally statement}
  4037. A \var{Try..Finally} statement has the following form:
  4038. \input{syntax/finally.syn}
  4039. If no exception occurs inside the \var{statement List}, then the program
  4040. runs as if the \var{Try}, \var{Finally} and \var{End} keywords were not
  4041. present.
  4042. If, however, an exception occurs, the program flow is immediatly
  4043. transferred from the point where the excepion was raised to the first
  4044. statement of the \var{Finally statements}.
  4045. All statements after the finally keyword will be executed, and then
  4046. the exception will be automatically re-raised. Any statements between the
  4047. place where the exception was raised and the first statement of the
  4048. \var{Finally Statements} are skipped.
  4049. As an example consider the following routine:
  4050. \begin{verbatim}
  4051. Procedure Doit (Name : string);
  4052. Var F : Text;
  4053. begin
  4054. Try
  4055. Assign (F,Name);
  4056. Rewrite (name);
  4057. ... File handling ...
  4058. Finally
  4059. Close(F);
  4060. end;
  4061. \end{verbatim}
  4062. If during the execution of the file handling an execption occurs, then
  4063. program flow will continue at the \var{close(F)} statement, skipping any
  4064. file operations that might follow between the place where the exception
  4065. was raised, and the \var{Close} statement.
  4066. If no exception occurred, all file operations will be executed, and the file
  4067. will be closed at the end.
  4068. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  4069. % Exception handling nesting
  4070. \section{Exception handling nesting}
  4071. It is possible to nest \var{Try...Except} blocks with \var{Try...Finally}
  4072. blocks. Program flow will be done according to a \var{lifo} (last in, first
  4073. out) principle: The code of the last encountered \var{Try...Except} or
  4074. \var{Try...Finally} block will be executed first. If the exception is not
  4075. caught, or it was a finally statement, program flow will be transferred to
  4076. the last-but-one block, {\em ad infinitum}.
  4077. If an exception occurs, and there is no exception handler present, then a
  4078. runerror 217 will be generated. When using the \file{sysutils} unit, a default
  4079. handler is installed which will show the exception object message, and the
  4080. address where the exception occurred, after which the program will exit with
  4081. a \var{Halt} instruction.
  4082. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  4083. % Exception classes
  4084. \section{Exception classes}
  4085. \label{se:exceptclasses}
  4086. The \file{sysutils} unit contains a great deal of exception handling.
  4087. It defines the following exception types:
  4088. \begin{verbatim}
  4089. Exception = class(TObject)
  4090. private
  4091. fmessage : string;
  4092. fhelpcontext : longint;
  4093. public
  4094. constructor create(const msg : string);
  4095. constructor createres(indent : longint);
  4096. property helpcontext : longint read fhelpcontext write fhelpcontext;
  4097. property message : string read fmessage write fmessage;
  4098. end;
  4099. ExceptClass = Class of Exception;
  4100. { mathematical exceptions }
  4101. EIntError = class(Exception);
  4102. EDivByZero = class(EIntError);
  4103. ERangeError = class(EIntError);
  4104. EIntOverflow = class(EIntError);
  4105. EMathError = class(Exception);
  4106. \end{verbatim}
  4107. The sysutils unit also installs an exception handler. If an exception is
  4108. unhandled by any exception handling block, this handler is called by the
  4109. Run-Time library. Basically, it prints the exception address, and it prints
  4110. the message of the Exception object, and exits with a exit code of 217.
  4111. If the exception object is not a descendent object of the \var{Exception}
  4112. object, then the class name is printed instead of the exception message.
  4113. It is recommended to use the \var{Exception} object or a descendant class for
  4114. all \var{raise} statements, since then the message field of the
  4115. exception object can be used.
  4116. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  4117. % Using Assembler
  4118. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  4119. \chapter{Using assembler}
  4120. \fpc supports the use of assembler in code, but not inline
  4121. assembler macros. To have more information on the processor
  4122. specific assembler syntax and its limitations, see the \progref.
  4123. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  4124. % Assembler statements
  4125. \section{Assembler statements }
  4126. The following is an example of assembler inclusion in pascal code.
  4127. \begin{verbatim}
  4128. ...
  4129. Statements;
  4130. ...
  4131. Asm
  4132. the asm code here
  4133. ...
  4134. end;
  4135. ...
  4136. Statements;
  4137. \end{verbatim}
  4138. The assembler instructions between the \var{Asm} and \var{end} keywords will
  4139. be inserted in the assembler generated by the compiler.
  4140. Conditionals can be used ib assembler, the compiler will recognise it,
  4141. and treat it as any other conditionals.
  4142. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  4143. % Assembler procedures and functions
  4144. \section{Assembler procedures and functions}
  4145. Assembler procedures and functions are declared using the
  4146. \var{Assembler} directive. This permits the code generator to make a number
  4147. of code generation optimizations.
  4148. The code generator does not generate any stack frame (entry and exit
  4149. code for the routine) if it contains no local variables and no
  4150. parameters. In the case of functions, ordinal values must be returned
  4151. in the accumulator. In the case of floating point values, these depend
  4152. on the target processor and emulation options.
  4153. %
  4154. % System unit reference guide.
  4155. %
  4156. \part{Reference : The System unit}
  4157. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  4158. % The system unit
  4159. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  4160. \chapter{The system unit}
  4161. \label{ch:refchapter}
  4162. \FPCexampledir{refex}
  4163. The system unit contains the standard supported functions of \fpc. It is the
  4164. same for all platforms. Basically it is the same as the system unit provided
  4165. with Borland or Turbo Pascal.
  4166. Functions are listed in alphabetical order. Arguments of functions or
  4167. procedures that are optional are put between square brackets.
  4168. The pre-defined constants and variables are listed in the first section.
  4169. The second section contains an overview of all functions, grouped by
  4170. functionality, and the last section contains the supported functions
  4171. and procedures.
  4172. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  4173. % Types, Constants and Variables
  4174. \section{Types, Constants and Variables}
  4175. \subsection{Types}
  4176. The following integer types are defined in the System unit:
  4177. \begin{verbatim}
  4178. Shortint = -128..127;
  4179. SmallInt = -32768..32767;
  4180. Longint = $80000000..$7fffffff;
  4181. byte = 0..255;
  4182. word = 0..65535;
  4183. dword = longword;
  4184. cardinal = longword;
  4185. Integer = smallint;
  4186. \end{verbatim}
  4187. The following types are used for the functions that need compiler magic
  4188. such as \seep{Val} or \seep{Str}:
  4189. \begin{verbatim}
  4190. StrLenInt = LongInt;
  4191. ValSInt = Longint;
  4192. ValUInt = Cardinal;
  4193. ValReal = Extended;
  4194. \end{verbatim}
  4195. The \var{Real48} type is defined to emulate the old \tp \var{Real} type:
  4196. \begin{verbatim}
  4197. Real48 = Array[0..5] of byte;
  4198. \end{verbatim}
  4199. The assignment operator has been overloaded so this type can be assigned
  4200. to the \fpc native \var{Double} and \var{Extended} types.
  4201. \seefl{Real2Double}{RealToDouble}.
  4202. The following character types are defined for Delphi compatibility:
  4203. \begin{verbatim}
  4204. TAnsiChar = Char;
  4205. AnsiChar = TAnsiChar;
  4206. \end{verbatim}
  4207. And the following pointer types as well:
  4208. \begin{verbatim}
  4209. PChar = ^char;
  4210. pPChar = ^PChar;
  4211. PAnsiChar = PChar;
  4212. PQWord = ^QWord;
  4213. PInt64 = ^Int64;
  4214. pshortstring = ^shortstring;
  4215. plongstring = ^longstring;
  4216. pansistring = ^ansistring;
  4217. pwidestring = ^widestring;
  4218. pextended = ^extended;
  4219. ppointer = ^pointer;
  4220. \end{verbatim}
  4221. For the \seef{SetJmp} and \seep{LongJmp} calls, the following jump bufer
  4222. type is defined (for the I386 processor):
  4223. \begin{verbatim}
  4224. jmp_buf = record
  4225. ebx,esi,edi : Longint;
  4226. bp,sp,pc : Pointer;
  4227. end;
  4228. PJmp_buf = ^jmp_buf;
  4229. \end{verbatim}
  4230. The following records and pointers can be used to scan the
  4231. entries in the string message handler tables:
  4232. \begin{verbatim}
  4233. tmsgstrtable = record
  4234. name : pshortstring;
  4235. method : pointer;
  4236. end;
  4237. pmsgstrtable = ^tmsgstrtable;
  4238. tstringmessagetable = record
  4239. count : dword;
  4240. msgstrtable : array[0..0] of tmsgstrtable;
  4241. end;
  4242. pstringmessagetable = ^tstringmessagetable;
  4243. \end{verbatim}
  4244. The base class for all classes is defined as:
  4245. \begin{verbatim}
  4246. Type
  4247. TObject = Class
  4248. Public
  4249. constructor create;
  4250. destructor destroy;virtual;
  4251. class function newinstance : tobject;virtual;
  4252. procedure freeinstance;virtual;
  4253. function safecallexception(exceptobject : tobject;
  4254. exceptaddr : pointer) : longint;virtual;
  4255. procedure defaulthandler(var message);virtual;
  4256. procedure free;
  4257. class function initinstance(instance : pointer) : tobject;
  4258. procedure cleanupinstance;
  4259. function classtype : tclass;
  4260. class function classinfo : pointer;
  4261. class function classname : shortstring;
  4262. class function classnameis(const name : string) : boolean;
  4263. class function classparent : tclass;
  4264. class function instancesize : longint;
  4265. class function inheritsfrom(aclass : tclass) : boolean;
  4266. class function inheritsfrom(aclass : tclass) : boolean;
  4267. class function stringmessagetable : pstringmessagetable;
  4268. procedure dispatch(var message);
  4269. procedure dispatchstr(var message);
  4270. class function methodaddress(const name : shortstring) : pointer;
  4271. class function methodname(address : pointer) : shortstring;
  4272. function fieldaddress(const name : shortstring) : pointer;
  4273. procedure AfterConstruction;virtual;
  4274. procedure BeforeDestruction;virtual;
  4275. procedure DefaultHandlerStr(var message);virtual;
  4276. end;
  4277. TClass = Class Of TObject;
  4278. PClass = ^TClass;
  4279. \end{verbatim}
  4280. Unhandled exceptions can be treated using a constant of the
  4281. \var{TExceptProc} type:
  4282. \begin{verbatim}
  4283. TExceptProc = Procedure (Obj : TObject; Addr,Frame: Pointer);
  4284. \end{verbatim}
  4285. \var{Obj} is the exception object that was used to raise the exception,
  4286. \var{Addr} and \var{Frame} contain the exact address and stack frame
  4287. where the exception was raised.
  4288. The \var{TVarRec} type is used to access the elements passed in a \var{Array
  4289. of Const} argument to a function or procedure:
  4290. \begin{verbatim}
  4291. Type
  4292. PVarRec = ^TVarRec;
  4293. TVarRec = record
  4294. case VType : Longint of
  4295. vtInteger : (VInteger: Longint);
  4296. vtBoolean : (VBoolean: Boolean);
  4297. vtChar : (VChar: Char);
  4298. vtExtended : (VExtended: PExtended);
  4299. vtString : (VString: PShortString);
  4300. vtPointer : (VPointer: Pointer);
  4301. vtPChar : (VPChar: PChar);
  4302. vtObject : (VObject: TObject);
  4303. vtClass : (VClass: TClass);
  4304. vtAnsiString : (VAnsiString: Pointer);
  4305. vtWideString : (VWideString: Pointer);
  4306. vtInt64 : (VInt64: PInt64);
  4307. end;
  4308. \end{verbatim}
  4309. The heap manager uses the \var{TMemoryManager} type:
  4310. \begin{verbatim}
  4311. PMemoryManager = ^TMemoryManager;
  4312. TMemoryManager = record
  4313. Getmem : Function(Size:Longint):Pointer;
  4314. Freemem : Function(var p:pointer):Longint;
  4315. FreememSize : Function(var p:pointer;Size:Longint):Longint;
  4316. AllocMem : Function(Size:longint):Pointer;
  4317. ReAllocMem : Function(var p:pointer;Size:longint):Pointer;
  4318. MemSize : function(p:pointer):Longint;
  4319. MemAvail : Function:Longint;
  4320. MaxAvail : Function:Longint;
  4321. HeapSize : Function:Longint;
  4322. end;
  4323. \end{verbatim}
  4324. More information on using this record can be found in \progref.
  4325. \subsection{Constants}
  4326. The following constants define the maximum values that can be used with
  4327. various types:
  4328. \begin{verbatim}
  4329. MaxSIntValue = High(ValSInt);
  4330. MaxUIntValue = High(ValUInt);
  4331. maxint = maxsmallint;
  4332. maxLongint = $7fffffff;
  4333. maxSmallint = 32767;
  4334. \end{verbatim}
  4335. The following constants for file-handling are defined in the system unit:
  4336. \begin{verbatim}
  4337. Const
  4338. fmclosed = $D7B0;
  4339. fminput = $D7B1;
  4340. fmoutput = $D7B2;
  4341. fminout = $D7B3;
  4342. fmappend = $D7B4;
  4343. filemode : byte = 2;
  4344. \end{verbatim}
  4345. The \var{filemode} variable is used when a non-text file is opened using
  4346. \var{Reset}. It indicates how the file will be opened. \var{filemode} can have one of
  4347. the following values:
  4348. \begin{description}
  4349. \item[0] The file is opened for reading.
  4350. \item[1] The file is opened for writing.
  4351. \item[2] The file is opened for reading and writing.
  4352. \end{description}
  4353. The default value is 2. Other values are possible but are operating system specific.
  4354. Further, the following non processor specific general-purpose constants
  4355. are also defined:
  4356. \begin{verbatim}
  4357. const
  4358. erroraddr : pointer = nil;
  4359. errorcode : word = 0;
  4360. { max level in dumping on error }
  4361. max_frame_dump : word = 20;
  4362. \end{verbatim}
  4363. \begin{remark}
  4364. Processor specific global constants are named Testxxxx where xxxx
  4365. represents the processor number (such as Test8086, Test68000),
  4366. and are used to determine on what generation of processor the program
  4367. is running on.
  4368. \end{remark}
  4369. The following constants are defined to access VMT entries:
  4370. \begin{verbatim}
  4371. vmtInstanceSize = 0;
  4372. vmtParent = 8;
  4373. vmtClassName = 12;
  4374. vmtDynamicTable = 16;
  4375. vmtMethodTable = 20;
  4376. vmtFieldTable = 24;
  4377. vmtTypeInfo = 28;
  4378. vmtInitTable = 32;
  4379. vmtAutoTable = 36;
  4380. vmtIntfTable = 40;
  4381. vmtMsgStrPtr = 44;
  4382. vmtMethodStart = 48;
  4383. vmtDestroy = vmtMethodStart;
  4384. vmtNewInstance = vmtMethodStart+4;
  4385. vmtFreeInstance = vmtMethodStart+8;
  4386. vmtSafeCallException = vmtMethodStart+12;
  4387. vmtDefaultHandler = vmtMethodStart+16;
  4388. vmtAfterConstruction = vmtMethodStart+20;
  4389. vmtBeforeDestruction = vmtMethodStart+24;
  4390. vmtDefaultHandlerStr = vmtMethodStart+28;
  4391. \end{verbatim}
  4392. The constant names should be used, and never their values, because
  4393. the VMT table can change, breaking code that uses direct values.
  4394. The following constants will be used for the planned \var{variant} support:
  4395. \begin{verbatim}
  4396. varEmpty = $0000;
  4397. varNull = $0001;
  4398. varSmallint = $0002;
  4399. varInteger = $0003;
  4400. varSingle = $0004;
  4401. varDouble = $0005;
  4402. varCurrency = $0006;
  4403. varDate = $0007;
  4404. varOleStr = $0008;
  4405. varDispatch = $0009;
  4406. varError = $000A;
  4407. varBoolean = $000B;
  4408. varVariant = $000C;
  4409. varUnknown = $000D;
  4410. varByte = $0011;
  4411. varString = $0100;
  4412. varAny = $0101;
  4413. varTypeMask = $0FFF;
  4414. varArray = $2000;
  4415. varByRef = $4000;
  4416. \end{verbatim}
  4417. The following constants are used in the \var{TVarRec} record:
  4418. \begin{verbatim}
  4419. vtInteger = 0;
  4420. vtBoolean = 1;
  4421. vtChar = 2;
  4422. vtExtended = 3;
  4423. vtString = 4;
  4424. vtPointer = 5;
  4425. vtPChar = 6;
  4426. vtObject = 7;
  4427. vtClass = 8;
  4428. vtWideChar = 9;
  4429. vtPWideChar = 10;
  4430. vtAnsiString = 11;
  4431. vtCurrency = 12;
  4432. vtVariant = 13;
  4433. vtInterface = 14;
  4434. vtWideString = 15;
  4435. vtInt64 = 16;
  4436. vtQWord = 17;
  4437. \end{verbatim}
  4438. The \var{ExceptProc} is called when an unhandled exception occurs:
  4439. \begin{verbatim}
  4440. Const
  4441. ExceptProc : TExceptProc = Nil;
  4442. \end{verbatim}
  4443. It is set in the \file{objpas} unit, but it can be set by the programmer
  4444. to change the default exception handling.
  4445. The following constants are defined to describe the operating system's file
  4446. system:
  4447. \begin{verbatim}
  4448. LineEnding = #10;
  4449. LFNSupport = true;
  4450. DirectorySeparator = '/';
  4451. DriveSeparator = ':';
  4452. PathSeparator = ':';
  4453. FileNameCaseSensitive : Boolean = True;
  4454. \end{verbatim}
  4455. (the shown values are for \unix platforms, but will be different on other
  4456. platforms)
  4457. The meaning of the constants is the following:
  4458. \begin{description}
  4459. \item[LineEnding] End of line marker. This constant is used when writing end
  4460. of lines to text files.
  4461. \item[LFNSupport] This is \var{True} if the system supports long file names,
  4462. i.e. filenames that are not restricted to 8.3 characters.
  4463. \item[DirectorySeparator] The character that is used as a directory
  4464. separator, i.e. it appears between various parts of a path to a file.
  4465. \item[DriveSeparator] On systems that support drive letters, this character
  4466. separates the drive indication from the rest of a filename.
  4467. \item[PathSeparator] This character can be found between elements in a
  4468. series of paths (such as the contents of the \var{PATH} environment
  4469. variable.
  4470. \item[FileNameCaseSensitive] Indicates whether filenames are case sensitive.
  4471. \end{description}
  4472. When programming cross-platform, use these constants instead of hard-coded
  4473. characters. This will enhance portability of an application.
  4474. \subsection{Variables}
  4475. The following variables are defined and initialized in the system unit:
  4476. \begin{verbatim}
  4477. var
  4478. output,input,stderr : text;
  4479. exitproc : pointer;
  4480. exitcode : word;
  4481. stackbottom : Cardinal;
  4482. \end{verbatim}
  4483. The variables \var{ExitProc}, \var{exitcode} are used in the \fpc exit
  4484. scheme. It works similarly to the one in Turbo Pascal:
  4485. When a program halts (be it through the call of the \var{Halt} function or
  4486. \var{Exit} or through a run-time error), the exit mechanism checks the value
  4487. of \var{ExitProc}. If this one is non-\var{Nil}, it is set to \var{Nil}, and
  4488. the procedure is called. If the exit procedure exits, the value of ExitProc
  4489. is checked again. If it is non-\var{Nil} then the above steps are repeated.
  4490. So when an exit procedure must be installed, the old value of \var{ExitProc}
  4491. should be saved (it may be non-\var{Nil}, since other units could have set
  4492. it). In the exit procedure the value of \var{ExitProc} should be restored to
  4493. the previous value, such that if it was non-\var{Nil} the exit-procedure can be
  4494. called.
  4495. \FPCexample{ex98}
  4496. The \var{ErrorAddr} and \var{ExitCode} can be used to check for
  4497. error-conditions. If \var{ErrorAddr} is non-\var{Nil}, a run-time error has
  4498. occurred. If so, \var{ExitCode} contains the error code. If \var{ErrorAddr} is
  4499. \var{Nil}, then {ExitCode} contains the argument to \var{Halt} or 0 if the
  4500. program terminated normally.
  4501. \var{ExitCode} is always passed to the operating system as the exit-code of
  4502. the current process.
  4503. \begin{remark}
  4504. The maximum error code under \linux and \unix like operating systems is 127.
  4505. \end{remark}
  4506. Under \file{GO32}, the following constants are also defined :
  4507. \begin{verbatim}
  4508. const
  4509. seg0040 = $0040;
  4510. segA000 = $A000;
  4511. segB000 = $B000;
  4512. segB800 = $B800;
  4513. \end{verbatim}
  4514. These constants allow easy access to the bios/screen segment via mem/absolute.
  4515. The randomize function uses a seed stored in the \var{RandSeed} variable:
  4516. \begin{verbatim}
  4517. RandSeed : Cardinal;
  4518. \end{verbatim}
  4519. This variable is initialized in the initialization code of the system unit.
  4520. Other variables indicate the state of the application.
  4521. \begin{verbatim}
  4522. IsLibrary : boolean;
  4523. IsMultiThread : boolean;
  4524. \end{verbatim}
  4525. The \var{IsLibrary} variable is set to true if this module is a
  4526. shared library instead of an application. The \var{IsMultiThread}
  4527. variable is set to True if the application has spawned other
  4528. threads, otherwise, and by default, it is set to False.
  4529. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  4530. % Functions and Procedures by category
  4531. \section{Function list by category}
  4532. What follows is a listing of the available functions, grouped by category.
  4533. For each function there is a reference to the page where the
  4534. function can be found:
  4535. \subsection{File handling}
  4536. Functions concerning input and output from and to file.
  4537. \begin{funclist}
  4538. \procref{Append}{Open a file in append mode}
  4539. \procref{Assign}{Assign a name to a file}
  4540. \procref{Blockread}{Read data from a file into memory}
  4541. \procref{Blockwrite}{Write data from memory to a file}
  4542. \procref{Close}{Close a file}
  4543. \funcref{Eof}{Check for end of file}
  4544. \funcref{Eoln}{Check for end of line}
  4545. \procref{Erase}{Delete file from disk}
  4546. \funcref{Filepos}{Position in file}
  4547. \funcref{Filesize}{Size of file}
  4548. \procref{Flush}{Write file buffers to disk}
  4549. \funcref{IOresult}{Return result of last file IO operation}
  4550. \procref{Read}{Read from file into variable}
  4551. \procref{Readln}{Read from file into variable and goto next line}
  4552. \procref{Rename}{Rename file on disk}
  4553. \procref{Reset}{Open file for reading}
  4554. \procref{Rewrite}{Open file for writing}
  4555. \procref{Seek}{Set file position}
  4556. \funcref{SeekEof}{Set file position to end of file}
  4557. \funcref{SeekEoln}{Set file position to end of line}
  4558. \procref{SetTextBuf}{Set size of file buffer}
  4559. \procref{Truncate}{Truncate the file at position}
  4560. \procref{Write}{Write variable to file}
  4561. \procref{WriteLn}{Write variable to file and append newline}
  4562. \end{funclist}
  4563. \subsection{Memory management}
  4564. Functions concerning memory issues.
  4565. \begin{funclist}
  4566. \funcref{Addr}{Return address of variable}
  4567. \funcref{Assigned}{Check if a pointer is valid}
  4568. \funcref{CompareByte}{Compare 2 memory buffers byte per byte}
  4569. \funcref{CompareChar}{Compare 2 memory buffers byte per byte}
  4570. \funcref{CompareDWord}{Compare 2 memory buffers byte per byte}
  4571. \funcref{CompareWord}{Compare 2 memory buffers byte per byte}
  4572. \funcref{CSeg}{Return code segment}
  4573. \procref{Dispose}{Free dynamically allocated memory}
  4574. \funcref{DSeg}{Return data segment}
  4575. \procref{FillByte}{Fill memory region with 8-bit pattern}
  4576. \procref{Fillchar}{Fill memory region with certain character}
  4577. \procref{FillDWord}{Fill memory region with 32-bit pattern}
  4578. \procref{Fillword}{Fill memory region with 16-bit pattern}
  4579. \procref{Freemem}{Release allocated memory}
  4580. \procref{Getmem}{Allocate new memory}
  4581. \procref{GetMemoryManager}{Return current memory manager}
  4582. \funcref{High}{Return highest index of open array or enumerated}
  4583. \funcref{IsMemoryManagerSet}{Is the memory manager set}
  4584. \funcref{Low}{Return lowest index of open array or enumerated}
  4585. \procref{Mark}{Mark current memory position}
  4586. \funcref{Maxavail}{Return size of largest free memory block}
  4587. \funcref{Memavail}{Return total available memory}
  4588. \procref{Move}{Move data from one location in memory to another}
  4589. \procrefl{MoveChar0}{MoveCharNull}{Move data till first zero character}
  4590. \procref{New}{Dynamically allocate memory for variable}
  4591. \funcref{Ofs}{Return offset of variable}
  4592. \funcref{Ptr}{Combine segment and offset to pointer}
  4593. \procref{Release}{Release memory above mark point}
  4594. \funcref{Seg}{Return segment}
  4595. \procref{SetMemoryManager}{Set a memory manager}
  4596. \funcref{Sptr}{Return current stack pointer}
  4597. \funcref{SSeg}{Return stack segment register value}
  4598. \end{funclist}
  4599. \subsection{Mathematical routines}
  4600. Functions connected to calculating and coverting numbers.
  4601. \begin{funclist}
  4602. \funcref{Abs}{Calculate absolute value}
  4603. \funcref{Arctan}{Calculate inverse tangent}
  4604. \funcref{Cos}{Calculate cosine of angle}
  4605. \procref{Dec}{Decrease value of variable}
  4606. \funcref{Exp}{Exponentiate}
  4607. \funcref{Frac}{Return fractional part of floating point value}
  4608. \funcref{Hi}{Return high byte/word of value}
  4609. \procref{Inc}{Increase value of variable}
  4610. \funcref{Int}{Calculate integer part of floating point value}
  4611. \funcref{Ln}{Calculate logarithm}
  4612. \funcref{Lo}{Return low byte/word of value}
  4613. \funcref{Odd}{Is a value odd or even ? }
  4614. \funcref{Pi}{Return the value of pi}
  4615. \funcref{Power}{Raise float to integer power}
  4616. \funcref{Random}{Generate random number}
  4617. \procref{Randomize}{Initialize random number generator}
  4618. \funcref{Round}{Round floating point value to nearest integer number}
  4619. \funcref{Sin}{Calculate sine of angle}
  4620. \funcref{Sqr}{Calculate the square of a value}
  4621. \funcref{Sqrt}{Calculate the square root of a value}
  4622. \funcref{Swap}{Swap high and low bytes/words of a variable}
  4623. \funcref{Trunc}{Truncate a floating point value}
  4624. \end{funclist}
  4625. \subsection{String handling}
  4626. All things connected to string handling.
  4627. \begin{funclist}
  4628. \funcref{BinStr}{Construct binary representation of integer}
  4629. \funcref{Chr}{Convert ASCII code to character}
  4630. \funcref{Concat}{Concatenate two strings}
  4631. \funcref{Copy}{Copy part of a string}
  4632. \procref{Delete}{Delete part of a string}
  4633. \funcref{HexStr}{Construct hexadecimal representation of integer}
  4634. \procref{Insert}{Insert one string in another}
  4635. \funcref{Length}{Return length of string}
  4636. \funcref{Lowercase}{Convert string to all-lowercase}
  4637. \funcref{OctStr}{Construct octal representation of integer}
  4638. \funcref{Pos}{Calculate position of one string in another}
  4639. \procref{SetLength}{Set length of a string}
  4640. \procref{SetString}{Set contents and length of a string}
  4641. \procref{Str}{Convert number to string representation}
  4642. \funcref{StringOfChar}{Create string consisting of a number of characters}
  4643. \funcref{Upcase}{Convert string to all-uppercase}
  4644. \procref{Val}{Convert string to number}
  4645. \end{funclist}
  4646. \subsection{Operating System functions}
  4647. Functions that are connected to the operating system.
  4648. \begin{funclist}
  4649. \procref{Chdir}{Change working directory}
  4650. \procref{Getdir}{Return current working directory}
  4651. \procref{Halt}{Halt program execution}
  4652. \funcref{Paramcount}{Number of parameters with which program was called}
  4653. \funcref{Paramstr}{Retrieve parameters with which program was called}
  4654. \procref{Mkdir}{Make a directory}
  4655. \procref{Rmdir}{Remove a directory}
  4656. \procref{Runerror}{Abort program execution with error condition}
  4657. \end{funclist}
  4658. \subsection{Miscellaneous functions}
  4659. Functions that do not belong in one of the other categories.
  4660. \begin{funclist}
  4661. \procref{Assert}{Conditionally abort program with error}
  4662. \procref{Break}{Abort current loop}
  4663. \procref{Continue}{Next cycle in current loop}
  4664. \procref{Exclude}{Exclude an element from a set}
  4665. \procref{Exit}{Exit current function or procedure}
  4666. \procref{Include}{Include an element into a set}
  4667. \procref{LongJmp}{Jump to execution point}
  4668. \funcref{Ord}{Return ordinal value of enumerated type}
  4669. \funcref{Pred}{Return previous value of ordinal type}
  4670. \funcref{SetJmp}{Mark execution point for jump}
  4671. \funcref{SizeOf}{Return size of variable or type}
  4672. \funcref{Succ}{Return next value of ordinal type}
  4673. \end{funclist}
  4674. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  4675. % Functions and Procedures
  4676. \section{Functions and Procedures}
  4677. \begin{function}{Abs}
  4678. \Declaration
  4679. Function Abs (X : Every numerical type) : Every numerical type;
  4680. \Description
  4681. \var{Abs} returns the absolute value of a variable. The result of the
  4682. function has the same type as its argument, which can be any numerical
  4683. type.
  4684. \Errors
  4685. None.
  4686. \SeeAlso
  4687. \seef{Round}
  4688. \end{function}
  4689. \FPCexample{ex1}
  4690. \begin{function}{Addr}
  4691. \Declaration
  4692. Function Addr (X : Any type) : Pointer;
  4693. \Description
  4694. \var{Addr} returns a pointer to its argument, which can be any type, or a
  4695. function or procedure name. The returned pointer isn't typed.
  4696. The same result can be obtained by the \var{@} operator, which can return a
  4697. typed pointer (\progref).
  4698. \Errors
  4699. None
  4700. \SeeAlso
  4701. \seef{SizeOf}
  4702. \end{function}
  4703. \FPCexample{ex2}
  4704. \begin{procedure}{Append}
  4705. \Declaration
  4706. Procedure Append (Var F : Text);
  4707. \Description
  4708. \var{Append} opens an existing file in append mode. Any data written to
  4709. \var{F} will be appended to the file. Only text files can be opened in
  4710. append mode. After a call to \var{Append}, the file \var{F} becomes
  4711. write-only.
  4712. File sharing is not taken into account when calling \var{Append}.
  4713. \Errors
  4714. If the file doesn't exist when appending, a run-time error will be generated.
  4715. This behaviour has changed on Windows and Linux platforms, where in versions
  4716. prior to 1.0.6, the file would be created in append mode.
  4717. \SeeAlso
  4718. \seep{Rewrite},\seep{Close}, \seep{Reset}
  4719. \end{procedure}
  4720. \FPCexample{ex3}
  4721. \begin{function}{Arctan}
  4722. \Declaration
  4723. Function Arctan (X : Real) : Real;
  4724. \Description
  4725. \var{Arctan} returns the Arctangent of \var{X}, which can be any Real type.
  4726. The resulting angle is in radial units.
  4727. \Errors
  4728. None
  4729. \SeeAlso
  4730. \seef{Sin}, \seef{Cos}
  4731. \end{function}
  4732. \FPCexample{ex4}
  4733. \begin{procedure}{Assert}
  4734. \Declaration
  4735. Procedure Assert(expr : Boolean [; const msg: string]);
  4736. \Description
  4737. With assertions on, \var{Assert} tests if \var{expr} is
  4738. false, and if so, aborts the application with a Runtime error
  4739. 227 and an optional error message in \var{msg}.
  4740. If \var{expr} is true, program execution continues normally.
  4741. If assertions are not enabled at compile time, this routine does
  4742. nothing, and no code is generated for the \var{Assert} call.
  4743. Enabling and disabling assertions at compile time is done via
  4744. the \var{\$C} or \var{\$ASSERTIONS} compiler switches. These are
  4745. global switches.
  4746. The default behavior of the assert call can be changed by
  4747. setting a new handler in the \var{AssertErrorProc} variable.
  4748. Sysutils overrides the default handler to raise a \var{EAssertionFailed}
  4749. exception.
  4750. \Errors
  4751. None.
  4752. \SeeAlso
  4753. \seep{Halt}, \seep{Runerror}
  4754. \end{procedure}
  4755. \begin{procedure}{Assign}
  4756. \Declaration
  4757. Procedure Assign (Var F; Name : String);
  4758. \Description
  4759. \var{Assign} assigns a name to \var{F}, which can be any file type.
  4760. This call doesn't open the file, it just assigns a name to a file variable,
  4761. and marks the file as closed.
  4762. \Errors
  4763. None.
  4764. \SeeAlso
  4765. \seep{Reset}, \seep{Rewrite}, \seep{Append}
  4766. \end{procedure}
  4767. \FPCexample{ex5}
  4768. \begin{function}{Assigned}
  4769. \Declaration
  4770. Function Assigned (P : Pointer) : Boolean;
  4771. \Description
  4772. \var{Assigned} returns \var{True} if \var{P} is non-nil
  4773. and retuns \var{False} of \var{P} is nil.
  4774. The main use of Assigned is that Procedural variables, method variables and
  4775. class-type variables also can be passed to \var{Assigned}.
  4776. \Errors
  4777. None
  4778. \SeeAlso
  4779. \seep{New}
  4780. \end{function}
  4781. \FPCexample{ex96}
  4782. \begin{function}{BinStr}
  4783. \Declaration
  4784. Function BinStr (Value : longint; cnt : byte) : String;
  4785. \Description
  4786. \var{BinStr} returns a string with the binary representation
  4787. of \var{Value}. The string has at most \var{cnt} characters.
  4788. (i.e. only the \var{cnt} rightmost bits are taken into account)
  4789. To have a complete representation of any longint-type value, 32
  4790. bits are needed, i.e. \var{cnt=32}
  4791. \Errors
  4792. None.
  4793. \SeeAlso
  4794. \seep{Str},\seep{Val},\seef{HexStr}, \seef{OctStr}
  4795. \end{function}
  4796. \FPCexample{ex82}
  4797. \begin{procedure}{Blockread}
  4798. \Declaration
  4799. Procedure Blockread (Var F : File; Var Buffer; Var Count : Longint [; var
  4800. Result : Longint]);
  4801. \Description
  4802. \var{Blockread} reads \var{count} or less records from file \var{F}. A
  4803. record is a block of bytes with size specified by the \seep{Rewrite} or
  4804. \seep{Reset} statement.
  4805. The result is placed in \var{Buffer}, which must contain enough room for
  4806. \var{Count} records. The function cannot read partial records.
  4807. If \var{Result} is specified, it contains the number of records actually
  4808. read. If \var{Result} isn't specified, and less than \var{Count} records were
  4809. read, a run-time error is generated. This behavior can be controlled by the
  4810. \var{\{\$i\}} switch.
  4811. \Errors
  4812. Depending on the state of the \var{\{\$I\}} switch, a runtime error can be
  4813. generated if there is an error. In the \var{\{\$I-\}} state, use \var{IOResult}
  4814. to check for errors.
  4815. \SeeAlso
  4816. \seep{Blockwrite}, \seep{Close}, \seep{Reset}, \seep{Assign}
  4817. \end{procedure}
  4818. \FPCexample{ex6}
  4819. \begin{procedure}{Blockwrite}
  4820. \Declaration
  4821. Procedure Blockwrite (Var F : File; Var Buffer; Var Count : Longint);
  4822. \Description
  4823. \var{BlockWrite} writes \var{count} records from \var{buffer} to the file
  4824. \var{F}.A record is a block of bytes with size specified by the \seep{Rewrite} or
  4825. \seep{Reset} statement.
  4826. If the records couldn't be written to disk, a run-time error is generated.
  4827. This behavior can be controlled by the \var{\{\$i\}} switch.
  4828. \Errors
  4829. Depending on the state of the \var{\{\$I\}} switch, a runtime error can be
  4830. generated if there is an error. In the \var{\{\$I-\}} state, use \var{IOResult}
  4831. to check for errors.
  4832. \SeeAlso
  4833. \seep{Blockread},\seep{Close}, \seep{Rewrite}, \seep{Assign}
  4834. \end{procedure}
  4835. For the example, see \seep{Blockread}.
  4836. \begin{procedure}{Break}
  4837. \Declaration
  4838. Procedure Break;
  4839. \Description
  4840. \var{Break} jumps to the statement following the end of the current
  4841. repetitive statement. The code between the \var{Break} call and
  4842. the end of the repetitive statement is skipped.
  4843. The condition of the repetitive statement is NOT evaluated.
  4844. This can be used with \var{For}, var{repeat} and \var{While} statements.
  4845. Note that while this is a procedure, \var{Break} is a reserved word
  4846. and hence cannot be redefined.
  4847. \Errors
  4848. None.
  4849. \SeeAlso
  4850. \seep{Continue}, \seep{Exit}
  4851. \end{procedure}
  4852. \FPCexample{ex87}
  4853. \begin{procedure}{Chdir}
  4854. \Declaration
  4855. Procedure Chdir (const S : string);
  4856. \Description
  4857. \var{Chdir} changes the working directory of the process to \var{S}.
  4858. \Errors
  4859. \Errors
  4860. Depending on the state of the \var{\{\$I\}} switch, a runtime error can be
  4861. generated if there is an error. In the \var{\{\$I-\}} state, use \var{IOResult}
  4862. to check for errors.
  4863. \SeeAlso
  4864. \seep{Mkdir}, \seep{Rmdir}
  4865. \end{procedure}
  4866. \FPCexample{ex7}
  4867. \begin{function}{Chr}
  4868. \Declaration
  4869. Function Chr (X : byte) : Char;
  4870. \Description
  4871. \var{Chr} returns the character which has ASCII value \var{X}.
  4872. \Errors
  4873. None.
  4874. \SeeAlso
  4875. \seef{Ord}, \seep{Str}
  4876. \end{function}
  4877. \FPCexample{ex8}
  4878. \begin{procedure}{Close}
  4879. \Declaration
  4880. Procedure Close (Var F : Anyfiletype);
  4881. \Description
  4882. \var{Close} flushes the buffer of the file \var{F} and closes \var{F}.
  4883. After a call to \var{Close}, data can no longer be read from or written to
  4884. \var{F}.
  4885. To reopen a file closed with \var{Close}, it isn't necessary to assign the
  4886. file again. A call to \seep{Reset} or \seep{Rewrite} is sufficient.
  4887. \Errors
  4888. Depending on the state of the \var{\{\$I\}} switch, a runtime error can be
  4889. generated if there is an error. In the \var{\{\$I-\}} state, use \var{IOResult}
  4890. to check for errors.
  4891. \SeeAlso
  4892. \seep{Assign}, \seep{Reset}, \seep{Rewrite}, \seep{Flush}
  4893. \end{procedure}
  4894. \FPCexample{ex9}
  4895. \begin{function}{CompareByte}
  4896. \Declaration
  4897. function CompareByte(var buf1,buf2;len:longint):longint;
  4898. \Description
  4899. \var{CompareByte} compares two memory regions \var{buf1},\var{buf2} on a
  4900. byte-per-byte basis for a total of \var{len} bytes.
  4901. The function returns one of the following values:
  4902. \begin{description}
  4903. \item[-1] if \var{buf1} and \var{buf2} contain different bytes
  4904. in the first \var{len} bytes, and the first such byte is smaller in \var{buf1}
  4905. than the byte at the same position in \var{buf2}.
  4906. \item[0] if the first \var{len} bytes in \var{buf1} and \var{buf2} are
  4907. equal.
  4908. \item [1] if \var{buf1} and \var{buf2} contain different bytes
  4909. in the first \var{len} bytes, and the first such byte is larger in \var{buf1}
  4910. than the byte at the same position in \var{buf2}.
  4911. \end{description}
  4912. \Errors
  4913. None.
  4914. \SeeAlso
  4915. \seef{CompareChar},\seef{CompareWord},\seef{CompareDWord}
  4916. \end{function}
  4917. \FPCexample{ex99}
  4918. \begin{function}{CompareChar}
  4919. \Declaration
  4920. function CompareChar(var buf1,buf2;len:longint):longint;
  4921. function CompareChar0(var buf1,buf2;len:longint):longint;
  4922. \Description
  4923. \var{CompareChar} compares two memory regions \var{buf1},\var{buf2} on a
  4924. character-per-character basis for a total of \var{len} characters.
  4925. The \var{CompareChar0} variant compares \var{len} bytes, or until
  4926. a zero character is found.
  4927. The function returns one of the following values:
  4928. \begin{description}
  4929. \item[-1] if \var{buf1} and \var{buf2} contain different characters
  4930. in the first \var{len} positions, and the first such character is smaller in \var{buf1}
  4931. than the character at the same position in \var{buf2}.
  4932. \item[0] if the first \var{len} characters in \var{buf1} and \var{buf2} are
  4933. equal.
  4934. \item [1] if \var{buf1} and \var{buf2} contain different characters
  4935. in the first \var{len} positions, and the first such character is larger in
  4936. \var{buf1} than the character at the same position in \var{buf2}.
  4937. \end{description}
  4938. \Errors
  4939. None.
  4940. \SeeAlso
  4941. \seef{CompareByte},\seef{CompareWord},\seef{CompareDWord}
  4942. \end{function}
  4943. \FPCexample{ex100}
  4944. \begin{function}{CompareDWord}
  4945. \Declaration
  4946. function CompareDWord(var buf1,buf2;len:longint):longint;
  4947. \Description
  4948. \var{CompareDWord} compares two memory regions \var{buf1},\var{buf2} on a
  4949. DWord-per-DWord basis for a total of \var{len} DWords. (A DWord is 4 bytes).
  4950. The function returns one of the following values:
  4951. \begin{description}
  4952. \item[-1] if \var{buf1} and \var{buf2} contain different DWords
  4953. in the first \var{len} DWords, and the first such DWord is smaller in \var{buf1}
  4954. than the DWord at the same position in \var{buf2}.
  4955. \item[0] if the first \var{len} DWords in \var{buf1} and \var{buf2} are
  4956. equal.
  4957. \item [1] if \var{buf1} and \var{buf2} contain different DWords
  4958. in the first \var{len} DWords, and the first such DWord is larger in \var{buf1}
  4959. than the DWord at the same position in \var{buf2}.
  4960. \end{description}
  4961. \Errors
  4962. None.
  4963. \SeeAlso
  4964. \seef{CompareChar},\seef{CompareByte},\seef{CompareWord},
  4965. \end{function}
  4966. \FPCexample{ex101}
  4967. \begin{function}{CompareWord}
  4968. \Declaration
  4969. function CompareWord(var buf1,buf2;len:longint):longint;
  4970. \Description
  4971. \var{CompareWord} compares two memory regions \var{buf1},\var{buf2} on a
  4972. Word-per-Word basis for a total of \var{len} Words. (A Word is 2 bytes).
  4973. The function returns one of the following values:
  4974. \begin{description}
  4975. \item[-1] if \var{buf1} and \var{buf2} contain different Words
  4976. in the first \var{len} Words, and the first such Word is smaller in \var{buf1}
  4977. than the Word at the same position in \var{buf2}.
  4978. \item[0] if the first \var{len} Words in \var{buf1} and \var{buf2} are
  4979. equal.
  4980. \item [1] if \var{buf1} and \var{buf2} contain different Words
  4981. in the first \var{len} Words, and the first such Word is larger in \var{buf1}
  4982. than the Word at the same position in \var{buf2}.
  4983. \end{description}
  4984. \Errors
  4985. None.
  4986. \SeeAlso
  4987. \seef{CompareChar},\seef{CompareByte},\seef{CompareWord},
  4988. \end{function}
  4989. \FPCexample{ex102}
  4990. \begin{function}{Concat}
  4991. \Declaration
  4992. Function Concat (S1,S2 [,S3, ... ,Sn]) : String;
  4993. \Description
  4994. \var{Concat} concatenates the strings \var{S1},\var{S2} etc. to one long
  4995. string. The resulting string is truncated at a length of 255 bytes.
  4996. The same operation can be performed with the \var{+} operation.
  4997. \Errors
  4998. None.
  4999. \SeeAlso
  5000. \seef{Copy}, \seep{Delete}, \seep{Insert}, \seef{Pos}, \seef{Length}
  5001. \end{function}
  5002. \FPCexample{ex10}
  5003. \begin{procedure}{Continue}
  5004. \Declaration
  5005. Procedure Continue;
  5006. \Description
  5007. \var{Continue} jumps to the end of the current repetitive statement.
  5008. The code between the \var{Continue} call and the end of the repetitive
  5009. statement is skipped. The condition of the repetitive statement is then
  5010. checked again.
  5011. This can be used with \var{For}, var{repeat} and \var{While} statements.
  5012. Note that while this is a procedure, \var{Continue} is a reserved word
  5013. and hence cannot be redefined.
  5014. \Errors
  5015. None.
  5016. \SeeAlso
  5017. \seep{Break}, \seep{Exit}
  5018. \end{procedure}
  5019. \FPCexample{ex86}
  5020. \begin{function}{Copy}
  5021. \Declaration
  5022. Function Copy (Const S : String;Index : Integer;Count : Integer) : String;
  5023. \Description
  5024. \var{Copy} returns a string which is a copy if the \var{Count} characters
  5025. in \var{S}, starting at position \var{Index}. If \var{Count} is larger than
  5026. the length of the string \var{S}, the result is truncated.
  5027. If \var{Index} is larger than the length of the string \var{S}, then an
  5028. empty string is returned.
  5029. \Errors
  5030. None.
  5031. \SeeAlso
  5032. \seep{Delete}, \seep{Insert}, \seef{Pos}
  5033. \end{function}
  5034. \FPCexample{ex11}
  5035. \begin{function}{Cos}
  5036. \Declaration
  5037. Function Cos (X : Real) : Real;
  5038. \Description
  5039. \var{Cos} returns the cosine of \var{X}, where X is an angle, in radians.
  5040. If the absolute value of the argument is larger than \var{2\^{}63}, then the
  5041. result is undefined.
  5042. \Errors
  5043. None.
  5044. \SeeAlso
  5045. \seef{Arctan}, \seef{Sin}
  5046. \end{function}
  5047. \FPCexample{ex12}
  5048. \begin{function}{CSeg}
  5049. \Declaration
  5050. Function CSeg : Word;
  5051. \Description
  5052. \var{CSeg} returns the Code segment register. In \fpc, it returns always a
  5053. zero, since \fpc is a 32 bit compiler.
  5054. \Errors
  5055. None.
  5056. \SeeAlso
  5057. \seef{DSeg}, \seef{Seg}, \seef{Ofs}, \seef{Ptr}
  5058. \end{function}
  5059. \FPCexample{ex13}
  5060. \begin{procedure}{Dec}
  5061. \Declaration
  5062. Procedure Dec (Var X : Any ordinal type[; Decrement : Any ordinal type]);
  5063. \Description
  5064. \var{Dec} decreases the value of \var{X} with \var{Decrement}.
  5065. If \var{Decrement} isn't specified, then 1 is taken as a default.
  5066. \Errors
  5067. A range check can occur, or an underflow error, if an attempt it made
  5068. to decrease \var{X} below its minimum value.
  5069. \SeeAlso
  5070. \seep{Inc}
  5071. \end{procedure}
  5072. \FPCexample{ex14}
  5073. \begin{procedure}{Delete}
  5074. \Declaration
  5075. Procedure Delete (var S : string;Index : Integer;Count : Integer);
  5076. \Description
  5077. \var{Delete} removes \var{Count} characters from string \var{S}, starting
  5078. at position \var{Index}. All characters after the delected characters are
  5079. shifted \var{Count} positions to the left, and the length of the string is adjusted.
  5080. \Errors
  5081. None.
  5082. \SeeAlso
  5083. \seef{Copy},\seef{Pos},\seep{Insert}
  5084. \end{procedure}
  5085. \FPCexample{ex15}
  5086. \begin{procedure}{Dispose}
  5087. \Declaration
  5088. Procedure Dispose (P : pointer);\\
  5089. Procedure Dispose (P : Typed Pointer; Des : Procedure);
  5090. \Description
  5091. The first form \var{Dispose} releases the memory allocated with a call to
  5092. \seep{New}. The pointer \var{P} must be typed. The released memory is
  5093. returned to the heap.
  5094. The second form of \var{Dispose} accepts as a first parameter a pointer
  5095. to an object type, and as a second parameter the name of a destructor
  5096. of this object. The destructor will be called, and the memory allocated
  5097. for the object will be freed.
  5098. \Errors
  5099. An runtime error will occur if the pointer doesn't point to a location in the
  5100. heap.
  5101. \SeeAlso
  5102. \seep{New}, \seep{Getmem}, \seep{Freemem}
  5103. \end{procedure}
  5104. \FPCexample{ex16}
  5105. \begin{function}{DSeg}
  5106. \Declaration
  5107. Function DSeg : Word;
  5108. \Description
  5109. \var{DSeg} returns the data segment register. In \fpc, it returns always a
  5110. zero, since \fpc is a 32 bit compiler.
  5111. \Errors
  5112. None.
  5113. \SeeAlso
  5114. \seef{CSeg}, \seef{Seg}, \seef{Ofs}, \seef{Ptr}
  5115. \end{function}
  5116. \FPCexample{ex17}
  5117. \begin{function}{Eof}
  5118. \Declaration
  5119. Function Eof [(F : Any file type)] : Boolean;
  5120. \Description
  5121. \var{Eof} returns \var{True} if the file-pointer has reached the end of the
  5122. file, or if the file is empty. In all other cases \var{Eof} returns
  5123. \var{False}.
  5124. If no file \var{F} is specified, standard input is assumed.
  5125. \Errors
  5126. Depending on the state of the \var{\{\$I\}} switch, a runtime error can be
  5127. generated if there is an error. In the \var{\{\$I-\}} state, use \var{IOResult}
  5128. to check for errors.
  5129. \SeeAlso
  5130. \seef{Eoln}, \seep{Assign}, \seep{Reset}, \seep{Rewrite}
  5131. \end{function}
  5132. \FPCexample{ex18}
  5133. \begin{function}{Eoln}
  5134. \Declaration
  5135. Function Eoln [(F : Text)] : Boolean;
  5136. \Description
  5137. \var{Eof} returns \var{True} if the file pointer has reached the end of a
  5138. line, which is demarcated by a line-feed character (ASCII value 10), or if
  5139. the end of the file is reached.
  5140. In all other cases \var{Eof} returns \var{False}.
  5141. If no file \var{F} is specified, standard input is assumed.
  5142. It can only be used on files of type \var{Text}.
  5143. \Errors
  5144. None.
  5145. \SeeAlso
  5146. \seef{Eof}, \seep{Assign}, \seep{Reset}, \seep{Rewrite}
  5147. \end{function}
  5148. \FPCexample{ex19}
  5149. \begin{procedure}{Erase}
  5150. \Declaration
  5151. Procedure Erase (Var F : Any file type);
  5152. \Description
  5153. \var{Erase} removes an unopened file from disk. The file should be
  5154. assigned with \var{Assign}, but not opened with \var{Reset} or \var{Rewrite}
  5155. \Errors
  5156. Depending on the state of the \var{\{\$I\}} switch, a runtime error can be
  5157. generated if there is an error. In the \var{\{\$I-\}} state, use \var{IOResult}
  5158. to check for errors.
  5159. \SeeAlso
  5160. \seep{Assign}
  5161. \end{procedure}
  5162. \FPCexample{ex20}
  5163. \begin{procedure}{Exclude}
  5164. \Declaration
  5165. Procedure Exclude (Var S : Any set type; E : Set element);
  5166. \Description
  5167. \var{Exclude} removes \var{E} from the set \var{S} if it is
  5168. included inthe set. E should be of the same type as the base type
  5169. of the set \var{S}.
  5170. Thus, the two following statements do the same thing:
  5171. \begin{verbatim}
  5172. S:=S-[E];
  5173. Exclude(S,E);
  5174. \end{verbatim}
  5175. \Errors
  5176. If the type of the element \var{E} is not equal to the base type of the
  5177. set \var{S}, the compiler will generate an error.
  5178. \SeeAlso
  5179. \seep{Include}
  5180. \end{procedure}
  5181. \FPCexample{ex111}
  5182. \begin{procedure}{Exit}
  5183. \Declaration
  5184. Procedure Exit ([Var X : return type )];
  5185. \Description
  5186. \var{Exit} exits the current subroutine, and returns control to the calling
  5187. routine. If invoked in the main program routine, exit stops the program.
  5188. The optional argument \var{X} allows to specify a return value, in the case
  5189. \var{Exit} is invoked in a function. The function result will then be
  5190. equal to \var{X}.
  5191. \Errors
  5192. None.
  5193. \SeeAlso
  5194. \seep{Halt}
  5195. \end{procedure}
  5196. \FPCexample{ex21}
  5197. \begin{function}{Exp}
  5198. \Declaration
  5199. Function Exp (Var X : Real) : Real;
  5200. \Description
  5201. \var{Exp} returns the exponent of \var{X}, i.e. the number \var{e} to the
  5202. power \var{X}.
  5203. \Errors
  5204. None.
  5205. \SeeAlso
  5206. \seef{Ln}, \seef{Power}
  5207. \end{function}
  5208. \FPCexample{ex22}
  5209. \begin{function}{Filepos}
  5210. \Declaration
  5211. Function Filepos (Var F : Any file type) : Longint;
  5212. \Description
  5213. \var{Filepos} returns the current record position of the file-pointer in file
  5214. \var{F}. It cannot be invoked with a file of type \var{Text}. A compiler error
  5215. will be generated if this is attempted.
  5216. \Errors
  5217. Depending on the state of the \var{\{\$I\}} switch, a runtime error can be
  5218. generated if there is an error. In the \var{\{\$I-\}} state, use \var{IOResult}
  5219. to check for errors.
  5220. \SeeAlso
  5221. \seef{Filesize}
  5222. \end{function}
  5223. \FPCexample{ex23}
  5224. \begin{function}{Filesize}
  5225. \Declaration
  5226. Function Filesize (Var F : Any file type) : Longint;
  5227. \Description
  5228. \var{Filesize} returns the total number of records in file \var{F}.
  5229. It cannot be invoked with a file of type \var{Text}. (under \linux and \unix, this
  5230. also means that it cannot be invoked on pipes).
  5231. If \var{F} is empty, 0 is returned.
  5232. \Errors
  5233. Depending on the state of the \var{\{\$I\}} switch, a runtime error can be
  5234. generated if there is an error. In the \var{\{\$I-\}} state, use \var{IOResult}
  5235. to check for errors.
  5236. \SeeAlso
  5237. \seef{Filepos}
  5238. \end{function}
  5239. \FPCexample{ex24}
  5240. \begin{procedure}{FillByte}
  5241. \Declaration
  5242. Procedure FillByte(var X;Count:longint;Value:byte);
  5243. \Description
  5244. \var{FillByte} fills the memory starting at \var{X} with \var{Count} bytes
  5245. with value equal to \var{Value}.
  5246. This is useful for quickly zeroing out a memory location. When the size of
  5247. the memory location to be filled out is a multiple of 2 bytes, it is better
  5248. to use \seep{Fillword}, and if it is a multiple of 4 bytes it is better
  5249. to use \seep{FillDWord}, these routines are optimized for their respective sizes.
  5250. \Errors
  5251. No checking on the size of \var{X} is done.
  5252. \SeeAlso
  5253. \seep{Fillchar}, \seep{FillDWord}, \seep{Fillword}, \seep{Move}
  5254. \end{procedure}
  5255. \FPCexample{ex102}
  5256. \begin{procedure}{Fillchar}
  5257. \Declaration
  5258. Procedure Fillchar (Var X;Count : Longint;Value : char or byte);;
  5259. \Description
  5260. \var{Fillchar} fills the memory starting at \var{X} with \var{Count} bytes
  5261. or characters with value equal to \var{Value}.
  5262. \Errors
  5263. No checking on the size of \var{X} is done.
  5264. \SeeAlso
  5265. \seep{Fillword}, \seep{Move}, \seep{FillByte}, \seep{FillDWord}
  5266. \end{procedure}
  5267. \FPCexample{ex25}
  5268. \begin{procedure}{FillDWord}
  5269. \Declaration
  5270. Procedure FillDWord (Var X;Count : Longint;Value : DWord);;
  5271. \Description
  5272. \var{Fillword} fills the memory starting at \var{X} with \var{Count} DWords
  5273. with value equal to \var{Value}. A DWord is 4 bytes in size.
  5274. \Errors
  5275. No checking on the size of \var{X} is done.
  5276. \SeeAlso
  5277. \seep{FillByte}, \seep{Fillchar}, \seep{Fillword}, \seep{Move}
  5278. \end{procedure}
  5279. \FPCexample{ex103}
  5280. \begin{procedure}{Fillword}
  5281. \Declaration
  5282. Procedure Fillword (Var X;Count : Longint;Value : Word);;
  5283. \Description
  5284. \var{Fillword} fills the memory starting at \var{X} with \var{Count} words
  5285. with value equal to \var{Value}. A word is 2 bytes in size.
  5286. \Errors
  5287. No checking on the size of \var{X} is done.
  5288. \SeeAlso
  5289. \seep{Fillchar}, \seep{Move}
  5290. \end{procedure}
  5291. \FPCexample{ex76}
  5292. \begin{procedure}{Flush}
  5293. \Declaration
  5294. Procedure Flush (Var F : Text);
  5295. \Description
  5296. \var{Flush} empties the internal buffer of an opened file \var{F} and writes the
  5297. contents to disk. The file is \textit{not} closed as a result of this call.
  5298. \Errors
  5299. Depending on the state of the \var{\{\$I\}} switch, a runtime error can be
  5300. generated if there is an error. In the \var{\{\$I-\}} state, use \var{IOResult}
  5301. to check for errors.
  5302. \SeeAlso
  5303. \seep{Close}
  5304. \end{procedure}
  5305. \FPCexample{ex26}
  5306. \begin{function}{Frac}
  5307. \Declaration
  5308. Function Frac (X : Real) : Real;
  5309. \Description
  5310. \var{Frac} returns the non-integer part of \var{X}.
  5311. \Errors
  5312. None.
  5313. \SeeAlso
  5314. \seef{Round}, \seef{Int}
  5315. \end{function}
  5316. \FPCexample{ex27}
  5317. \begin{procedure}{Freemem}
  5318. \Declaration
  5319. Procedure Freemem (Var P : pointer; Count : Longint);
  5320. \Description
  5321. \var{Freemem} releases the memory occupied by the pointer \var{P}, of size
  5322. \var{Count} (in bytes), and returns it to the heap. \var{P} should point to the memory
  5323. allocated to a dynamic variable.
  5324. \Errors
  5325. An error will occur when \var{P} doesn't point to the heap.
  5326. \SeeAlso
  5327. \seep{Getmem}, \seep{New}, \seep{Dispose}
  5328. \end{procedure}
  5329. \FPCexample{ex28}
  5330. \begin{procedure}{Getdir}
  5331. \Declaration
  5332. Procedure Getdir (drivenr : byte;var dir : string);
  5333. \Description
  5334. \var{Getdir} returns in \var{dir} the current directory on the drive
  5335. \var{drivenr}, where {drivenr} is 1 for the first floppy drive, 3 for the
  5336. first hard disk etc. A value of 0 returns the directory on the current disk.
  5337. On \linux and \unix systems, \var{drivenr} is ignored, as there is only one
  5338. directory tree.
  5339. \Errors
  5340. An error is returned under \dos, if the drive requested isn't ready.
  5341. \SeeAlso
  5342. \seep{Chdir}
  5343. \end{procedure}
  5344. \FPCexample{ex29}
  5345. \begin{procedure}{Getmem}
  5346. \Declaration
  5347. Procedure Getmem (var p : pointer;size : Longint);
  5348. \Description
  5349. \var{Getmem} reserves \var{Size} bytes memory on the heap, and returns a
  5350. pointer to this memory in \var{p}. If no more memory is available, nil is
  5351. returned.
  5352. \Errors
  5353. None.
  5354. \SeeAlso
  5355. \seep{Freemem}, \seep{Dispose}, \seep{New}
  5356. \end{procedure}
  5357. For an example, see \seep{Freemem}.
  5358. \begin{procedure}{GetMemoryManager}
  5359. \Declaration
  5360. procedure GetMemoryManager(var MemMgr: TMemoryManager);
  5361. \Description
  5362. \var{GetMemoryManager} stores the current Memory Manager record in
  5363. \var{MemMgr}.
  5364. \Errors
  5365. None.
  5366. \SeeAlso
  5367. \seep{SetMemoryManager}, \seef{IsMemoryManagerSet}.
  5368. \end{procedure}
  5369. For an example, see \progref.
  5370. \begin{procedure}{Halt}
  5371. \Declaration
  5372. Procedure Halt [(Errnum : byte)];
  5373. \Description
  5374. \var{Halt} stops program execution and returns control to the calling
  5375. program. The optional argument \var{Errnum} specifies an exit value. If
  5376. omitted, zero is returned.
  5377. \Errors
  5378. None.
  5379. \SeeAlso
  5380. \seep{Exit}
  5381. \end{procedure}
  5382. \FPCexample{ex30}
  5383. \begin{function}{HexStr}
  5384. \Declaration
  5385. Function HexStr (Value : longint; cnt : byte) : String;
  5386. Function HexStr (Value : int64; cnt : byte) : String;
  5387. \Description
  5388. \var{HexStr} returns a string with the hexadecimal representation
  5389. of \var{Value}. The string has exactly \var{cnt} charaters.
  5390. (i.e. only the \var{cnt} rightmost nibbles are taken into account)
  5391. To have a complete representation of a Longint-type value, 8
  5392. nibbles are needed, i.e. \var{cnt=8}.
  5393. \Errors
  5394. None.
  5395. \SeeAlso
  5396. \seep{Str}, \seep{Val}, \seef{BinStr}
  5397. \end{function}
  5398. \FPCexample{ex81}
  5399. \begin{function}{Hi}
  5400. \Declaration
  5401. Function Hi (X : Ordinal type) : Word or byte;
  5402. \Description
  5403. \var{Hi} returns the high byte or word from \var{X}, depending on the size
  5404. of X. If the size of X is 4, then the high word is returned. If the size is
  5405. 2 then the high byte is returned.
  5406. \var{Hi} cannot be invoked on types of size 1, such as byte or char.
  5407. \Errors
  5408. None
  5409. \SeeAlso
  5410. \seef{Lo}
  5411. \end{function}
  5412. \FPCexample{ex31}
  5413. \begin{function}{High}
  5414. \Declaration
  5415. Function High (Type identifier or variable reference) : Ordinal;
  5416. \Description
  5417. The return value of \var{High} depends on it's argument:
  5418. \begin{enumerate}
  5419. \item If the argument is an ordinal type, \var{High} returns the highest
  5420. value in the range of the given ordinal type.
  5421. \item If the argument is an array type or an array type variable then
  5422. \var{High} returns the highest possible value of it's index.
  5423. \item If the argument is an open array identifier in a function or
  5424. procedure, then \var{High} returns the highest index of the array, as if the
  5425. array has a zero-based index.
  5426. \end{enumerate}
  5427. The return type is always the same type as the type of the argument
  5428. (This can lead to some nasty surprises !).
  5429. \Errors
  5430. None.
  5431. \SeeAlso
  5432. \seef{Low}, \seef{Ord}, \seef{Pred}, \seef{Succ}
  5433. \end{function}
  5434. \FPCexample{ex80}
  5435. \begin{procedure}{Inc}
  5436. \Declaration
  5437. Procedure Inc (Var X : Any ordinal type[; Increment : Any ordinal type]);
  5438. \Description
  5439. \var{Inc} increases the value of \var{X} with \var{Increment}.
  5440. If \var{Increment} isn't specified, then 1 is taken as a default.
  5441. \Errors
  5442. If range checking is on, then A range check can occur, or an overflow
  5443. error, when an attempt is made to increase \var{X} over its maximum value.
  5444. \SeeAlso
  5445. \seep{Dec}
  5446. \end{procedure}
  5447. \FPCexample{ex32}
  5448. \begin{procedure}{Include}
  5449. \Declaration
  5450. Procedure Include (Var S : Any set type; E : Set element);
  5451. \Description
  5452. \var{Include} includes \var{E} in the set \var{S} if it is
  5453. not yet part of the set. E should be of the same type as the base type
  5454. of the set \var{S}.
  5455. Thus, the two following statements do the same thing:
  5456. \begin{verbatim}
  5457. S:=S+[E];
  5458. Include(S,E);
  5459. \end{verbatim}
  5460. \Errors
  5461. If the type of the element \var{E} is not equal to the base type of the
  5462. set \var{S}, the compiler will generate an error.
  5463. \SeeAlso
  5464. \seep{Exclude}
  5465. \end{procedure}
  5466. For an example, see \seep{Exclude}
  5467. \begin{function}{IndexByte}
  5468. \Declaration
  5469. function IndexByte(var buf;len:longint;b:byte):longint;
  5470. \Description
  5471. \var{IndexByte} searches the memory at \var{buf} for maximally \var{len}
  5472. positions for the byte \var{b} and returns it's position if it found one.
  5473. If \var{b} is not found then -1 is returned.
  5474. The position is zero-based.
  5475. \Errors
  5476. \var{Buf} and \var{Len} are not checked to see if they are valid values.
  5477. \SeeAlso
  5478. \seef{IndexChar}, \seef{IndexDWord}, \seef{IndexWord}, \seef{CompareByte}
  5479. \end{function}
  5480. \FPCexample{ex105}
  5481. \begin{function}{IndexChar}
  5482. \Declaration
  5483. function IndexChar(var buf;len:longint;b:char):longint;
  5484. \Declaration
  5485. function IndexChar0(var buf;len:longint;b:char):longint;
  5486. \Description
  5487. \var{IndexChar} searches the memory at \var{buf} for maximally \var{len}
  5488. positions for the character \var{b} and returns it's position if it found one.
  5489. If \var{b} is not found then -1 is returned.
  5490. The position is zero-based. The \var{IndexChar0} variant stops looking if
  5491. a null character is found, and returns -1 in that case.
  5492. \Errors
  5493. \var{Buf} and \var{Len} are not checked to see if they are valid values.
  5494. \SeeAlso
  5495. \seef{IndexByte}, \seef{IndexDWord}, \seef{IndexWord}, \seef{CompareChar}
  5496. \end{function}
  5497. \FPCexample{ex108}
  5498. \begin{function}{IndexDWord}
  5499. \Declaration
  5500. function IndexDWord(var buf;len:longint;DW:DWord):longint;
  5501. \Description
  5502. \var{IndexChar} searches the memory at \var{buf} for maximally \var{len}
  5503. positions for the DWord \var{DW} and returns it's position if it found one.
  5504. If \var{DW} is not found then -1 is returned.
  5505. The position is zero-based.
  5506. \Errors
  5507. \var{Buf} and \var{Len} are not checked to see if they are valid values.
  5508. \SeeAlso
  5509. \seef{IndexByte}, \seef{IndexChar}, \seef{IndexWord}, \seef{CompareDWord}
  5510. \end{function}
  5511. \FPCexample{ex106}
  5512. \begin{function}{IndexWord}
  5513. \Declaration
  5514. function IndexWord(var buf;len:longint;W:word):longint;
  5515. \Description
  5516. \var{IndexChar} searches the memory at \var{buf} for maximally \var{len}
  5517. positions for the Word \var{W} and returns it's position if it found one.
  5518. If \var{W} is not found then -1 is returned.
  5519. \Errors
  5520. \var{Buf} and \var{Len} are not checked to see if they are valid values.
  5521. \SeeAlso
  5522. \seef{IndexByte}, \seef{IndexDWord}, \seef{IndexChar}, \seef{CompareWord}
  5523. \end{function}
  5524. \FPCexample{ex107}
  5525. \begin{procedure}{Insert}
  5526. \Declaration
  5527. Procedure Insert (Const Source : String;var S : String;Index : Integer);
  5528. \Description
  5529. \var{Insert} inserts string \var{Source} in string \var{S}, at position
  5530. \var{Index}, shifting all characters after \var{Index} to the right. The
  5531. resulting string is truncated at 255 characters, if needed. (i.e. for
  5532. shortstrings)
  5533. \Errors
  5534. None.
  5535. \SeeAlso
  5536. \seep{Delete}, \seef{Copy}, \seef{Pos}
  5537. \end{procedure}
  5538. \FPCexample{ex33}
  5539. \begin{function}{IsMemoryManagerSet}
  5540. \Declaration
  5541. function IsMemoryManagerSet: Boolean;
  5542. \Description
  5543. \var{IsMemoryManagerSet} will return \var{True} if the memory manager has
  5544. been set to another value than the system heap manager, it will return
  5545. \var{False} otherwise.
  5546. \Errors
  5547. None.
  5548. \SeeAlso
  5549. \seep{SetMemoryManager}, \seep{GetMemoryManager}
  5550. \end{function}
  5551. \begin{function}{Int}
  5552. \Declaration
  5553. Function Int (X : Real) : Real;
  5554. \Description
  5555. \var{Int} returns the integer part of any Real \var{X}, as a Real.
  5556. \Errors
  5557. None.
  5558. \SeeAlso
  5559. \seef{Frac}, \seef{Round}
  5560. \end{function}
  5561. \FPCexample{ex34}
  5562. \begin{function}{IOresult}
  5563. \Declaration
  5564. Function IOresult : Word;
  5565. \Description
  5566. IOresult contains the result of any input/output call, when the
  5567. \var{\{\$i-\}} compiler directive is active, disabling IO checking.
  5568. When the flag is read, it is reset to zero.
  5569. If \var{IOresult} is zero, the operation completed successfully. If
  5570. non-zero, an error occurred. The following errors can occur:
  5571. \dos errors :
  5572. \begin{description}
  5573. \item [2\ ] File not found.
  5574. \item [3\ ] Path not found.
  5575. \item [4\ ] Too many open files.
  5576. \item [5\ ] Access denied.
  5577. \item [6\ ] Invalid file handle.
  5578. \item [12\ ] Invalid file-access mode.
  5579. \item [15\ ] Invalid disk number.
  5580. \item [16\ ] Cannot remove current directory.
  5581. \item [17\ ] Cannot rename across volumes.
  5582. \end{description}
  5583. I/O errors :
  5584. \begin{description}
  5585. \item [100\ ] Error when reading from disk.
  5586. \item [101\ ] Error when writing to disk.
  5587. \item [102\ ] File not assigned.
  5588. \item [103\ ] File not open.
  5589. \item [104\ ] File not opened for input.
  5590. \item [105\ ] File not opened for output.
  5591. \item [106\ ] Invalid number.
  5592. \end{description}
  5593. Fatal errors :
  5594. \begin{description}
  5595. \item [150\ ] Disk is write protected.
  5596. \item [151\ ] Unknown device.
  5597. \item [152\ ] Drive not ready.
  5598. \item [153\ ] Unknown command.
  5599. \item [154\ ] CRC check failed.
  5600. \item [155\ ] Invalid drive specified..
  5601. \item [156\ ] Seek error on disk.
  5602. \item [157\ ] Invalid media type.
  5603. \item [158\ ] Sector not found.
  5604. \item [159\ ] Printer out of paper.
  5605. \item [160\ ] Error when writing to device.
  5606. \item [161\ ] Error when reading from device.
  5607. \item [162\ ] Hardware failure.
  5608. \end{description}
  5609. \Errors
  5610. None.
  5611. \SeeAlso
  5612. All I/O functions.
  5613. \end{function}
  5614. \FPCexample{ex35}
  5615. \begin{function}{Length}
  5616. \Declaration
  5617. Function Length (S : String) : Integer;
  5618. \Description
  5619. \var{Length} returns the length of the string \var{S}, which is limited
  5620. to 255 for shortstrings. If the strings \var{S} is empty, 0 is returned.
  5621. {\em Note:} The length of the string \var{S} is stored in \var{S[0]} for
  5622. shortstrings only. The \var{Length} fuction should always be used on
  5623. ansistrings and widestrings.
  5624. \Errors
  5625. None.
  5626. \SeeAlso
  5627. \seef{Pos}
  5628. \end{function}
  5629. \FPCexample{ex36}
  5630. \begin{function}{Ln}
  5631. \Declaration
  5632. Function Ln (X : Real) : Real;
  5633. \Description
  5634. \var{Ln} returns the natural logarithm of the Real parameter \var{X}.
  5635. \var{X} must be positive.
  5636. \Errors
  5637. An run-time error will occur when \var{X} is negative.
  5638. \SeeAlso
  5639. \seef{Exp}, \seef{Power}
  5640. \end{function}
  5641. \FPCexample{ex37}
  5642. \begin{function}{Lo}
  5643. \Declaration
  5644. Function Lo (O : Word or Longint) : Byte or Word;
  5645. \Description
  5646. \var{Lo} returns the low byte of its argument if this is of type
  5647. \var{Integer} or
  5648. \var{Word}. It returns the low word of its argument if this is of type
  5649. \var{Longint} or \var{Cardinal}.
  5650. \Errors
  5651. None.
  5652. \SeeAlso
  5653. \seef{Ord}, \seef{Chr}, \seef{Hi}
  5654. \end{function}
  5655. \FPCexample{ex38}
  5656. \begin{procedure}{LongJmp}
  5657. \Declaration
  5658. Procedure LongJmp (Var env : Jmp\_Buf; Value : Longint);
  5659. \Description
  5660. \var{LongJmp} jumps to the adress in the \var{env} \var{jmp\_buf},
  5661. and restores the registers that were stored in it at the corresponding
  5662. \seef{SetJmp} call.
  5663. In effect, program flow will continue at the \var{SetJmp} call, which will
  5664. return \var{value} instead of 0. If a \var{value} equal to zero is passed,
  5665. it will be converted to 1 before passing it on. The call will not return, so it must be
  5666. used with extreme care.
  5667. This can be used for error recovery, for instance when a segmentation fault
  5668. occurred.
  5669. \Errors
  5670. None.
  5671. \SeeAlso
  5672. \seef{SetJmp}
  5673. \end{procedure}
  5674. For an example, see \seef{SetJmp}
  5675. \begin{function}{Low}
  5676. \Declaration
  5677. Function Low (Type identifier or variable reference) : Longint;
  5678. \Description
  5679. The return value of \var{Low} depends on it's argument:
  5680. \begin{enumerate}
  5681. \item If the argument is an ordinal type, \var{Low} returns the lowest
  5682. value in the range of the given ordinal type.
  5683. \item If the argument is an array type or an array type variable then
  5684. \var{Low} returns the lowest possible value of it's index.
  5685. \end{enumerate}
  5686. The return type is always the same type as the type of the argument
  5687. \Errors
  5688. None.
  5689. \SeeAlso
  5690. \seef{High}, \seef{Ord}, \seef{Pred}, \seef{Succ}
  5691. \end{function}
  5692. for an example, see \seef{High}.
  5693. \begin{function}{Lowercase}
  5694. \Declaration
  5695. Function Lowercase (C : Char or String) : Char or String;
  5696. \Description
  5697. \var{Lowercase} returns the lowercase version of its argument \var{C}.
  5698. If its argument is a string, then the complete string is converted to
  5699. lowercase. The type of the returned value is the same as the type of the
  5700. argument.
  5701. \Errors
  5702. None.
  5703. \SeeAlso
  5704. \seef{Upcase}
  5705. \end{function}
  5706. \FPCexample{ex73}
  5707. \begin{procedure}{Mark}
  5708. \Declaration
  5709. Procedure Mark (Var P : Pointer);
  5710. \Description
  5711. This routine is here for compatibility with Turbo Pascal, but
  5712. it is not implemented and currently does nothing.
  5713. \Errors
  5714. None.
  5715. \SeeAlso
  5716. \seep{Getmem}, \seep{Freemem}, \seep{New}, \seep{Dispose}, \seef{Maxavail}
  5717. \end{procedure}
  5718. \begin{function}{Maxavail}
  5719. \Declaration
  5720. Function Maxavail : Longint;
  5721. \Description
  5722. \var{Maxavail} returns the size, in bytes, of the biggest free memory block in
  5723. the heap.
  5724. \begin{remark}
  5725. The heap grows dynamically if more memory is needed than is available.
  5726. \end{remark}
  5727. \Errors
  5728. None.
  5729. \SeeAlso
  5730. \seep{Release}, \seef{Memavail},\seep{Freemem}, \seep{Getmem}
  5731. \end{function}
  5732. \FPCexample{ex40}
  5733. \begin{function}{Memavail}
  5734. \Declaration
  5735. Function Memavail : Longint;
  5736. \Description
  5737. \var{Memavail} returns the size, in bytes, of the free heap memory.
  5738. \begin{remark}
  5739. The heap grows dynamically if more memory is needed than is available. The
  5740. heap size is not equal to the size of the memory available to the
  5741. operating system, it is internal to the programs created by \fpc.
  5742. \end{remark}
  5743. \Errors
  5744. None.
  5745. \SeeAlso
  5746. \seef{Maxavail},\seep{Freemem}, \seep{Getmem}
  5747. \end{function}
  5748. \FPCexample{ex41}
  5749. \begin{procedure}{Mkdir}
  5750. \Declaration
  5751. Procedure Mkdir (const S : string);
  5752. \Description
  5753. \var{Mkdir} creates a new directory \var{S}.
  5754. \Errors
  5755. Depending on the state of the \var{\{\$I\}} switch, a runtime error can be
  5756. generated if there is an error. In the \var{\{\$I-\}} state, use \var{IOResult}
  5757. to check for errors.
  5758. \SeeAlso
  5759. \seep{Chdir}, \seep{Rmdir}
  5760. \end{procedure}
  5761. For an example, see \seep{Rmdir}.
  5762. \begin{procedure}{Move}
  5763. \Declaration
  5764. Procedure Move (var Source,Dest;Count : Longint);
  5765. \Description
  5766. \var{Move} moves \var{Count} bytes from \var{Source} to \var{Dest}.
  5767. \Errors
  5768. If either \var{Dest} or \var{Source} is outside the accessible memory for
  5769. the process, then a run-time error will be generated.
  5770. \SeeAlso
  5771. \seep{Fillword}, \seep{Fillchar}
  5772. \end{procedure}
  5773. \FPCexample{ex42}
  5774. \begin{procedurel}{MoveChar0}{MoveCharNull}
  5775. \Declaration
  5776. procedure MoveChar0(var Src,Dest;Count:longint);
  5777. \Description
  5778. \var{MoveChar0} moves \var{Count} bytes from \var{Src} to \var{Dest}, and
  5779. stops moving if a zero character is found.
  5780. \Errors
  5781. No checking is done to see if \var{Count} stays within the memory allocated
  5782. to the process.
  5783. \SeeAlso
  5784. \seep{Move}
  5785. \end{procedurel}
  5786. \FPCexample{ex109}
  5787. \begin{procedure}{New}
  5788. \Declaration
  5789. Procedure New (Var P : Pointer[, Constructor]);
  5790. \Description
  5791. \var{New} allocates a new instance of the type pointed to by \var{P}, and
  5792. puts the address in \var{P}.
  5793. If P is an object, then it is possible to
  5794. specify the name of the constructor with which the instance will be created.
  5795. \Errors
  5796. If not enough memory is available, \var{Nil} will be returned.
  5797. \SeeAlso
  5798. \seep{Dispose}, \seep{Freemem}, \seep{Getmem}, \seef{Memavail},
  5799. \seef{Maxavail}
  5800. \end{procedure}
  5801. For an example, see \seep{Dispose}.
  5802. \begin{function}{Odd}
  5803. \Declaration
  5804. Function Odd (X : Longint) : Boolean;
  5805. \Description
  5806. \var{Odd} returns \var{True} if \var{X} is odd, or \var{False} otherwise.
  5807. \Errors
  5808. None.
  5809. \SeeAlso
  5810. \seef{Abs}, \seef{Ord}
  5811. \end{function}
  5812. \FPCexample{ex43}
  5813. \begin{function}{OctStr}
  5814. \Declaration
  5815. Function OctStr (Value : longint; cnt : byte) : String;
  5816. Function OctStr (Value : int64; cnt : byte) : String;
  5817. \Description
  5818. \var{OctStr} returns a string with the octal representation
  5819. of \var{Value}. The string has exactly \var{cnt} charaters.
  5820. \Errors
  5821. None.
  5822. \SeeAlso
  5823. \seep{Str}, \seep{Val}, \seef{BinStr}, \seef{HexStr}
  5824. \end{function}
  5825. \FPCexample{ex112}
  5826. \begin{function}{Ofs}
  5827. \Declaration
  5828. Function Ofs (Var X) : Longint;
  5829. \Description
  5830. \var{Ofs} returns the offset of the address of a variable.
  5831. This function is only supported for compatibility. In \fpc, it
  5832. returns always the complete address of the variable, since \fpc is a 32 bit
  5833. compiler.
  5834. \Errors
  5835. None.
  5836. \SeeAlso
  5837. \seef{DSeg}, \seef{CSeg}, \seef{Seg}, \seef{Ptr}
  5838. \end{function}
  5839. \FPCexample{ex44}
  5840. \begin{function}{Ord}
  5841. \Declaration
  5842. Function Ord (X : Any ordinal type) : Longint;
  5843. \Description
  5844. \var{Ord} returns the Ordinal value of a ordinal-type variable \var{X}.
  5845. \Errors
  5846. None.
  5847. \SeeAlso
  5848. \seef{Chr}, \seef{Succ}, \seef{Pred}, \seef{High}, \seef{Low}
  5849. \end{function}
  5850. \FPCexample{ex45}
  5851. \begin{function}{Paramcount}
  5852. \Declaration
  5853. Function Paramcount : Longint;
  5854. \Description
  5855. \var{Paramcount} returns the number of command-line arguments. If no
  5856. arguments were given to the running program, \var{0} is returned.
  5857. \Errors
  5858. None.
  5859. \SeeAlso
  5860. \seef{Paramstr}
  5861. \end{function}
  5862. \FPCexample{ex46}
  5863. \begin{function}{Paramstr}
  5864. \Declaration
  5865. Function Paramstr (L : Longint) : String;
  5866. \Description
  5867. \var{Paramstr} returns the \var{L}-th command-line argument. \var{L} must
  5868. be between \var{0} and \var{Paramcount}, these values included.
  5869. The zeroth argument is the path and file name with which the program was
  5870. started.
  5871. The command-line parameters will be truncated to a length of 255,
  5872. even though the operating system may support bigger command-lines.
  5873. The \var{Objpas} unit (used in \var{objfpc} or \var{delphi} mode) define versions
  5874. of \var{Paramstr} which return the full-length command-line arguments.
  5875. When the complete command-line must be accessed, the \var{argv} pointer
  5876. should be used to retrieve the real values of the command-line parameters.
  5877. \Errors
  5878. None.
  5879. \SeeAlso
  5880. \seef{Paramcount}
  5881. \end{function}
  5882. For an example, see \seef{Paramcount}.
  5883. \begin{function}{Pi}
  5884. \Declaration
  5885. Function Pi : Real;
  5886. \Description
  5887. \var{Pi} returns the value of Pi (3.1415926535897932385).
  5888. \Errors
  5889. None.
  5890. \SeeAlso
  5891. \seef{Cos}, \seef{Sin}
  5892. \end{function}
  5893. \FPCexample{ex47}
  5894. \begin{function}{Pos}
  5895. \Declaration
  5896. Function Pos (Const Substr : String;Const S : String) : Integer;
  5897. \Description
  5898. \var{Pos} returns the index of \var{Substr} in \var{S}, if \var{S} contains
  5899. \var{Substr}. In case \var{Substr} isn't found, \var{0} is returned.
  5900. The search is case-sensitive.
  5901. \Errors
  5902. None
  5903. \SeeAlso
  5904. \seef{Length}, \seef{Copy}, \seep{Delete}, \seep{Insert}
  5905. \end{function}
  5906. \FPCexample{ex48}
  5907. \begin{function}{Power}
  5908. \Declaration
  5909. Function Power (base,expon : Real) : Real;
  5910. \Description
  5911. \var{Power} returns the value of \var{base} to the power \var{expon}.
  5912. \var{Base} and \var{expon} can be of type Longint, in which case the
  5913. result will also be a Longint.
  5914. The function actually returns \var{Exp(expon*Ln(base))}
  5915. \Errors
  5916. None.
  5917. \SeeAlso
  5918. \seef{Exp}, \seef{Ln}
  5919. \end{function}
  5920. \FPCexample{ex78}
  5921. \begin{function}{Pred}
  5922. \Declaration
  5923. Function Pred (X : Any ordinal type) : Same type;
  5924. \Description
  5925. \var{Pred} returns the element that precedes the element that was passed
  5926. to it. If it is applied to the first value of the ordinal type, and the
  5927. program was compiled with range checking on (\var{\{\$R+\}}, then a run-time
  5928. error will be generated.
  5929. \Errors
  5930. Run-time error 201 is generated when the result is out of
  5931. range.
  5932. \SeeAlso
  5933. \seef{Ord}, \seef{Pred}, \seef{High}, \seef{Low}
  5934. \end{function}
  5935. for an example, see \seef{Ord}
  5936. \begin{function}{Ptr}
  5937. \Declaration
  5938. Function Ptr (Sel,Off : Longint) : Pointer;
  5939. \Description
  5940. \var{Ptr} returns a pointer, pointing to the address specified by
  5941. segment \var{Sel} and offset \var{Off}.
  5942. \begin{remark}
  5943. \begin{enumerate}
  5944. \item In the 32-bit flat-memory model supported by \fpc, this
  5945. function is obsolete.
  5946. \item The returned address is simply the offset.
  5947. \end{enumerate}
  5948. \end{remark}
  5949. \Errors
  5950. None.
  5951. \SeeAlso
  5952. \seef{Addr}
  5953. \end{function}
  5954. \FPCexample{ex59}
  5955. \begin{function}{Random}
  5956. \Declaration
  5957. Function Random [(L : Longint)] : Longint or Real;
  5958. \Description
  5959. \var{Random} returns a random number larger or equal to \var{0} and
  5960. strictly less than \var{L}.
  5961. If the argument \var{L} is omitted, a Real number between 0 and 1 is returned.
  5962. (0 included, 1 excluded)
  5963. \Errors
  5964. None.
  5965. \SeeAlso
  5966. \seep{Randomize}
  5967. \end{function}
  5968. \FPCexample{ex49}
  5969. \begin{procedure}{Randomize}
  5970. \Declaration
  5971. Procedure Randomize ;
  5972. \Description
  5973. \var{Randomize} initializes the random number generator of \fpc, by giving
  5974. a value to \var{Randseed}, calculated with the system clock.
  5975. \Errors
  5976. None.
  5977. \SeeAlso
  5978. \seef{Random}
  5979. \end{procedure}
  5980. For an example, see \seef{Random}.
  5981. \begin{procedure}{Read}
  5982. \Declaration
  5983. Procedure Read ([Var F : Any file type], V1 [, V2, ... , Vn]);
  5984. \Description
  5985. \var{Read} reads one or more values from a file \var{F}, and stores the
  5986. result in \var{V1}, \var{V2}, etc.; If no file \var{F} is specified, then
  5987. standard input is read.
  5988. If \var{F} is of type \var{Text}, then the variables \var{V1, V2} etc. must be
  5989. of type \var{Char}, \var{Integer}, \var{Real}, \var{String} or \var{PChar}.
  5990. If \var{F} is a typed file, then each of the variables must be of the type
  5991. specified in the declaration of \var{F}. Untyped files are not allowed as an
  5992. argument.
  5993. \Errors
  5994. If no data is available, a run-time error is generated. This behavior can
  5995. be controlled with the \var{\{\$i\}} compiler switch.
  5996. \SeeAlso
  5997. \seep{Readln}, \seep{Blockread}, \seep{Write}, \seep{Blockwrite}
  5998. \end{procedure}
  5999. \FPCexample{ex50}
  6000. \begin{procedure}{Readln}
  6001. \Declaration
  6002. Procedure Readln [Var F : Text], V1 [, V2, ... , Vn]);
  6003. \Description
  6004. \var{Read} reads one or more values from a file \var{F}, and stores the
  6005. result in \var{V1}, \var{V2}, etc. After that it goes to the next line in
  6006. the file (defined by the \var{LineFeed (\#10)} character).
  6007. If no file \var{F} is specified, then standard input is read.
  6008. The variables \var{V1, V2} etc. must be of type \var{Char}, \var{Integer},
  6009. \var{Real}, \var{String} or \var{PChar}.
  6010. \Errors
  6011. If no data is available, a run-time error is generated. This behavior can
  6012. be controlled with the \var{\{\$i\}} compiler switch.
  6013. \SeeAlso
  6014. \seep{Read}, \seep{Blockread}, \seep{Write}, \seep{Blockwrite}
  6015. \end{procedure}
  6016. For an example, see \seep{Read}.
  6017. \begin{functionl}{Real2Double}{RealToDouble}
  6018. \Declaration
  6019. Function Real2Double(r : real48) : double;
  6020. \Description
  6021. The \var{Real2Double} function converts a \tp style real (6 bytes long) to
  6022. a native \fpc double type. It can be used e.g. to read old binary TP files with
  6023. FPC and convert them to Free Pacal binary files.
  6024. Note that the assignment operator has been overloaded so a \var{Real48} type
  6025. can be assigned directly to a double or extended.
  6026. \Errors
  6027. None.
  6028. \SeeAlso
  6029. \end{functionl}
  6030. \FPCexample{ex110}
  6031. \begin{procedure}{Release}
  6032. \Declaration
  6033. Procedure Release (Var P : pointer);
  6034. \Description
  6035. This routine is here for compatibility with Turbo Pascal, but
  6036. it is not implemented and currently does nothing.
  6037. \Errors
  6038. None.
  6039. \SeeAlso
  6040. \seep{Mark}, \seef{Memavail}, \seef{Maxavail}, \seep{Getmem}, \seep{Freemem}
  6041. \seep{New}, \seep{Dispose}
  6042. \end{procedure}
  6043. \begin{procedure}{Rename}
  6044. \Declaration
  6045. Procedure Rename (Var F : Any Filetype; Const S : String);
  6046. \Description
  6047. \var{Rename} changes the name of the assigned file \var{F} to \var{S}.
  6048. \var{F}
  6049. must be assigned, but not opened.
  6050. \Errors
  6051. Depending on the state of the \var{\{\$I\}} switch, a runtime error can be
  6052. generated if there is an error. In the \var{\{\$I-\}} state, use \var{IOResult}
  6053. to check for errors.
  6054. \SeeAlso
  6055. \seep{Erase}
  6056. \end{procedure}
  6057. \FPCexample{ex77}
  6058. \begin{procedure}{Reset}
  6059. \Declaration
  6060. Procedure Reset (Var F : Any File Type[; L : Longint]);
  6061. \Description
  6062. \var{Reset} opens a file \var{F} for reading. \var{F} can be any file type.
  6063. If \var{F} is a text file, or refers to standard I/O (e.g : '') then it is
  6064. opened read-only, otherwise it is opened using the mode specified in
  6065. \var{filemode}.
  6066. If \var{F} is an untyped file, the record size can be specified in
  6067. the optional parameter \var{L}. A default value of 128 is used.
  6068. File sharing is not taken into account when calling \var{Reset}.
  6069. \Errors
  6070. Depending on the state of the \var{\{\$I\}} switch, a runtime error can be
  6071. generated if there is an error. In the \var{\{\$I-\}} state, use \var{IOResult}
  6072. to check for errors.
  6073. \SeeAlso
  6074. \seep{Rewrite}, \seep{Assign}, \seep{Close}, \seep{Append}
  6075. \end{procedure}
  6076. \FPCexample{ex51}
  6077. \begin{procedure}{Rewrite}
  6078. \Declaration
  6079. Procedure Rewrite (Var F : Any File Type[; L : Longint]);
  6080. \Description
  6081. \var{Rewrite} opens a file \var{F} for writing. \var{F} can be any file type.
  6082. If \var{F} is an untyped or typed file, then it is opened for reading and
  6083. writing. If \var{F} is an untyped file, the record size can be specified in
  6084. the optional parameter \var{L}. Default a value of 128 is used.
  6085. if \var{Rewrite} finds a file with the same name as \var{F}, this file is
  6086. truncated to length \var{0}. If it doesn't find such a file, a new file is
  6087. created.
  6088. Contrary to \tp, \fpc opens the file with mode \var{fmoutput}. If it should
  6089. be opened in \var{fminout} mode, an extra call to \seep{Reset} is needed.
  6090. File sharing is not taken into account when calling \var{Rewrite}.
  6091. \Errors
  6092. Depending on the state of the \var{\{\$I\}} switch, a runtime error can be
  6093. generated if there is an error. In the \var{\{\$I-\}} state, use \var{IOResult}
  6094. to check for errors.
  6095. \SeeAlso
  6096. \seep{Reset}, \seep{Assign}, \seep{Close}, \seep{Flush}, \seep{Append}
  6097. \end{procedure}
  6098. \FPCexample{ex52}
  6099. \begin{procedure}{Rmdir}
  6100. \Declaration
  6101. Procedure Rmdir (const S : string);
  6102. \Description
  6103. \var{Rmdir} removes the directory \var{S}.
  6104. \Errors
  6105. \Errors
  6106. Depending on the state of the \var{\{\$I\}} switch, a runtime error can be
  6107. generated if there is an error. In the \var{\{\$I-\}} state, use \var{IOResult}
  6108. to check for errors.
  6109. \SeeAlso
  6110. \seep{Chdir}, \seep{Mkdir}
  6111. \end{procedure}
  6112. \FPCexample{ex53}
  6113. \begin{function}{Round}
  6114. \Declaration
  6115. Function Round (X : Real) : Longint;
  6116. \Description
  6117. \var{Round} rounds \var{X} to the closest integer, which may be bigger or
  6118. smaller than \var{X}.
  6119. \Errors
  6120. None.
  6121. \SeeAlso
  6122. \seef{Frac}, \seef{Int}, \seef{Trunc}
  6123. \end{function}
  6124. \FPCexample{ex54}
  6125. \begin{procedure}{Runerror}
  6126. \Declaration
  6127. Procedure Runerror (ErrorCode : Word);
  6128. \Description
  6129. \var{Runerror} stops the execution of the program, and generates a
  6130. run-time error \var{ErrorCode}.
  6131. \Errors
  6132. None.
  6133. \SeeAlso
  6134. \seep{Exit}, \seep{Halt}
  6135. \end{procedure}
  6136. \FPCexample{ex55}
  6137. \begin{procedure}{Seek}
  6138. \Declaration
  6139. Procedure Seek (Var F; Count : Longint);
  6140. \Description
  6141. \var{Seek} sets the file-pointer for file \var{F} to record Nr. \var{Count}.
  6142. The first record in a file has \var{Count=0}. F can be any file type, except
  6143. \var{Text}. If \var{F} is an untyped file, with no record size specified in
  6144. \seep{Reset} or \seep{Rewrite}, 128 is assumed.
  6145. \Errors
  6146. Depending on the state of the \var{\{\$I\}} switch, a runtime error can be
  6147. generated if there is an error. In the \var{\{\$I-\}} state, use \var{IOResult}
  6148. to check for errors.
  6149. \SeeAlso
  6150. \seef{Eof}, \seef{SeekEof}, \seef{SeekEoln}
  6151. \end{procedure}
  6152. \FPCexample{ex56}
  6153. \begin{function}{SeekEof}
  6154. \Declaration
  6155. Function SeekEof [(Var F : text)] : Boolean;
  6156. \Description
  6157. \var{SeekEof} returns \var{True} is the file-pointer is at the end of the
  6158. file. It ignores all whitespace.
  6159. Calling this function has the effect that the file-position is advanced
  6160. until the first non-whitespace character or the end-of-file marker is
  6161. reached.
  6162. If the end-of-file marker is reached, \var{True} is returned. Otherwise,
  6163. False is returned.
  6164. If the parameter \var{F} is omitted, standard \var{Input} is assumed.
  6165. \Errors
  6166. A run-time error is generated if the file \var{F} isn't opened.
  6167. \SeeAlso
  6168. \seef{Eof}, \seef{SeekEoln}, \seep{Seek}
  6169. \end{function}
  6170. \FPCexample{ex57}
  6171. \begin{function}{SeekEoln}
  6172. \Declaration
  6173. Function SeekEoln [(Var F : text)] : Boolean;
  6174. \Description
  6175. \var{SeekEoln} returns \var{True} is the file-pointer is at the end of the
  6176. current line. It ignores all whitespace.
  6177. Calling this function has the effect that the file-position is advanced
  6178. until the first non-whitespace character or the end-of-line marker is
  6179. reached.
  6180. If the end-of-line marker is reached, \var{True} is returned. Otherwise,
  6181. False is returned.
  6182. The end-of-line marker is defined as \var{\#10}, the LineFeed character.
  6183. If the parameter \var{F} is omitted, standard \var{Input} is assumed.
  6184. \Errors
  6185. A run-time error is generated if the file \var{F} isn't opened.
  6186. \SeeAlso
  6187. \seef{Eof}, \seef{SeekEof}, \seep{Seek}
  6188. \end{function}
  6189. \FPCexample{ex58}
  6190. \begin{function}{Seg}
  6191. \Declaration
  6192. Function Seg (Var X) : Longint;
  6193. \Description
  6194. \var{Seg} returns the segment of the address of a variable.
  6195. This function is only supported for compatibility. In \fpc, it
  6196. returns always 0, since \fpc is a 32 bit compiler, segments have no meaning.
  6197. \Errors
  6198. None.
  6199. \SeeAlso
  6200. \seef{DSeg}, \seef{CSeg}, \seef{Ofs}, \seef{Ptr}
  6201. \end{function}
  6202. \FPCexample{ex60}
  6203. \begin{procedure}{SetMemoryManager}
  6204. \Declaration
  6205. procedure SetMemoryManager(const MemMgr: TMemoryManager);
  6206. \Description
  6207. \var{SetMemoryManager} sets the current memory manager record to
  6208. \var{MemMgr}.
  6209. \Errors
  6210. None.
  6211. \SeeAlso
  6212. \seep{GetMemoryManager}, \seef{IsMemoryManagerSet}
  6213. \end{procedure}
  6214. For an example, see \progref.
  6215. \begin{function}{SetJmp}
  6216. \Declaration
  6217. Function SetJmp (Var Env : Jmp\_Buf) : Longint;
  6218. \Description
  6219. \var{SetJmp} fills \var{env} with the necessary data for a jump back to the
  6220. point where it was called. It returns zero if called in this way.
  6221. If the function returns nonzero, then it means that a call to \seep{LongJmp}
  6222. with \var{env} as an argument was made somewhere in the program.
  6223. \Errors
  6224. None.
  6225. \SeeAlso
  6226. \seep{LongJmp}
  6227. \end{function}
  6228. \FPCexample{ex79}
  6229. \begin{procedure}{SetLength}
  6230. \Declaration
  6231. Procedure SetLength(var S : String; Len : Longint);
  6232. \Description
  6233. \var{SetLength} sets the length of the string \var{S} to \var{Len}. \var{S}
  6234. can be an ansistring, a short string or a widestring.
  6235. For \var{ShortStrings}, \var{Len} can maximally be 255. For \var{AnsiStrings}
  6236. it can have any value. For \var{AnsiString} strings, \var{SetLength} {\em
  6237. must} be used to set the length of the string.
  6238. \Errors
  6239. None.
  6240. \SeeAlso
  6241. \seef{Length}
  6242. \end{procedure}
  6243. \FPCexample{ex85}
  6244. \begin{procedure}{SetString}
  6245. \Declaration
  6246. Procedure SetString(var S : String; Buf : PChar; Len : Longint);
  6247. \Description
  6248. \var{SetString} sets the length of the string \var{S} to \var{Len} and
  6249. if \var{Buf} is non-nil, copies \var{Len} characters from \var{Buf}
  6250. into \var{S}. \var{S} can be an ansistring, a short string or a widestring.
  6251. For \var{ShortStrings}, \var{Len} can maximally be 255.
  6252. \Errors
  6253. None.
  6254. \SeeAlso
  6255. \seep{SetLength}
  6256. \end{procedure}
  6257. \begin{procedure}{SetTextBuf}
  6258. \Declaration
  6259. Procedure SetTextBuf (Var f : Text; Var Buf[; Size : Word]);
  6260. \Description
  6261. \var{SetTextBuf} assigns an I/O buffer to a text file. The new buffer is
  6262. located at \var{Buf} and is \var{Size} bytes long. If \var{Size} is omitted,
  6263. then \var{SizeOf(Buf)} is assumed.
  6264. The standard buffer of any text file is 128 bytes long. For heavy I/O
  6265. operations this may prove too slow. The \var{SetTextBuf} procedure allows
  6266. to set a bigger buffer for the IO of the application, thus reducing the number of
  6267. system calls, and thus reducing the load on the system resources.
  6268. The maximum size of the newly assigned buffer is 65355 bytes.
  6269. \begin{remark}
  6270. \begin{itemize}
  6271. \item Never assign a new buffer to an opened file. A
  6272. new buffer can be assigned immediately after a call to \seep{Rewrite}, \seep{Reset} or
  6273. \var{Append}, but not after the file was read from/written to. This may cause
  6274. loss of data. If a new buffer must be assigned after read/write
  6275. operations have been performed, the file should be flushed first.
  6276. This will ensure that the current buffer is emptied.
  6277. \item Take care that the assigned buffer is always valid. If a local variable is
  6278. assigned as a buffer, then after the program exits the local program block,
  6279. the buffer will no longer be valid, and stack problems may occur.
  6280. \end{itemize}
  6281. \end{remark}
  6282. \Errors
  6283. No checking on \var{Size} is done.
  6284. \SeeAlso
  6285. \seep{Assign}, \seep{Reset}, \seep{Rewrite}, \seep{Append}
  6286. \end{procedure}
  6287. \FPCexample{ex61}
  6288. \begin{function}{Sin}
  6289. \Declaration
  6290. Function Sin (X : Real) : Real;
  6291. \Description
  6292. \var{Sin} returns the sine of its argument \var{X}, where \var{X} is an
  6293. angle in radians.
  6294. If the absolute value of the argument is larger than \var{2\^{}63}, then the
  6295. result is undefined.
  6296. \Errors
  6297. None.
  6298. \SeeAlso
  6299. \seef{Cos}, \seef{Pi}, \seef{Exp}, \seef{Ln}
  6300. \end{function}
  6301. \FPCexample{ex62}
  6302. \begin{function}{SizeOf}
  6303. \Declaration
  6304. Function SizeOf (X : Any Type) : Longint;
  6305. \Description
  6306. \var{SizeOf} returns the size, in bytes, of any variable or type-identifier.
  6307. \begin{remark}
  6308. This isn't really a RTL function. Its result is calculated at
  6309. compile-time, and hard-coded in the executable.
  6310. \end{remark}
  6311. \Errors
  6312. None.
  6313. \SeeAlso
  6314. \seef{Addr}
  6315. \end{function}
  6316. \FPCexample{ex63}
  6317. \begin{function}{Sptr}
  6318. \Declaration
  6319. Function Sptr : Pointer;
  6320. \Description
  6321. \var{Sptr} returns the current stack pointer.
  6322. \Errors
  6323. None.
  6324. \SeeAlso
  6325. \seef{SSeg}
  6326. \end{function}
  6327. \FPCexample{ex64}
  6328. \begin{function}{Sqr}
  6329. \Declaration
  6330. Function Sqr (X : Real) : Real;
  6331. \Description
  6332. \var{Sqr} returns the square of its argument \var{X}.
  6333. \Errors
  6334. None.
  6335. \SeeAlso
  6336. \seef{Sqrt}, \seef{Ln}, \seef{Exp}
  6337. \end{function}
  6338. \FPCexample{ex65}
  6339. \begin{function}{Sqrt}
  6340. \Declaration
  6341. Function Sqrt (X : Real) : Real;
  6342. \Description
  6343. \var{Sqrt} returns the square root of its argument \var{X}, which must be
  6344. positive.
  6345. \Errors
  6346. If \var{X} is negative, then a run-time error is generated.
  6347. \SeeAlso
  6348. \seef{Sqr}, \seef{Ln}, \seef{Exp}
  6349. \end{function}
  6350. \FPCexample{ex66}
  6351. \begin{function}{SSeg}
  6352. \Declaration
  6353. Function SSeg : Longint;
  6354. \Description
  6355. \var{SSeg} returns the Stack Segment. This function is only
  6356. supported for compatibility reasons, as \var{Sptr} returns the
  6357. correct contents of the stackpointer.
  6358. \Errors
  6359. None.
  6360. \SeeAlso
  6361. \seef{Sptr}
  6362. \end{function}
  6363. \FPCexample{ex67}
  6364. \begin{procedure}{Str}
  6365. \Declaration
  6366. Procedure Str (Var X[:NumPlaces[:Decimals]]; Var S : String);
  6367. \Description
  6368. \var{Str} returns a string which represents the value of X. X can be any
  6369. numerical type.
  6370. The optional \var{NumPLaces} and \var{Decimals} specifiers control the
  6371. formatting of the string.
  6372. \Errors
  6373. None.
  6374. \SeeAlso
  6375. \seep{Val}
  6376. \end{procedure}
  6377. \FPCexample{ex68}
  6378. \begin{function}{StringOfChar}
  6379. \Declaration
  6380. Function StringOfChar(c : char;l : Integer) : String;
  6381. \Description
  6382. \var{StringOfChar} creates a new String of length \var{l} and fills
  6383. it with the character \var{c}.
  6384. It is equivalent to the following calls:
  6385. \begin{verbatim}
  6386. SetLength(StringOfChar,l);
  6387. FillChar(Pointer(StringOfChar)^,Length(StringOfChar),c);
  6388. \end{verbatim}
  6389. \Errors
  6390. None.
  6391. \SeeAlso
  6392. \seep{SetLength}
  6393. \end{function}
  6394. \FPCexample{ex97}
  6395. \begin{function}{Succ}
  6396. \Declaration
  6397. Function Succ (X : Any ordinal type) : Same type;
  6398. \Description
  6399. \var{Succ} returns the element that succeeds the element that was passed
  6400. to it. If it is applied to the last value of the ordinal type, and the
  6401. program was compiled with range checking on (\var{\{\$R+\}}), then a run-time
  6402. error will be generated.
  6403. \Errors
  6404. Run-time error 201 is generated when the result is out of
  6405. range.
  6406. \SeeAlso
  6407. \seef{Ord}, \seef{Pred}, \seef{High}, \seef{Low}
  6408. \end{function}
  6409. for an example, see \seef{Ord}.
  6410. \begin{function}{Swap}
  6411. \Declaration
  6412. Function Swap (X) : Type of X;
  6413. \Description
  6414. \var{Swap} swaps the high and low order bytes of \var{X} if \var{X} is of
  6415. type \var{Word} or \var{Integer}, or swaps the high and low order words of
  6416. \var{X} if \var{X} is of type \var{Longint} or \var{Cardinal}.
  6417. The return type is the type of \var{X}
  6418. \Errors
  6419. None.
  6420. \SeeAlso
  6421. \seef{Lo}, \seef{Hi}
  6422. \end{function}
  6423. \FPCexample{ex69}
  6424. \begin{function}{Trunc}
  6425. \Declaration
  6426. Function Trunc (X : Real) : Longint;
  6427. \Description
  6428. \var{Trunc} returns the integer part of \var{X},
  6429. which is always smaller than (or equal to) \var{X} in absolute value.
  6430. \Errors
  6431. None.
  6432. \SeeAlso
  6433. \seef{Frac}, \seef{Int}, \seef{Round}
  6434. \end{function}
  6435. \FPCexample{ex70}
  6436. \begin{procedure}{Truncate}
  6437. \Declaration
  6438. Procedure Truncate (Var F : file);
  6439. \Description
  6440. \var{Truncate} truncates the (opened) file \var{F} at the current file
  6441. position.
  6442. \Errors
  6443. Depending on the state of the \var{\{\$I\}} switch, a runtime error can be
  6444. generated if there is an error. In the \var{\{\$I-\}} state, use \var{IOResult}
  6445. to check for errors.
  6446. \SeeAlso
  6447. \seep{Append}, \seef{Filepos},
  6448. \seep{Seek}
  6449. \end{procedure}
  6450. \FPCexample{ex71}
  6451. \begin{function}{Upcase}
  6452. \Declaration
  6453. Function Upcase (C : Char or string) : Char or String;
  6454. \Description
  6455. \var{Upcase} returns the uppercase version of its argument \var{C}.
  6456. If its argument is a string, then the complete string is converted to
  6457. uppercase. The type of the returned value is the same as the type of the
  6458. argument.
  6459. \Errors
  6460. None.
  6461. \SeeAlso
  6462. \seef{Lowercase}
  6463. \end{function}
  6464. \FPCexample{ex72}
  6465. \begin{procedure}{Val}
  6466. \Declaration
  6467. Procedure Val (const S : string;var V;var Code : word);
  6468. \Description
  6469. \var{Val} converts the value represented in the string \var{S} to a numerical
  6470. value, and stores this value in the variable \var{V}, which
  6471. can be of type \var{Longint}, \var{Real} and \var{Byte}.
  6472. If the conversion isn't succesfull, then the parameter \var{Code} contains
  6473. the index of the character in \var{S} which prevented the conversion.
  6474. The string \var{S} is allowed to contain spaces in the beginning.
  6475. The string \var{S} can contain a number in decimal, hexadecimal, binary
  6476. or octal format, as described in the language reference.
  6477. \Errors
  6478. If the conversion doesn't succeed, the value of \var{Code} indicates the
  6479. position where the conversion went wrong.
  6480. \SeeAlso
  6481. \seep{Str}
  6482. \end{procedure}
  6483. \FPCexample{ex74}
  6484. \begin{procedure}{Write}
  6485. \Declaration
  6486. Procedure Write ([Var F : Any filetype;] V1 [; V2; ... , Vn)];
  6487. \Description
  6488. \var{Write} writes the contents of the variables \var{V1}, \var{V2} etc. to
  6489. the file \var{F}. \var{F} can be a typed file, or a \var{Text} file.
  6490. If \var{F} is a typed file, then the variables \var{V1}, \var{V2} etc. must
  6491. be of the same type as the type in the declaration of \var{F}. Untyped files
  6492. are not allowed.
  6493. If the parameter \var{F} is omitted, standard output is assumed.
  6494. If \var{F} is of type \var{Text}, then the necessary conversions are done
  6495. such that the output of the variables is in human-readable format.
  6496. This conversion is done for all numerical types. Strings are printed exactly
  6497. as they are in memory, as well as \var{PChar} types.
  6498. The format of the numerical conversions can be influenced through
  6499. the following modifiers:
  6500. \var{ OutputVariable : NumChars [: Decimals ] }
  6501. This will print the value of \var{OutputVariable} with a minimum of
  6502. \var{NumChars} characters, from which \var{Decimals} are reserved for the
  6503. decimals. If the number cannot be represented with \var{NumChars} characters,
  6504. \var{NumChars} will be increased, until the representation fits. If the
  6505. representation requires less than \var{NumChars} characters then the output
  6506. is filled up with spaces, to the left of the generated string, thus
  6507. resulting in a right-aligned representation.
  6508. If no formatting is specified, then the number is written using its natural
  6509. length, with nothing in front of it if it's positive, and a minus sign if
  6510. it's negative.
  6511. Real numbers are, by default, written in scientific notation.
  6512. \Errors
  6513. If an error occurs, a run-time error is generated. This behavior can be
  6514. controlled with the \var{\{\$i\}} switch.
  6515. \SeeAlso
  6516. \seep{WriteLn}, \seep{Read}, \seep{Readln}, \seep{Blockwrite}
  6517. \end{procedure}
  6518. \begin{procedure}{WriteLn}
  6519. \Declaration
  6520. Procedure WriteLn [([Var F : Text;] [V1 [; V2; ... , Vn)]];
  6521. \Description
  6522. \var{WriteLn} does the same as \seep{Write} for text files, and emits a
  6523. Carriage Return - LineFeed character pair after that.
  6524. If the parameter \var{F} is omitted, standard output is assumed.
  6525. If no variables are specified, a Carriage Return - LineFeed character pair
  6526. is emitted, resulting in a new line in the file \var{F}.
  6527. \begin{remark}
  6528. Under \linux and \unix, the Carriage Return character is omitted, as
  6529. customary in Unix environments.
  6530. \end{remark}
  6531. \Errors
  6532. If an error occurs, a run-time error is generated. This behavior can be
  6533. controlled with the \var{\{\$i\}} switch.
  6534. \SeeAlso
  6535. \seep{Write}, \seep{Read}, \seep{Readln}, \seep{Blockwrite}
  6536. \end{procedure}
  6537. \FPCexample{ex75}
  6538. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  6539. % The objpas unit
  6540. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  6541. \chapter{The OBJPAS unit}
  6542. The \file{objpas} unit is meant for compatibility with Object Pascal as
  6543. implemented by Delphi. The unit is loaded automatically by the \fpc compiler
  6544. whenever the \var{Delphi} or \var{objfpc} more is entered, either through
  6545. the command line switches \var{-Sd} or \var{-Sh} or with the \var{\{\$MODE
  6546. DELPHI\}} or \var{\{\$MODE OBJFPC\}} directives.
  6547. It redefines some basic pascal types, introduces some functions for
  6548. compatibility with Delphi's system unit, and introduces some methods for the
  6549. management of the resource string tables.
  6550. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  6551. % Tytpes
  6552. \section{Types}
  6553. The \file{objpas} unit redefines two integer types, for compatibity with
  6554. Delphi:
  6555. \begin{verbatim}
  6556. type
  6557. smallint = system.integer;
  6558. integer = system.longint;
  6559. \end{verbatim}
  6560. The resource string tables can be managed with a callback function which the
  6561. user must provide: \var{TResourceIterator}.
  6562. \begin{verbatim}
  6563. Type
  6564. TResourceIterator =
  6565. Function (Name,Value : AnsiString;Hash : Longint):AnsiString;
  6566. \end{verbatim}
  6567. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  6568. % Functions and procedures
  6569. \section{Functions and Procedures}
  6570. \begin{procedure}{AssignFile}
  6571. \Declaration
  6572. Procedure AssignFile(Var f: FileType;Name: Character type);
  6573. \Description
  6574. \var{AssignFile} is completely equivalent to the system unit's \seep{Assign}
  6575. function: It assigns \var{Name} to a function of any type (\var{FileType}
  6576. can be \var{Text} or a typed or untyped \var{File} variable). \var{Name} can
  6577. be a string, a single character or a \var{PChar}.
  6578. It is most likely introduced to avoid confusion between the regular
  6579. \seep{Assign} function and the \var{Assign} method of \var{TPersistent}
  6580. in the Delphi VCL.
  6581. \Errors
  6582. None.
  6583. \SeeAlso
  6584. \seep{CloseFile}, \seep{Assign}, \seep{Reset}, \seep{Rewrite}, \seep{Append}
  6585. \end{procedure}
  6586. \FPCexample{ex88}
  6587. \begin{procedure}{CloseFile}
  6588. \Declaration
  6589. Procedure CloseFile(Var F: FileType);
  6590. \Description
  6591. \var{CloseFile} flushes and closes a file \var{F} of any file type.
  6592. \var{F} can be \var{Text} or a typed or untyped \var{File} variable.
  6593. After a call to \var{CloseFile}, any attempt to write to the file \var{F}
  6594. will result in an error.
  6595. It is most likely introduced to avoid confusion between the regular
  6596. \seep{Close} function and the \var{Close} method of \var{TForm}
  6597. in the Delphi VCL.
  6598. \Errors
  6599. None.
  6600. \SeeAlso
  6601. \seep{Close}, \seep{AssignFile}, \seep{Reset}, \seep{Rewrite}, \seep{Append}
  6602. \end{procedure}
  6603. for an example, see \seep{AssignFile}.
  6604. \begin{procedurel}{Freemem}{objpasfreemem}
  6605. \Declaration
  6606. Procedure FreeMem(Var p:pointer[;Size:Longint]);
  6607. \Description
  6608. \var{FreeMem} releases the memory reserved by a call to
  6609. \seepl{GetMem}{objpasgetmem}. The (optional) \var{Size} parameter is
  6610. ignored, since the object pascal version of \var{GetMem} stores the amount
  6611. of memory that was requested.
  6612. Be sure not to release memory that was not obtained with the \var{Getmem}
  6613. call in \file{Objpas}. Normally, this should not happen, since objpas
  6614. changes the default memory manager to it's own memory manager.
  6615. \Errors
  6616. None.
  6617. \SeeAlso
  6618. \seep{Freemem}, \seepl{GetMem}{objpasgetmem}, \seep{Getmem}
  6619. \end{procedurel}
  6620. \FPCexample{ex89}
  6621. \begin{procedurel}{Getmem}{objpasgetmem}
  6622. \Declaration
  6623. Procedure Getmem(Var P:pointer;Size:Longint);
  6624. \Description
  6625. \var{GetMem} reserves \var{Size} bytes of memory on the heap and returns
  6626. a pointer to it in \var{P}. \var{Size} is stored at offset -4 of the
  6627. result, and is used to release the memory again. \var{P} can be a typed or
  6628. untyped pointer.
  6629. Be sure to release this memory with the \seepl{FreeMem}{objpasfreemem} call
  6630. defined in the \file{objpas} unit.
  6631. \Errors
  6632. In case no more memory is available, and no more memory could be obtained
  6633. from the system a run-time error is triggered.
  6634. \SeeAlso
  6635. \seepl{FreeMem}{objpasfreemem}, \seep{Getmem}.
  6636. \end{procedurel}
  6637. For an example, see \seepl{FreeMem}{objpasfreemem}.
  6638. \begin{function}{GetResourceStringCurrentValue}
  6639. \Declaration
  6640. Function GetResourceStringCurrentValue(TableIndex,StringIndex : Longint) : AnsiString;
  6641. \Description
  6642. \var{GetResourceStringCurrentValue} returns the current value of the
  6643. resourcestring in table \var{TableIndex} with index \var{StringIndex}.
  6644. The current value depends on the system of internationalization that was
  6645. used, and which language is selected when the program is executed.
  6646. \Errors
  6647. If either \var{TableIndex} or \var{StringIndex} are out of range, then
  6648. a empty string is returned.
  6649. \SeeAlso
  6650. \seep{SetResourceStrings},
  6651. \seef{GetResourceStringDefaultValue},
  6652. \seef{GetResourceStringHash},
  6653. \seef{GetResourceStringName},
  6654. \seef{ResourceStringTableCount},
  6655. \seef{ResourceStringCount}
  6656. \end{function}
  6657. \FPCexample{ex90}
  6658. \begin{function}{GetResourceStringDefaultValue}
  6659. \Declaration
  6660. Function GetResourceStringDefaultValue(TableIndex,StringIndex : Longint) : AnsiString
  6661. \Description
  6662. \var{GetResourceStringDefaultValue} returns the default value of the
  6663. resourcestring in table \var{TableIndex} with index \var{StringIndex}.
  6664. The default value is the value of the string that appears in the source code
  6665. of the programmer, and is compiled into the program.
  6666. \Errors
  6667. If either \var{TableIndex} or \var{StringIndex} are out of range, then
  6668. a empty string is returned.
  6669. \Errors
  6670. \SeeAlso
  6671. \seep{SetResourceStrings},
  6672. \seef{GetResourceStringCurrentValue},
  6673. \seef{GetResourceStringHash},
  6674. \seef{GetResourceStringName},
  6675. \seef{ResourceStringTableCount},
  6676. \seef{ResourceStringCount}
  6677. \end{function}
  6678. \FPCexample{ex91}
  6679. \begin{function}{GetResourceStringHash}
  6680. \Declaration
  6681. Function GetResourceStringHash(TableIndex,StringIndex : Longint) : Longint;
  6682. \Description
  6683. \var{GetResourceStringHash} returns the hash value associated with the
  6684. resource string in table \var{TableIndex}, with index \var{StringIndex}.
  6685. The hash value is calculated from the default value of the resource string
  6686. in a manner that gives the same result as the GNU \file{gettext} mechanism.
  6687. It is stored in the resourcestring tables, so retrieval is faster than
  6688. actually calculating the hash for each string.
  6689. \Errors
  6690. If either \var{TableIndex} or \var{StringIndex} is zero, 0 is returned.
  6691. \SeeAlso
  6692. \seef{Hash}
  6693. \seep{SetResourceStrings},
  6694. \seef{GetResourceStringDefaultValue},
  6695. \seef{GetResourceStringHash},
  6696. \seef{GetResourceStringName},
  6697. \seef{ResourceStringTableCount},
  6698. \seef{ResourceStringCount}
  6699. \end{function}
  6700. For an example, see \seef{Hash}.
  6701. \begin{function}{GetResourceStringName}
  6702. \Declaration
  6703. Function GetResourceStringName(TableIndex,StringIndex : Longint) : Ansistring;
  6704. \Description
  6705. \var{GetResourceStringName} returns the name of the resourcestring in table
  6706. \var{TableIndex} with index \var{StringIndex}. The name of the string is
  6707. always the unit name in which the string was declared, followed by a period
  6708. and the name of the constant, all in lowercase.
  6709. If a unit \file{MyUnit} declares a resourcestring \var{MyTitle} then the
  6710. name returned will be \var{myunit.mytitle}. A resourcestring in the program file
  6711. will have the name of the program prepended.
  6712. The name returned by this function is also the name that is stored in the
  6713. resourcestring file generated by the compiler.
  6714. Strictly speaking, this information isn't necessary for the functioning
  6715. of the program, it is provided only as a means to easier translation of
  6716. strings.
  6717. \Errors
  6718. If either \var{TableIndex} or \var{StringIndex} is zero, an empty string
  6719. is returned.
  6720. \SeeAlso
  6721. \seep{SetResourceStrings},
  6722. \seef{GetResourceStringDefaultValue},
  6723. \seef{GetResourceStringHash},
  6724. \seef{GetResourceStringName},
  6725. \seef{ResourceStringTableCount},
  6726. \seef{ResourceStringCount}
  6727. \end{function}
  6728. \FPCexample{ex92}
  6729. \begin{function}{Hash}
  6730. \Declaration
  6731. Function Hash(S : AnsiString) : longint;
  6732. \Description
  6733. \var{Hash} calculates the hash value of the string \var{S} in a manner that
  6734. is compatible with the GNU gettext hash value for the string. It is the same
  6735. value that is stored in the Resource string tables, and which can be
  6736. retrieved with the \seef{GetResourceStringHash} function call.
  6737. \Errors
  6738. None. In case the calculated hash value should be 0, the returned result
  6739. will be -1.
  6740. \SeeAlso
  6741. \seef{GetResourceStringHash},
  6742. \end{function}
  6743. \FPCexample{ex93}
  6744. \begin{functionl}{Paramstr}{objpasparamstr}
  6745. \Declaration
  6746. Function ParamStr(Param : Integer) : Ansistring;
  6747. \Description
  6748. \var{ParamStr} returns the \var{Param}-th command-line parameter as an
  6749. AnsiString. The system unit \seef{Paramstr} function limits the result to
  6750. 255 characters.
  6751. The zeroeth command-line parameter contains the path of the executable,
  6752. except on \linux, where it is the command as typed on the command-line.
  6753. \Errors
  6754. In case \var{Param} is an invalid value, an empty string is returned.
  6755. \SeeAlso
  6756. \seef{Paramstr}
  6757. \end{functionl}
  6758. For an example, see \seef{Paramstr}.
  6759. \begin{procedure}{ResetResourceTables}
  6760. \Declaration
  6761. Procedure ResetResourceTables;
  6762. \Description
  6763. \var{ResetResourceTables} resets all resource strings to their default
  6764. (i.e. as in the source code) values.
  6765. Normally, this should never be called from a user's program. It is called
  6766. in the initialization code of the \file{objpas} unit. However, if the
  6767. resourcetables get messed up for some reason, this procedure will fix them
  6768. again.
  6769. \Errors
  6770. None.
  6771. \SeeAlso
  6772. \seep{SetResourceStrings},
  6773. \seef{GetResourceStringDefaultValue},
  6774. \seef{GetResourceStringHash},
  6775. \seef{GetResourceStringName},
  6776. \seef{ResourceStringTableCount},
  6777. \seef{ResourceStringCount}
  6778. \end{procedure}
  6779. \begin{function}{ResourceStringCount}
  6780. \Declaration
  6781. Function ResourceStringCount(TableIndex : longint) : longint;
  6782. \Description
  6783. \var{ResourceStringCount} returns the number of resourcestrings in
  6784. the table with index \var{TableIndex}. The strings in a particular table
  6785. are numbered from \var{0} to \var{ResourceStringCount-1}, i.e. they're zero
  6786. based.
  6787. \Errors
  6788. If an invalid \var{TableIndex} is given, \var{-1} is returned.
  6789. \SeeAlso
  6790. \seep{SetResourceStrings},
  6791. \seef{GetResourceStringCurrentValue},
  6792. \seef{GetResourceStringDefaultValue},
  6793. \seef{GetResourceStringHash},
  6794. \seef{GetResourceStringName},
  6795. \seef{ResourceStringTableCount},
  6796. \end{function}
  6797. For an example, see \seef{GetResourceStringDefaultValue}
  6798. \begin{function}{ResourceStringTableCount}
  6799. \Declaration
  6800. Function ResourceStringTableCount : Longint;
  6801. \Description
  6802. \var{ResourceStringTableCount} returns the number of resource string tables;
  6803. this may be zero if no resource strings are used in a program.
  6804. The tables are numbered from 0 to \var{ResourceStringTableCount-1}, i.e.
  6805. they're zero based.
  6806. \Errors
  6807. \SeeAlso
  6808. \seep{SetResourceStrings},
  6809. \seef{GetResourceStringDefaultValue},
  6810. \seef{GetResourceStringHash},
  6811. \seef{GetResourceStringName},
  6812. \seef{ResourceStringCount}
  6813. \end{function}
  6814. For an example, see \seef{GetResourceStringDefaultValue}
  6815. \begin{procedure}{SetResourceStrings}
  6816. \Declaration
  6817. TResourceIterator = Function (Name,Value : AnsiString;Hash : Longint):AnsiString;
  6818. Procedure SetResourceStrings (SetFunction : TResourceIterator);
  6819. \Description
  6820. \var{SetResourceStrings} calls \var{SetFunction} for all resourcestrings
  6821. in the resourcestring tables and sets the resourcestring's current value
  6822. to the value returned by \var{SetFunction}.
  6823. The \var{Name},\var{Value} and \var{Hash} parameters passed to the iterator
  6824. function are the values stored in the tables.
  6825. \Errors
  6826. None.
  6827. \SeeAlso
  6828. \seef{GetResourceStringCurrentValue},
  6829. \seef{GetResourceStringDefaultValue},
  6830. \seef{GetResourceStringHash},
  6831. \seef{GetResourceStringName},
  6832. \seef{ResourceStringTableCount},
  6833. \seef{ResourceStringCount}
  6834. \end{procedure}
  6835. \FPCexample{ex95}
  6836. \begin{function}{SetResourceStringValue}
  6837. \Declaration
  6838. Function SetResourceStringValue(TableIndex,StringIndex : longint; Value : Ansistring) : Boolean;
  6839. \Description
  6840. \var{SetResourceStringValue} assigns \var{Value} to the resource string in
  6841. table \var{TableIndex} with index \var{StringIndex}.
  6842. \Errors
  6843. \SeeAlso
  6844. \seep{SetResourceStrings},
  6845. \seef{GetResourceStringCurrentValue},
  6846. \seef{GetResourceStringDefaultValue},
  6847. \seef{GetResourceStringHash},
  6848. \seef{GetResourceStringName},
  6849. \seef{ResourceStringTableCount},
  6850. \seef{ResourceStringCount}
  6851. \end{function}
  6852. \FPCexample{ex94}
  6853. %
  6854. % The index.
  6855. %
  6856. \printindex
  6857. \end{document}