sysutils.tex 86 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314231523162317231823192320232123222323232423252326232723282329233023312332233323342335233623372338233923402341234223432344234523462347234823492350235123522353235423552356235723582359236023612362236323642365236623672368236923702371237223732374237523762377237823792380238123822383238423852386238723882389239023912392239323942395239623972398239924002401240224032404240524062407240824092410241124122413241424152416241724182419242024212422242324242425242624272428242924302431243224332434243524362437243824392440244124422443244424452446244724482449245024512452245324542455245624572458245924602461246224632464246524662467246824692470247124722473247424752476247724782479248024812482248324842485248624872488248924902491249224932494249524962497249824992500250125022503250425052506250725082509251025112512251325142515251625172518251925202521252225232524252525262527252825292530253125322533253425352536253725382539254025412542254325442545254625472548254925502551255225532554255525562557255825592560256125622563256425652566256725682569257025712572257325742575257625772578257925802581258225832584258525862587258825892590259125922593259425952596259725982599260026012602260326042605260626072608260926102611261226132614261526162617261826192620262126222623262426252626262726282629263026312632263326342635263626372638263926402641264226432644264526462647264826492650265126522653265426552656265726582659266026612662266326642665266626672668266926702671267226732674267526762677267826792680268126822683268426852686
  1. %
  2. % $Id$
  3. % This file is part of the FPC documentation.
  4. % Copyright (C) 1999, 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. \chapter{The SYSUTILS unit.}
  22. This chapter describes the \file{sysutils} unit. The \var{sysutils} unit
  23. was largely written by Gertjan Schouten, and completed by michael Van Canneyt.
  24. It aims to be compatible to the Delphi sysutils unit, but in contrast with
  25. the latter, it is designed to work on multiple platforms. It is implemented
  26. on all supported platforms.
  27. This chapter starts out with a definition of all types and constants
  28. that are defined, followed by an overview of functions grouped by
  29. functionality, and lastly the complete explanation of each function.
  30. \section{Constants and types}
  31. The following general-purpose constants are defined:
  32. \begin{verbatim}
  33. const
  34. SecsPerDay = 24 * 60 * 60; // Seconds and milliseconds per day
  35. MSecsPerDay = SecsPerDay * 1000;
  36. DateDelta = 693594; // Days between 1/1/0001 and 12/31/1899
  37. Eoln = #10;
  38. \end{verbatim}
  39. The following types are used frequently in date and time functions.
  40. They are the same on all platforms.
  41. \begin{verbatim}
  42. type
  43. TSystemTime = record
  44. Year, Month, Day: word;
  45. Hour, Minute, Second, MilliSecond: word;
  46. end ;
  47. TDateTime = double;
  48. TTimeStamp = record
  49. Time: integer; { Number of milliseconds since midnight }
  50. Date: integer; { One plus number of days since 1/1/0001 }
  51. end ;
  52. \end{verbatim}
  53. The following type is used in the \seef{FindFirst},\seef{FindNext}
  54. and \seepl{FindClose}{FindCloseSys} functions. The \var{win32} version differs from
  55. the other versions. If code is to be portable, that part shouldn't
  56. be used.
  57. \begin{verbatim}
  58. Type
  59. THandle = Longint;
  60. TSearchRec = Record
  61. Time,Size, Attr : Longint;
  62. Name : TFileName;
  63. ExcludeAttr : Longint;
  64. FindHandle : THandle;
  65. {$ifdef Win32}
  66. FindData : TWin32FindData;
  67. {$endif}
  68. end;
  69. \end{verbatim}
  70. The following constants are file-attributes that need to be matched in the
  71. findfirst call.
  72. \begin{verbatim}
  73. Const
  74. faReadOnly = $00000001;
  75. faHidden = $00000002;
  76. faSysFile = $00000004;
  77. faVolumeId = $00000008;
  78. faDirectory = $00000010;
  79. faArchive = $00000020;
  80. faAnyFile = $0000003f;
  81. \end{verbatim}
  82. The following constants can be used in the \seef{FileOpen} call.
  83. \begin{verbatim}
  84. Const
  85. fmOpenRead = $0000;
  86. fmOpenWrite = $0001;
  87. fmOpenReadWrite = $0002;
  88. \end{verbatim}
  89. The following constants can be used in the \seef{FileSeek} call.
  90. \begin{verbatim}
  91. Const
  92. fsFromBeginning = 0;
  93. fsFromCurrent = 1;
  94. fsFromEnd = 2;
  95. \end{verbatim}
  96. The following variables are used in the case translation routines.
  97. \begin{verbatim}
  98. type
  99. TCaseTranslationTable = array[0..255] of char;
  100. var
  101. UpperCaseTable: TCaseTranslationTable;
  102. LowerCaseTable: TCaseTranslationTable;
  103. \end{verbatim}
  104. The initialization code of the \file{sysutils} unit fills these
  105. tables with the appropriate values. For the win32 and go32v2
  106. versions, this information is obtained from the operating system.
  107. The following constants control the formatting of dates.
  108. For the Win32 version of the \file{sysutils} unit, these
  109. constants are set according to the internationalization
  110. settings of Windows by the initialization code of the unit.
  111. \begin{verbatim}
  112. Const
  113. DateSeparator: char = '-';
  114. ShortDateFormat: string = 'd/m/y';
  115. LongDateFormat: string = 'dd" "mmmm" "yyyy';
  116. ShortMonthNames: array[1..12] of string[128] =
  117. ('Jan','Feb','Mar','Apr','May','Jun',
  118. 'Jul','Aug','Sep','Oct','Nov','Dec');
  119. LongMonthNames: array[1..12] of string[128] =
  120. ('January','February','March','April',
  121. 'May','June','July','August',
  122. 'September','October','November','December');
  123. ShortDayNames: array[1..7] of string[128] =
  124. ('Sun','Mon','Tue','Wed','Thu','Fri','Sat');
  125. LongDayNames: array[1..7] of string[128] =
  126. ('Sunday','Monday','Tuesday','Wednesday',
  127. 'Thursday','Friday','Saturday');
  128. \end{verbatim}
  129. The following constants control the formatting of times.
  130. For the Win32 version of the \file{sysutils} unit, these
  131. constants are set according to the internationalization
  132. settings of Windows by the initialization code of the unit.
  133. \begin{verbatim}
  134. Const
  135. ShortTimeFormat: string = 'hh:nn';
  136. LongTimeFormat: string = 'hh:nn:ss';
  137. TimeSeparator: char = ':';
  138. TimeAMString: string[7] = 'AM';
  139. TimePMString: string[7] = 'PM';
  140. \end{verbatim}
  141. The following constants control the formatting of currencies
  142. and numbers. For the Win32 version of the \file{sysutils} unit,
  143. these constants are set according to the internationalization
  144. settings of Windows by the initialization code of the unit.
  145. \begin{verbatim}
  146. Const
  147. DecimalSeparator : Char = '.';
  148. ThousandSeparator : Char = ',';
  149. CurrencyDecimals : Byte = 2;
  150. CurrencyString : String[7] = '$';
  151. { Format to use when formatting currency :
  152. 0 = $1 1 = 1$ 2 = $ 1 3 = 1 $
  153. 4 = Currency string replaces decimal indicator.
  154. e.g. 1$50
  155. }
  156. CurrencyFormat : Byte = 1;
  157. { Same as above, only for negative currencies:
  158. 0 = ($1)
  159. 1 = -$1
  160. 2 = $-1
  161. 3 = $1-
  162. 4 = (1$)
  163. 5 = -1$
  164. 6 = 1-$
  165. 7 = 1$-
  166. 8 = -1 $
  167. 9 = -$ 1
  168. 10 = $ 1-
  169. }
  170. NegCurrFormat : Byte = 5;
  171. \end{verbatim}
  172. The following types are used in various string functions.
  173. \begin{verbatim}
  174. type
  175. PString = ^String;
  176. TFloatFormat = (ffGeneral, ffExponent, ffFixed, ffNumber, ffCurrency);
  177. \end{verbatim}
  178. The following constants are used in the file name handling routines. Do not
  179. use a slash of backslash character directly as a path separator; instead
  180. use the \var{OsDirSeparator} character.
  181. \begin{verbatim}
  182. Const
  183. DirSeparators : set of char = ['/','\'];
  184. {$ifdef Linux}
  185. OSDirSeparator = '/';
  186. {$else}
  187. OsDirSeparator = '\';
  188. {$endif}
  189. \end{verbatim}
  190. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  191. % Functions and procedures by category
  192. \section{Function list by category}
  193. What follows is a listing of the available functions, grouped by category.
  194. For each function there is a reference to the page where you can find the
  195. function.
  196. \subsection{String functions}
  197. Functions for handling strings.
  198. \begin{funclist}
  199. \funcref{AnsiCompareStr}{Compare two strings}
  200. \funcref{AnsiCompareText}{Compare two strings, case insensitive}
  201. \funcref{AnsiExtractQuotedStr}{Removes quotes from string}
  202. \funcref{AnsiLastChar}{Get last character of string}
  203. \funcref{AnsiLowerCase}{Convert string to all-lowercase}
  204. \funcref{AnsiQuotedStr}{Qoutes a string}
  205. \funcref{AnsiStrComp}{Compare strings case-sensitive}
  206. \funcref{AnsiStrIComp}{Compare strings case-insensitive}
  207. \funcref{AnsiStrLComp}{Compare L characters of strings case sensitive}
  208. \funcref{AnsiStrLIComp}{Compare L characters of strings case insensitive}
  209. \funcref{AnsiStrLastChar}{Get last character of string}
  210. \funcref{AnsiStrLower}{Convert string to all-lowercase}
  211. \funcref{AnsiStrUpper}{Convert string to all-uppercase}
  212. \funcref{AnsiUpperCase}{Convert string to all-uppercase}
  213. \procref{AppendStr}{Append 2 strings}
  214. \procref{AssignStr}{Assign value of strings on heap}
  215. \funcref{CompareStr}{Compare two strings case sensitive}
  216. \funcref{CompareText}{Compare two strings case insensitive}
  217. \procrefl{DisposeStr}{DisposeStrSys}{Remove string from heap}
  218. \funcref{IsValidIdent}{Is string a valid pascal identifier}
  219. \funcref{LeftStr}{Get first N characters of a string}
  220. \funcref{LoadStr}{Load string from resources}
  221. \funcref{LowerCase}{Convert string to all-lowercase}
  222. \funcrefl{NewStr}{NewStrSys}{Allocate new string on heap}
  223. \funcref{RightStr}{Get last N characters of a string}
  224. \funcrefl{StrAlloc}{StrAllocSys}{Allocate memory for string}
  225. \funcref{StrBufSize}{Reserve memory for a string}
  226. \procrefl{StrDispose}{StrDisposeSys}{Remove string from heap}
  227. \funcrefl{StrPas}{StrPasSys}{Convert PChar to pascal string}
  228. \funcrefl{StrPCopy}{StrPCopySys}{Copy pascal string}
  229. \funcrefl{StrPLCopy}{StrPLCopySys}{Copy N bytes of pascal string}
  230. \funcref{UpperCase}{Convert string to all-uppercase}
  231. \end{funclist}
  232. \subsection{Formatting strings}
  233. Functions for formatting strings.
  234. \begin{funclist}
  235. \funcref{AdjustLineBreaks}{Convert line breaks to line breaks for system}
  236. \funcref{FormatBuf}{Format a buffer}
  237. \funcref{Format}{Format arguments in string}
  238. \procref{FmtStr}{Format buffer}
  239. \funcref{QuotedStr}{Quote a string}
  240. \funcref{StrFmt}{Format arguments in a string}
  241. \funcref{StrLFmt}{Format maximum L characters in a string}
  242. \funcref{TrimLeft}{Remove whitespace at the left of a string}
  243. \funcref{TrimRight}{Remove whitespace at the right of a string}
  244. \funcref{Trim}{Remove whitespace at both ends of a string}
  245. \end{funclist}
  246. \subsection{File input/output routines}
  247. Functions for reading/writing to file.
  248. \begin{funclist}
  249. \funcref{FileCreate}{Create a file and return handle}
  250. \funcref{FileOpen}{Open file end return handle}
  251. \funcref{FileRead}{Read from file}
  252. \funcref{FileSeek}{Set file position}
  253. \funcref{FileTruncate}{Truncate file length}
  254. \funcref{FileWrite}{Write to file}
  255. \procref{FileClose}{Close file handle}
  256. \end{funclist}
  257. \subsection{File handling routines}
  258. Functions for file manipulation.
  259. \begin{funclist}
  260. \funcref{AddDisk}{Add sisk to list of disk drives}
  261. \funcref{ChangeFileExt}{Change extension of file name}
  262. \funcref{CreateDir}{Create a directory}
  263. \funcref{DeleteFile}{Delete a file}
  264. \funcrefl{DiskFree}{DiskFreeSys}{Free space on disk}
  265. \funcrefl{DiskSize}{DiskSizeSys}{Total size of disk}
  266. \funcref{ExpandFileName}{Create full file name}
  267. \funcref{ExpandUNCFileName}{Create full UNC file name}
  268. \funcref{ExtractFileDir}{Extract directory part of filename}
  269. \funcref{ExtractFileDrive}{Extract drive part of filename}
  270. \funcref{ExtractFileExt}{Extract extension part of filename}
  271. \funcref{ExtractFileName}{Extract name part of filename}
  272. \funcref{ExtractFilePath}{Extrct path part of filename}
  273. \funcref{ExtractRelativePath}{Construct relative path between two files}
  274. \funcref{FileAge}{Return file age}
  275. \funcref{FileDateToDateTime}{Convert file date to system date}
  276. \funcref{FileExists}{Determine whether a file exists on disk}
  277. \funcref{FileGetAttr}{Get attributes of file}
  278. \funcref{FileGetDate}{Get date of last file modification}
  279. \funcref{FileSearch}{Search for file in path}
  280. \funcrefl{FileSetAttr}{FileSetAttr}{Get file attributes}
  281. \funcrefl{FileSetDate}{FileSetDate}{Get file dates}
  282. \funcref{FindFirst}{Start finding a file}
  283. \funcref{FindNext}{Find next file}
  284. \funcref{GetCurrentDir}{Return current working directory}
  285. \funcref{RemoveDir}{Remove a directory from disk}
  286. \funcref{RenameFile}{Rename a file on disk}
  287. \funcref{SetCurrentDir}{Set current working directory}
  288. \funcref{SetDirSeparators}{Set directory separator characters}
  289. \procrefl{FindClose}{FindCloseSys}{Stop searching a file}
  290. \procref{DoDirSeparators}{Replace directory separator characters}
  291. \end{funclist}
  292. \subsection{Date/time routines}
  293. Functions for date and time handling.
  294. \begin{funclist}
  295. \funcref{DateTimeToFileDate}{Convert DateTime type to file date}
  296. \funcref{DateTimeToStr}{Construct string representation of DateTime}
  297. \procref{DateTimeToString}{Construct string representation of DateTime}
  298. \procref{DateTimeToSystemTime}{Convert DateTime to system time}
  299. \funcref{DateTimeToTimeStamp}{Convert DateTime to timestamp}
  300. \funcref{DateToStr}{Construct string representation of date}
  301. \funcref{Date}{Get current date}
  302. \funcref{DayOfWeek}{Get day of week}
  303. \procref{DecodeDate}{Decode DateTime to year month and day}
  304. \procref{DecodeTime}{Decode DateTime to hours, minutes and seconds}
  305. \funcref{EncodeDate}{Encode year, day and month to DateTime}
  306. \funcref{EncodeTime}{Encode hours, minutes and seconds to DateTime}
  307. \funcref{FormatDateTime}{Return string representation of DateTime}
  308. \funcref{IncMonth}{Add 1 to month}
  309. \funcref{IsLeapYear}{Determine if year is leap year}
  310. \funcref{MSecsToTimeStamp}{Convert nr of milliseconds to timestamp}
  311. \funcref{Now}{Get current date and time}
  312. \funcref{StrToDateTime}{Convert string to DateTime}
  313. \funcref{StrToDate}{Convert string to date}
  314. \funcref{StrToTime}{Convert string to time}
  315. \funcref{SystemTimeToDateTime}{Convert system time to datetime}
  316. \funcref{TimeStampToDateTime}{Convert time stamp to DateTime}
  317. \funcref{TimeStampToMSecs}{Convert Timestamp to number of millicseconds}
  318. \funcref{TimeToStr}{return string representation of Time}
  319. \funcref{Time}{Get current tyme}
  320. \end{funclist}
  321. \section{Miscellaneous conversion routines}
  322. Functions for various conversions.
  323. \begin{funclist}
  324. \funcref{BCDToInt}{Convert BCD number to integer}
  325. \funcref{CompareMem}{Compare two memory regions}
  326. \funcref{FloatToStrF}{Convert float to formatted string}
  327. \funcref{FloatToStr}{Convert float to string}
  328. \funcref{FloatToText}{Convert float to string}
  329. \funcref{GetDirs}{Split string in list of directories}
  330. \funcref{IntToHex}{return hexadecimal representation of integer}
  331. \funcref{IntToStr}{return decumal representation of integer}
  332. \funcref{StrToIntDef}{Convert string to integer with default value}
  333. \funcref{StrToInt}{Convert string to integer}
  334. \end{funclist}
  335. \section{Date and time functions}
  336. \subsection{Date and time formatting characters}
  337. \label{se:formatchars}
  338. Various date and time formatting routines accept a format string.
  339. to format the date and or time. The following characters can be used
  340. to control the date and time formatting:
  341. \begin{description}
  342. \item[c] : shortdateformat + ' ' + shorttimeformat
  343. \item[d] : day of month
  344. \item[dd] : day of month (leading zero)
  345. \item[ddd] : day of week (abbreviation)
  346. \item[dddd] : day of week (full)
  347. \item[ddddd] : shortdateformat
  348. \item[dddddd] : longdateformat
  349. \item[m] : month
  350. \item[mm] : month (leading zero)
  351. \item[mmm] : month (abbreviation)
  352. \item[mmmm] : month (full)
  353. \item[y] : year (four digits)
  354. \item[yy] : year (two digits)
  355. \item[yyyy] : year (with century)
  356. \item[h] : hour
  357. \item[hh] : hour (leading zero)
  358. \item[n] : minute
  359. \item[nn] : minute (leading zero)
  360. \item[s] : second
  361. \item[ss] : second (leading zero)
  362. \item[t] : shorttimeformat
  363. \item[tt] : longtimeformat
  364. \item[am/pm] : use 12 hour clock and display am and pm accordingly
  365. \item[a/p] : use 12 hour clock and display a and p accordingly
  366. \item[/] : insert date seperator
  367. \item[:] : insert time seperator
  368. \item["xx"] : literal text
  369. \item['xx'] : literal text
  370. \end{description}
  371. \begin{type}{TDateTime}
  372. \Declaration
  373. TDateTime = Double;
  374. \Description
  375. Many functions return or require a \var{TDateTime} type, which contains
  376. a date and time in encoded form. The date and time are converted to a double
  377. as follows:
  378. \end{type}
  379. \begin{function}{Date}
  380. \Declaration
  381. Function Date: TDateTime;
  382. \Description
  383. \var{Date} returns the current date in \var{TDateTime} format.
  384. For more information about the \var{TDateTime} type, see \seetype{TDateTime}.
  385. \Errors
  386. None.
  387. \SeeAlso
  388. \seef{Time},\seef{Now}, \seetype{TDateTime}.
  389. \end{function}
  390. \latex{\lstinputlisting{sysutex/ex1.pp}}
  391. \html{\input{sysutex/ex1.tex}}
  392. \begin{function}{DateTimeToFileDate}
  393. \Declaration
  394. Function DateTimeToFileDate(DateTime : TDateTime) : Longint;
  395. \Description
  396. \var{DateTimeToFileDate} function converts a date/time indication in
  397. \var{TDateTime} format to a filedate function, such as returned for
  398. instance by the \seef{FileAge} function.
  399. \Errors
  400. None.
  401. \SeeAlso
  402. \seef{Time}, \seef{Date}, \seef{FileDateToDateTime},
  403. \seep{DateTimeToSystemTime}, \seef{DateTimeToTimeStamp}
  404. \end{function}
  405. \latex{\lstinputlisting{sysutex/ex2.pp}}
  406. \html{\input{sysutex/ex2.tex}}
  407. \begin{function}{DateTimeToStr}
  408. \Declaration
  409. Function DateTimeToStr(DateTime: TDateTime): string;
  410. \Description
  411. \var{DateTimeToStr} returns a string representation of
  412. \var{DateTime} using the formatting specified in
  413. \var{ShortDateTimeFormat}. It corresponds to a call to
  414. \var{FormatDateTime('c',DateTime)} (see \sees{formatchars}).
  415. \Errors
  416. None.
  417. \SeeAlso
  418. \seef{FormatDateTime}, \seetype{TDateTime}.
  419. \end{function}
  420. \latex{\lstinputlisting{sysutex/ex3.pp}}
  421. \html{\input{sysutex/ex3.tex}}
  422. \begin{procedure}{DateTimeToString}
  423. \Declaration
  424. Procedure DateTimeToString(var Result: string; const FormatStr: string; const DateTime: TDateTime);
  425. \Description
  426. \var{DateTimeToString} returns in \var{Result} a string representation of
  427. \var{DateTime} using the formatting specified in \var{FormatStr}.
  428. for a list of characters that can be used in the \var{FormatStr} formatting
  429. string, see \sees{formatchars}.
  430. \Errors
  431. In case a wrong formatting character is found, an \var{EConvertError} is
  432. raised.
  433. \SeeAlso
  434. \seef{FormatDateTime}, \sees{formatchars}.
  435. \end{procedure}
  436. \latex{\lstinputlisting{sysutex/ex4.pp}}
  437. \html{\input{sysutex/ex4.tex}}
  438. \begin{procedure}{DateTimeToSystemTime}
  439. \Declaration
  440. Procedure DateTimeToSystemTime(DateTime: TDateTime; var SystemTime: TSystemTime);
  441. \Description
  442. \var{DateTimeToSystemTime} converts a date/time pair in \var{DateTime}, with
  443. \var{TDateTime} format to a system time \var{SystemTime}.
  444. \Errors
  445. None.
  446. \SeeAlso
  447. \seef{DateTimeToFileDate}, \seef{SystemTimeToDateTime},
  448. \seef{DateTimeToTimeStamp}
  449. \end{procedure}
  450. \latex{\lstinputlisting{sysutex/ex5.pp}}
  451. \html{\input{sysutex/ex5.tex}}
  452. \begin{function}{DateTimeToTimeStamp}
  453. \Declaration
  454. Function DateTimeToTimeStamp(DateTime: TDateTime): TTimeStamp;
  455. \Description
  456. \var{DateTimeToSystemTime} converts a date/time pair in \var{DateTime}, with
  457. \var{TDateTime} format to a \var{TTimeStamp} format.
  458. \Errors
  459. None.
  460. \SeeAlso
  461. \seef{DateTimeToFileDate}, \seef{SystemTimeToDateTime},
  462. \seep{DateTimeToSystemTime}
  463. \end{function}
  464. \latex{\lstinputlisting{sysutex/ex6.pp}}
  465. \html{\input{sysutex/ex6.tex}}
  466. \begin{function}{DateToStr}
  467. \Declaration
  468. Function DateToStr(Date: TDateTime): string;
  469. \Description
  470. \var{DateToStr} converts \var{Date} to a string representation. It uses
  471. \var{ShortDateFormat} as it's formatting string. It is hence completely
  472. equivalent to a \var{FormatDateTime('ddddd', Date)}.
  473. \Errors
  474. None.
  475. \SeeAlso
  476. \seef{TimeToStr}, \seef{DateTimeToStr}, \seef{FormatDateTime},
  477. \seef{StrToDate}
  478. \end{function}
  479. \latex{\lstinputlisting{sysutex/ex7.pp}}
  480. \html{\input{sysutex/ex7.tex}}
  481. \begin{function}{DayOfWeek}
  482. \Declaration
  483. Function DayOfWeek(DateTime: TDateTime): integer;
  484. \Description
  485. \var{DayOfWeek} returns the day of the week from \var{DateTime}.
  486. \var{Sunday} is counted as day 1, \var{Saturday} is counted as
  487. day 7. The result of \var{DayOfWeek} can serve as an index to
  488. the \var{LongDayNames} constant array, to retrieve the name of
  489. the day.
  490. \Errors
  491. None.
  492. \SeeAlso
  493. \seef{Date}, \seef{DateToStr}
  494. \end{function}
  495. \latex{\lstinputlisting{sysutex/ex8.pp}}
  496. \html{\input{sysutex/ex8.tex}}
  497. \begin{procedure}{DecodeDate}
  498. \Declaration
  499. Procedure DecodeDate(Date: TDateTime; var Year, Month, Day: word);
  500. \Description
  501. \var{DecodeDate} decodes the Year, Month and Day stored in \var{Date},
  502. and returns them in the \var{Year}, \var{Month} and \var{Day} variables.
  503. \Errors
  504. None.
  505. \SeeAlso
  506. \seef{EncodeDate}, \seep{DecodeTime}.
  507. \end{procedure}
  508. \latex{\lstinputlisting{sysutex/ex9.pp}}
  509. \html{\input{sysutex/ex9.tex}}
  510. \begin{procedure}{DecodeTime}
  511. \Declaration
  512. Procedure DecodeTime(Time: TDateTime; var Hour, Minute, Second, MilliSecond: word);
  513. \Description
  514. \var{DecodeDate} decodes the hours, minutes, second and milliseconds stored
  515. in \var{Time}, and returns them in the \var{Hour}, \var{Minute} and
  516. \var{Second} and \var{MilliSecond} variables.
  517. \Errors
  518. None.
  519. \SeeAlso
  520. \seef{EncodeTime}, \seep{DecodeDate}.
  521. \end{procedure}
  522. \latex{\lstinputlisting{sysutex/ex10.pp}}
  523. \html{\input{sysutex/ex10.tex}}
  524. \begin{function}{EncodeDate}
  525. \Declaration
  526. Function EncodeDate(Year, Month, Day :word): TDateTime;
  527. \Description
  528. \var{EncodeDate} encodes the \var{Year}, \var{Month} and \var{Day} variables to
  529. a date in \var{TDateTime} format. It does the opposite of the
  530. \seep{DecodeDate} procedure.
  531. The parameters must lie withing valid ranges (boundaries included):
  532. \begin{description}
  533. \item[Year] must be between 1 and 9999.
  534. \item[Month] must be within the range 1-12.
  535. \item[Day] msut be between 1 and 31.
  536. \end{description}
  537. \Errors
  538. In case one of the parameters is out of it's valid range, 0 is returned.
  539. \SeeAlso
  540. \seef{EncodeTime}, \seep{DecodeDate}.
  541. \end{function}
  542. \latex{\lstinputlisting{sysutex/ex11.pp}}
  543. \html{\input{sysutex/ex11.tex}}
  544. \begin{function}{EncodeTime}
  545. \Declaration
  546. Function EncodeTime(Hour, Minute, Second, MilliSecond:word): TDateTime;
  547. \Description
  548. \var{EncodeTime} encodes the \var{Hour}, \var{Minute}, \var{Second},
  549. \var{MilliSecond} variables to a \var{TDateTime} format result.
  550. It does the opposite of the \seep{DecodeTime} procedure.
  551. The parameters must have a valid range (boundaries included):
  552. \begin{description}
  553. \item[Hour] must be between 0 and 23.
  554. \item[Minute,second] must both be between 0 and 59.
  555. \item[Millisecond] must be between 0 and 999.
  556. \end{description}
  557. \Errors
  558. In case one of the parameters is outside of it's valid range, 0 is returned.
  559. \SeeAlso
  560. \seef{EncodeDate}, \seep{DecodeTime}.
  561. \end{function}
  562. \latex{\lstinputlisting{sysutex/ex12.pp}}
  563. \html{\input{sysutex/ex12.tex}}
  564. \begin{function}{FileDateToDateTime}
  565. \Declaration
  566. Function FileDateToDateTime(Filedate : Longint) : TDateTime;
  567. \Description
  568. \var{FileDateToDateTime} converts the date/time encoded in \var{filedate}
  569. to a \var{TDateTime} encoded form. It can be used to convert date/time values
  570. returned by the \seef{FileAge} or \seef{FindFirst}/\seef{FindNext}
  571. functions to \var{TDateTime} form.
  572. \Errors
  573. None.
  574. \SeeAlso
  575. \seef{DateTimeToFileDate}
  576. \end{function}
  577. \latex{\lstinputlisting{sysutex/ex13.pp}}
  578. \html{\input{sysutex/ex13.tex}}
  579. \begin{function}{FormatDateTime}
  580. \Declaration
  581. Function FormatDateTime(FormatStr: string; DateTime: TDateTime):string;
  582. \Description
  583. \var{FormatDateTime} formats the date and time encoded in \var{DateTime}
  584. according to the formatting given in \var{FormatStr}. The complete list
  585. of formatting characters can be found in \sees{formatchars}.
  586. \Errors
  587. On error (such as an invalid character in the formatting string), and
  588. \var{EConvertError} exception is raised.
  589. \SeeAlso
  590. \seef{DateTimeToStr}, \seef{DateToStr}, \seef{TimeToStr},
  591. \seef{StrToDateTime}
  592. \end{function}
  593. \latex{\lstinputlisting{sysutex/ex14.pp}}
  594. \html{\input{sysutex/ex14.tex}}
  595. \begin{function}{IncMonth}
  596. \Declaration
  597. Function IncMonth(const DateTime: TDateTime; NumberOfMonths: integer): TDateTime;
  598. \Description
  599. \var{IncMonth} increases the month number in \var{DateTime} with
  600. \var{NumberOfMonths}. It wraps the result as to get a month between 1 and
  601. 12, and updates the year accordingly. \var{NumberOfMonths} can be negative,
  602. and can be larger than 12 (in absolute value).
  603. \Errors
  604. None.
  605. \SeeAlso
  606. \seef{Date}, \seef{Time}, \seef{Now}
  607. \end{function}
  608. \latex{\lstinputlisting{sysutex/ex15.pp}}
  609. \html{\input{sysutex/ex15.tex}}
  610. \begin{function}{IsLeapYear}
  611. \Declaration
  612. Function IsLeapYear(Year: Word): boolean;
  613. \Description
  614. \var{IsLeapYear} returns \var{True} if \var{Year} is a leap year,
  615. \var{False} otherwise.
  616. \Errors
  617. None.
  618. \SeeAlso
  619. \seef{IncMonth}, \seef{Date}
  620. \end{function}
  621. \latex{\lstinputlisting{sysutex/ex16.pp}}
  622. \html{\input{sysutex/ex16.tex}}
  623. \begin{function}{MSecsToTimeStamp}
  624. \Declaration
  625. Function MSecsToTimeStamp(MSecs: Comp): TTimeStamp;
  626. \Description
  627. \var{MSecsTiTimeStamp} converts the given number of milliseconds to
  628. a \var{TTimeStamp} date/time notation.
  629. Use \var{TTimeStamp} variables if you need to keep very precise track of
  630. time.
  631. \Errors
  632. None.
  633. \SeeAlso
  634. \seef{TimeStampToMSecs}, \seef{DateTimeToTimeStamp},
  635. \end{function}
  636. \latex{\lstinputlisting{sysutex/ex17.pp}}
  637. \html{\input{sysutex/ex17.tex}}
  638. \begin{function}{Now}
  639. \Declaration
  640. Function Now: TDateTime;
  641. \Description
  642. \var{Now} returns the current date and time. It is equivalent to
  643. \var{Date+Time}.
  644. \Errors
  645. None.
  646. \SeeAlso
  647. \seef{Date}, \seef{Time}
  648. \end{function}
  649. \latex{\lstinputlisting{sysutex/ex18.pp}}
  650. \html{\input{sysutex/ex18.tex}}
  651. \begin{function}{StrToDate}
  652. \Declaration
  653. Function StrToDate(const S: string): TDateTime;
  654. \Description
  655. \var{StrToDate} converts the string \var{S} to a \var{TDateTime} date
  656. value. The Date must consist of 1 to three digits, separated by the
  657. \var{DateSeparator} character. If two numbers are given, they
  658. are supposed to form the day and month of the current year. If only
  659. one number is given, it is supposed to represent the day of the
  660. current month. (This is \em{not} supported in Delphi)
  661. The order of the digits (y/m/d, m/d/y, d/m/y) is determined from the
  662. \var{ShortDateFormat} variable.
  663. \Errors
  664. On error (e.g. an invalid date or invalid character),
  665. an \var{EConvertError} exception is raised.
  666. \SeeAlso
  667. \seef{StrToTime}, \seef{DateToStr}n \seef{TimeToStr}.
  668. \end{function}
  669. \latex{\lstinputlisting{sysutex/ex19.pp}}
  670. \html{\input{sysutex/ex19.tex}}
  671. \begin{function}{StrToDateTime}
  672. \Declaration
  673. Function StrToDateTime(const S: string): TDateTime;
  674. \Description
  675. \var{StrToDateTime} converts the string \var{S} to a \var{TDateTime} date
  676. and time value. The Date must consist of 1 to three digits, separated by the
  677. \var{DateSeparator} character. If two numbers are given, they
  678. are supposed to form the day and month of the current year. If only
  679. one number is given, it is supposed to represent the day of the
  680. current month. (This is \em{not} supported in Delphi)
  681. The order of the digits (y/m/d, m/d/y, d/m/y) is determined from the
  682. \var{ShortDateFormat} variable.
  683. \Errors
  684. On error (e.g. an invalid date or invalid character),
  685. an \var{EConvertError} exception is raised.
  686. \SeeAlso
  687. \seef{StrToDate}, \seef{StrToTime}, \seef{DateTimeToStr}
  688. \end{function}
  689. \latex{\lstinputlisting{sysutex/ex20.pp}}
  690. \html{\input{sysutex/ex20.tex}}
  691. \begin{function}{StrToTime}
  692. \Declaration
  693. Function StrToTime(const S: string): TDateTime;
  694. \Description
  695. \var{StrToTime} converts the string \var{S} to a \var{TDateTime} time
  696. value. The time must consist of 1 to 4 digits, separated by the
  697. \var{TimeSeparator} character. If two numbers are given, they
  698. are supposed to form the hour and minutes.
  699. \Errors
  700. On error (e.g. an invalid date or invalid character),
  701. an \var{EConvertError} exception is raised.
  702. \SeeAlso
  703. \seef{StrToDate}, \seef{StrToDateTime}, \seef{TimeToStr}
  704. \end{function}
  705. \latex{\lstinputlisting{sysutex/ex21.pp}}
  706. \html{\input{sysutex/ex21.tex}}
  707. \begin{function}{SystemTimeToDateTime}
  708. \Declaration
  709. Function SystemTimeToDateTime(const SystemTime: TSystemTime): TDateTime;
  710. \Description
  711. \var{SystemTimeToDateTime} converts a \var{TSystemTime} record to a
  712. \var{TDateTime} style date/time indication.
  713. \Errors
  714. None.
  715. \SeeAlso
  716. \seep{DateTimeToSystemTime}
  717. \end{function}
  718. \latex{\lstinputlisting{sysutex/ex22.pp}}
  719. \html{\input{sysutex/ex22.tex}}
  720. \begin{function}{Time}
  721. \Declaration
  722. Function Time: TDateTime;
  723. \Description
  724. \var{Time} returns the current time in \var{TDateTime} format. The date
  725. part of the \var{TDateTimeValue} is set to zero.
  726. \Errors
  727. None.
  728. \SeeAlso
  729. \seef{Now}, \seef{Date}
  730. \end{function}
  731. \latex{\lstinputlisting{sysutex/ex23.pp}}
  732. \html{\input{sysutex/ex23.tex}}
  733. \begin{function}{TimeStampToDateTime}
  734. \Declaration
  735. Function TimeStampToDateTime(const TimeStamp: TTimeStamp): TDateTime;
  736. \Description
  737. \var{TimeStampToDateTime} converts \var{TimeStamp} to a \var{TDateTime}
  738. format variable. It is the inverse operation of \seef{DateTimeToTimeStamp}.
  739. \Errors
  740. None.
  741. \SeeAlso
  742. \seef{DateTimeToTimeStamp}, \seef{TimeStampToMSecs}
  743. \end{function}
  744. \latex{\lstinputlisting{sysutex/ex24.pp}}
  745. \html{\input{sysutex/ex24.tex}}
  746. \begin{function}{TimeStampToMSecs}
  747. \Declaration
  748. Function TimeStampToMSecs(const TimeStamp: TTimeStamp): comp;
  749. \Description
  750. \var{TimeStampToMSecs} converts {TimeStamp} to the number of seconds
  751. since \var{1/1/0001}.
  752. Use \var{TTimeStamp} variables if you need to keep very precise track of
  753. time.
  754. \Errors
  755. None.
  756. \SeeAlso
  757. \seef{MSecsToTimeStamp}, \seef{TimeStampToDateTime}
  758. \end{function}
  759. For an example, see \seef{MSecsToTimeStamp}.
  760. \begin{function}{TimeToStr}
  761. \Declaration
  762. Function TimeToStr(Time: TDateTime): string;
  763. \Description
  764. \var{TimeToStr} converts the time in \var{Time} to a string. It uses
  765. the \var{ShortTimeFormat} variable to see what formatting needs to be
  766. applied. It is therefor entirely equivalent to a
  767. \var{FormatDateTime('t',Time)} call.
  768. \Errors
  769. None.
  770. \SeeAlso
  771. \end{function}
  772. \latex{\lstinputlisting{sysutex/ex25.pp}}
  773. \html{\input{sysutex/ex25.tex}}
  774. \section{Disk functions}
  775. \begin{functionl}{AddDisk (Linux only)}{AddDisk}
  776. \Declaration
  777. Function AddDisk (Const PAth : String) : Longint;
  778. \Description
  779. On Linux both the \seef{DiskFree} and \seef{DiskSize} functions need a
  780. file on the specified drive, since is required for the statfs system call.
  781. These filenames are set in drivestr[0..26], and the first 4 have been
  782. preset to :
  783. \begin{description}
  784. \item[Disk 0] \var{'.'} default drive - hence current directory is used.
  785. \item[Disk 1] \var{'/fd0/.'} floppy drive 1.
  786. \item[Disk 2] \var{'/fd1/.'} floppy drive 2.
  787. \item[Disk 3] \var{'/'} \file{C:} equivalent of DOS is the root partition.
  788. \end{description}
  789. Drives 4..26 can be set by your own applications with the \var{AddDisk} call.
  790. The \var{AddDisk} call adds \var{Path} to the names of drive files, and
  791. returns the number of the disk that corresponds to this drive. If you
  792. add more than 21 drives, the count is wrapped to 4.
  793. \Errors
  794. None.
  795. \SeeAlso
  796. \seefl{DiskFree}{DiskFreeSys}, \seefl{DiskSize}{DiskSizeSys}
  797. \end{functionl}
  798. \begin{function}{CreateDir}
  799. \Declaration
  800. Function CreateDir(Const NewDir : String) : Boolean;
  801. \Description
  802. \var{CreateDir} creates a new directory with name \var{NewDir}.
  803. If the directory doesn't contain an absolute path, then the directory is
  804. created below the current working directory.
  805. The function returns \var{True} if the directory was successfully
  806. created, \var{False} otherwise.
  807. \Errors
  808. In case of an error, the function returns \var{False}.
  809. \SeeAlso
  810. \seef{RemoveDir}
  811. \end{function}
  812. \latex{\lstinputlisting{sysutex/ex26.pp}}
  813. \html{\input{sysutex/ex26.tex}}
  814. \begin{functionl}{DiskFree}{DiskFreeSys}
  815. \Declaration
  816. Function DiskFree(Drive : Byte) : Longint;
  817. \Description
  818. \var{DiskFree} returns the free space (in bytes) on disk \var{Drive}.
  819. Drive is the number of the disk drive:
  820. \begin{description}
  821. \item[0] for the current drive.
  822. \item[1] for the first floppy drive.
  823. \item[2] for the second floppy drive.
  824. \item[3] for the first hard-disk parttion.
  825. \item[4-26] for all other drives and partitions.
  826. \end{description}
  827. {\em Remark} Under \linux, and Unix in general, the concept of disk is
  828. different than the \dos one, since the filesystem is seen as one big
  829. directory tree. For this reason, the \var{DiskFree} and \seef{DiskSize}
  830. functions must be mimicked using filenames that reside on the partitions.
  831. For more information, see \seef{AddDisk}
  832. \Errors
  833. On error, \var{-1} is returned.
  834. \SeeAlso
  835. \seefl{DiskSize}{DiskSizeSys}, \seef{AddDisk}
  836. \end{functionl}
  837. \latex{\lstinputlisting{sysutex/ex27.pp}}
  838. \html{\input{sysutex/ex27.tex}}
  839. \begin{functionl}{DiskSize}{DiskSizeSys}
  840. \Declaration
  841. Function DiskSize(Drive : Byte) : Longint;
  842. \Description
  843. \var{DiskSize} returns the size (in bytes) of disk \var{Drive}.
  844. Drive is the number of the disk drive:
  845. \begin{description}
  846. \item[0] for the current drive.
  847. \item[1] for the first floppy drive.
  848. \item[2] for the second floppy drive.
  849. \item[3] for the first hard-disk parttion.
  850. \item[4-26] for all other drives and partitions.
  851. \end{description}
  852. {\em Remark} Under \linux, and Unix in general, the concept of disk is
  853. different than the \dos one, since the filesystem is seen as one big
  854. directory tree. For this reason, the \seef{DiskFree} and \var{DiskSize}
  855. functions must be mimicked using filenames that reside on the partitions.
  856. For more information, see \seef{AddDisk}
  857. \Errors
  858. On error, \var{-1} is returned.
  859. \SeeAlso
  860. \seefl{DiskFree}{DiskFreeSys}, \seef{AddDisk}
  861. \end{functionl}
  862. For an example, see \seefl{DiskFree}{DiskFreeSys}.
  863. \begin{function}{GetCurrentDir}
  864. \Declaration
  865. Function GetCurrentDir : String;
  866. \Description
  867. \var{GetCurrentDir} returns the current working directory.
  868. \Errors
  869. None.
  870. \SeeAlso
  871. \seef{SetCurrentDir}, \seef{DiskFree}, \seef{DiskSize}
  872. \end{function}
  873. \latex{\lstinputlisting{sysutex/ex28.pp}}
  874. \html{\input{sysutex/ex28.tex}}
  875. \begin{function}{RemoveDir}
  876. \Declaration
  877. Function RemoveDir(Const Dir : String) : Boolean;
  878. \Description
  879. \var{RemoveDir} removes directory \var{Dir} from the disk.
  880. If the directory is not absolue, it is appended to the current working
  881. directory.
  882. \Errors
  883. In case of error (e.g. the directory isn't empty) the function returns
  884. \var{False}. If successful, \var{True} is returned.
  885. \SeeAlso
  886. \end{function}
  887. For an example, see \seef{CreateDir}.
  888. \begin{function}{SetCurrentDir}
  889. \Declaration
  890. Function SetCurrentDir(Const NewDir : String) : Boolean;
  891. \Description
  892. \var{SetCurrentDir} sets the current working directory of your program
  893. to \var{NewDir}. It returns \var{True} if the function was successfull,
  894. \var{False} otherwise.
  895. \Errors
  896. In case of error, \var{False} is returned.
  897. \SeeAlso
  898. \seef{GetCurrentDir}
  899. \end{function}
  900. \latex{\lstinputlisting{sysutex/ex29.pp}}
  901. \html{\input{sysutex/ex29.tex}}
  902. \section{File handling functions}
  903. \begin{function}{ChangeFileExt}
  904. \Declaration
  905. Function ChangeFileExt(const FileName, Extension: string): string;
  906. \Description
  907. \var{ChangeFileExt} changes the file extension in \var{FileName} to
  908. \var{Extension}.
  909. The extension \var{Extension} includes the starting \var{.} (dot).
  910. The previous extension of \var{FileName} are all characters after the
  911. last \var{.}, the \var{.} character included.
  912. If \var{FileName} doesn't have an extension, \var{Extension} is just
  913. appended.
  914. \Errors
  915. None.
  916. \SeeAlso
  917. \seef{ExtractFileName}, \seef{ExtractFilePath}, \seef{ExpandFileName}
  918. \end{function}
  919. \begin{function}{DeleteFile}
  920. \Declaration
  921. Function DeleteFile(Const FileName : String) : Boolean;
  922. \Description
  923. \var{DeleteFile} deletes file \var{FileName} from disk. The function
  924. returns \var{True} if the file was successfully removed, \var{False}
  925. otherwise.
  926. \Errors
  927. On error, \var{False} is returned.
  928. \SeeAlso
  929. \seef{FileCreate}, \seef{FileExists}
  930. \end{function}
  931. \latex{\lstinputlisting{sysutex/ex31.pp}}
  932. \html{\input{sysutex/ex31.tex}}
  933. \begin{procedure}{DoDirSeparators}
  934. \Declaration
  935. Procedure DoDirSeparators(Var FileName : String);
  936. \Description
  937. This function replaces all directory separators \var{'\' and '/'}
  938. to the directory separator character for the current system.
  939. \Errors
  940. None.
  941. \SeeAlso
  942. \seef{ExtractFileName}, \seef{ExtractFilePath}
  943. \end{procedure}
  944. \latex{\lstinputlisting{sysutex/ex32.pp}}
  945. \html{\input{sysutex/ex32.tex}}
  946. \begin{function}{ExpandFileName}
  947. \Declaration
  948. Function ExpandFileName(Const FileName : string): String;
  949. \Description
  950. \var{ExpandFileName} expands the filename to an absolute filename.
  951. It changes all directory separator characters to the one appropriate for the
  952. system first.
  953. \Errors
  954. None.
  955. \SeeAlso
  956. \seef{ExtractFileName}, \seef{ExtractFilePath}, \seef{ExtractFileDir},
  957. \seef{ExtractFileDrive}, \seef{ExtractFileExt}, \seef{ExtractRelativePath}
  958. \end{function}
  959. \latex{\lstinputlisting{sysutex/ex33.pp}}
  960. \html{\input{sysutex/ex33.tex}}
  961. \begin{function}{ExpandUNCFileName}
  962. \Declaration
  963. Function ExpandUNCFileName(Const FileName : string): String;
  964. \Description
  965. \var{ExpandUNCFileName} runs \seef{ExpandFileName} on \var{FileName}
  966. and then attempts to replace the driveletter by the name of a shared disk.
  967. \Errors
  968. \SeeAlso
  969. \seef{ExtractFileName}, \seef{ExtractFilePath}, \seef{ExtractFileDir},
  970. \seef{ExtractFileDrive}, \seef{ExtractFileExt}, \seef{ExtractRelativePath}
  971. \end{function}
  972. \begin{function}{ExtractFileDir}
  973. \Declaration
  974. Function ExtractFileDir(Const FileName : string): string;
  975. \Description
  976. \var{ExtractFileDir} returns only the directory part of \var{FileName},
  977. not including a driveletter. The directory name has NO ending directory
  978. separator, in difference with \seef{ExtractFilePath}.
  979. \Errors
  980. None.
  981. \SeeAlso
  982. \seef{ExtractFileName}, \seef{ExtractFilePath}, \seef{ExtractFileDir},
  983. \seef{ExtractFileDrive}, \seef{ExtractFileExt}, \seef{ExtractRelativePath}
  984. \end{function}
  985. \latex{\lstinputlisting{sysutex/ex34.pp}}
  986. \html{\input{sysutex/ex34.tex}}
  987. \begin{function}{ExtractFileDrive}
  988. \Declaration
  989. Function ExtractFileDrive(const FileName: string): string;
  990. \Description
  991. \var{Extract}
  992. \Errors
  993. \SeeAlso
  994. \seef{ExtractFileName}, \seef{ExtractFilePath}, \seef{ExtractFileDir},
  995. \seef{ExtractFileDrive}, \seef{ExtractFileExt}, \seef{ExtractRelativePath}
  996. \end{function}
  997. For an example, see \seef{ExtractFileDir}.
  998. \begin{function}{ExtractFileExt}
  999. \Declaration
  1000. Function ExtractFileExt(const FileName: string): string;
  1001. \Description
  1002. \var{ExtractFileExt} returns the extension (including the
  1003. \var{.}(dot) character) of \var{FileName}.
  1004. \Errors
  1005. None.
  1006. \SeeAlso
  1007. \seef{ExtractFileName}, \seef{ExtractFilePath}, \seef{ExtractFileDir},
  1008. \seef{ExtractFileDrive}, \seef{ExtractFileExt}, \seef{ExtractRelativePath}
  1009. \end{function}
  1010. For an example, see \seef{ExtractFileDir}.
  1011. \begin{function}{ExtractFileName}
  1012. \Declaration
  1013. Function ExtractFileName(const FileName: string): string;
  1014. \Description
  1015. \var{ExtractFileName} returns the filename part from \var{FileName}.
  1016. The filename consists of all characters after the last directory separator
  1017. character ('/' or '\') or drive letter.
  1018. The full filename can always be reconstucted by concatenating the result
  1019. of \seef{ExtractFilePath} and \var{ExtractFileName}.
  1020. \Errors
  1021. None.
  1022. \SeeAlso
  1023. \seef{ExtractFileName}, \seef{ExtractFilePath}, \seef{ExtractFileDir},
  1024. \seef{ExtractFileDrive}, \seef{ExtractFileExt},\seef{ExtractRelativePath}
  1025. \end{function}
  1026. For an example, see \seef{ExtractFileDir}.
  1027. \begin{function}{ExtractFilePath}
  1028. \Declaration
  1029. Function ExtractFilePath(const FileName: string): string;
  1030. \Description
  1031. \var{ExtractFilePath} returns the path part (including driveletter) from
  1032. \var{FileName}. The path consists of all characters before the last
  1033. directory separator character ('/' or '\'), including the directory
  1034. separator itself.
  1035. In case there is only a drive letter, that will be returned.
  1036. The full filename can always be reconstucted by concatenating the result
  1037. of \var{ExtractFilePath} and \seef{ExtractFileName}.
  1038. \Errors
  1039. None.
  1040. \SeeAlso
  1041. \seef{ExtractFileName}, \seef{ExtractFilePath}, \seef{ExtractFileDir},
  1042. \seef{ExtractFileDrive}, \seef{ExtractFileExt}, \seef{ExtractRelativePath}
  1043. \end{function}
  1044. For an example, see \seef{ExtractFileDir}.
  1045. \begin{function}{ExtractRelativePath}
  1046. \Declaration
  1047. Function ExtractRelativePath(Const BaseName,DestNAme : String): String;
  1048. \Description
  1049. \var{ExtractRelativePath} constructs a relative path to go from
  1050. \var{BaseName} to \var{DestName}. If \var{DestName} is on another drive
  1051. (Not on Linux) then the whole \var{Destname} is returned.
  1052. {\em Note:} This function does not exist in the Delphi unit.
  1053. \Errors
  1054. None.
  1055. \SeeAlso
  1056. \seef{ExtractFileName}, \seef{ExtractFilePath}, \seef{ExtractFileDir},
  1057. \seef{ExtractFileDrive}, \seef{ExtractFileExt},
  1058. \end{function}
  1059. \latex{\lstinputlisting{sysutex/ex35.pp}}
  1060. \html{\input{sysutex/ex35.tex}}
  1061. \begin{function}{FileAge}
  1062. \Declaration
  1063. Function FileAge(Const FileName : String): Longint;
  1064. \Description
  1065. \var{FileAge} returns the last modification time of file \var{FileName}.
  1066. The FileDate format can be transformed to \var{TDateTime} format with the
  1067. \seef{FileDateToDateTime} function.
  1068. \Errors
  1069. In case of errors, \var{-1} is returned.
  1070. \SeeAlso
  1071. \seef{FileDateToDateTime}, \seef{FileExists}, \seef{FileGetAttr}
  1072. \end{function}
  1073. \latex{\lstinputlisting{sysutex/ex36.pp}}
  1074. \html{\input{sysutex/ex36.tex}}
  1075. \begin{procedure}{FileClose}
  1076. \Declaration
  1077. Procedure FileClose(Handle : Longint);
  1078. \Description
  1079. \var{FileClose} closes the file handle \var{Handle}. After this call,
  1080. attempting to read or write from the handle will result in an error.
  1081. \Errors
  1082. None.
  1083. \SeeAlso
  1084. \seef{FileCreate}, \seef{FileWrite}, \seef{FileOpen}, \seef{FileRead},
  1085. \seef{FileTruncate}, \seef{FileSeek}
  1086. \end{procedure}
  1087. For an example, see \seef{FileCreate}
  1088. \begin{function}{FileCreate}
  1089. \Declaration
  1090. Function FileCreate(Const FileName : String) : Longint;
  1091. \Description
  1092. \var{FileCreate} creates a new file with name \var{FileName} on the disk and
  1093. returns a file handle which can be used to read or write from the file with
  1094. the \seef{FileRead} and \seef{FileWrite} functions.
  1095. If a file with name \var{FileName} already existed on the disk, it is
  1096. overwritten.
  1097. \Errors
  1098. If an error occurs (e.g. disk full or non-existent path), the function
  1099. returns \var{-1}.
  1100. \SeeAlso
  1101. \seep{FileClose}, \seef{FileWrite}, \seef{FileOpen}, \seef{FileRead},
  1102. \seef{FileTruncate}, \seef{FileSeek}
  1103. \end{function}
  1104. \latex{\lstinputlisting{sysutex/ex37.pp}}
  1105. \html{\input{sysutex/ex37.tex}}
  1106. \begin{function}{FileExists}
  1107. \Declaration
  1108. Function FileExists(Const FileName : String) : Boolean;
  1109. \Description
  1110. \var{FileExists} returns \var{True} if a file with name \var{FileName}
  1111. exists on the disk, \var{False} otherwise.
  1112. \Errors
  1113. None.
  1114. \SeeAlso
  1115. \seef{FileAge}, \seef{FileGetAttr}, \seef{FileSetAttr}
  1116. \end{function}
  1117. \latex{\lstinputlisting{sysutex/ex38.pp}}
  1118. \html{\input{sysutex/ex38.tex}}
  1119. \begin{function}{FileGetAttr}
  1120. \Declaration
  1121. Function FileGetAttr(Const FileName : String) : Longint;
  1122. \Description
  1123. \var{FileGetAttr} returns the attribute settings of file
  1124. \var{FileName}. The attribute is a \var{OR}-ed combination
  1125. of the following constants:
  1126. \begin{description}
  1127. \item[faReadOnly] The file is read-only.
  1128. \item[faHidden] The file is hidden. (On \linux, this means that the filename
  1129. starts with a dot)
  1130. \item[faSysFile] The file is a system file (On \linux, this means that the
  1131. file is a character, block or FIFO file).
  1132. \item[faVolumeId] Volume Label. Not possible under \linux.
  1133. \item[faDirectory] File is a directory.
  1134. \item[faArchive] file is an archive. Not possible on \linux.
  1135. \end{description}
  1136. \Errors
  1137. In case of error, -1 is returned.
  1138. \SeeAlso
  1139. \seef{FileSetAttr}, \seef{FileAge}, \seef{FileGetDate}.
  1140. \end{function}
  1141. \latex{\lstinputlisting{sysutex/ex40.pp}}
  1142. \html{\input{sysutex/ex40.tex}}
  1143. \begin{function}{FileGetDate}
  1144. \Declaration
  1145. Function FileGetDate(Handle : Longint) : Longint;
  1146. \Description
  1147. \var{FileGetdate} returns the filetime of the opened file with filehandle
  1148. \var{Handle}. It is the same as \seef{FileAge}, with this difference that
  1149. \var{FileAge} only needs the file name, while \var{FilegetDate} needs an
  1150. open file handle.
  1151. \Errors
  1152. On error, -1 is returned.
  1153. \SeeAlso
  1154. \seef{FileAge}
  1155. \end{function}
  1156. \latex{\lstinputlisting{sysutex/ex39.pp}}
  1157. \html{\input{sysutex/ex39.tex}}
  1158. \begin{function}{FileOpen}
  1159. \Declaration
  1160. Function FileOpen(Const FileName : string; Mode : Integer) : Longint;
  1161. \Description
  1162. \var{FileOpen} opens a file with name \var{FileName} with mode \var{Mode}.
  1163. \var{Mode} can be one of the following constants:
  1164. \begin{description}
  1165. \item[fmOpenRead] The file is opened for reading.
  1166. \item[fmOpenWrite] The file is opened for writing.
  1167. \item[fmOpenReadWrite] The file is opened for reading and writing.
  1168. \end{description}
  1169. If the file has been successfully opened, it can be read from or written to
  1170. (depending on the \var{Mode} parameter) with the \seef{FileRead} and
  1171. \var{FileWrite} functions.
  1172. Remark that you cannot open a file if it doesn't exist yet, i.e. it will not
  1173. be created for you. If you want tp create a new file, or overwrite an old
  1174. one, use the \seef{FileCreate} function.
  1175. \Errors
  1176. On Error, -1 is returned.
  1177. \SeeAlso
  1178. \seep{FileClose}, \seef{FileWrite}, \seef{FileCreate}, \seef{FileRead},
  1179. \seef{FileTruncate}, \seef{FileSeek}
  1180. \end{function}
  1181. For an example, see \seef{FileRead}
  1182. \begin{function}{FileRead}
  1183. \Declaration
  1184. Function FileRead(Handle : Longint; Var Buffer; Count : longint) : Longint;
  1185. \Description
  1186. \var{FileRead} reads \var{Count} bytes from file-handle \var{Handle} and
  1187. stores them into \var{Buffer}. Buffer must be at least \var{Count} bytes
  1188. long. No checking on this is performed, so be careful not to overwrite any
  1189. memory. \var{Handle} must be the result of a \seef{FileOpen} call.
  1190. \Errors
  1191. On error, -1 is returned.
  1192. \SeeAlso
  1193. \seep{FileClose}, \seef{FileWrite}, \seef{FileCreate}, \seef{FileOpen},
  1194. \seef{FileTruncate}, \seef{FileSeek}
  1195. \end{function}
  1196. For an example, see \seef{FileOpen}
  1197. \begin{function}{FileSearch}
  1198. \Declaration
  1199. Function FileSearch(Const Name, DirList : String) : String;
  1200. \Description
  1201. \var{FileSearch} looks for the file \var{Name} in \var{DirList}, where
  1202. dirlist is a list of directories, separated by semicolons or colons.
  1203. It returns the full filename of the first match found.
  1204. \Errors
  1205. On error, an empty string is returned.
  1206. \SeeAlso
  1207. \seef{ExpandFileName}, \seef{FindFirst}
  1208. \end{function}
  1209. \latex{\lstinputlisting{sysutex/ex41.pp}}
  1210. \html{\input{sysutex/ex41.tex}}
  1211. \begin{function}{FileSeek}
  1212. \Declaration
  1213. Function FileSeek(Handle,Offset,Origin : Longint) : Longint;
  1214. \Description
  1215. \var{FileSeek} sets the file pointer on position \var{Offset}, starting from
  1216. \var{Origin}. Origin can be one of the following values:
  1217. \begin{description}
  1218. \item[fsFromBeginning] \var{Offset} is relative to the first byte of the file. This
  1219. position is zero-based. i.e. the first byte is at offset 0.
  1220. \item[fsFromCurrent] \var{Offset} is relative to the current position.
  1221. \item[fsFromEnd] \var{Offset} is relative to the end of the file. This means
  1222. that \var{Offset} can only be zero or negative in this case.
  1223. \end{description}
  1224. If successfull, the function returns the new file position, relative to the
  1225. beginning of the file.
  1226. {\em Remark:} The abovementioned constants do not exist in Delphi.
  1227. \Errors
  1228. On error, -1 is returned.
  1229. \SeeAlso
  1230. \seep{FileClose}, \seef{FileWrite}, \seef{FileCreate}, \seef{FileOpen}
  1231. \seef{FileRead}, \seef{FileTruncate}
  1232. \end{function}
  1233. \latex{\lstinputlisting{sysutex/ex42.pp}}
  1234. \html{\input{sysutex/ex42.tex}}
  1235. For an example, see \seef{FileCreate}
  1236. \begin{functionl}{FileSetAttr (Not on Linux)}{FileSetAttr}
  1237. \Declaration
  1238. Function FileSetAttr(Const Filename : String; Attr: longint) : Longint;
  1239. \Description
  1240. \var{FileSetAttr} sets the attributes of \var{FileName} to \var{Attr}.
  1241. If the function was successful, 0 is returned, -1 otherwise.
  1242. \var{Attr} can be set to an OR-ed combination of the pre-defined
  1243. \var{faXXX} constants.
  1244. \Errors
  1245. On error, -1 is returned (always on linux).
  1246. \SeeAlso
  1247. \seef{FileGetAttr}, \seef{FileGetDate}, \seef{FileSetDate}.
  1248. \end{functionl}
  1249. \begin{functionl}{FileSetDate (Not on Linux)}{FileSetDate}
  1250. \Declaration
  1251. Function FileSetDate(Handle,Age : Longint) : Longint;
  1252. \Description
  1253. \var{FileSetDate} sets the file date of the file with handle \var{Handle}
  1254. to \var{Age}, where \var{Age} is a DOS date-and-time stamp value.
  1255. The function returns zero of successfull.
  1256. \Errors
  1257. On Linux, -1 is always returned, since this is impossible to implement.
  1258. On Windows and DOS, a negative error code is returned.
  1259. \SeeAlso
  1260. \end{functionl}
  1261. \begin{function}{FileTruncate}
  1262. \Declaration
  1263. Function FileTruncate(Handle,Size: Longint) : boolean;
  1264. \Description
  1265. \var{FileTruncate} truncates the file with handle \var{Handle} to
  1266. \var{Size} bytes. The file must have been opened for writing prior
  1267. to this call. The function returns \var{True} is successful, \var{False}
  1268. otherwise.
  1269. \Errors
  1270. On error, the function returns \var{False}.
  1271. \SeeAlso
  1272. \seep{FileClose}, \seef{FileWrite}, \seef{FileCreate}, \seef{FileOpen}
  1273. \seef{FileRead}, \seef{FileSeek}
  1274. \end{function}
  1275. For an example, see \seef{FileCreate}.
  1276. \begin{function}{FileWrite}
  1277. \Declaration
  1278. Function FileWrite(Handle : Longint; Var Buffer; Count : Longint) : Longint;
  1279. \Description
  1280. \var{FileWrite} writes \var{Count} bytes from \var{Buffer} to the file with
  1281. handle \var{Handle}. Prior to this call, the file must have been opened
  1282. for writing. \var{Buffer} must be at least \var{Count} bytes large, or
  1283. a memory access error may occur.
  1284. The function returns the number of bytes written, or -1 in case of an
  1285. error.
  1286. \Errors
  1287. In case of error, -1 is returned.
  1288. \SeeAlso
  1289. \seep{FileClose}, \seef{FileCreate}, \seef{FileOpen}
  1290. \seef{FileRead}, \seef{FileTruncate}, \seef{FileSeek}
  1291. \end{function}
  1292. For an example, see \seef{FileCreate}.
  1293. \begin{procedurel}{FindClose}{FindCloseSys}
  1294. \Declaration
  1295. Procedure FindClose(Var F : TSearchrec);
  1296. \Description
  1297. \var{FindClose} ends a series of \seef{FindFirst}/\seef{FindNext} calls,
  1298. and frees any memory used by these calls. It is {\em absolutely} necessary
  1299. to do this call, or huge memory losses may occur.
  1300. \Errors
  1301. None.
  1302. \SeeAlso
  1303. \seef{FindFirst}, \seef{FindNext}.
  1304. \end{procedurel}
  1305. For an example, see \seef{FindFirst}.
  1306. \begin{function}{FindFirst}
  1307. \Declaration
  1308. Function FindFirst(Const Path : String; Attr : Longint; Var Rslt : TSearchRec) : Longint;
  1309. \Description
  1310. \var{FindFirst} looks for files that match the name (possibly with
  1311. wildcards) in \var{Path} and attributes \var{Attr}. It then fills up the
  1312. \var{Rslt} record with data gathered about the file. It returns 0 if a file
  1313. matching the specified criteria is found, a nonzero value (-1 on linux)
  1314. otherwise.
  1315. The \var{Rslt} record can be fed to subsequent calls to \var{FindNext}, in
  1316. order to find other files matching the specifications.
  1317. {\em remark:} A \var{FindFirst} call must {\em always} be followed by a
  1318. \seepl{FindClose}{FindCloseSys} call with the same \var{Rslt} record. Failure to do so will
  1319. result in memory loss.
  1320. \Errors
  1321. On error the function returns -1 on linux, a nonzero error code on Windows.
  1322. \SeeAlso
  1323. \seep{FindClose}{FindCloseSys}, \seef{FindNext}.
  1324. \end{function}
  1325. \latex{\lstinputlisting{sysutex/ex43.pp}}
  1326. \html{\input{sysutex/ex43.tex}}
  1327. \begin{function}{FindNext}
  1328. \Declaration
  1329. Function FindNext(Var Rslt : TSearchRec) : Longint;
  1330. \Description
  1331. \var{FindNext} finds a next occurrence of a search sequence initiated by
  1332. \var{FindFirst}. If another record matching the criteria in Rslt is found, 0
  1333. is returned, a nonzero constant is returned otherwise.
  1334. {\em remark:} The last \var{FindNext} call must {\em always} be followed by a
  1335. \var{FindClose} call with the same \var{Rslt} record. Failure to do so will
  1336. result in memory loss.
  1337. \Errors
  1338. On error (no more file is found), a nonzero constant is returned.
  1339. \SeeAlso
  1340. \seef{FindFirst}, \seep{FindClose}
  1341. \end{function}
  1342. For an example, see \seef{FindFirst}
  1343. \begin{function}{GetDirs}
  1344. \Declaration
  1345. Function GetDirs(Var DirName : String; Var Dirs : Array of pchar) : Longint;
  1346. \Description
  1347. \var{GetDirs} splits DirName in a null-byte separated list of directory names,
  1348. \var{Dirs} is an array of \var{PChars}, pointing to these directory names.
  1349. The function returns the number of directories found, or -1 if none were found.
  1350. DirName must contain only OSDirSeparator as Directory separator chars.
  1351. \Errors
  1352. None.
  1353. \SeeAlso
  1354. \seef{ExtractRelativePath}
  1355. \end{function}
  1356. \latex{\lstinputlisting{sysutex/ex45.pp}}
  1357. \html{\input{sysutex/ex45.tex}}
  1358. \begin{function}{RenameFile}
  1359. \Declaration
  1360. Function RenameFile(Const OldName, NewName : String) : Boolean;
  1361. \Description
  1362. \var{RenameFile} renames a file from \var{OldName} to \var{NewName}. The
  1363. function returns \var{True} if successful, \var{False} otherwise.
  1364. {\em Remark:} you cannot rename across disks or partitions.
  1365. \Errors
  1366. On Error, \var{False} is returned.
  1367. \SeeAlso
  1368. \seef{DeleteFile}
  1369. \end{function}
  1370. \latex{\lstinputlisting{sysutex/ex44.pp}}
  1371. \html{\input{sysutex/ex44.tex}}
  1372. \begin{function}{SetDirSeparators}
  1373. \Declaration
  1374. Function SetDirSeparators(Const FileName : String) : String;
  1375. \Description
  1376. \var{SetDirSeparators} returns \var{FileName} with all possible
  1377. DirSeparators replaced by \var{OSDirSeparator}.
  1378. \Errors
  1379. None.
  1380. \SeeAlso
  1381. \seef{ExpandFileName}, \seef{ExtractFilePath}, \seef{ExtractFileDir}
  1382. \end{function}
  1383. \latex{\lstinputlisting{sysutex/ex47.pp}}
  1384. \html{\input{sysutex/ex47.tex}}
  1385. \section{PChar functions}
  1386. \subsection{Introduction}
  1387. Most PChar functions are the same as their counterparts in the \file{STRINGS}
  1388. unit. The following functions are the same :
  1389. \begin{enumerate}
  1390. \item \seef{StrCat} : Concatenates two \var{PChar} strings.
  1391. \item \seef{StrComp} : Compares two \var{PChar} strings.
  1392. \item \seef{StrCopy} : Copies a \var{PChar} string.
  1393. \item \seef{StrECopy} : Copies a \var{PChar} string and returns a pointer to
  1394. the terminating null byte.
  1395. \item \seef{StrEnd} : Returns a pointer to the terminating null byte.
  1396. \item \seef{StrIComp} : Case insensitive compare of 2 \var{PChar} strings.
  1397. \item \seef{StrLCat} : Appends at most L characters from one \var{PChar} to
  1398. another \var{PChar}.
  1399. \item \seef{StrLComp} : Case sensitive compare of at most L characters of 2
  1400. \var{PChar} strings.
  1401. \item \seef{StrLCopy} : Copies at most L characters from one \var{PChar} to
  1402. another.
  1403. \item \seef{StrLen} : Returns the length (exclusive terminating null byte)
  1404. of a \var{PChar} string.
  1405. \item \seef{StrLIComp} : Case insensitive compare of at most L characters of 2
  1406. \var{PChar} strings.
  1407. \item \seef{StrLower} : Converts a \var{PChar} to all lowercase letters.
  1408. \item \seef{StrMove} : Moves one \var{PChar} to another.
  1409. \item \seef{StrNew} : Makes a copy of a \var{PChar} on the heap, and returns
  1410. a pointer to this copy.
  1411. \item \seef{StrPos} : Returns the position of one \var{PChar} string in
  1412. another?
  1413. \item \seef{StrRScan} : returns a pointer to the last occurrence of on
  1414. \var{PChar} string in another one.
  1415. \item \seef{StrScan} : returns a pointer to the first occurrence of on
  1416. \var{PChar} string in another one.
  1417. \item \seef{StrUpper} : Converts a \var{PChar} to all uppercase letters.
  1418. \end{enumerate}
  1419. The subsequent functions are different from their counterparts in
  1420. \file{STRINGS}, although the same examples can be used.
  1421. \begin{functionl}{StrAlloc}{StrAllocSys}
  1422. \Declaration
  1423. Function StrAlloc(Size: cardinal): PChar;
  1424. \Description
  1425. \var{StrAlloc} reserves memory on the heap for a string with length \var{Len},
  1426. terminating \var{\#0} included, and returns a pointer to it.
  1427. Additionally, \var{StrAlloc} allocates 4 extra bytes to store the size of
  1428. the allocated memory. Therefore this function is NOT compatible with the
  1429. \seef{StrAlloc} function of the \var{Strings} unit.
  1430. \Errors
  1431. None.
  1432. \SeeAlso
  1433. \seef{StrBufSize}, \seepl{StrDispose}{StrDisposeSys}, \seef{StrAlloc}
  1434. \end{functionl}
  1435. For an example, see \seef{StrBufSize}.
  1436. \begin{function}{StrBufSize}
  1437. \Declaration
  1438. Function StrBufSize(var Str: PChar): cardinal;
  1439. \Description
  1440. \var{StrBufSize} returns the memory allocated for \var{Str}. This function
  1441. ONLY gives the correct result if \var{Str} was allocated using
  1442. \seefl{StrAlloc}{StrAllocSys}.
  1443. \Errors
  1444. If no more memory is available, a runtime error occurs.
  1445. \SeeAlso
  1446. \seefl{StrAlloc}{StrAllocSys}.\seepl{StrDispose}{StrDisposeSys}.
  1447. \end{function}
  1448. \latex{\lstinputlisting{sysutex/ex46.pp}}
  1449. \html{\input{sysutex/ex46.tex}}
  1450. \begin{procedurel}{StrDispose}{StrDisposeSys}
  1451. \Declaration
  1452. Procedure StrDispose(var Str: PChar);
  1453. \Description
  1454. \var{StrDispose} frees any memory allocated for \var{Str}. This function
  1455. will only function correctly if \var{Str} has been allocated using
  1456. \seefl{StrAlloc}{StrAllocSys} from the \file{SYSUTILS} unit.
  1457. \Errors
  1458. If an invalid pointer is passed, or a pointer not allocated with
  1459. \var{StrAlloc}, an error may occur.
  1460. \SeeAlso
  1461. \seef{StrBufSize}, \seefl{StrAlloc}{StrAllocSys}, \seep{StrDispose}
  1462. \end{procedurel}
  1463. For an example, see \seef{StrBufSize}.
  1464. \begin{functionl}{StrPCopy}{StrPCopySys}
  1465. \Declaration
  1466. Function StrPCopy(Dest: PChar; Source: string): PChar;
  1467. \Description
  1468. \var{StrPCopy} Converts the Ansistring in \var{Source} to a Null-terminated
  1469. string, and copies it to \var{Dest}. \var{Dest} needs enough room to contain
  1470. the string \var{Source}, i.e. \var{Length(Source)+1} bytes.
  1471. \Errors
  1472. No checking is performed to see whether \var{Dest} points to enough memory
  1473. to contain \var{Source}.
  1474. \SeeAlso
  1475. \seefl{StrPLCopy}{StrPLCopySys}, \seef{StrPCopy}
  1476. \end{functionl}
  1477. For an example, see \seef{StrPCopy}.
  1478. \begin{functionl}{StrPLCopy}{StrPLCopySys}
  1479. \Declaration
  1480. Function StrPLCopy(Dest: PChar; Source: string; MaxLen: cardinal): PChar;
  1481. \Description
  1482. \var{StrPLCopy} Converts maximally \var{MaxLen} characters of the
  1483. Ansistring in \var{Source} to a Null-terminated string, and copies
  1484. it to \var{Dest}. \var{Dest} needs enough room to contain
  1485. the characters.
  1486. \Errors
  1487. No checking is performed to see whether \var{Dest} points to enough memory
  1488. to contain L characters of \var{Source}.
  1489. \Errors
  1490. \SeeAlso
  1491. \seefl{StrPCopy}{StrPCopySys}.
  1492. \end{functionl}
  1493. \begin{functionl}{StrPas}{StrPasSys}
  1494. \Declaration
  1495. Function StrPas(Str: PChar): string;
  1496. \Description
  1497. Converts a null terminated string in \var{Str} to an Ansitring, and returns
  1498. this string. This string is NOT truncated at 255 characters as is the
  1499. \Errors
  1500. None.
  1501. \SeeAlso
  1502. \seef{StrPas}.
  1503. \end{functionl}
  1504. For an example, see \seef{StrPas}.
  1505. \section{String handling functions}
  1506. \begin{function}{AdjustLineBreaks}
  1507. \Declaration
  1508. Function AdjustLineBreaks(const S: string): string;
  1509. \Description
  1510. \var{AdjustLineBreaks} will change all \var{\#13} characters with
  1511. \var{\#13\#10} on \windowsnt and \dos. On \linux, all \var{\#13\#10}
  1512. character pairs are converted to \var{\#10} and single \var{\#13}
  1513. characters also.
  1514. \Errors
  1515. None.
  1516. \SeeAlso
  1517. \seef{AnsiCompareStr}, \seef{AnsiCompareText}
  1518. \end{function}
  1519. \latex{\lstinputlisting{sysutex/ex48.pp}}
  1520. \html{\input{sysutex/ex48.tex}}
  1521. \begin{function}{AnsiCompareStr}
  1522. \Declaration
  1523. Function AnsiCompareStr(const S1, S2: string): integer;
  1524. \Description
  1525. \var{AnsiCompareStr} compares two strings and returns the following
  1526. result:
  1527. \begin{description}
  1528. \item[<0] if \var{S1<S2}.
  1529. \item[0] if \var{S1=S2}.
  1530. \item[>0] if \var{S1>S2}.
  1531. \end{description}
  1532. the comparision takes into account Ansi characters, i.e. it takes
  1533. care of strange accented characters. Contrary to \seef{AnsiCompareText},
  1534. the comparision is case sensitive.
  1535. \Errors
  1536. None.
  1537. \SeeAlso
  1538. \seef{AdjustLineBreaks}, \seef{AnsiCompareText}
  1539. \end{function}
  1540. \latex{\lstinputlisting{sysutex/ex49.pp}}
  1541. \html{\input{sysutex/ex49.tex}}
  1542. \begin{function}{AnsiCompareText}
  1543. \Declaration
  1544. Function AnsiCompareText(const S1, S2: string): integer;
  1545. \Description
  1546. \Description
  1547. \var{AnsiCompareText} compares two strings and returns the following
  1548. result:
  1549. \begin{description}
  1550. \item[<0] if \var{S1<S2}.
  1551. \item[0] if \var{S1=S2}.
  1552. \item[>0] if \var{S1>S2}.
  1553. \end{description}
  1554. the comparision takes into account Ansi characters, i.e. it takes
  1555. care of strange accented characters. Contrary to \seef{AnsiCompareStr},
  1556. the comparision is case insensitive.
  1557. \Errors
  1558. None.
  1559. \SeeAlso
  1560. \seef{AdjustLineBreaks}, \seef{AnsiCompareText}
  1561. \end{function}
  1562. \latex{\lstinputlisting{sysutex/ex50.pp}}
  1563. \html{\input{sysutex/ex50.tex}}
  1564. \begin{function}{AnsiExtractQuotedStr}
  1565. \Declaration
  1566. Function AnsiExtractQuotedStr(var Src: PChar; Quote: Char): string;
  1567. \Description
  1568. \var{AnsiExtractQuotedStr} Returns \var{Src} as a string,, with \var{Quute}
  1569. characters removed from the beginning and end of the string, and double
  1570. \var{Quote} characters replaced by a single \var{Quote} characters.
  1571. As such, it revereses the action of \seef{AnsiQuotedStr}.
  1572. \Errors
  1573. None.
  1574. \SeeAlso
  1575. \seef{AnsiQuotedStr}
  1576. \end{function}
  1577. \latex{\lstinputlisting{sysutex/ex51.pp}}
  1578. \html{\input{sysutex/ex51.tex}}
  1579. \begin{function}{AnsiLastChar}
  1580. \Declaration
  1581. Function AnsiLastChar(const S: string): PChar;
  1582. \Description
  1583. This function returns a pointer to the last character of \var{S}.
  1584. Since multibyte characters are not yet supported, this is the same
  1585. as \var{@S[Length(S)])}.
  1586. \Errors
  1587. None.
  1588. \SeeAlso
  1589. \seef{AnsiStrLastChar}
  1590. \end{function}
  1591. \latex{\lstinputlisting{sysutex/ex52.pp}}
  1592. \html{\input{sysutex/ex52.tex}}
  1593. \begin{function}{AnsiLowerCase}
  1594. \Declaration
  1595. Function AnsiLowerCase(const s: string): string;
  1596. \Description
  1597. \var{AnsiLowerCase} converts the string \var{S} to lowercase characters
  1598. and returns the resulting string.
  1599. It takes into account the operating system language
  1600. settings when doing this, so spcial characters are converted correctly as
  1601. well.
  1602. {\em Remark} On linux, no language setting is taken in account yet.
  1603. \Errors
  1604. None.
  1605. \SeeAlso
  1606. \seef{AnsiUpperCase}, \seef{AnsiStrLower}, \seef{AnsiStrUpper}
  1607. \end{function}
  1608. \latex{\lstinputlisting{sysutex/ex53.pp}}
  1609. \html{\input{sysutex/ex53.tex}}
  1610. \begin{function}{AnsiQuotedStr}
  1611. \Declaration
  1612. Function AnsiQuotedStr(const S: string; Quote: char): string;
  1613. \Description
  1614. \var{AnsiQuotedString} quotes the string \var{S} and returns the result.
  1615. This means that it puts the \var{Quote} character at both the beginning and
  1616. end of the string and replaces any occurrence of \var{Quote} in \var{S}
  1617. with 2 \var{Quote} characters. The action of \var{AnsiQuotedString} can be
  1618. reversed by \seef{AnsiExtractQuotedStr}.
  1619. \Errors
  1620. None.
  1621. \SeeAlso
  1622. \seef{AnsiExtractQuotedStr}
  1623. \end{function}
  1624. For an example, see \seef{AnsiExtractQuotedStr}
  1625. \begin{function}{AnsiStrComp}
  1626. \Declaration
  1627. Function AnsiStrComp(S1, S2: PChar): integer;
  1628. \Description
  1629. \var{AnsiStrComp} compares 2 \var{PChar} strings, and returns the following
  1630. result:
  1631. \begin{description}
  1632. \item[<0] if \var{S1<S2}.
  1633. \item[0] if \var{S1=S2}.
  1634. \item[>0] if \var{S1>S2}.
  1635. \end{description}
  1636. The comparision of the two strings is case-sensitive.
  1637. The function does not yet take internationalization settings into account.
  1638. \Errors
  1639. None.
  1640. \SeeAlso
  1641. \seef{AnsiCompareText}, \seef{AnsiCompareStr}
  1642. \end{function}
  1643. \latex{\lstinputlisting{sysutex/ex54.pp}}
  1644. \html{\input{sysutex/ex54.tex}}
  1645. \begin{function}{AnsiStrIComp}
  1646. \Declaration
  1647. Function AnsiStrIComp(S1, S2: PChar): integer;
  1648. \Description
  1649. \var{AnsiStrIComp} compares 2 \var{PChar} strings, and returns the following
  1650. result:
  1651. \begin{description}
  1652. \item[<0] if \var{S1<S2}.
  1653. \item[0] if \var{S1=S2}.
  1654. \item[>0] if \var{S1>S2}.
  1655. \end{description}
  1656. The comparision of the two strings is case-insensitive.
  1657. The function does not yet take internationalization settings into account.
  1658. \Errors
  1659. None.
  1660. \SeeAlso
  1661. \seef{AnsiCompareText}, \seef{AnsiCompareStr}
  1662. \end{function}
  1663. \latex{\lstinputlisting{sysutex/ex55.pp}}
  1664. \html{\input{sysutex/ex55.tex}}
  1665. \begin{function}{AnsiStrLastChar}
  1666. \Declaration
  1667. function AnsiStrLastChar(Str: PChar): PChar;
  1668. \Declaration
  1669. \var{AnsiStrLastChar} returns a pointer to the last character of \var{Str}.
  1670. Since multibyte characters are not yet supported, this is the same
  1671. as \var{StrEnd(Str)-1}.
  1672. \Errors
  1673. None.
  1674. \SeeAlso
  1675. \seef{AnsiLastChar}
  1676. \end{function}
  1677. \latex{\lstinputlisting{sysutex/ex58.pp}}
  1678. \html{\input{sysutex/ex58.tex}}
  1679. \begin{function}{AnsiStrLComp}
  1680. \Declaration
  1681. Function AnsiStrLComp(S1, S2: PChar; MaxLen: cardinal): integer;
  1682. \Description
  1683. \var{AnsiStrLComp} compares the first \var{Maxlen} characters of
  1684. 2 \var{PChar} strings, \var{S1} and \var{S2}, and returns the following
  1685. result:
  1686. \begin{description}
  1687. \item[<0] if \var{S1<S2}.
  1688. \item[0] if \var{S1=S2}.
  1689. \item[>0] if \var{S1>S2}.
  1690. \end{description}
  1691. The comparision of the two strings is case-sensitive.
  1692. The function does not yet take internationalization settings into account.
  1693. \Errors
  1694. None.
  1695. \SeeAlso
  1696. \seef{AnsiCompareText}, \seef{AnsiCompareStr}
  1697. \end{function}
  1698. \latex{\lstinputlisting{sysutex/ex56.pp}}
  1699. \html{\input{sysutex/ex56.tex}}
  1700. \begin{function}{AnsiStrLIComp}
  1701. \Declaration
  1702. Function AnsiStrLIComp(S1, S2: PChar; MaxLen: cardinal): integer;
  1703. \Description
  1704. \var{AnsiStrLIComp} compares the first \var{Maxlen} characters of
  1705. 2 \var{PChar} strings, \var{S1} and \var{S2}, and returns the following
  1706. result:
  1707. \begin{description}
  1708. \item[<0] if \var{S1<S2}.
  1709. \item[0] if \var{S1=S2}.
  1710. \item[>0] if \var{S1>S2}.
  1711. \end{description}
  1712. The comparision of the two strings is case-insensitive.
  1713. The function does not yet take internationalization settings into account.
  1714. \Errors
  1715. None.
  1716. \SeeAlso
  1717. \seef{AnsiCompareText}, \seef{AnsiCompareStr}
  1718. \end{function}
  1719. \latex{\lstinputlisting{sysutex/ex57.pp}}
  1720. \html{\input{sysutex/ex57.tex}}
  1721. \begin{function}{AnsiStrLower}
  1722. \Declaration
  1723. Function AnsiStrLower(Str: PChar): PChar;
  1724. \Description
  1725. \var{AnsiStrLower} converts the PChar \var{Str} to lowercase characters
  1726. and returns the resulting pchar. Note that \var{Str} itself is modified,
  1727. not a copy, as in the case of \seef{AnsiLowerCase}.
  1728. It takes into account the operating system language
  1729. settings when doing this, so spcial characters are converted correctly as
  1730. well.
  1731. {\em Remark} On linux, no language setting is taken in account yet.
  1732. \Errors
  1733. None.
  1734. \SeeAlso
  1735. \seef{AnsiStrUpper}, \seef{AnsiLowerCase}
  1736. \end{function}
  1737. \latex{\lstinputlisting{sysutex/ex59.pp}}
  1738. \html{\input{sysutex/ex59.tex}}
  1739. \begin{function}{AnsiStrUpper}
  1740. \Declaration
  1741. Function AnsiStrUpper(Str: PChar): PChar;
  1742. \Description
  1743. \var{AnsiStrUpper} converts the \var{PChar} \var{Str} to uppercase characters
  1744. and returns the resulting string. Note that \var{Str} itself is modified,
  1745. not a copy, as in the case of \seef{AnsiUpperCase}.
  1746. It takes into account the operating system language
  1747. settings when doing this, so spcial characters are converted correctly as
  1748. well.
  1749. {\em Remark} On linux, no language setting is taken in account yet.
  1750. \Errors
  1751. None.
  1752. \SeeAlso
  1753. \seef{AnsiUpperCase}, \seef{AnsiStrLower}, \seef{AnsiLowerCase}
  1754. \end{function}
  1755. \latex{\lstinputlisting{sysutex/ex60.pp}}
  1756. \html{\input{sysutex/ex60.tex}}
  1757. \begin{function}{AnsiUpperCase}
  1758. \Declaration
  1759. Function AnsiUpperCase(const s: string): string;
  1760. \Description
  1761. \var{AnsiUpperCase} converts the string \var{S} to uppercase characters
  1762. and returns the resulting string.
  1763. It takes into account the operating system language
  1764. settings when doing this, so spcial characters are converted correctly as
  1765. well.
  1766. {\em Remark} On linux, no language setting is taken in account yet.
  1767. \Errors
  1768. None.
  1769. \SeeAlso
  1770. \seef{AnsiStrUpper}, \seef{AnsiStrLower}, \seef{AnsiLowerCase}
  1771. \end{function}
  1772. \latex{\lstinputlisting{sysutex/ex61.pp}}
  1773. \html{\input{sysutex/ex61.tex}}
  1774. \begin{procedure}{AppendStr}
  1775. \Declaration
  1776. Procedure AppendStr(var Dest: String; const S: string);
  1777. \Description
  1778. \var{AppendStr} appends \var{S} to Dest.
  1779. This function is provided for Delphi
  1780. compatibility only, since it is completely equivalent to \var{Dest:=Dest+S}.
  1781. \Errors
  1782. None.
  1783. \SeeAlso
  1784. \seep{AssignStr},\seef{NewStr}, \seep{DisposeStr}
  1785. \end{procedure}
  1786. \latex{\lstinputlisting{sysutex/ex62.pp}}
  1787. \html{\input{sysutex/ex62.tex}}
  1788. \begin{procedure}{AssignStr}
  1789. \Declaration
  1790. Procedure AssignStr(var P: PString; const S: string);
  1791. \Description
  1792. \var{AssignStr} allocates \var{S} to P. The old value of \var{P} is
  1793. disposed of.
  1794. This function is provided for Delphi compatibility only. \var{AnsiStrings}
  1795. are managed on the heap and should be preferred to the mechanism of
  1796. dynamically allocated strings.
  1797. \Errors
  1798. None.
  1799. \SeeAlso
  1800. \seef{NewStr}, \seep{AppendStr}, \seep{DisposeStr}
  1801. \end{procedure}
  1802. \latex{\lstinputlisting{sysutex/ex63.pp}}
  1803. \html{\input{sysutex/ex63.tex}}
  1804. \begin{function}{BCDToInt}
  1805. \Declaration
  1806. Function BCDToInt(Value: integer): integer;
  1807. \Description
  1808. \var{BCDToInt} converts a \var{BCD} coded integer to a normal integer.
  1809. \Errors
  1810. None.
  1811. \SeeAlso
  1812. \seef{StrToInt}, \seef{IntToStr}
  1813. \end{function}
  1814. \latex{\lstinputlisting{sysutex/ex64.pp}}
  1815. \html{\input{sysutex/ex64.tex}}
  1816. \begin{function}{CompareMem}
  1817. \Declaration
  1818. Function CompareMem(P1, P2: Pointer; Length: cardinal): integer;
  1819. \Description
  1820. \var{CompareMem} compares, byte by byte, 2 memory areas pointed
  1821. to by \var{P1} and \var{P2}, for a length of \var{L} bytes.
  1822. It returns the following values:
  1823. \begin{description}
  1824. \item[<0] if at some position the byte at \var{P1} is less than the byte at the
  1825. same postion at \var{P2}.
  1826. \item[0] if all \var{L} bytes are the same.
  1827. \item[3]
  1828. \end{description}
  1829. \Errors
  1830. \SeeAlso
  1831. \end{function}
  1832. \begin{function}{CompareStr}
  1833. \Declaration
  1834. Function CompareStr(const S1, S2: string): Integer;
  1835. \Description
  1836. \var{CompareStr} compares two strings, \var{S1} and \var{S2},
  1837. and returns the following
  1838. result:
  1839. \begin{description}
  1840. \item[<0] if \var{S1<S2}.
  1841. \item[0] if \var{S1=S2}.
  1842. \item[>0] if \var{S1>S2}.
  1843. \end{description}
  1844. The comparision of the two strings is case-sensitive.
  1845. The function does not take internationalization settings into account, it
  1846. simply compares ASCII values.
  1847. \Errors
  1848. None.
  1849. \SeeAlso
  1850. \seef{AnsiCompareText}, \seef{AnsiCompareStr}, \seef{CompareText}
  1851. \end{function}
  1852. \latex{\lstinputlisting{sysutex/ex65.pp}}
  1853. \html{\input{sysutex/ex65.tex}}
  1854. \begin{function}{CompareText}
  1855. \Declaration
  1856. Function CompareText(const S1, S2: string): integer;
  1857. \Description
  1858. \var{CompareText} compares two strings, \var{S1} and \var{S2},
  1859. and returns the following
  1860. result:
  1861. \begin{description}
  1862. \item[<0] if \var{S1<S2}.
  1863. \item[0] if \var{S1=S2}.
  1864. \item[>0] if \var{S1>S2}.
  1865. \end{description}
  1866. The comparision of the two strings is case-insensitive.
  1867. The function does not take internationalization settings into account, it
  1868. simply compares ASCII values.
  1869. \Errors
  1870. None.
  1871. \SeeAlso
  1872. \seef{AnsiCompareText}, \seef{AnsiCompareStr}, \seef{CompareStr}
  1873. \end{function}
  1874. \latex{\lstinputlisting{sysutex/ex66.pp}}
  1875. \html{\input{sysutex/ex66.tex}}
  1876. \begin{procedurel}{DisposeStr}{DisposeStrSys}
  1877. \Declaration
  1878. Procedure DisposeStr(S: PString);
  1879. \Description
  1880. \var{DisposeStr} removes the dynamically allocated string \var{S} from the
  1881. heap, and releases the occupied memory.
  1882. This function is provided for Delphi compatibility only. \var{AnsiStrings}
  1883. are managed on the heap and should be preferred to the mechanism of
  1884. dynamically allocated strings.
  1885. \Errors
  1886. None.
  1887. \SeeAlso
  1888. \seef{NewStr}, \seep{AppendStr}, \seep{AssignStr}
  1889. \end{procedurel}
  1890. For an example, see \seep{DisposeStr}.
  1891. \begin{function}{FloatToStr}
  1892. \Declaration
  1893. Function FloatToStr(Value: Extended): String;
  1894. \Description
  1895. \var{FloatToStr} converts the floating point variable \var{Value} to a
  1896. string representation. It will choose the shortest possible notation of the
  1897. two following formats:
  1898. \begin{description}
  1899. \item[Fixed format] will represent the string in fixed notation,
  1900. \item[Decimal format] will represent the string in scientific notation.
  1901. \end{description}
  1902. (more information on these formats can be found in \seef{FloatToStrF})
  1903. \var{FloatToStr} is completely equivalent to a \var{FloatToStrF(Value, ffGeneral,
  1904. 15, 0);} call.
  1905. \Errors
  1906. None.
  1907. \SeeAlso
  1908. \seef{FloatToStrF}
  1909. %, \seef{FormatFloat}
  1910. \end{function}
  1911. \latex{\lstinputlisting{sysutex/ex67.pp}}
  1912. \html{\input{sysutex/ex67.tex}}
  1913. \begin{function}{FloatToStrF}
  1914. \Declaration
  1915. Function FloatToStrF(Value: Extended; format: TFloatFormat; Precision, Digits: Integer): String;
  1916. \Description
  1917. \var{FloatToStrF} converts the floating point number \var{value} to a string
  1918. representation, according to the settings of the parameters \var{Format},
  1919. \var{Precision} and \var{Digits}.
  1920. The meaning of the \var{Precision} and \var{Digits} parameter depends on the
  1921. \var{Format} parameter. The format is controlled mainly by the \var{Format}
  1922. parameter. It can have one of the following values:
  1923. \begin{description}
  1924. \item[ffcurrency] Money format. \var{Value} is converted to a string using
  1925. the global variables \var{CurrencyString}, \var{CurrencyFormat} and
  1926. \var{NegCurrencyFormat}. The \var{Digits} paramater specifies the number of digits
  1927. following the decimal point and should be in the range -1 to 18. If Digits
  1928. equals \var{-1}, \var{CurrencyDecimals} is assumed. The \var{Precision} parameter is ignored.
  1929. %
  1930. \item[ffExponent] Scientific format. \var{Value} is converted to a
  1931. string using scientific notation: 1 digit before the decimal point, possibly
  1932. preceded by a minus sign if \var{Value} is negative. The number of
  1933. digits after the decimal point is controlled by \var{Precision} and must lie
  1934. in the range 0 to 15.
  1935. %
  1936. \item[ffFixed] Fixed point format. \var{Value} is converted to a string
  1937. using fixed point notation. The result is composed of all digits of the
  1938. integer part of \var{Value}, preceded by a minus sign if \var{Value} is
  1939. negative. Following the integer part is \var{DecimalSeparator} and then the
  1940. fractional part of \var{Value}, rounded off to \var{Digits} numbers.
  1941. If the number is too large then the result will be in scientific notation.
  1942. %
  1943. \item[ffGeneral] General number format. The argument is converted to a
  1944. string using \var{ffExponent} or \var{ffFixed} format, depending on wich one
  1945. gives the shortest string. There will be no trailing zeroes. If \var{Value}
  1946. is less than \var{0.00001} or if the number of decimals left of the decimal
  1947. point is larger than \var{Precision} then scientific notation is used, and
  1948. \var{Digits} is the minimum number of digits in the exponent. Otherwise
  1949. \var{Digits} is ignored.
  1950. \item[ffnumber] Is the same as \var{ffFixed}, except that thousand separators
  1951. are inserted in the resultig string.
  1952. \end{description}
  1953. \Errors
  1954. None.
  1955. \SeeAlso
  1956. \seef{FloatToStr}, \seef{FloatToText}
  1957. \end{function}
  1958. \latex{\lstinputlisting{sysutex/ex68.pp}}
  1959. \html{\input{sysutex/ex68.tex}}
  1960. \begin{function}{FloatToText}
  1961. \Declaration
  1962. Function FloatToText(Buffer : Pchar;Value: Extended; Format: TFloatFormat; Precision, Digits: Integer): Longint;
  1963. \Description
  1964. \var{FloatToText} converts the floating point variable \var{Value} to a
  1965. string representation and stores it in \var{Buffer}. The conversion is
  1966. giverned by \var{format}, \var{Precisison} and \var{Digits}.
  1967. more information on these parameters can be found in \seef{FloatToStrF}.
  1968. \var{Buffer} should point to enough space to hold the result. No checking on
  1969. this is performed.
  1970. The result is the number of characters that was copied in \var{Buffer}.
  1971. \Errors
  1972. None.
  1973. \SeeAlso
  1974. \seef{FloatToStr}, \seef{FloatToStrF}
  1975. \end{function}
  1976. \latex{\lstinputlisting{sysutex/ex69.pp}}
  1977. \html{\input{sysutex/ex69.tex}}
  1978. \begin{procedure}{FmtStr}
  1979. \Declaration
  1980. Procedure (Var Res: String; Const Fmt : String; Const args: Array of const);
  1981. \Description
  1982. \var{FmtStr} calls \seef{Format} with \var{Fmt} and \var{Args} as arguments,
  1983. and stores the result in \var{Res}. For more information on how the
  1984. resulting string is composed, see \seef{Format}.
  1985. \Errors
  1986. In case of error, a \var{EConvertError} exception is raised.
  1987. \SeeAlso
  1988. \seef{Format}, \seef{FormatBuf}.
  1989. \end{procedure}
  1990. \latex{\lstinputlisting{sysutex/ex70.pp}}
  1991. \html{\input{sysutex/ex70.tex}}
  1992. \begin{function}{Format}
  1993. \Declaration
  1994. Function Format(Const Fmt : String; const Args : Array of const) : String;
  1995. \Description
  1996. Format replaces all placeholders in\var{Fmt} with the arguments passed in
  1997. \var{Args} and returns the resulting string. A placeholder looks as follows:
  1998. \begin{verbatim}
  1999. '%' [Index':'] ['-'] [Width] ['.' Precision] ArgType
  2000. \end{verbatim}
  2001. elements between single quotes must be typed as shown without the quotes,
  2002. and elements between square brackets \var{[ ]} are optional. The meaning
  2003. of the different elements is shown below:
  2004. \begin{description}
  2005. \item['\%'] starts the placeholder. If you want to insert a literal
  2006. \var{\%} character, then you must insert two of them : \var{\%\%}.
  2007. \item[Index ':'] takes the \var{Index}-th element in the argument array
  2008. as the element to insert.
  2009. \item['-'] tells \var{Format} to left-align the inserted text. The default
  2010. behaviour is to right-align inserted text. This can only take effect if the
  2011. \var{Width} element is also specified.
  2012. \item[Width] the inserted string must have at least have \var{Width}
  2013. characters. If not, the inserted string will be padded with spaces. By
  2014. default, the string is left-padded, resulting in a right-aligned string.
  2015. This behaviour can be changed by the \var{'-'} character.
  2016. \item['.' Precision] Indicates the precision to be used when converting
  2017. the argument. The exact meaning of this parameter depends on \var{ArgType}.
  2018. \end{description}
  2019. The \var{Index}, \var{Width} and \var{Precision} parameters can be replaced
  2020. by \var{*}, in which case their value will be read from the next element in
  2021. the \var{Args} array. This value must be an integer, or an
  2022. \var{EConvertError} exception will be raised.
  2023. The argument type is determined from \var{ArgType}. It can have one of the
  2024. following values (case insensitive):
  2025. \begin{description}
  2026. \item[D] Decimal format. The next argument in the \var{Args} array should be
  2027. an integer. The argument is converted to a decimal string,. If precision is
  2028. specified, then the string will have at least \var{Precision} digits in it.
  2029. If needed, the string is (left) padded with zeroes.
  2030. \item[E] scientific format. The next argument in the \var{Args} array should
  2031. be a Floating point value. The argument is converted to a decimal string
  2032. using scientific notation, using \seef{FloatToStrF}, where the optional
  2033. precision is used to specify the total number of decimals. (defalt a valueof
  2034. 15 is used). The exponent is formatted using maximally 3 digits.
  2035. In short, the \var{E} specifier formats it's arguument as follows:
  2036. \begin{verbatim}
  2037. FloatToStrF(Argument,ffexponent,Precision,3)
  2038. \end{verbatim}
  2039. \item[F] fixed point format. The next argument in the \var{Args} array
  2040. should be a floating point value. The argument is converted to a
  2041. decimal string, using fixed notation (see \seef{FloatToStrF}).
  2042. \var{Precision} indicates the number of digits following the
  2043. decimal point.
  2044. In short, the \var{F} specifier formats it's arguument as follows:
  2045. \begin{verbatim}
  2046. FloatToStrF(Argument,ffFixed,ffixed,9999,Precision)
  2047. \end{verbatim}
  2048. \item[G] General number format. The next argument in the \var{Args} array
  2049. should be a floating point value. The argument is converted to a decimal
  2050. string using fixed point notation or scientific notation, depending on which
  2051. gives the shortest result. \var{Precision} is used to determine the number
  2052. of digits after the decimal point.
  2053. In short, the \var{G} specifier formats it's arguument as follows:
  2054. \begin{verbatim}
  2055. FloatToStrF(Argument,ffGeneral,Precision,3)
  2056. \end{verbatim}
  2057. \item[M] Currency format. the next argument in the var{Args} array must
  2058. be a floating point value. The argument is converted to a decimal string
  2059. using currency notation. This means that fixed-point notation is used, but
  2060. that the currency symbol is appended. If precision is specified, then
  2061. then it overrides the \var{CurrencyDecimals} global variable used in the
  2062. \seef{FloatToStrF}
  2063. In short, the \var{M} specifier formats it's arguument as follows:
  2064. \begin{verbatim}
  2065. FloatToStrF(Argument,ffCurrency,9999,Precision)
  2066. \end{verbatim}
  2067. \item[N] Number format. This is the same as fixed point format, except that
  2068. thousand separators are inserted in the resulting string.
  2069. \item[P] Pointer format. The next argument in the \var{Args} array must be a
  2070. pointer (typed or untyped). The pointer value is converted to a string of
  2071. length 8, representing the hexadecimal value of the pointer.
  2072. \item[S] String format. The next argument in the \var{Args} array must be
  2073. a string. The argument is simply copied to the result string. If
  2074. \var{Precision} is specified, then only \var{Precision} characters are
  2075. copied to the result string.
  2076. \item[X] hexadecimal format. The next argument in the \var{Args} array must
  2077. be an integer. The argument is converted to a hexadecimal string with just
  2078. enough characters to contain the value of the integer. If \var{Precision}
  2079. is specified then the resulting hexadecimal representation will have at
  2080. least \var{Precision} characters in it (with a maximum value of 32).
  2081. \end{description}
  2082. \Errors
  2083. In case of error, an \var{EConversionError} exception is raised. Possible
  2084. errors are:
  2085. \begin{enumerate}
  2086. \item Errors in the format specifiers.
  2087. \item The next argument is not of the type needed by a specifier.
  2088. \item The number of arguments is not sufficient for all format specifiers.
  2089. \end{enumerate}
  2090. \SeeAlso
  2091. \seef{FormatBuf}
  2092. \end{function}
  2093. \latex{\lstinputlisting{sysutex/ex71.pp}}
  2094. \html{\input{sysutex/ex71.tex}}
  2095. \begin{function}{FormatBuf}
  2096. \Declaration
  2097. Function FormatBuf(Var Buffer; BufLen : Cardinal; Const Fmt; fmtLen : Cardinal; Const Args : Array of const) : Cardinal;
  2098. \Description
  2099. \var{Format}
  2100. \Errors
  2101. \SeeAlso
  2102. \end{function}
  2103. \latex{\lstinputlisting{sysutex/ex72.pp}}
  2104. \html{\input{sysutex/ex72.tex}}
  2105. \begin{function}{IntToHex}
  2106. \Declaration
  2107. Function IntToHex(Value: integer; Digits: integer): string;
  2108. \Description
  2109. \var{IntToHex} converts \var{Value} to a hexadecimal string
  2110. representation. The result will contain at least \var{Digits}
  2111. characters. If \var{Digits} is less than the needed number of characters,
  2112. the string will NOT be truncated. If \var{Digits} is larger than the needed
  2113. number of characters, the result is padded with zeroes.
  2114. \Errors
  2115. None.
  2116. \SeeAlso
  2117. \seef{IntToStr}, \var{StrToInt}
  2118. \end{function}
  2119. \latex{\lstinputlisting{sysutex/ex73.pp}}
  2120. \html{\input{sysutex/ex73.tex}}
  2121. \begin{function}{IntToStr}
  2122. \Declaration
  2123. Function IntToStr(Value: integer): string;
  2124. \Description
  2125. \var{IntToStr} coverts \var{Value} to it's string representation.
  2126. The resulting string has only as much characters as needed to represent
  2127. the value. If the value is negative a minus sign is prepended to the
  2128. string.
  2129. \Errors
  2130. None.
  2131. \SeeAlso
  2132. \seef{IntToHex}, \seef{StrToInt}
  2133. \end{function}
  2134. \latex{\lstinputlisting{sysutex/ex74.pp}}
  2135. \html{\input{sysutex/ex74.tex}}
  2136. \begin{function}{IsValidIdent}
  2137. \Declaration
  2138. Function IsValidIdent(const Ident: string): boolean;
  2139. \Description
  2140. \var{IsValidIdent} returns \var{True} if \var{Ident} can be used as a
  2141. compoent name. It returns \var{False} otherwise. \var{Ident} must consist of
  2142. a letter or underscore, followed by a combination of letters, numbers or
  2143. underscores to be a valid identifier.
  2144. \Errors
  2145. None.
  2146. \SeeAlso
  2147. \end{function}
  2148. \latex{\lstinputlisting{sysutex/ex75.pp}}
  2149. \html{\input{sysutex/ex75.tex}}
  2150. \begin{function}{LeftStr}
  2151. \Declaration
  2152. Function LeftStr(const S: string; Count: integer): string;
  2153. \Description
  2154. \var{LeftStr} returns the \var{Count} leftmost characters of \var{S}.
  2155. It is equivalent to a call to \var{Copy(S,1,Count)}.
  2156. \Errors
  2157. None.
  2158. \SeeAlso
  2159. \seef{RightStr}, \seef{TrimLeft}, \seef{TrimRight}, \seef{Trim}
  2160. \end{function}
  2161. \latex{\lstinputlisting{sysutex/ex76.pp}}
  2162. \html{\input{sysutex/ex76.tex}}
  2163. \begin{function}{LoadStr}
  2164. \Declaration
  2165. Function LoadStr(Ident: integer): string;
  2166. \Description
  2167. This function is not yet implemented. resources are not yet supported.
  2168. \Errors
  2169. \SeeAlso
  2170. \end{function}
  2171. \begin{function}{LowerCase}
  2172. \Declaration
  2173. Function LowerCase(const s: string): string;
  2174. \Description
  2175. \var{LowerCase} returns the lowercase equivalent of \var{S}. Ansi characters
  2176. are not taken into account, only ASCII codes below 127 are converted. It is
  2177. completely equivalent to the lowercase function of the system unit, and is
  2178. provided for compatiibility only.
  2179. \Errors
  2180. None.
  2181. \SeeAlso
  2182. \seef{AnsiLowerCase}, \seef{UpperCase}, \seef{AnsiUpperCase}
  2183. \end{function}
  2184. \latex{\lstinputlisting{sysutex/ex77.pp}}
  2185. \html{\input{sysutex/ex77.tex}}
  2186. \begin{functionl}{NewStr}{NewStrSys}
  2187. \Declaration
  2188. Function NewStr(const S: string): PString;
  2189. \Description
  2190. \var{NewStr} assigns a new dynamic string on the heap, copies \var{S} into
  2191. it, and returns a pointer to the newly assigned string.
  2192. This function is obsolete, and shouldn't be used any more. The
  2193. \var{AnsiString} mechanism also allocates ansistrings on the heap, and
  2194. should be preferred over this mechanism.
  2195. \Errors
  2196. If not enough memory is present, an EOutOfMemory exception will be raised.
  2197. \SeeAlso
  2198. \seep{AssignStr}, \seepl{DisposeStr}{DisposeStrSys}
  2199. \end{functionl}
  2200. For an example, see \seep{AssignStr}.
  2201. \begin{function}{QuotedStr}
  2202. \Declaration
  2203. Function QuotedStr(const S: string): string;
  2204. \Description
  2205. \var{QuotedStr} returns the string \var{S}, quoted with single quotes. This means
  2206. that \var{S} is enclosed in single quotes, and every single quote in \var{S}
  2207. is doubled. It is equivalent to a call to \var{AnsiQuotedStr(s, '''')}.
  2208. \Errors
  2209. None.
  2210. \SeeAlso
  2211. \seef{AnsiQuotedStr}, \seef{AnsiExtractQuotedStr}.
  2212. \end{function}
  2213. \latex{\lstinputlisting{sysutex/ex78.pp}}
  2214. \html{\input{sysutex/ex78.tex}}
  2215. \begin{function}{RightStr}
  2216. \Declaration
  2217. Function RightStr(const S: string; Count: integer): string;
  2218. \Description
  2219. \var{RightStr} returns the \var{Count} rightmost characters of \var{S}.
  2220. It is equivalent to a call to \var{Copy(S,Length(S)+1-Count,Count)}.
  2221. If \var{Count} is larger than the actual length of \var{S} only the real
  2222. length will be used.
  2223. \Errors
  2224. None.
  2225. \SeeAlso
  2226. \seef{LeftStr},\seef{Trim}, \seef{TrimLeft}, \seef{TrimRight}
  2227. \end{function}
  2228. \latex{\lstinputlisting{sysutex/ex79.pp}}
  2229. \html{\input{sysutex/ex79.tex}}
  2230. \begin{function}{StrFmt}
  2231. \Declaration
  2232. Function StrFmt(Buffer,Fmt : PChar; Const args: Array of const) : Pchar;
  2233. \Description
  2234. \var{StrFmt} will format \var{fmt} with \var{Args}, as the \seef{Format}
  2235. function does, and it will store the result in \var{Buffer}. The function
  2236. returns \var{Buffer}. \var{Buffer} should point to enough space to contain
  2237. the whole result.
  2238. \Errors
  2239. for a list of errors, see \seef{Format}.
  2240. \SeeAlso
  2241. \seef{StrLFmt}, \seep{FmtStr}, \seef{Format}, \seef{FormatBuf}
  2242. \end{function}
  2243. \latex{\lstinputlisting{sysutex/ex80.pp}}
  2244. \html{\input{sysutex/ex80.tex}}
  2245. \begin{function}{StrLFmt}
  2246. \Declaration
  2247. Function StrLFmt(Buffer : PCHar; Maxlen : Cardinal;Fmt : PChar; Const args: Array of const) : Pchar;
  2248. \Description
  2249. \var{StrLFmt} will format \var{fmt} with \var{Args}, as the \seef{Format}
  2250. function does, and it will store maximally \var{Maxlen characters} of the
  2251. result in \var{Buffer}. The function returns \var{Buffer}. \var{Buffer}
  2252. should point to enough space to contain \var{MaxLen} characters.
  2253. \Errors
  2254. for a list of errors, see \seef{Format}.
  2255. \SeeAlso
  2256. \seef{StrFmt}, \seep{FmtStr}, \seef{Format}, \seef{FormatBuf}
  2257. \end{function}
  2258. \latex{\lstinputlisting{sysutex/ex81.pp}}
  2259. \html{\input{sysutex/ex81.tex}}
  2260. \begin{function}{StrToInt}
  2261. \Declaration
  2262. Function StrToInt(const s: string): integer;
  2263. \Description
  2264. \var{StrToInt} will convert the string \var{S}to an integer.
  2265. If the string contains invalid characters or has an invalid format,
  2266. then an \var{EConvertError} is raised.
  2267. To be successfully converted, a string can contain a combination
  2268. of \var{numerical} characters, possibly preceded by a minus sign (\var{-}).
  2269. Spaces are not allowed.
  2270. \Errors
  2271. In case of error, an \var{EConvertError} is raised.
  2272. \SeeAlso
  2273. \seef{IntToStr}, \seef{StrToIntDef}
  2274. \end{function}
  2275. \latex{\lstinputlisting{sysutex/ex82.pp}}
  2276. \html{\input{sysutex/ex82.tex}}
  2277. \begin{function}{StrToIntDef}
  2278. \Declaration
  2279. Function StrToIntDef(const S: string; Default: integer): integer;
  2280. \Description
  2281. \var{StrToIntDef} will convert a string to an integer. If the string contains
  2282. invalid characters or has an invalid format, then \var{Default} is returned.
  2283. To be successfully converted, a string can contain a combination of
  2284. \var{numerical} characters, possibly preceded by a minus sign (\var{-}).
  2285. Spaces are not allowed.
  2286. \Errors
  2287. None.
  2288. \SeeAlso
  2289. \seef{IntToStr}, \seef{StrToInt}
  2290. \end{function}
  2291. \latex{\lstinputlisting{sysutex/ex83.pp}}
  2292. \html{\input{sysutex/ex83.tex}}
  2293. \begin{function}{Trim}
  2294. \Declaration
  2295. Function Trim(const S: string): string;
  2296. \Description
  2297. \var{Trim} strips blank characters (spaces) at the beginning and end of \var{S}
  2298. and returns the resulting string. Only \var{\#32} characters are stripped.
  2299. If the string contains only spaces, an empty string is returned.
  2300. \Errors
  2301. None.
  2302. \SeeAlso
  2303. \seef{TrimLeft}, \seef{TrimRight}
  2304. \end{function}
  2305. \latex{\lstinputlisting{sysutex/ex84.pp}}
  2306. \html{\input{sysutex/ex84.tex}}
  2307. \begin{function}{TrimLeft}
  2308. \Declaration
  2309. Function TrimLeft(const S: string): string;
  2310. \Description
  2311. \var{TrimLeft} strips blank characters (spaces) at the beginning of \var{S}
  2312. and returns the resulting string. Only \var{\#32} characters are stripped.
  2313. If the string contains only spaces, an empty string is returned.
  2314. \Errors
  2315. None.
  2316. \SeeAlso
  2317. \seef{Trim}, \seef{TrimRight}
  2318. \end{function}
  2319. \latex{\lstinputlisting{sysutex/ex85.pp}}
  2320. \html{\input{sysutex/ex85.tex}}
  2321. \begin{function}{TrimRight}
  2322. \Declaration
  2323. Function TrimRight(const S: string): string;
  2324. \Description
  2325. \var{Trim} strips blank characters (spaces) at the end of \var{S}
  2326. and returns the resulting string. Only \var{\#32} characters are stripped.
  2327. If the string contains only spaces, an empty string is returned.
  2328. \Errors
  2329. None.
  2330. \SeeAlso
  2331. \seef{Trim}, \seef{TrimLeft}
  2332. \end{function}
  2333. \latex{\lstinputlisting{sysutex/ex86.pp}}
  2334. \html{\input{sysutex/ex86.tex}}
  2335. \begin{function}{UpperCase}
  2336. \Declaration
  2337. Function UpperCase(const s: string): string;
  2338. \Description
  2339. \var{UpperCase} returns the uppercase equivalent of \var{S}. Ansi characters
  2340. are not taken into account, only ASCII codes below 127 are converted. It is
  2341. completely equivalent to the \var{UpCase} function of the system unit, and is
  2342. provided for compatiibility only.
  2343. \Errors
  2344. None.
  2345. \SeeAlso
  2346. \seef{AnsiLowerCase}, \seef{LowerCase}, \seef{AnsiUpperCase}
  2347. \Errors
  2348. \SeeAlso
  2349. \end{function}
  2350. \latex{\lstinputlisting{sysutex/ex87.pp}}
  2351. \html{\input{sysutex/ex87.tex}}