% % $Id$ % This file is part of the FPC documentation. % Copyright (C) 1999, by Michael Van Canneyt % % The FPC documentation is free text; you can redistribute it and/or % modify it under the terms of the GNU Library General Public License as % published by the Free Software Foundation; either version 2 of the % License, or (at your option) any later version. % % The FPC Documentation is distributed in the hope that it will be useful, % but WITHOUT ANY WARRANTY; without even the implied warranty of % MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU % Library General Public License for more details. % % You should have received a copy of the GNU Library General Public % License along with the FPC documentation; see the file COPYING.LIB. If not, % write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, % Boston, MA 02111-1307, USA. % \chapter{The SYSUTILS unit.} \FPCexampledir{sysutex} This chapter describes the \file{sysutils} unit. The \file{sysutils} unit was largely written by Gertjan Schouten, and completed by Micha\"el Van Canneyt. It aims to be compatible to the Delphi \file{sysutils} unit, but in contrast with the latter, it is designed to work on multiple platforms. It is implemented on all supported platforms. This chapter starts out with a definition of all types and constants that are defined, followed by an overview of functions grouped by functionality, and lastly the complete explanation of each function. \section{Constants and types} The following general-purpose types are defined: \begin{verbatim} tfilename = string; tsyscharset = set of char; tintegerset = set of 0..sizeof(integer)*8-1; longrec = packed record lo,hi : word; end; wordrec = packed record lo,hi : byte; end; TMethod = packed record Code, Data: Pointer; end; \end{verbatim} The use and meaning of these types should be clear, so no extra information will be provided here. The following general-purpose constants are defined: \begin{verbatim} const SecsPerDay = 24 * 60 * 60; // Seconds and milliseconds per day MSecsPerDay = SecsPerDay * 1000; DateDelta = 693594; // Days between 1/1/0001 and 12/31/1899 Eoln = #10; \end{verbatim} The following types are used frequently in date and time functions. They are the same on all platforms. \begin{verbatim} type TSystemTime = record Year, Month, Day: word; Hour, Minute, Second, MilliSecond: word; end ; TDateTime = double; TTimeStamp = record Time: integer; { Number of milliseconds since midnight } Date: integer; { One plus number of days since 1/1/0001 } end ; \end{verbatim} The following type is used in the \seef{FindFirst},\seef{FindNext} and \seepl{FindClose}{FindCloseSys} functions. The \var{win32} version differs from the other versions. If code is to be portable, that part shouldn't be used. \begin{verbatim} Type THandle = Longint; TSearchRec = Record Time,Size, Attr : Longint; Name : TFileName; ExcludeAttr : Longint; FindHandle : THandle; {$ifdef Win32} FindData : TWin32FindData; {$endif} end; \end{verbatim} The following constants are file-attributes that need to be matched in the findfirst call. \begin{verbatim} Const faReadOnly = $00000001; faHidden = $00000002; faSysFile = $00000004; faVolumeId = $00000008; faDirectory = $00000010; faArchive = $00000020; faAnyFile = $0000003f; \end{verbatim} The following constants can be used in the \seef{FileOpen} call. \begin{verbatim} Const fmOpenRead = $0000; fmOpenWrite = $0001; fmOpenReadWrite = $0002; \end{verbatim} The following constants can be used in the \seef{FileSeek} call. \begin{verbatim} Const fsFromBeginning = 0; fsFromCurrent = 1; fsFromEnd = 2; \end{verbatim} The following variables are used in the case translation routines. \begin{verbatim} type TCaseTranslationTable = array[0..255] of char; var UpperCaseTable: TCaseTranslationTable; LowerCaseTable: TCaseTranslationTable; \end{verbatim} The initialization code of the \file{sysutils} unit fills these tables with the appropriate values. For the win32 and go32v2 versions, this information is obtained from the operating system. The following constants control the formatting of dates. For the Win32 version of the \file{sysutils} unit, these constants are set according to the internationalization settings of Windows by the initialization code of the unit. \begin{verbatim} Const DateSeparator: char = '-'; ShortDateFormat: string = 'd/m/y'; LongDateFormat: string = 'dd" "mmmm" "yyyy'; ShortMonthNames: array[1..12] of string[128] = ('Jan','Feb','Mar','Apr','May','Jun', 'Jul','Aug','Sep','Oct','Nov','Dec'); LongMonthNames: array[1..12] of string[128] = ('January','February','March','April', 'May','June','July','August', 'September','October','November','December'); ShortDayNames: array[1..7] of string[128] = ('Sun','Mon','Tue','Wed','Thu','Fri','Sat'); LongDayNames: array[1..7] of string[128] = ('Sunday','Monday','Tuesday','Wednesday', 'Thursday','Friday','Saturday'); \end{verbatim} The following constants control the formatting of times. For the Win32 version of the \file{sysutils} unit, these constants are set according to the internationalization settings of Windows by the initialization code of the unit. \begin{verbatim} Const ShortTimeFormat: string = 'hh:nn'; LongTimeFormat: string = 'hh:nn:ss'; TimeSeparator: char = ':'; TimeAMString: string[7] = 'AM'; TimePMString: string[7] = 'PM'; \end{verbatim} The following constants control the formatting of currencies and numbers. For the Win32 version of the \file{sysutils} unit, these constants are set according to the internationalization settings of Windows by the initialization code of the unit. \begin{verbatim} Const DecimalSeparator : Char = '.'; ThousandSeparator : Char = ','; CurrencyDecimals : Byte = 2; CurrencyString : String[7] = '$'; { Format to use when formatting currency : 0 = $1 1 = 1$ 2 = $ 1 3 = 1 $ 4 = Currency string replaces decimal indicator. e.g. 1$50 } CurrencyFormat : Byte = 1; { Same as above, only for negative currencies: 0 = ($1) 1 = -$1 2 = $-1 3 = $1- 4 = (1$) 5 = -1$ 6 = 1-$ 7 = 1$- 8 = -1 $ 9 = -$ 1 10 = $ 1- } NegCurrFormat : Byte = 5; \end{verbatim} The following types are used in various string functions. \begin{verbatim} type PString = ^String; TFloatFormat = (ffGeneral, ffExponent, ffFixed, ffNumber, ffCurrency); \end{verbatim} The following constants are used in the file name handling routines. Do not use a slash of backslash character directly as a path separator; instead use the \var{OsDirSeparator} character. \begin{verbatim} Const DirSeparators : set of char = ['/','\']; {$ifdef unix} OSDirSeparator = '/'; {$else} OsDirSeparator = '\'; {$endif} \end{verbatim} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Functions and procedures by category \section{Function list by category} What follows is a listing of the available functions, grouped by category. For each function there is a reference to the page where you can find the function. \subsection{String functions} Functions for handling strings. \begin{funclist} \funcref{AnsiCompareStr}{Compare two strings} \funcref{AnsiCompareText}{Compare two strings, case insensitive} \funcref{AnsiExtractQuotedStr}{Removes quotes from string} \funcref{AnsiLastChar}{Get last character of string} \funcref{AnsiLowerCase}{Convert string to all-lowercase} \funcref{AnsiQuotedStr}{Qoutes a string} \funcref{AnsiStrComp}{Compare strings case-sensitive} \funcref{AnsiStrIComp}{Compare strings case-insensitive} \funcref{AnsiStrLComp}{Compare L characters of strings case sensitive} \funcref{AnsiStrLIComp}{Compare L characters of strings case insensitive} \funcref{AnsiStrLastChar}{Get last character of string} \funcref{AnsiStrLower}{Convert string to all-lowercase} \funcref{AnsiStrUpper}{Convert string to all-uppercase} \funcref{AnsiUpperCase}{Convert string to all-uppercase} \procref{AppendStr}{Append 2 strings} \procref{AssignStr}{Assign value of strings on heap} \funcref{CompareStr}{Compare two strings case sensitive} \funcref{CompareText}{Compare two strings case insensitive} \procrefl{DisposeStr}{DisposeStrSys}{Remove string from heap} \funcref{IsValidIdent}{Is string a valid pascal identifier} \funcref{LastDelimiter}{Last occurance of character in a string} \funcref{LeftStr}{Get first N characters of a string} \funcref{LoadStr}{Load string from resources} \funcref{LowerCase}{Convert string to all-lowercase} \funcrefl{NewStr}{NewStrSys}{Allocate new string on heap} \funcref{RightStr}{Get last N characters of a string} \funcrefl{StrAlloc}{StrAllocSys}{Allocate memory for string} \funcref{StrBufSize}{Reserve memory for a string} \procrefl{StrDispose}{StrDisposeSys}{Remove string from heap} \funcrefl{StrPas}{StrPasSys}{Convert PChar to pascal string} \funcrefl{StrPCopy}{StrPCopySys}{Copy pascal string} \funcrefl{StrPLCopy}{StrPLCopySys}{Copy N bytes of pascal string} \funcref{UpperCase}{Convert string to all-uppercase} \end{funclist} \subsection{Formatting strings} Functions for formatting strings. \begin{funclist} \funcref{AdjustLineBreaks}{Convert line breaks to line breaks for system} \funcref{FormatBuf}{Format a buffer} \funcref{Format}{Format arguments in string} \procref{FmtStr}{Format buffer} \funcref{QuotedStr}{Quote a string} \funcref{StrFmt}{Format arguments in a string} \funcref{StrLFmt}{Format maximum L characters in a string} \funcref{TrimLeft}{Remove whitespace at the left of a string} \funcref{TrimRight}{Remove whitespace at the right of a string} \funcref{Trim}{Remove whitespace at both ends of a string} \end{funclist} \subsection{File input/output routines} Functions for reading/writing to file. \begin{funclist} \funcref{FileCreate}{Create a file and return handle} \funcref{FileOpen}{Open file end return handle} \funcref{FileRead}{Read from file} \funcref{FileSeek}{Set file position} \funcref{FileTruncate}{Truncate file length} \funcref{FileWrite}{Write to file} \procref{FileClose}{Close file handle} \end{funclist} \subsection{File handling routines} Functions for file manipulation. \begin{funclist} \funcref{AddDisk}{Add sisk to list of disk drives} \funcref{ChangeFileExt}{Change extension of file name} \funcref{CreateDir}{Create a directory} \funcref{DeleteFile}{Delete a file} \funcrefl{DiskFree}{DiskFreeSys}{Free space on disk} \funcrefl{DiskSize}{DiskSizeSys}{Total size of disk} \funcref{ExpandFileName}{Create full file name} \funcref{ExpandUNCFileName}{Create full UNC file name} \funcref{ExtractFileDir}{Extract directory part of filename} \funcref{ExtractFileDrive}{Extract drive part of filename} \funcref{ExtractFileExt}{Extract extension part of filename} \funcref{ExtractFileName}{Extract name part of filename} \funcref{ExtractFilePath}{Extrct path part of filename} \funcref{ExtractRelativePath}{Construct relative path between two files} \funcref{FileAge}{Return file age} \funcref{FileDateToDateTime}{Convert file date to system date} \funcref{FileExists}{Determine whether a file exists on disk} \funcref{FileGetAttr}{Get attributes of file} \funcref{FileGetDate}{Get date of last file modification} \funcref{FileSearch}{Search for file in path} \funcrefl{FileSetAttr}{FileSetAttr}{Get file attributes} \funcrefl{FileSetDate}{FileSetDate}{Get file dates} \funcref{FindFirst}{Start finding a file} \funcref{FindNext}{Find next file} \funcref{GetCurrentDir}{Return current working directory} \funcref{RemoveDir}{Remove a directory from disk} \funcref{RenameFile}{Rename a file on disk} \funcref{SetCurrentDir}{Set current working directory} \funcref{SetDirSeparators}{Set directory separator characters} \procrefl{FindClose}{FindCloseSys}{Stop searching a file} \procref{DoDirSeparators}{Replace directory separator characters} \end{funclist} \subsection{Date/time routines} Functions for date and time handling. \begin{funclist} \funcref{DateTimeToFileDate}{Convert DateTime type to file date} \funcref{DateTimeToStr}{Construct string representation of DateTime} \procref{DateTimeToString}{Construct string representation of DateTime} \procref{DateTimeToSystemTime}{Convert DateTime to system time} \funcref{DateTimeToTimeStamp}{Convert DateTime to timestamp} \funcref{DateToStr}{Construct string representation of date} \funcref{Date}{Get current date} \funcref{DayOfWeek}{Get day of week} \procref{DecodeDate}{Decode DateTime to year month and day} \procref{DecodeTime}{Decode DateTime to hours, minutes and seconds} \funcref{EncodeDate}{Encode year, day and month to DateTime} \funcref{EncodeTime}{Encode hours, minutes and seconds to DateTime} \funcref{FormatDateTime}{Return string representation of DateTime} \funcref{IncMonth}{Add 1 to month} \funcref{IsLeapYear}{Determine if year is leap year} \funcref{MSecsToTimeStamp}{Convert nr of milliseconds to timestamp} \funcref{Now}{Get current date and time} \funcref{StrToDateTime}{Convert string to DateTime} \funcref{StrToDate}{Convert string to date} \funcref{StrToTime}{Convert string to time} \funcref{SystemTimeToDateTime}{Convert system time to datetime} \funcref{TimeStampToDateTime}{Convert time stamp to DateTime} \funcref{TimeStampToMSecs}{Convert Timestamp to number of millicseconds} \funcref{TimeToStr}{return string representation of Time} \funcref{Time}{Get current tyme} \end{funclist} \section{Miscellaneous conversion routines} Functions for various conversions. \begin{funclist} \funcref{BCDToInt}{Convert BCD number to integer} \funcref{CompareMem}{Compare two memory regions} \funcref{FloatToStrF}{Convert float to formatted string} \funcref{FloatToStr}{Convert float to string} \funcref{FloatToText}{Convert float to string} \funcref{FormatFloat}{Format a floating point value} \funcref{GetDirs}{Split string in list of directories} \funcref{IntToHex}{return hexadecimal representation of integer} \funcref{IntToStr}{return decumal representation of integer} \funcref{StrToIntDef}{Convert string to integer with default value} \funcref{StrToInt}{Convert string to integer} \funcref{StrToFloat}{Convert string to float} \funcref{TextToFloat}{Convert null-terminated string to float} \end{funclist} \section{Date and time functions} \subsection{Date and time formatting characters} \label{se:formatchars} Various date and time formatting routines accept a format string. to format the date and or time. The following characters can be used to control the date and time formatting: \begin{description} \item[c] : shortdateformat + ' ' + shorttimeformat \item[d] : day of month \item[dd] : day of month (leading zero) \item[ddd] : day of week (abbreviation) \item[dddd] : day of week (full) \item[ddddd] : shortdateformat \item[dddddd] : longdateformat \item[m] : month \item[mm] : month (leading zero) \item[mmm] : month (abbreviation) \item[mmmm] : month (full) \item[y] : year (four digits) \item[yy] : year (two digits) \item[yyyy] : year (with century) \item[h] : hour \item[hh] : hour (leading zero) \item[n] : minute \item[nn] : minute (leading zero) \item[s] : second \item[ss] : second (leading zero) \item[t] : shorttimeformat \item[tt] : longtimeformat \item[am/pm] : use 12 hour clock and display am and pm accordingly \item[a/p] : use 12 hour clock and display a and p accordingly \item[/] : insert date seperator \item[:] : insert time seperator \item["xx"] : literal text \item['xx'] : literal text \end{description} \begin{type}{TDateTime} \Declaration TDateTime = Double; \Description Many functions return or require a \var{TDateTime} type, which contains a date and time in encoded form. The date and time are converted to a double as follows: \begin{itemize} \item The date part is stored in the integer part of the double as the number of days passed since January 1, 1900. \item The time part is stored in the fractional part of the double, as the number of milliseconds passed since midnight (00:00), divided by the total number of milliseconds in a day. \end{itemize} \end{type} \begin{function}{Date} \Declaration Function Date: TDateTime; \Description \var{Date} returns the current date in \var{TDateTime} format. For more information about the \var{TDateTime} type, see \seetype{TDateTime}. \Errors None. \SeeAlso \seef{Time},\seef{Now}, \seetype{TDateTime}. \end{function} \FPCexample{ex1} \begin{function}{DateTimeToFileDate} \Declaration Function DateTimeToFileDate(DateTime : TDateTime) : Longint; \Description \var{DateTimeToFileDate} function converts a date/time indication in \var{TDateTime} format to a filedate function, such as returned for instance by the \seef{FileAge} function. \Errors None. \SeeAlso \seef{Time}, \seef{Date}, \seef{FileDateToDateTime}, \seep{DateTimeToSystemTime}, \seef{DateTimeToTimeStamp} \end{function} \FPCexample{ex2} \begin{function}{DateTimeToStr} \Declaration Function DateTimeToStr(DateTime: TDateTime): string; \Description \var{DateTimeToStr} returns a string representation of \var{DateTime} using the formatting specified in \var{ShortDateTimeFormat}. It corresponds to a call to \var{FormatDateTime('c',DateTime)} (see \sees{formatchars}). \Errors None. \SeeAlso \seef{FormatDateTime}, \seetype{TDateTime}. \end{function} \FPCexample{ex3} \begin{procedure}{DateTimeToString} \Declaration Procedure DateTimeToString(var Result: string; const FormatStr: string; const DateTime: TDateTime); \Description \var{DateTimeToString} returns in \var{Result} a string representation of \var{DateTime} using the formatting specified in \var{FormatStr}. for a list of characters that can be used in the \var{FormatStr} formatting string, see \sees{formatchars}. \Errors In case a wrong formatting character is found, an \var{EConvertError} is raised. \SeeAlso \seef{FormatDateTime}, \sees{formatchars}. \end{procedure} \FPCexample{ex4} \begin{procedure}{DateTimeToSystemTime} \Declaration Procedure DateTimeToSystemTime(DateTime: TDateTime; var SystemTime: TSystemTime); \Description \var{DateTimeToSystemTime} converts a date/time pair in \var{DateTime}, with \var{TDateTime} format to a system time \var{SystemTime}. \Errors None. \SeeAlso \seef{DateTimeToFileDate}, \seef{SystemTimeToDateTime}, \seef{DateTimeToTimeStamp} \end{procedure} \FPCexample{ex5} \begin{function}{DateTimeToTimeStamp} \Declaration Function DateTimeToTimeStamp(DateTime: TDateTime): TTimeStamp; \Description \var{DateTimeToSystemTime} converts a date/time pair in \var{DateTime}, with \var{TDateTime} format to a \var{TTimeStamp} format. \Errors None. \SeeAlso \seef{DateTimeToFileDate}, \seef{SystemTimeToDateTime}, \seep{DateTimeToSystemTime} \end{function} \FPCexample{ex6} \begin{function}{DateToStr} \Declaration Function DateToStr(Date: TDateTime): string; \Description \var{DateToStr} converts \var{Date} to a string representation. It uses \var{ShortDateFormat} as it's formatting string. It is hence completely equivalent to a \var{FormatDateTime('ddddd', Date)}. \Errors None. \SeeAlso \seef{TimeToStr}, \seef{DateTimeToStr}, \seef{FormatDateTime}, \seef{StrToDate} \end{function} \FPCexample{ex7} \begin{function}{DayOfWeek} \Declaration Function DayOfWeek(DateTime: TDateTime): integer; \Description \var{DayOfWeek} returns the day of the week from \var{DateTime}. \var{Sunday} is counted as day 1, \var{Saturday} is counted as day 7. The result of \var{DayOfWeek} can serve as an index to the \var{LongDayNames} constant array, to retrieve the name of the day. \Errors None. \SeeAlso \seef{Date}, \seef{DateToStr} \end{function} \FPCexample{ex8} \begin{procedure}{DecodeDate} \Declaration Procedure DecodeDate(Date: TDateTime; var Year, Month, Day: word); \Description \var{DecodeDate} decodes the Year, Month and Day stored in \var{Date}, and returns them in the \var{Year}, \var{Month} and \var{Day} variables. \Errors None. \SeeAlso \seef{EncodeDate}, \seep{DecodeTime}. \end{procedure} \FPCexample{ex9} \begin{procedure}{DecodeTime} \Declaration Procedure DecodeTime(Time: TDateTime; var Hour, Minute, Second, MilliSecond: word); \Description \var{DecodeDate} decodes the hours, minutes, second and milliseconds stored in \var{Time}, and returns them in the \var{Hour}, \var{Minute} and \var{Second} and \var{MilliSecond} variables. \Errors None. \SeeAlso \seef{EncodeTime}, \seep{DecodeDate}. \end{procedure} \FPCexample{ex10} \begin{function}{EncodeDate} \Declaration Function EncodeDate(Year, Month, Day :word): TDateTime; \Description \var{EncodeDate} encodes the \var{Year}, \var{Month} and \var{Day} variables to a date in \var{TDateTime} format. It does the opposite of the \seep{DecodeDate} procedure. The parameters must lie withing valid ranges (boundaries included): \begin{description} \item[Year] must be between 1 and 9999. \item[Month] must be within the range 1-12. \item[Day] msut be between 1 and 31. \end{description} \Errors In case one of the parameters is out of it's valid range, 0 is returned. \SeeAlso \seef{EncodeTime}, \seep{DecodeDate}. \end{function} \FPCexample{ex11} \begin{function}{EncodeTime} \Declaration Function EncodeTime(Hour, Minute, Second, MilliSecond:word): TDateTime; \Description \var{EncodeTime} encodes the \var{Hour}, \var{Minute}, \var{Second}, \var{MilliSecond} variables to a \var{TDateTime} format result. It does the opposite of the \seep{DecodeTime} procedure. The parameters must have a valid range (boundaries included): \begin{description} \item[Hour] must be between 0 and 23. \item[Minute,second] must both be between 0 and 59. \item[Millisecond] must be between 0 and 999. \end{description} \Errors In case one of the parameters is outside of it's valid range, 0 is returned. \SeeAlso \seef{EncodeDate}, \seep{DecodeTime}. \end{function} \FPCexample{ex12} \begin{function}{FileDateToDateTime} \Declaration Function FileDateToDateTime(Filedate : Longint) : TDateTime; \Description \var{FileDateToDateTime} converts the date/time encoded in \var{filedate} to a \var{TDateTime} encoded form. It can be used to convert date/time values returned by the \seef{FileAge} or \seef{FindFirst}/\seef{FindNext} functions to \var{TDateTime} form. \Errors None. \SeeAlso \seef{DateTimeToFileDate} \end{function} \FPCexample{ex13} \begin{function}{FormatDateTime} \Declaration Function FormatDateTime(FormatStr: string; DateTime: TDateTime):string; \Description \var{FormatDateTime} formats the date and time encoded in \var{DateTime} according to the formatting given in \var{FormatStr}. The complete list of formatting characters can be found in \sees{formatchars}. \Errors On error (such as an invalid character in the formatting string), and \var{EConvertError} exception is raised. \SeeAlso \seef{DateTimeToStr}, \seef{DateToStr}, \seef{TimeToStr}, \seef{StrToDateTime} \end{function} \FPCexample{ex14} \begin{function}{IncMonth} \Declaration Function IncMonth(const DateTime: TDateTime; NumberOfMonths: integer): TDateTime; \Description \var{IncMonth} increases the month number in \var{DateTime} with \var{NumberOfMonths}. It wraps the result as to get a month between 1 and 12, and updates the year accordingly. \var{NumberOfMonths} can be negative, and can be larger than 12 (in absolute value). \Errors None. \SeeAlso \seef{Date}, \seef{Time}, \seef{Now} \end{function} \FPCexample{ex15} \begin{function}{IsLeapYear} \Declaration Function IsLeapYear(Year: Word): boolean; \Description \var{IsLeapYear} returns \var{True} if \var{Year} is a leap year, \var{False} otherwise. \Errors None. \SeeAlso \seef{IncMonth}, \seef{Date} \end{function} \FPCexample{ex16} \begin{function}{MSecsToTimeStamp} \Declaration Function MSecsToTimeStamp(MSecs: Comp): TTimeStamp; \Description \var{MSecsTiTimeStamp} converts the given number of milliseconds to a \var{TTimeStamp} date/time notation. Use \var{TTimeStamp} variables if you need to keep very precise track of time. \Errors None. \SeeAlso \seef{TimeStampToMSecs}, \seef{DateTimeToTimeStamp}, \end{function} \FPCexample{ex17} \begin{function}{Now} \Declaration Function Now: TDateTime; \Description \var{Now} returns the current date and time. It is equivalent to \var{Date+Time}. \Errors None. \SeeAlso \seef{Date}, \seef{Time} \end{function} \FPCexample{ex18} \begin{function}{StrToDate} \Declaration Function StrToDate(const S: string): TDateTime; \Description \var{StrToDate} converts the string \var{S} to a \var{TDateTime} date value. The Date must consist of 1 to three digits, separated by the \var{DateSeparator} character. If two numbers are given, they are supposed to form the day and month of the current year. If only one number is given, it is supposed to represent the day of the current month. (This is \em{not} supported in Delphi) The order of the digits (y/m/d, m/d/y, d/m/y) is determined from the \var{ShortDateFormat} variable. \Errors On error (e.g. an invalid date or invalid character), an \var{EConvertError} exception is raised. \SeeAlso \seef{StrToTime}, \seef{DateToStr}n \seef{TimeToStr}. \end{function} \FPCexample{ex19} \begin{function}{StrToDateTime} \Declaration Function StrToDateTime(const S: string): TDateTime; \Description \var{StrToDateTime} converts the string \var{S} to a \var{TDateTime} date and time value. The Date must consist of 1 to three digits, separated by the \var{DateSeparator} character. If two numbers are given, they are supposed to form the day and month of the current year. If only one number is given, it is supposed to represent the day of the current month. (This is \em{not} supported in Delphi) The order of the digits (y/m/d, m/d/y, d/m/y) is determined from the \var{ShortDateFormat} variable. \Errors On error (e.g. an invalid date or invalid character), an \var{EConvertError} exception is raised. \SeeAlso \seef{StrToDate}, \seef{StrToTime}, \seef{DateTimeToStr} \end{function} \FPCexample{ex20} \begin{function}{StrToTime} \Declaration Function StrToTime(const S: string): TDateTime; \Description \var{StrToTime} converts the string \var{S} to a \var{TDateTime} time value. The time must consist of 1 to 4 digits, separated by the \var{TimeSeparator} character. If two numbers are given, they are supposed to form the hour and minutes. \Errors On error (e.g. an invalid date or invalid character), an \var{EConvertError} exception is raised. \SeeAlso \seef{StrToDate}, \seef{StrToDateTime}, \seef{TimeToStr} \end{function} \FPCexample{ex21} \begin{function}{SystemTimeToDateTime} \Declaration Function SystemTimeToDateTime(const SystemTime: TSystemTime): TDateTime; \Description \var{SystemTimeToDateTime} converts a \var{TSystemTime} record to a \var{TDateTime} style date/time indication. \Errors None. \SeeAlso \seep{DateTimeToSystemTime} \end{function} \FPCexample{ex22} \begin{function}{Time} \Declaration Function Time: TDateTime; \Description \var{Time} returns the current time in \var{TDateTime} format. The date part of the \var{TDateTimeValue} is set to zero. \Errors None. \SeeAlso \seef{Now}, \seef{Date} \end{function} \FPCexample{ex23} \begin{function}{TimeStampToDateTime} \Declaration Function TimeStampToDateTime(const TimeStamp: TTimeStamp): TDateTime; \Description \var{TimeStampToDateTime} converts \var{TimeStamp} to a \var{TDateTime} format variable. It is the inverse operation of \seef{DateTimeToTimeStamp}. \Errors None. \SeeAlso \seef{DateTimeToTimeStamp}, \seef{TimeStampToMSecs} \end{function} \FPCexample{ex24} \begin{function}{TimeStampToMSecs} \Declaration Function TimeStampToMSecs(const TimeStamp: TTimeStamp): comp; \Description \var{TimeStampToMSecs} converts {TimeStamp} to the number of seconds since \var{1/1/0001}. Use \var{TTimeStamp} variables if you need to keep very precise track of time. \Errors None. \SeeAlso \seef{MSecsToTimeStamp}, \seef{TimeStampToDateTime} \end{function} For an example, see \seef{MSecsToTimeStamp}. \begin{function}{TimeToStr} \Declaration Function TimeToStr(Time: TDateTime): string; \Description \var{TimeToStr} converts the time in \var{Time} to a string. It uses the \var{ShortTimeFormat} variable to see what formatting needs to be applied. It is therefor entirely equivalent to a \var{FormatDateTime('t',Time)} call. \Errors None. \SeeAlso \end{function} \FPCexample{ex25} \section{Disk functions} \begin{functionl}{AddDisk (Linux only)}{AddDisk} \Declaration Function AddDisk (Const PAth : String) : Longint; \Description On Linux both the \seef{DiskFree} and \seef{DiskSize} functions need a file on the specified drive, since is required for the statfs system call. These filenames are set in drivestr[0..26], and the first 4 have been preset to : \begin{description} \item[Disk 0] \var{'.'} default drive - hence current directory is used. \item[Disk 1] \var{'/fd0/.'} floppy drive 1. \item[Disk 2] \var{'/fd1/.'} floppy drive 2. \item[Disk 3] \var{'/'} \file{C:} equivalent of DOS is the root partition. \end{description} Drives 4..26 can be set by your own applications with the \var{AddDisk} call. The \var{AddDisk} call adds \var{Path} to the names of drive files, and returns the number of the disk that corresponds to this drive. If you add more than 21 drives, the count is wrapped to 4. \Errors None. \SeeAlso \seefl{DiskFree}{DiskFreeSys}, \seefl{DiskSize}{DiskSizeSys} \end{functionl} \begin{function}{CreateDir} \Declaration Function CreateDir(Const NewDir : String) : Boolean; \Description \var{CreateDir} creates a new directory with name \var{NewDir}. If the directory doesn't contain an absolute path, then the directory is created below the current working directory. The function returns \var{True} if the directory was successfully created, \var{False} otherwise. \Errors In case of an error, the function returns \var{False}. \SeeAlso \seef{RemoveDir} \end{function} \FPCexample{ex26} \begin{functionl}{DiskFree}{DiskFreeSys} \Declaration Function DiskFree(Drive : Byte) : Int64; \Description \var{DiskFree} returns the free space (in bytes) on disk \var{Drive}. Drive is the number of the disk drive: \begin{description} \item[0] for the current drive. \item[1] for the first floppy drive. \item[2] for the second floppy drive. \item[3] for the first hard-disk parttion. \item[4-26] for all other drives and partitions. \end{description} {\em Remark} Under \linux, and Unix in general, the concept of disk is different than the \dos one, since the filesystem is seen as one big directory tree. For this reason, the \var{DiskFree} and \seef{DiskSize} functions must be mimicked using filenames that reside on the partitions. For more information, see \seef{AddDisk} \Errors On error, \var{-1} is returned. \SeeAlso \seefl{DiskSize}{DiskSizeSys}, \seef{AddDisk} \end{functionl} \FPCexample{ex27} \begin{functionl}{DiskSize}{DiskSizeSys} \Declaration Function DiskSize(Drive : Byte) : Int64; \Description \var{DiskSize} returns the size (in bytes) of disk \var{Drive}. Drive is the number of the disk drive: \begin{description} \item[0] for the current drive. \item[1] for the first floppy drive. \item[2] for the second floppy drive. \item[3] for the first hard-disk parttion. \item[4-26] for all other drives and partitions. \end{description} {\em Remark} Under \linux, and Unix in general, the concept of disk is different than the \dos one, since the filesystem is seen as one big directory tree. For this reason, the \seef{DiskFree} and \var{DiskSize} functions must be mimicked using filenames that reside on the partitions. For more information, see \seef{AddDisk} \Errors On error, \var{-1} is returned. \SeeAlso \seefl{DiskFree}{DiskFreeSys}, \seef{AddDisk} \end{functionl} For an example, see \seefl{DiskFree}{DiskFreeSys}. \begin{function}{GetCurrentDir} \Declaration Function GetCurrentDir : String; \Description \var{GetCurrentDir} returns the current working directory. \Errors None. \SeeAlso \seef{SetCurrentDir}, \seef{DiskFree}, \seef{DiskSize} \end{function} \FPCexample{ex28} \begin{function}{RemoveDir} \Declaration Function RemoveDir(Const Dir : String) : Boolean; \Description \var{RemoveDir} removes directory \var{Dir} from the disk. If the directory is not absolue, it is appended to the current working directory. \Errors In case of error (e.g. the directory isn't empty) the function returns \var{False}. If successful, \var{True} is returned. \SeeAlso \end{function} For an example, see \seef{CreateDir}. \begin{function}{SetCurrentDir} \Declaration Function SetCurrentDir(Const NewDir : String) : Boolean; \Description \var{SetCurrentDir} sets the current working directory of your program to \var{NewDir}. It returns \var{True} if the function was successfull, \var{False} otherwise. \Errors In case of error, \var{False} is returned. \SeeAlso \seef{GetCurrentDir} \end{function} \FPCexample{ex29} \section{File handling functions} \begin{function}{ChangeFileExt} \Declaration Function ChangeFileExt(const FileName, Extension: string): string; \Description \var{ChangeFileExt} changes the file extension in \var{FileName} to \var{Extension}. The extension \var{Extension} includes the starting \var{.} (dot). The previous extension of \var{FileName} are all characters after the last \var{.}, the \var{.} character included. If \var{FileName} doesn't have an extension, \var{Extension} is just appended. \Errors None. \SeeAlso \seef{ExtractFileName}, \seef{ExtractFilePath}, \seef{ExpandFileName} \end{function} \begin{function}{DeleteFile} \Declaration Function DeleteFile(Const FileName : String) : Boolean; \Description \var{DeleteFile} deletes file \var{FileName} from disk. The function returns \var{True} if the file was successfully removed, \var{False} otherwise. \Errors On error, \var{False} is returned. \SeeAlso \seef{FileCreate}, \seef{FileExists} \end{function} \FPCexample{ex31} \begin{procedure}{DoDirSeparators} \Declaration Procedure DoDirSeparators(Var FileName : String); \Description This function replaces all directory separators \var{'\\' and '/'} to the directory separator character for the current system. \Errors None. \SeeAlso \seef{ExtractFileName}, \seef{ExtractFilePath} \end{procedure} \FPCexample{ex32} \begin{function}{ExpandFileName} \Declaration Function ExpandFileName(Const FileName : string): String; \Description \var{ExpandFileName} expands the filename to an absolute filename. It changes all directory separator characters to the one appropriate for the system first. \Errors None. \SeeAlso \seef{ExtractFileName}, \seef{ExtractFilePath}, \seef{ExtractFileDir}, \seef{ExtractFileDrive}, \seef{ExtractFileExt}, \seef{ExtractRelativePath} \end{function} \FPCexample{ex33} \begin{function}{ExpandUNCFileName} \Declaration Function ExpandUNCFileName(Const FileName : string): String; \Description \var{ExpandUNCFileName} runs \seef{ExpandFileName} on \var{FileName} and then attempts to replace the driveletter by the name of a shared disk. \Errors None. \SeeAlso \seef{ExtractFileName}, \seef{ExtractFilePath}, \seef{ExtractFileDir}, \seef{ExtractFileDrive}, \seef{ExtractFileExt}, \seef{ExtractRelativePath} \end{function} \begin{function}{ExtractFileDir} \Declaration Function ExtractFileDir(Const FileName : string): string; \Description \var{ExtractFileDir} returns only the directory part of \var{FileName}, not including a driveletter. The directory name has NO ending directory separator, in difference with \seef{ExtractFilePath}. \Errors None. \SeeAlso \seef{ExtractFileName}, \seef{ExtractFilePath}, \seef{ExtractFileDir}, \seef{ExtractFileDrive}, \seef{ExtractFileExt}, \seef{ExtractRelativePath} \end{function} \FPCexample{ex34} \begin{function}{ExtractFileDrive} \Declaration Function ExtractFileDrive(const FileName: string): string; \Description \var{Extract} \Errors \SeeAlso \seef{ExtractFileName}, \seef{ExtractFilePath}, \seef{ExtractFileDir}, \seef{ExtractFileDrive}, \seef{ExtractFileExt}, \seef{ExtractRelativePath} \end{function} For an example, see \seef{ExtractFileDir}. \begin{function}{ExtractFileExt} \Declaration Function ExtractFileExt(const FileName: string): string; \Description \var{ExtractFileExt} returns the extension (including the \var{.}(dot) character) of \var{FileName}. \Errors None. \SeeAlso \seef{ExtractFileName}, \seef{ExtractFilePath}, \seef{ExtractFileDir}, \seef{ExtractFileDrive}, \seef{ExtractFileExt}, \seef{ExtractRelativePath} \end{function} For an example, see \seef{ExtractFileDir}. \begin{function}{ExtractFileName} \Declaration Function ExtractFileName(const FileName: string): string; \Description \var{ExtractFileName} returns the filename part from \var{FileName}. The filename consists of all characters after the last directory separator character ('/' or '\') or drive letter. The full filename can always be reconstucted by concatenating the result of \seef{ExtractFilePath} and \var{ExtractFileName}. \Errors None. \SeeAlso \seef{ExtractFileName}, \seef{ExtractFilePath}, \seef{ExtractFileDir}, \seef{ExtractFileDrive}, \seef{ExtractFileExt},\seef{ExtractRelativePath} \end{function} For an example, see \seef{ExtractFileDir}. \begin{function}{ExtractFilePath} \Declaration Function ExtractFilePath(const FileName: string): string; \Description \var{ExtractFilePath} returns the path part (including driveletter) from \var{FileName}. The path consists of all characters before the last directory separator character ('/' or '\'), including the directory separator itself. In case there is only a drive letter, that will be returned. The full filename can always be reconstucted by concatenating the result of \var{ExtractFilePath} and \seef{ExtractFileName}. \Errors None. \SeeAlso \seef{ExtractFileName}, \seef{ExtractFilePath}, \seef{ExtractFileDir}, \seef{ExtractFileDrive}, \seef{ExtractFileExt}, \seef{ExtractRelativePath} \end{function} For an example, see \seef{ExtractFileDir}. \begin{function}{ExtractRelativePath} \Declaration Function ExtractRelativePath(Const BaseName,DestNAme : String): String; \Description \var{ExtractRelativePath} constructs a relative path to go from \var{BaseName} to \var{DestName}. If \var{DestName} is on another drive (Not on Linux) then the whole \var{Destname} is returned. {\em Note:} This function does not exist in the Delphi unit. \Errors None. \SeeAlso \seef{ExtractFileName}, \seef{ExtractFilePath}, \seef{ExtractFileDir}, \seef{ExtractFileDrive}, \seef{ExtractFileExt}, \end{function} \FPCexample{ex35} \begin{function}{FileAge} \Declaration Function FileAge(Const FileName : String): Longint; \Description \var{FileAge} returns the last modification time of file \var{FileName}. The FileDate format can be transformed to \var{TDateTime} format with the \seef{FileDateToDateTime} function. \Errors In case of errors, \var{-1} is returned. \SeeAlso \seef{FileDateToDateTime}, \seef{FileExists}, \seef{FileGetAttr} \end{function} \FPCexample{ex36} \begin{procedure}{FileClose} \Declaration Procedure FileClose(Handle : Longint); \Description \var{FileClose} closes the file handle \var{Handle}. After this call, attempting to read or write from the handle will result in an error. \Errors None. \SeeAlso \seef{FileCreate}, \seef{FileWrite}, \seef{FileOpen}, \seef{FileRead}, \seef{FileTruncate}, \seef{FileSeek} \end{procedure} For an example, see \seef{FileCreate} \begin{function}{FileCreate} \Declaration Function FileCreate(Const FileName : String) : Longint; \Description \var{FileCreate} creates a new file with name \var{FileName} on the disk and returns a file handle which can be used to read or write from the file with the \seef{FileRead} and \seef{FileWrite} functions. If a file with name \var{FileName} already existed on the disk, it is overwritten. \Errors If an error occurs (e.g. disk full or non-existent path), the function returns \var{-1}. \SeeAlso \seep{FileClose}, \seef{FileWrite}, \seef{FileOpen}, \seef{FileRead}, \seef{FileTruncate}, \seef{FileSeek} \end{function} \FPCexample{ex37} \begin{function}{FileExists} \Declaration Function FileExists(Const FileName : String) : Boolean; \Description \var{FileExists} returns \var{True} if a file with name \var{FileName} exists on the disk, \var{False} otherwise. \Errors None. \SeeAlso \seef{FileAge}, \seef{FileGetAttr}, \seef{FileSetAttr} \end{function} \FPCexample{ex38} \begin{function}{FileGetAttr} \Declaration Function FileGetAttr(Const FileName : String) : Longint; \Description \var{FileGetAttr} returns the attribute settings of file \var{FileName}. The attribute is a \var{OR}-ed combination of the following constants: \begin{description} \item[faReadOnly] The file is read-only. \item[faHidden] The file is hidden. (On \linux, this means that the filename starts with a dot) \item[faSysFile] The file is a system file (On \linux, this means that the file is a character, block or FIFO file). \item[faVolumeId] Volume Label. Not possible under \linux. \item[faDirectory] File is a directory. \item[faArchive] file is an archive. Not possible on \linux. \end{description} \Errors In case of error, -1 is returned. \SeeAlso \seef{FileSetAttr}, \seef{FileAge}, \seef{FileGetDate}. \end{function} \FPCexample{ex40} \begin{function}{FileGetDate} \Declaration Function FileGetDate(Handle : Longint) : Longint; \Description \var{FileGetdate} returns the filetime of the opened file with filehandle \var{Handle}. It is the same as \seef{FileAge}, with this difference that \var{FileAge} only needs the file name, while \var{FilegetDate} needs an open file handle. \Errors On error, -1 is returned. \SeeAlso \seef{FileAge} \end{function} \FPCexample{ex39} \begin{function}{FileOpen} \Declaration Function FileOpen(Const FileName : string; Mode : Integer) : Longint; \Description \var{FileOpen} opens a file with name \var{FileName} with mode \var{Mode}. \var{Mode} can be one of the following constants: \begin{description} \item[fmOpenRead] The file is opened for reading. \item[fmOpenWrite] The file is opened for writing. \item[fmOpenReadWrite] The file is opened for reading and writing. \end{description} If the file has been successfully opened, it can be read from or written to (depending on the \var{Mode} parameter) with the \seef{FileRead} and \var{FileWrite} functions. Remark that you cannot open a file if it doesn't exist yet, i.e. it will not be created for you. If you want tp create a new file, or overwrite an old one, use the \seef{FileCreate} function. \Errors On Error, -1 is returned. \SeeAlso \seep{FileClose}, \seef{FileWrite}, \seef{FileCreate}, \seef{FileRead}, \seef{FileTruncate}, \seef{FileSeek} \end{function} For an example, see \seef{FileOpen} \begin{function}{FileRead} \Declaration Function FileRead(Handle : Longint; Var Buffer; Count : longint) : Longint; \Description \var{FileRead} reads \var{Count} bytes from file-handle \var{Handle} and stores them into \var{Buffer}. Buffer must be at least \var{Count} bytes long. No checking on this is performed, so be careful not to overwrite any memory. \var{Handle} must be the result of a \seef{FileOpen} call. \Errors On error, -1 is returned. \SeeAlso \seep{FileClose}, \seef{FileWrite}, \seef{FileCreate}, \seef{FileOpen}, \seef{FileTruncate}, \seef{FileSeek} \end{function} For an example, see \seef{FileCreate} \begin{function}{FileSearch} \Declaration Function FileSearch(Const Name, DirList : String) : String; \Description \var{FileSearch} looks for the file \var{Name} in \var{DirList}, where dirlist is a list of directories, separated by semicolons or colons. It returns the full filename of the first match found. \Errors On error, an empty string is returned. \SeeAlso \seef{ExpandFileName}, \seef{FindFirst} \end{function} \FPCexample{ex41} \begin{function}{FileSeek} \Declaration Function FileSeek(Handle,Offset,Origin : Longint) : Longint; \Description \var{FileSeek} sets the file pointer on position \var{Offset}, starting from \var{Origin}. Origin can be one of the following values: \begin{description} \item[fsFromBeginning] \var{Offset} is relative to the first byte of the file. This position is zero-based. i.e. the first byte is at offset 0. \item[fsFromCurrent] \var{Offset} is relative to the current position. \item[fsFromEnd] \var{Offset} is relative to the end of the file. This means that \var{Offset} can only be zero or negative in this case. \end{description} If successfull, the function returns the new file position, relative to the beginning of the file. {\em Remark:} The abovementioned constants do not exist in Delphi. \Errors On error, -1 is returned. \SeeAlso \seep{FileClose}, \seef{FileWrite}, \seef{FileCreate}, \seef{FileOpen} \seef{FileRead}, \seef{FileTruncate} \end{function} \FPCexample{ex42} For an example, see \seef{FileCreate} \begin{functionl}{FileSetAttr (Not on Linux)}{FileSetAttr} \Declaration Function FileSetAttr(Const Filename : String; Attr: longint) : Longint; \Description \var{FileSetAttr} sets the attributes of \var{FileName} to \var{Attr}. If the function was successful, 0 is returned, -1 otherwise. \var{Attr} can be set to an OR-ed combination of the pre-defined \var{faXXX} constants. \Errors On error, -1 is returned (always on linux). \SeeAlso \seef{FileGetAttr}, \seef{FileGetDate}, \seef{FileSetDate}. \end{functionl} \begin{functionl}{FileSetDate (Not on Linux)}{FileSetDate} \Declaration Function FileSetDate(Handle,Age : Longint) : Longint; \Description \var{FileSetDate} sets the file date of the file with handle \var{Handle} to \var{Age}, where \var{Age} is a DOS date-and-time stamp value. The function returns zero of successfull. \Errors On Linux, -1 is always returned, since this is impossible to implement. On Windows and DOS, a negative error code is returned. \SeeAlso \end{functionl} \begin{function}{FileTruncate} \Declaration Function FileTruncate(Handle,Size: Longint) : boolean; \Description \var{FileTruncate} truncates the file with handle \var{Handle} to \var{Size} bytes. The file must have been opened for writing prior to this call. The function returns \var{True} is successful, \var{False} otherwise. \Errors On error, the function returns \var{False}. \SeeAlso \seep{FileClose}, \seef{FileWrite}, \seef{FileCreate}, \seef{FileOpen} \seef{FileRead}, \seef{FileSeek} \end{function} For an example, see \seef{FileCreate}. \begin{function}{FileWrite} \Declaration Function FileWrite(Handle : Longint; Var Buffer; Count : Longint) : Longint; \Description \var{FileWrite} writes \var{Count} bytes from \var{Buffer} to the file with handle \var{Handle}. Prior to this call, the file must have been opened for writing. \var{Buffer} must be at least \var{Count} bytes large, or a memory access error may occur. The function returns the number of bytes written, or -1 in case of an error. \Errors In case of error, -1 is returned. \SeeAlso \seep{FileClose}, \seef{FileCreate}, \seef{FileOpen} \seef{FileRead}, \seef{FileTruncate}, \seef{FileSeek} \end{function} For an example, see \seef{FileCreate}. \begin{procedurel}{FindClose}{FindCloseSys} \Declaration Procedure FindClose(Var F : TSearchrec); \Description \var{FindClose} ends a series of \seef{FindFirst}/\seef{FindNext} calls, and frees any memory used by these calls. It is {\em absolutely} necessary to do this call, or huge memory losses may occur. \Errors None. \SeeAlso \seef{FindFirst}, \seef{FindNext}. \end{procedurel} For an example, see \seef{FindFirst}. \begin{function}{FindFirst} \Declaration Function FindFirst(Const Path : String; Attr : Longint; Var Rslt : TSearchRec) : Longint; \Description \var{FindFirst} looks for files that match the name (possibly with wildcards) in \var{Path} and attributes \var{Attr}. It then fills up the \var{Rslt} record with data gathered about the file. It returns 0 if a file matching the specified criteria is found, a nonzero value (-1 on linux) otherwise. The \var{Rslt} record can be fed to subsequent calls to \var{FindNext}, in order to find other files matching the specifications. {\em remark:} A \var{FindFirst} call must {\em always} be followed by a \seepl{FindClose}{FindCloseSys} call with the same \var{Rslt} record. Failure to do so will result in memory loss. \Errors On error the function returns -1 on linux, a nonzero error code on Windows. \SeeAlso \seep{FindClose}{FindCloseSys}, \seef{FindNext}. \end{function} \FPCexample{ex43} \begin{function}{FindNext} \Declaration Function FindNext(Var Rslt : TSearchRec) : Longint; \Description \var{FindNext} finds a next occurrence of a search sequence initiated by \var{FindFirst}. If another record matching the criteria in Rslt is found, 0 is returned, a nonzero constant is returned otherwise. {\em remark:} The last \var{FindNext} call must {\em always} be followed by a \var{FindClose} call with the same \var{Rslt} record. Failure to do so will result in memory loss. \Errors On error (no more file is found), a nonzero constant is returned. \SeeAlso \seef{FindFirst}, \seep{FindClose} \end{function} For an example, see \seef{FindFirst} \begin{function}{GetDirs} \Declaration Function GetDirs(Var DirName : String; Var Dirs : Array of pchar) : Longint; \Description \var{GetDirs} splits DirName in a null-byte separated list of directory names, \var{Dirs} is an array of \var{PChars}, pointing to these directory names. The function returns the number of directories found, or -1 if none were found. DirName must contain only OSDirSeparator as Directory separator chars. \Errors None. \SeeAlso \seef{ExtractRelativePath} \end{function} \FPCexample{ex45} \begin{function}{RenameFile} \Declaration Function RenameFile(Const OldName, NewName : String) : Boolean; \Description \var{RenameFile} renames a file from \var{OldName} to \var{NewName}. The function returns \var{True} if successful, \var{False} otherwise. {\em Remark:} you cannot rename across disks or partitions. \Errors On Error, \var{False} is returned. \SeeAlso \seef{DeleteFile} \end{function} \FPCexample{ex44} \begin{function}{SetDirSeparators} \Declaration Function SetDirSeparators(Const FileName : String) : String; \Description \var{SetDirSeparators} returns \var{FileName} with all possible DirSeparators replaced by \var{OSDirSeparator}. \Errors None. \SeeAlso \seef{ExpandFileName}, \seef{ExtractFilePath}, \seef{ExtractFileDir} \end{function} \FPCexample{ex47} \section{PChar functions} \subsection{Introduction} Most PChar functions are the same as their counterparts in the \file{STRINGS} unit. The following functions are the same : \begin{enumerate} \item \seef{StrCat} : Concatenates two \var{PChar} strings. \item \seef{StrComp} : Compares two \var{PChar} strings. \item \seef{StrCopy} : Copies a \var{PChar} string. \item \seef{StrECopy} : Copies a \var{PChar} string and returns a pointer to the terminating null byte. \item \seef{StrEnd} : Returns a pointer to the terminating null byte. \item \seef{StrIComp} : Case insensitive compare of 2 \var{PChar} strings. \item \seef{StrLCat} : Appends at most L characters from one \var{PChar} to another \var{PChar}. \item \seef{StrLComp} : Case sensitive compare of at most L characters of 2 \var{PChar} strings. \item \seef{StrLCopy} : Copies at most L characters from one \var{PChar} to another. \item \seef{StrLen} : Returns the length (exclusive terminating null byte) of a \var{PChar} string. \item \seef{StrLIComp} : Case insensitive compare of at most L characters of 2 \var{PChar} strings. \item \seef{StrLower} : Converts a \var{PChar} to all lowercase letters. \item \seef{StrMove} : Moves one \var{PChar} to another. \item \seef{StrNew} : Makes a copy of a \var{PChar} on the heap, and returns a pointer to this copy. \item \seef{StrPos} : Returns the position of one \var{PChar} string in another? \item \seef{StrRScan} : returns a pointer to the last occurrence of on \var{PChar} string in another one. \item \seef{StrScan} : returns a pointer to the first occurrence of on \var{PChar} string in another one. \item \seef{StrUpper} : Converts a \var{PChar} to all uppercase letters. \end{enumerate} The subsequent functions are different from their counterparts in \file{STRINGS}, although the same examples can be used. \begin{functionl}{StrAlloc}{StrAllocSys} \Declaration Function StrAlloc(Size: cardinal): PChar; \Description \var{StrAlloc} reserves memory on the heap for a string with length \var{Len}, terminating \var{\#0} included, and returns a pointer to it. Additionally, \var{StrAlloc} allocates 4 extra bytes to store the size of the allocated memory. Therefore this function is NOT compatible with the \seef{StrAlloc} function of the \var{Strings} unit. \Errors None. \SeeAlso \seef{StrBufSize}, \seepl{StrDispose}{StrDisposeSys}, \seef{StrAlloc} \end{functionl} For an example, see \seef{StrBufSize}. \begin{function}{StrBufSize} \Declaration Function StrBufSize(var Str: PChar): cardinal; \Description \var{StrBufSize} returns the memory allocated for \var{Str}. This function ONLY gives the correct result if \var{Str} was allocated using \seefl{StrAlloc}{StrAllocSys}. \Errors If no more memory is available, a runtime error occurs. \SeeAlso \seefl{StrAlloc}{StrAllocSys}.\seepl{StrDispose}{StrDisposeSys}. \end{function} \FPCexample{ex46} \begin{procedurel}{StrDispose}{StrDisposeSys} \Declaration Procedure StrDispose(var Str: PChar); \Description \var{StrDispose} frees any memory allocated for \var{Str}. This function will only function correctly if \var{Str} has been allocated using \seefl{StrAlloc}{StrAllocSys} from the \file{SYSUTILS} unit. \Errors If an invalid pointer is passed, or a pointer not allocated with \var{StrAlloc}, an error may occur. \SeeAlso \seef{StrBufSize}, \seefl{StrAlloc}{StrAllocSys}, \seep{StrDispose} \end{procedurel} For an example, see \seef{StrBufSize}. \begin{functionl}{StrPCopy}{StrPCopySys} \Declaration Function StrPCopy(Dest: PChar; Source: string): PChar; \Description \var{StrPCopy} Converts the Ansistring in \var{Source} to a Null-terminated string, and copies it to \var{Dest}. \var{Dest} needs enough room to contain the string \var{Source}, i.e. \var{Length(Source)+1} bytes. \Errors No checking is performed to see whether \var{Dest} points to enough memory to contain \var{Source}. \SeeAlso \seefl{StrPLCopy}{StrPLCopySys}, \seef{StrPCopy} \end{functionl} For an example, see \seef{StrPCopy}. \begin{functionl}{StrPLCopy}{StrPLCopySys} \Declaration Function StrPLCopy(Dest: PChar; Source: string; MaxLen: cardinal): PChar; \Description \var{StrPLCopy} Converts maximally \var{MaxLen} characters of the Ansistring in \var{Source} to a Null-terminated string, and copies it to \var{Dest}. \var{Dest} needs enough room to contain the characters. \Errors No checking is performed to see whether \var{Dest} points to enough memory to contain L characters of \var{Source}. \Errors \SeeAlso \seefl{StrPCopy}{StrPCopySys}. \end{functionl} \begin{functionl}{StrPas}{StrPasSys} \Declaration Function StrPas(Str: PChar): string; \Description Converts a null terminated string in \var{Str} to an Ansitring, and returns this string. This string is NOT truncated at 255 characters as is the \Errors None. \SeeAlso \seef{StrPas}. \end{functionl} For an example, see \seef{StrPas}. \section{String handling functions} \begin{function}{AdjustLineBreaks} \Declaration Function AdjustLineBreaks(const S: string): string; \Description \var{AdjustLineBreaks} will change all \var{\#13} characters with \var{\#13\#10} on \windowsnt and \dos. On \linux, all \var{\#13\#10} character pairs are converted to \var{\#10} and single \var{\#13} characters also. \Errors None. \SeeAlso \seef{AnsiCompareStr}, \seef{AnsiCompareText} \end{function} \FPCexample{ex48} \begin{function}{AnsiCompareStr} \Declaration Function AnsiCompareStr(const S1, S2: string): integer; \Description \var{AnsiCompareStr} compares two strings and returns the following result: \begin{description} \item[<0] if \var{S10] if \var{S1>S2}. \end{description} the comparision takes into account Ansi characters, i.e. it takes care of strange accented characters. Contrary to \seef{AnsiCompareText}, the comparision is case sensitive. \Errors None. \SeeAlso \seef{AdjustLineBreaks}, \seef{AnsiCompareText} \end{function} \FPCexample{ex49} \begin{function}{AnsiCompareText} \Declaration Function AnsiCompareText(const S1, S2: string): integer; \Description \Description \var{AnsiCompareText} compares two strings and returns the following result: \begin{description} \item[<0] if \var{S10] if \var{S1>S2}. \end{description} the comparision takes into account Ansi characters, i.e. it takes care of strange accented characters. Contrary to \seef{AnsiCompareStr}, the comparision is case insensitive. \Errors None. \SeeAlso \seef{AdjustLineBreaks}, \seef{AnsiCompareText} \end{function} \FPCexample{ex50} \begin{function}{AnsiExtractQuotedStr} \Declaration Function AnsiExtractQuotedStr(var Src: PChar; Quote: Char): string; \Description \var{AnsiExtractQuotedStr} Returns \var{Src} as a string, with \var{Quote} characters removed from the beginning and end of the string, and double \var{Quote} characters replaced by a single \var{Quote} characters. As such, it revereses the action of \seef{AnsiQuotedStr}. \Errors None. \SeeAlso \seef{AnsiQuotedStr} \end{function} \FPCexample{ex51} \begin{function}{AnsiLastChar} \Declaration Function AnsiLastChar(const S: string): PChar; \Description This function returns a pointer to the last character of \var{S}. Since multibyte characters are not yet supported, this is the same as \var{@S[Length(S)])}. \Errors None. \SeeAlso \seef{AnsiStrLastChar} \end{function} \FPCexample{ex52} \begin{function}{AnsiLowerCase} \Declaration Function AnsiLowerCase(const s: string): string; \Description \var{AnsiLowerCase} converts the string \var{S} to lowercase characters and returns the resulting string. It takes into account the operating system language settings when doing this, so spcial characters are converted correctly as well. {\em Remark} On linux, no language setting is taken in account yet. \Errors None. \SeeAlso \seef{AnsiUpperCase}, \seef{AnsiStrLower}, \seef{AnsiStrUpper} \end{function} \FPCexample{ex53} \begin{function}{AnsiQuotedStr} \Declaration Function AnsiQuotedStr(const S: string; Quote: char): string; \Description \var{AnsiQuotedString} quotes the string \var{S} and returns the result. This means that it puts the \var{Quote} character at both the beginning and end of the string and replaces any occurrence of \var{Quote} in \var{S} with 2 \var{Quote} characters. The action of \var{AnsiQuotedString} can be reversed by \seef{AnsiExtractQuotedStr}. \Errors None. \SeeAlso \seef{AnsiExtractQuotedStr} \end{function} For an example, see \seef{AnsiExtractQuotedStr} \begin{function}{AnsiStrComp} \Declaration Function AnsiStrComp(S1, S2: PChar): integer; \Description \var{AnsiStrComp} compares 2 \var{PChar} strings, and returns the following result: \begin{description} \item[<0] if \var{S10] if \var{S1>S2}. \end{description} The comparision of the two strings is case-sensitive. The function does not yet take internationalization settings into account. \Errors None. \SeeAlso \seef{AnsiCompareText}, \seef{AnsiCompareStr} \end{function} \FPCexample{ex54} \begin{function}{AnsiStrIComp} \Declaration Function AnsiStrIComp(S1, S2: PChar): integer; \Description \var{AnsiStrIComp} compares 2 \var{PChar} strings, and returns the following result: \begin{description} \item[<0] if \var{S10] if \var{S1>S2}. \end{description} The comparision of the two strings is case-insensitive. The function does not yet take internationalization settings into account. \Errors None. \SeeAlso \seef{AnsiCompareText}, \seef{AnsiCompareStr} \end{function} \FPCexample{ex55} \begin{function}{AnsiStrLastChar} \Declaration function AnsiStrLastChar(Str: PChar): PChar; \Declaration \var{AnsiStrLastChar} returns a pointer to the last character of \var{Str}. Since multibyte characters are not yet supported, this is the same as \var{StrEnd(Str)-1}. \Errors None. \SeeAlso \seef{AnsiLastChar} \end{function} \FPCexample{ex58} \begin{function}{AnsiStrLComp} \Declaration Function AnsiStrLComp(S1, S2: PChar; MaxLen: cardinal): integer; \Description \var{AnsiStrLComp} compares the first \var{Maxlen} characters of 2 \var{PChar} strings, \var{S1} and \var{S2}, and returns the following result: \begin{description} \item[<0] if \var{S10] if \var{S1>S2}. \end{description} The comparision of the two strings is case-sensitive. The function does not yet take internationalization settings into account. \Errors None. \SeeAlso \seef{AnsiCompareText}, \seef{AnsiCompareStr} \end{function} \FPCexample{ex56} \begin{function}{AnsiStrLIComp} \Declaration Function AnsiStrLIComp(S1, S2: PChar; MaxLen: cardinal): integer; \Description \var{AnsiStrLIComp} compares the first \var{Maxlen} characters of 2 \var{PChar} strings, \var{S1} and \var{S2}, and returns the following result: \begin{description} \item[<0] if \var{S10] if \var{S1>S2}. \end{description} The comparision of the two strings is case-insensitive. The function does not yet take internationalization settings into account. \Errors None. \SeeAlso \seef{AnsiCompareText}, \seef{AnsiCompareStr} \end{function} \FPCexample{ex57} \begin{function}{AnsiStrLower} \Declaration Function AnsiStrLower(Str: PChar): PChar; \Description \var{AnsiStrLower} converts the PChar \var{Str} to lowercase characters and returns the resulting pchar. Note that \var{Str} itself is modified, not a copy, as in the case of \seef{AnsiLowerCase}. It takes into account the operating system language settings when doing this, so spcial characters are converted correctly as well. {\em Remark} On linux, no language setting is taken in account yet. \Errors None. \SeeAlso \seef{AnsiStrUpper}, \seef{AnsiLowerCase} \end{function} \FPCexample{ex59} \begin{function}{AnsiStrUpper} \Declaration Function AnsiStrUpper(Str: PChar): PChar; \Description \var{AnsiStrUpper} converts the \var{PChar} \var{Str} to uppercase characters and returns the resulting string. Note that \var{Str} itself is modified, not a copy, as in the case of \seef{AnsiUpperCase}. It takes into account the operating system language settings when doing this, so spcial characters are converted correctly as well. {\em Remark} On linux, no language setting is taken in account yet. \Errors None. \SeeAlso \seef{AnsiUpperCase}, \seef{AnsiStrLower}, \seef{AnsiLowerCase} \end{function} \FPCexample{ex60} \begin{function}{AnsiUpperCase} \Declaration Function AnsiUpperCase(const s: string): string; \Description \var{AnsiUpperCase} converts the string \var{S} to uppercase characters and returns the resulting string. It takes into account the operating system language settings when doing this, so spcial characters are converted correctly as well. {\em Remark} On linux, no language setting is taken in account yet. \Errors None. \SeeAlso \seef{AnsiStrUpper}, \seef{AnsiStrLower}, \seef{AnsiLowerCase} \end{function} \FPCexample{ex61} \begin{procedure}{AppendStr} \Declaration Procedure AppendStr(var Dest: String; const S: string); \Description \var{AppendStr} appends \var{S} to Dest. This function is provided for Delphi compatibility only, since it is completely equivalent to \var{Dest:=Dest+S}. \Errors None. \SeeAlso \seep{AssignStr},\seef{NewStr}, \seep{DisposeStr} \end{procedure} \FPCexample{ex62} \begin{procedure}{AssignStr} \Declaration Procedure AssignStr(var P: PString; const S: string); \Description \var{AssignStr} allocates \var{S} to P. The old value of \var{P} is disposed of. This function is provided for Delphi compatibility only. \var{AnsiStrings} are managed on the heap and should be preferred to the mechanism of dynamically allocated strings. \Errors None. \SeeAlso \seef{NewStr}, \seep{AppendStr}, \seep{DisposeStr} \end{procedure} \FPCexample{ex63} \begin{function}{BCDToInt} \Declaration Function BCDToInt(Value: integer): integer; \Description \var{BCDToInt} converts a \var{BCD} coded integer to a normal integer. \Errors None. \SeeAlso \seef{StrToInt}, \seef{IntToStr} \end{function} \FPCexample{ex64} \begin{function}{CompareMem} \Declaration Function CompareMem(P1, P2: Pointer; Length: cardinal): integer; \Description \var{CompareMem} compares, byte by byte, 2 memory areas pointed to by \var{P1} and \var{P2}, for a length of \var{L} bytes. It returns the following values: \begin{description} \item[<0] if at some position the byte at \var{P1} is less than the byte at the same postion at \var{P2}. \item[0] if all \var{L} bytes are the same. \item[3] \end{description} \Errors \SeeAlso \end{function} \begin{function}{CompareStr} \Declaration Function CompareStr(const S1, S2: string): Integer; \Description \var{CompareStr} compares two strings, \var{S1} and \var{S2}, and returns the following result: \begin{description} \item[<0] if \var{S10] if \var{S1>S2}. \end{description} The comparision of the two strings is case-sensitive. The function does not take internationalization settings into account, it simply compares ASCII values. \Errors None. \SeeAlso \seef{AnsiCompareText}, \seef{AnsiCompareStr}, \seef{CompareText} \end{function} \FPCexample{ex65} \begin{function}{CompareText} \Declaration Function CompareText(const S1, S2: string): integer; \Description \var{CompareText} compares two strings, \var{S1} and \var{S2}, and returns the following result: \begin{description} \item[<0] if \var{S10] if \var{S1>S2}. \end{description} The comparision of the two strings is case-insensitive. The function does not take internationalization settings into account, it simply compares ASCII values. \Errors None. \SeeAlso \seef{AnsiCompareText}, \seef{AnsiCompareStr}, \seef{CompareStr} \end{function} \FPCexample{ex66} \begin{procedurel}{DisposeStr}{DisposeStrSys} \Declaration Procedure DisposeStr(S: PString); \Description \var{DisposeStr} removes the dynamically allocated string \var{S} from the heap, and releases the occupied memory. This function is provided for Delphi compatibility only. \var{AnsiStrings} are managed on the heap and should be preferred to the mechanism of dynamically allocated strings. \Errors None. \SeeAlso \seef{NewStr}, \seep{AppendStr}, \seep{AssignStr} \end{procedurel} For an example, see \seep{DisposeStr}. \begin{function}{FloatToStr} \Declaration Function FloatToStr(Value: Extended): String; \Description \var{FloatToStr} converts the floating point variable \var{Value} to a string representation. It will choose the shortest possible notation of the two following formats: \begin{description} \item[Fixed format] will represent the string in fixed notation, \item[Decimal format] will represent the string in scientific notation. \end{description} (more information on these formats can be found in \seef{FloatToStrF}) \var{FloatToStr} is completely equivalent to a \var{FloatToStrF(Value, ffGeneral, 15, 0);} call. \Errors None. \SeeAlso \seef{FloatToStrF}, \seef{FormatFloat}, \seef{StrToFloat} \end{function} \FPCexample{ex67} \begin{function}{FloatToStrF} \Declaration Function FloatToStrF(Value: Extended; format: TFloatFormat; Precision, Digits: Integer): String; \Description \var{FloatToStrF} converts the floating point number \var{value} to a string representation, according to the settings of the parameters \var{Format}, \var{Precision} and \var{Digits}. The meaning of the \var{Precision} and \var{Digits} parameter depends on the \var{Format} parameter. The format is controlled mainly by the \var{Format} parameter. It can have one of the following values: \begin{description} \item[ffcurrency] Money format. \var{Value} is converted to a string using the global variables \var{CurrencyString}, \var{CurrencyFormat} and \var{NegCurrencyFormat}. The \var{Digits} paramater specifies the number of digits following the decimal point and should be in the range -1 to 18. If Digits equals \var{-1}, \var{CurrencyDecimals} is assumed. The \var{Precision} parameter is ignored. % \item[ffExponent] Scientific format. \var{Value} is converted to a string using scientific notation: 1 digit before the decimal point, possibly preceded by a minus sign if \var{Value} is negative. The number of digits after the decimal point is controlled by \var{Precision} and must lie in the range 0 to 15. % \item[ffFixed] Fixed point format. \var{Value} is converted to a string using fixed point notation. The result is composed of all digits of the integer part of \var{Value}, preceded by a minus sign if \var{Value} is negative. Following the integer part is \var{DecimalSeparator} and then the fractional part of \var{Value}, rounded off to \var{Digits} numbers. If the number is too large then the result will be in scientific notation. % \item[ffGeneral] General number format. The argument is converted to a string using \var{ffExponent} or \var{ffFixed} format, depending on wich one gives the shortest string. There will be no trailing zeroes. If \var{Value} is less than \var{0.00001} or if the number of decimals left of the decimal point is larger than \var{Precision} then scientific notation is used, and \var{Digits} is the minimum number of digits in the exponent. Otherwise \var{Digits} is ignored. \item[ffnumber] Is the same as \var{ffFixed}, except that thousand separators are inserted in the resultig string. \end{description} \Errors None. \SeeAlso \seef{FloatToStr}, \seef{FloatToText} \end{function} \FPCexample{ex68} \begin{function}{FloatToText} \Declaration Function FloatToText(Buffer : Pchar;Value: Extended; Format: TFloatFormat; Precision, Digits: Integer): Longint; \Description \var{FloatToText} converts the floating point variable \var{Value} to a string representation and stores it in \var{Buffer}. The conversion is giverned by \var{format}, \var{Precisison} and \var{Digits}. more information on these parameters can be found in \seef{FloatToStrF}. \var{Buffer} should point to enough space to hold the result. No checking on this is performed. The result is the number of characters that was copied in \var{Buffer}. \Errors None. \SeeAlso \seef{FloatToStr}, \seef{FloatToStrF} \end{function} \FPCexample{ex69} \begin{procedure}{FmtStr} \Declaration Procedure (Var Res: String; Const Fmt : String; Const args: Array of const); \Description \var{FmtStr} calls \seef{Format} with \var{Fmt} and \var{Args} as arguments, and stores the result in \var{Res}. For more information on how the resulting string is composed, see \seef{Format}. \Errors In case of error, a \var{EConvertError} exception is raised. \SeeAlso \seef{Format}, \seef{FormatBuf}. \end{procedure} \FPCexample{ex70} \begin{function}{Format} \Declaration Function Format(Const Fmt : String; const Args : Array of const) : String; \Description Format replaces all placeholders in\var{Fmt} with the arguments passed in \var{Args} and returns the resulting string. A placeholder looks as follows: \begin{verbatim} '%' [Index':'] ['-'] [Width] ['.' Precision] ArgType \end{verbatim} elements between single quotes must be typed as shown without the quotes, and elements between square brackets \var{[ ]} are optional. The meaning of the different elements is shown below: \begin{description} \item['\%'] starts the placeholder. If you want to insert a literal \var{\%} character, then you must insert two of them : \var{\%\%}. \item[Index ':'] takes the \var{Index}-th element in the argument array as the element to insert. \item['-'] tells \var{Format} to left-align the inserted text. The default behaviour is to right-align inserted text. This can only take effect if the \var{Width} element is also specified. \item[Width] the inserted string must have at least have \var{Width} characters. If not, the inserted string will be padded with spaces. By default, the string is left-padded, resulting in a right-aligned string. This behaviour can be changed by the \var{'-'} character. \item['.' Precision] Indicates the precision to be used when converting the argument. The exact meaning of this parameter depends on \var{ArgType}. \end{description} The \var{Index}, \var{Width} and \var{Precision} parameters can be replaced by \var{*}, in which case their value will be read from the next element in the \var{Args} array. This value must be an integer, or an \var{EConvertError} exception will be raised. The argument type is determined from \var{ArgType}. It can have one of the following values (case insensitive): \begin{description} \item[D] Decimal format. The next argument in the \var{Args} array should be an integer. The argument is converted to a decimal string,. If precision is specified, then the string will have at least \var{Precision} digits in it. If needed, the string is (left) padded with zeroes. \item[E] scientific format. The next argument in the \var{Args} array should be a Floating point value. The argument is converted to a decimal string using scientific notation, using \seef{FloatToStrF}, where the optional precision is used to specify the total number of decimals. (defalt a valueof 15 is used). The exponent is formatted using maximally 3 digits. In short, the \var{E} specifier formats it's arguument as follows: \begin{verbatim} FloatToStrF(Argument,ffexponent,Precision,3) \end{verbatim} \item[F] fixed point format. The next argument in the \var{Args} array should be a floating point value. The argument is converted to a decimal string, using fixed notation (see \seef{FloatToStrF}). \var{Precision} indicates the number of digits following the decimal point. In short, the \var{F} specifier formats it's arguument as follows: \begin{verbatim} FloatToStrF(Argument,ffFixed,ffixed,9999,Precision) \end{verbatim} \item[G] General number format. The next argument in the \var{Args} array should be a floating point value. The argument is converted to a decimal string using fixed point notation or scientific notation, depending on which gives the shortest result. \var{Precision} is used to determine the number of digits after the decimal point. In short, the \var{G} specifier formats it's arguument as follows: \begin{verbatim} FloatToStrF(Argument,ffGeneral,Precision,3) \end{verbatim} \item[M] Currency format. the next argument in the var{Args} array must be a floating point value. The argument is converted to a decimal string using currency notation. This means that fixed-point notation is used, but that the currency symbol is appended. If precision is specified, then then it overrides the \var{CurrencyDecimals} global variable used in the \seef{FloatToStrF} In short, the \var{M} specifier formats it's arguument as follows: \begin{verbatim} FloatToStrF(Argument,ffCurrency,9999,Precision) \end{verbatim} \item[N] Number format. This is the same as fixed point format, except that thousand separators are inserted in the resulting string. \item[P] Pointer format. The next argument in the \var{Args} array must be a pointer (typed or untyped). The pointer value is converted to a string of length 8, representing the hexadecimal value of the pointer. \item[S] String format. The next argument in the \var{Args} array must be a string. The argument is simply copied to the result string. If \var{Precision} is specified, then only \var{Precision} characters are copied to the result string. \item[X] hexadecimal format. The next argument in the \var{Args} array must be an integer. The argument is converted to a hexadecimal string with just enough characters to contain the value of the integer. If \var{Precision} is specified then the resulting hexadecimal representation will have at least \var{Precision} characters in it (with a maximum value of 32). \end{description} \Errors In case of error, an \var{EConversionError} exception is raised. Possible errors are: \begin{enumerate} \item Errors in the format specifiers. \item The next argument is not of the type needed by a specifier. \item The number of arguments is not sufficient for all format specifiers. \end{enumerate} \SeeAlso \seef{FormatBuf} \end{function} \FPCexample{ex71} \begin{function}{FormatBuf} \Declaration Function FormatBuf(Var Buffer; BufLen : Cardinal; Const Fmt; fmtLen : Cardinal; Const Args : Array of const) : Cardinal; \Description \var{Format} \Errors \SeeAlso \end{function} \FPCexample{ex72} \begin{function}{FormatFloat} \Declaration Function FormatFloat(Const format: String; Value: Extended): String; \Description FormatFloat formats the floating-point value given by \var{Value} using the format specifications in \var{Format}. The format specifier can give format specifications for positive, negative or zero values (separated by a semicolon). If the formatspecifier is empty or the value needs more than 18 digits to be correctly represented, the result is formatted with a call to \seef{FloatToStrF} with the \var{ffGeneral} format option. The following format specifiers are supported: \begin{description} \item[0] is a digit place holder. If there is a corresponding digit in the value being formatted, then it replaces the 0. If not, the 0 is left as-is. \item[\#] is also a digit place holder. If there is a corresponding digit in the value being formatted, then it replaces the \#. If not, it is removed. by a space. \item[.] determines the location of the decimal point. Only the first '.' character is taken into account. If the value contains digits after the decimal point, then it is replaced by the value of the \var{DecimalSeparator} character. \item[,] determines the use of the thousand separator character in the output string. If the format string contains one or more ',' charactes, then thousand separators will be used. The \var{ThousandSeparator} character is used. \item[E+] determines the use of scientific notation. If 'E+' or 'E-' (or their lowercase counterparts) are present then scientific notation is used. The number of digits in the output string is determined by the number of \var{0} characters after the '\var{E+}' \item[;] This character separates sections for positive, negative, and zero numbers in the format string. \end{description} \Errors If an error occurs, an exception is raised. \SeeAlso \seef{FloatToStr} \end{function} \FPCexample{ex89} \begin{function}{IntToHex} \Declaration Function IntToHex(Value: integer; Digits: integer): string; \Description \var{IntToHex} converts \var{Value} to a hexadecimal string representation. The result will contain at least \var{Digits} characters. If \var{Digits} is less than the needed number of characters, the string will NOT be truncated. If \var{Digits} is larger than the needed number of characters, the result is padded with zeroes. \Errors None. \SeeAlso \seef{IntToStr}, \var{StrToInt} \end{function} \FPCexample{ex73} \begin{function}{IntToStr} \Declaration Function IntToStr(Value: integer): string; \Description \var{IntToStr} coverts \var{Value} to it's string representation. The resulting string has only as much characters as needed to represent the value. If the value is negative a minus sign is prepended to the string. \Errors None. \SeeAlso \seef{IntToHex}, \seef{StrToInt} \end{function} \FPCexample{ex74} \begin{function}{IsValidIdent} \Declaration Function IsValidIdent(const Ident: string): boolean; \Description \var{IsValidIdent} returns \var{True} if \var{Ident} can be used as a compoent name. It returns \var{False} otherwise. \var{Ident} must consist of a letter or underscore, followed by a combination of letters, numbers or underscores to be a valid identifier. \Errors None. \SeeAlso \end{function} \FPCexample{ex75} \begin{function}{LastDelimiter} \Declaration Function LastDelimiter(const Delimiters, S: string): Integer; \Description \var{LastDelimiter} returns the {\em last} occurrence of any character in the set \var{Delimiters} in the string \var{S}. \Errors \SeeAlso \end{function} \FPCexample{ex88} \begin{function}{LeftStr} \Declaration Function LeftStr(const S: string; Count: integer): string; \Description \var{LeftStr} returns the \var{Count} leftmost characters of \var{S}. It is equivalent to a call to \var{Copy(S,1,Count)}. \Errors None. \SeeAlso \seef{RightStr}, \seef{TrimLeft}, \seef{TrimRight}, \seef{Trim} \end{function} \FPCexample{ex76} \begin{function}{LoadStr} \Declaration Function LoadStr(Ident: integer): string; \Description This function is not yet implemented. resources are not yet supported. \Errors \SeeAlso \end{function} \begin{function}{LowerCase} \Declaration Function LowerCase(const s: string): string; \Description \var{LowerCase} returns the lowercase equivalent of \var{S}. Ansi characters are not taken into account, only ASCII codes below 127 are converted. It is completely equivalent to the lowercase function of the system unit, and is provided for compatiibility only. \Errors None. \SeeAlso \seef{AnsiLowerCase}, \seef{UpperCase}, \seef{AnsiUpperCase} \end{function} \FPCexample{ex77} \begin{functionl}{NewStr}{NewStrSys} \Declaration Function NewStr(const S: string): PString; \Description \var{NewStr} assigns a new dynamic string on the heap, copies \var{S} into it, and returns a pointer to the newly assigned string. This function is obsolete, and shouldn't be used any more. The \var{AnsiString} mechanism also allocates ansistrings on the heap, and should be preferred over this mechanism. \Errors If not enough memory is present, an EOutOfMemory exception will be raised. \SeeAlso \seep{AssignStr}, \seepl{DisposeStr}{DisposeStrSys} \end{functionl} For an example, see \seep{AssignStr}. \begin{function}{QuotedStr} \Declaration Function QuotedStr(const S: string): string; \Description \var{QuotedStr} returns the string \var{S}, quoted with single quotes. This means that \var{S} is enclosed in single quotes, and every single quote in \var{S} is doubled. It is equivalent to a call to \var{AnsiQuotedStr(s, '''')}. \Errors None. \SeeAlso \seef{AnsiQuotedStr}, \seef{AnsiExtractQuotedStr}. \end{function} \FPCexample{ex78} \begin{function}{RightStr} \Declaration Function RightStr(const S: string; Count: integer): string; \Description \var{RightStr} returns the \var{Count} rightmost characters of \var{S}. It is equivalent to a call to \var{Copy(S,Length(S)+1-Count,Count)}. If \var{Count} is larger than the actual length of \var{S} only the real length will be used. \Errors None. \SeeAlso \seef{LeftStr},\seef{Trim}, \seef{TrimLeft}, \seef{TrimRight} \end{function} \FPCexample{ex79} \begin{function}{StrFmt} \Declaration Function StrFmt(Buffer,Fmt : PChar; Const args: Array of const) : Pchar; \Description \var{StrFmt} will format \var{fmt} with \var{Args}, as the \seef{Format} function does, and it will store the result in \var{Buffer}. The function returns \var{Buffer}. \var{Buffer} should point to enough space to contain the whole result. \Errors for a list of errors, see \seef{Format}. \SeeAlso \seef{StrLFmt}, \seep{FmtStr}, \seef{Format}, \seef{FormatBuf} \end{function} \FPCexample{ex80} \begin{function}{StrLFmt} \Declaration Function StrLFmt(Buffer : PCHar; Maxlen : Cardinal;Fmt : PChar; Const args: Array of const) : Pchar; \Description \var{StrLFmt} will format \var{fmt} with \var{Args}, as the \seef{Format} function does, and it will store maximally \var{Maxlen characters} of the result in \var{Buffer}. The function returns \var{Buffer}. \var{Buffer} should point to enough space to contain \var{MaxLen} characters. \Errors for a list of errors, see \seef{Format}. \SeeAlso \seef{StrFmt}, \seep{FmtStr}, \seef{Format}, \seef{FormatBuf} \end{function} \FPCexample{ex81} \begin{function}{StrToFloat} \Declaration Function StrToFloat(Const S : String) : Extended; \Description \var{StrToFloat} converts the string \var{S} to a floating point value. \var{S} should contain a valid stroing representation of a floating point value (either in decimal or scientific notation). If the string contains a decimal value, then the decimal separator character can either be a '.' or the value of the \var{DecimalSeparator} variable. \Errors If the string \var{S} doesn't contain a valid floating point string, then an exception will be raised. \SeeAlso \seef{TextToFloat},\seef{FloatToStr},\seef{FormatFloat},\seef{StrToInt} \end{function} \FPCexample{ex90} \begin{function}{StrToInt} \Declaration Function StrToInt(const s: string): integer; \Description \var{StrToInt} will convert the string \var{S}to an integer. If the string contains invalid characters or has an invalid format, then an \var{EConvertError} is raised. To be successfully converted, a string can contain a combination of \var{numerical} characters, possibly preceded by a minus sign (\var{-}). Spaces are not allowed. \Errors In case of error, an \var{EConvertError} is raised. \SeeAlso \seef{IntToStr}, \seef{StrToIntDef} \end{function} \FPCexample{ex82} \begin{function}{StrToIntDef} \Declaration Function StrToIntDef(const S: string; Default: integer): integer; \Description \var{StrToIntDef} will convert a string to an integer. If the string contains invalid characters or has an invalid format, then \var{Default} is returned. To be successfully converted, a string can contain a combination of \var{numerical} characters, possibly preceded by a minus sign (\var{-}). Spaces are not allowed. \Errors None. \SeeAlso \seef{IntToStr}, \seef{StrToInt} \end{function} \FPCexample{ex83} \begin{function}{TextToFloat} \Declaration Function TextToFloat(Buffer: PChar; Var Value: Extended): Boolean; \Description \var{TextToFloat} converts the string in \var{Buffer} to a floating point value. \var{Buffer} should contain a valid stroing representation of a floating point value (either in decimal or scientific notation). If the buffer contains a decimal value, then the decimal separator character can either be a '.' or the value of the \var{DecimalSeparator} variable. The function returns \var{True} if the conversion was successful. \Errors If there is an invalid character in the buffer, then the function returns \var{False} \SeeAlso \seef{StrToFloat},\seef{FloatToStr}, \seef{FormatFloat} \end{function} \FPCexample{ex91} \begin{function}{Trim} \Declaration Function Trim(const S: string): string; \Description \var{Trim} strips blank characters (spaces) at the beginning and end of \var{S} and returns the resulting string. Only \var{\#32} characters are stripped. If the string contains only spaces, an empty string is returned. \Errors None. \SeeAlso \seef{TrimLeft}, \seef{TrimRight} \end{function} \FPCexample{ex84} \begin{function}{TrimLeft} \Declaration Function TrimLeft(const S: string): string; \Description \var{TrimLeft} strips blank characters (spaces) at the beginning of \var{S} and returns the resulting string. Only \var{\#32} characters are stripped. If the string contains only spaces, an empty string is returned. \Errors None. \SeeAlso \seef{Trim}, \seef{TrimRight} \end{function} \FPCexample{ex85} \begin{function}{TrimRight} \Declaration Function TrimRight(const S: string): string; \Description \var{Trim} strips blank characters (spaces) at the end of \var{S} and returns the resulting string. Only \var{\#32} characters are stripped. If the string contains only spaces, an empty string is returned. \Errors None. \SeeAlso \seef{Trim}, \seef{TrimLeft} \end{function} \FPCexample{ex86} \begin{function}{UpperCase} \Declaration Function UpperCase(const s: string): string; \Description \var{UpperCase} returns the uppercase equivalent of \var{S}. Ansi characters are not taken into account, only ASCII codes below 127 are converted. It is completely equivalent to the \var{UpCase} function of the system unit, and is provided for compatiibility only. \Errors None. \SeeAlso \seef{AnsiLowerCase}, \seef{LowerCase}, \seef{AnsiUpperCase} \Errors \SeeAlso \end{function} \FPCexample{ex87}