ChangeFileExt changes the file extension in FileName to Extension. The extension Extension includes the starting . (dot). The previous extension of FileName are all characters after the last ., the . character included.

If FileName doesn't have an extension, Extension is just appended.

Extracts the drive letter from a filename. Note that some operating systems do not support drive letters.

For an example, see .

ExtractFileExt returns the extension (including the .(dot) character) of FileName.

For an example, see .

ExtractFileName returns the filename part from 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 and ExtractFileName.

For an example, see .

ExtractFilePath returns the path part (including driveletter) from 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 ExtractFilePath and .

For an example, see .

FileClose closes the file handle Handle. After this call, attempting to read or write from the handle will result in an error.

For an example, see

FileGetAttr returns the attribute settings of file FileName. The attribute is a OR-ed combination of the following constants:

faReadOnly

The file is read-only.

faHidden

The file is hidden. (On unix, this means that the filename starts with a dot)

faSysFile

The file is a system file (On unix, this means that the file is a character, block or FIFO file).

faVolumeId

Volume Label. Not possible under unix.

faDirectory

File is a directory.

faArchive

file is an archive. Not possible on Unix

FileOpen opens a file with name FileName with mode Mode. Mode can be one of the following constants:

fmOpenRead

The file is opened for reading.

fmOpenWrite

The file is opened for writing.

fmOpenReadWrite

The file is opened for reading and writing.

If the file has been successfully opened, it can be read from or written to (depending on the Mode parameter) with the and FileWrite functions.

For an example, see

FileRead reads Count bytes from file-handle Handle and stores them into Buffer. Buffer must be at least Count bytes long. No checking on this is performed, so be careful not to overwrite any memory. Handle must be the result of a call.

For an example, see

FileSeek sets the file pointer on position Offset, starting from Origin. Origin can be one of the following values:

fsFromBeginning

Offset is relative to the first byte of the file. This position is zero-based. i.e. the first byte is at offset 0.

fsFromCurrent

Offset is relative to the current position.

fsFromEnd

Offset is relative to the end of the file. This means that Offset can only be zero or negative in this case.

If successfull, the function returns the new file position, relative to the beginning of the file.

FileSetAttr sets the attributes of FileName to Attr. If the function was successful, 0 is returned, -1 otherwise. Attr can be set to an OR-ed combination of the pre-defined faXXX constants.

This function is not implemented on Unixes.

FileSetDate sets the file date of the file with handle Handle to Age, where Age is a DOS date-and-time stamp value.

The function returns zero if successfull. (not on unixes, where it is not implemented)

FileTruncate truncates the file with handle Handle to Size bytes. The file must have been opened for writing prior to this call. The function returns True is successful, False otherwise.

For an example, see .

FileWrite writes Count bytes from Buffer to the file with handle Handle. Prior to this call, the file must have been opened for writing. Buffer must be at least 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.

For an example, see .

FindClose ends a series of / calls, and frees any memory used by these calls. It is absolutely necessary to do this call, or huge memory losses may occur.

For an example, see .

FindFirst looks for files that match the name (possibly with wildcards) in Path and attributes Attr. It then fills up the 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 Rslt record can be fed to subsequent calls to FindNext, in order to find other files matching the specifications.

FindNext finds a next occurrence of a search sequence initiated by FindFirst. If another record matching the criteria in Rslt is found, 0 is returned, a nonzero constant is returned otherwise.

For an example, see

StrAlloc reserves memory on the heap for a string with length Len, terminating #0 included, and returns a pointer to it.

Additionally, StrAlloc allocates 4 extra bytes to store the size of the allocated memory. Therefore this function is NOT compatible with the function of the Strings unit.

For an example, see .

StrDispose frees any memory allocated for Str. This function will only function correctly if Str has been allocated using StrAlloc from the SysUtils unit.

For an example, see .

StrPCopy Converts the Ansistring in Source to a Null-terminated string, and copies it to Dest. Dest needs enough room to contain the string Source, i.e. Length(Source)+1 bytes.

For an example, see .

Converts a null terminated string in Str to an Ansitring, and returns this string. This string is NOT truncated at 255 characters as is the

For an example, see .

AnsiCompareStr compares two strings and returns the following result:

< 0

if S1<S2.

0

if S1=S2.

> 0

if S1>S2.

The comparision takes into account Ansi characters, i.e. it takes care of strange accented characters. Contrary to , the comparision is case sensitive.

AnsiCompareText compares two strings and returns the following result:

<0

if S1<S2.

0

if S1=S2.

>0

if S1>S2.

the comparision takes into account Ansi characters, i.e. it takes care of strange accented characters. Contrary to , the comparision is case insensitive.

AnsiLowerCase converts the string 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.

AnsiQuotedString quotes the string S and returns the result. This means that it puts the Quote character at both the beginning and end of the string and replaces any occurrence of Quote in S with 2 Quote characters. The action of AnsiQuotedString can be reversed by .

For an example, see

AnsiStrComp compares 2 PChar strings, and returns the following result:

<0

if S1<S2.

0

if S1=S2.

>0

if S1>S2.

The comparision of the two strings is case-sensitive. The function does not yet take internationalization settings into account.

AnsiStrIComp compares 2 PChar strings, and returns the following result:

<0

if S1<S2.

0

if S1=S2.

>0

if S1>S2.

The comparision of the two strings is case-insensitive. The function does not yet take internationalization settings into account.

Return a pointer to the last character of the null-terminated string.

AnsiStrLIComp compares the first Maxlen characters of 2 PChar strings, S1 and S2, and returns the following result:

<0

if S1<S2.

0

if S1=S2.

>0

if S1>S2.

The comparision of the two strings is case-insensitive. The function does not yet take internationalization settings into account.

AnsiStrLower converts the PChar Str to lowercase characters and returns the resulting pchar. Note that Str itself is modified, not a copy, as in the case of . It takes into account the operating system language settings when doing this, so special characters are converted correctly as well.

AnsiStrUpper converts the PChar Str to uppercase characters and returns the resulting string. Note that Str itself is modified, not a copy, as in the case of . It takes into account the operating system language settings when doing this, so special characters are converted correctly as well.

AnsiUpperCase converts the string S to uppercase characters and returns the resulting string. It takes into account the operating system language settings when doing this, so special characters are converted correctly as well.

AppendStr appends S to Dest.

This function is provided for Delphi compatibility only, since it is completely equivalent to Dest:=Dest+S.

AssignStr allocates S to P. The old value of P is disposed of.

This function is provided for Delphi compatibility only. AnsiStrings are managed on the heap and should be preferred to the mechanism of dynamically allocated strings.

CompareMem compares, byte by byte, 2 memory areas pointed to by P1 and P2, for a length of L bytes.

It returns the following values:

<0

if at some position the byte at P1 is less than the byte at the same postion at P2.

0

if all L bytes are the same.

>0

if at some position the byte at P1 is greater than the byte at the same postion at P2.

CompareStr compares two strings, S1 and S2, and returns the following result:

<0

if S1<S2.

0

if S1=S2.

>0

if S1>S2.

The comparision of the two strings is case-sensitive. The function does not take internationalization settings into account, it simply compares ASCII values.

CompareText compares two strings, S1 and S2, and returns the following result:

<0

if S1<S2.

0

if S1=S2.

>0

if S1>S2.

The comparision of the two strings is case-insensitive. The function does not take internationalization settings into account, it simply compares ASCII values.

DisposeStr removes the dynamically allocated string S from the heap, and releases the occupied memory.

This function is provided for Delphi compatibility only. AnsiStrings are managed on the heap and should be preferred to the mechanism of dynamically allocated strings.

For an example, see .

FloatToStr converts the floating point variable Value to a string representation. It will choose the shortest possible notation of the two following formats:

Fixed format

will represent the string in fixed notation,

Decimal format

will represent the string in scientific notation.

More information on these formats can be found in . FloatToStr is completely equivalent to the following call:

FloatToStrF converts the floating point number value to a string representation, according to the settings of the parameters Format, Precision and Digits.

The meaning of the Precision and Digits parameter depends on the Format parameter. The format is controlled mainly by the Format parameter. It can have one of the following values:

ffcurrency

Money format. Value is converted to a string using the global variables CurrencyString, CurrencyFormat and NegCurrencyFormat. The Digits paramater specifies the number of digits following the decimal point and should be in the range -1 to 18. If Digits equals -1, CurrencyDecimals is assumed. The Precision parameter is ignored.

ffExponent

Scientific format. Value is converted to a string using scientific notation: 1 digit before the decimal point, possibly preceded by a minus sign if Value is negative. The number of digits after the decimal point is controlled by Precision and must lie in the range 0 to 15.

ffFixed

Fixed point format. Value is converted to a string using fixed point notation. The result is composed of all digits of the integer part of Value, preceded by a minus sign if Value is negative. Following the integer part is DecimalSeparator and then the fractional part of Value, rounded off to Digits numbers. If the number is too large then the result will be in scientific notation.

ffGeneral

General number format. The argument is converted to a string using ffExponent or ffFixed format, depending on wich one gives the shortest string. There will be no trailing zeroes. If Value is less than 0.00001 or if the number of decimals left of the decimal point is larger than Precision then scientific notation is used, and Digits is the minimum number of digits in the exponent. Otherwise Digits is ignored.

ffnumber

Is the same as ffFixed, except that thousand separators are inserted in the resultig string.

FloatToText converts the floating point variable Value to a string representation and stores it in Buffer. The conversion is governed by format, Precisison and Digits. more information on these parameters can be found in . 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 Buffer.

Format replaces all placeholders inFmt with the arguments passed in Args and returns the resulting string. A placeholder looks as follows:

elements between single quotes must be typed as shown without the quotes, and elements between square brackets [ ] are optional. The meaning of the different elements is shown below:

'%'

starts the placeholder. If you want to insert a literal % character, then you must insert two of them : %%.

Index ':'

takes the Index-th element in the argument array as the element to insert.

'-'

tells Format to left-align the inserted text. The default behaviour is to right-align inserted text. This can only take effect if the Width element is also specified.

Width

the inserted string must have at least have 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 '-' character.

'.' Precision

Indicates the precision to be used when converting the argument. The exact meaning of this parameter depends on ArgType.

The Index, Width and Precision parameters can be replaced by *, in which case their value will be read from the next element in the Args array. This value must be an integer, or an EConvertError exception will be raised.

The argument type is determined from ArgType. It can have one of the following values (case insensitive):

D

Decimal format. The next argument in the 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 Precision digits in it. If needed, the string is (left) padded with zeroes.

E

Scientific format. The next argument in the Args array should be a Floating point value. The argument is converted to a decimal string using scientific notation, using , 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 E specifier formats it's argument as follows:

FloatToStrF(Argument,ffexponent,Precision,3)

F

Fixed point format. The next argument in the Args array should be a floating point value. The argument is converted to a decimal string, using fixed notation (see ). Precision indicates the number of digits following the decimal point.

In short, the F specifier formats it's argument as follows:

FloatToStrF(Argument,ffFixed,ffixed,9999,Precision)

G

General number format. The next argument in the 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. Precision is used to determine the number of digits after the decimal point.

In short, the G specifier formats it's argument as follows:

FloatToStrF(Argument,ffGeneral,Precision,3)

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 CurrencyDecimals global variable used in the

In short, the M specifier formats it's argument as follows:

FloatToStrF(Argument,ffCurrency,9999,Precision)

N

Number format. This is the same as fixed point format, except that thousand separators are inserted in the resulting string.

P

Pointer format. The next argument in the 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.

S

String format. The next argument in the Args array must be a string. The argument is simply copied to the result string. If Precision is specified, then only Precision characters are copied to the result string.

X

hexadecimal format. The next argument in the 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 Precision is specified then the resulting hexadecimal representation will have at least Precision characters in it (with a maximum value of 32).

FormatFloat formats the floating-point value given by Value using the format specifications in 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 with the ffGeneral format option.

The following format specifiers are supported:

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.

#

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.

.

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 DecimalSeparator character.

,

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 ThousandSeparator character is used.

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 0 characters after the 'E+'

;

This character separates sections for positive, negative, and zero numbers in the format string.

NewStr assigns a new dynamic string on the heap, copies S into it, and returns a pointer to the newly assigned string.

This function is obsolete, and shouldn't be used any more. The AnsiString mechanism also allocates ansistrings on the heap, and should be preferred over this mechanism.

For an example, see .

RightStr returns the Count rightmost characters of S. It is equivalent to a call to Copy(S,Length(S)+1-Count,Count).

If Count is larger than the actual length of S only the real length will be used.

StrToInt will convert the string Sto an integer. If the string contains invalid characters or has an invalid format, then an EConvertError is raised.

To be successfully converted, a string can contain a combination of numerical characters, possibly preceded by a minus sign (-). Spaces are not allowed.

StrToIntDef will convert a string to an integer. If the string contains invalid characters or has an invalid format, then Default is returned.

To be successfully converted, a string can contain a combination of numerical characters, possibly preceded by a minus sign (-). Spaces are not allowed.

TextToFloat converts the string in Buffer to a floating point value. 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 DecimalSeparator variable.

The function returns True if the conversion was successful.

Trim strips blank characters (spaces) at the beginning and end of S and returns the resulting string. Only #32 characters are stripped.

If the string contains only spaces, an empty string is returned.

GetLastOSError returns the error code from the last operating system call. It does not reset this code. In general, it should be called when an operating system call reported an error condition. In that case, GetLastOSError gives extended information about the error.

No assumptions should be made about the resetting of the error code by subsequent OS calls. This may be platform dependent.

GetEnvironmentVariable returns the value of the EnvVar environment variable. If the specified variable does not exist or EnvVar is empty, an empty string is returned.

Sleep suspends the execution of the program for the specified number of milliseconds (milliseconds). After the specified period has expired, program execution resumes.

GetAppConfigDir returns the name of a directory in which the application should store its configuration files on the current OS. If the parameter Global is True then the directory returned is a global directory, i.e. valid for all users on the system. If the parameter Global is false, then the directory is specific for the user who is executing the program. On systems that do not support multi-user environments, these two directories may be the same.

The directory which is returned is the name of the directory where the application is supposed to store files. This does not mean that the directory exists, or that the user can write in this directory (especially if Global=True). It just returns the name of the appropriate location.

On systems where the operating system provides a call to determine this location, this call will be used. On systems where there is no such call, an algorithm is used which reflects common practice on that system.

The application name is deduced from the binary name via the call, but can be configured by means of the callback.

GetAppConfigFile returns the name of a file in which the application can store its configuration parameters. The Global parameter determines whether it is a global configuration file (value True) or a personal configuration file (value False). The parameter SubDir, in case it is set to True, will insert the name of a directory before the filename. This can be used in case the application needs to store other data than configuration data in an application-specific directory. Default behaviour is to set this to False.

No assumptions should be made about the existence or writeability of this file, or the directory where the file should reside.

On systems where the operating system provides a call to determine the location of configuration files, this call will be used. On systems where there is no such call, an algorithm is used which reflects common practice on that system.

The application name is deduced from the binary name via the call, but can be configured by means of the callback.

SysConfigDir is the default system configuration directory. It is set at application startup by the sysutils initialization routines.

This directory may be returned by the call on some systems.

By default, the configuration file routines and use a default application name to construct a directory or filename. This callback can be used to provide an alternative application name.

Since the result of this callback will be used to construct a filename, care should be taken that the returned name does not contain directory separator characters or characters that cannot appear in a filename.

CompareMemRange compares the 2 memory locations pointed to by P1 and P2 byte per byte. It stops comparing after Length bytes have been compared, or when it has encountered 2 different bytes. The result is then

>0

if a byte in range P1 was found that is bigger than the corresponding byte in range P2.

0

if all bytes in range P1 are the same as the corresponding bytes in range P2.

<0

if a byte in range P1 was found that is less than the corresponding byte in range P2.

StrToInt64 converts the string S to a Int64 value, and returns this value. The string can only contain numerical characters, and optionally a minus sign as the first character. Whitespace is not allowed.

Hexadecimal values (starting with the $ character) are supported.

TryStrToInt64 tries to convert the string S to a Int64 value, and returns this value in I if successful. If the conversion was succesful, the function result is True, or False otherwise. The string can only contain numerical characters, and optionally a minus sign as the first character. Whitespace is not allowed.

Hexadecimal values (starting with the $ character) are supported.

CurrToStr will convert a currency value to a string with a maximum of 15 digits, and precision 2. Calling CurrToStr is equivalent to calling :

FloatToTextFmt returns a textual representation of Value in the memory location pointed to by Buffer. it uses the formatting specification in Format to do this. The return value is the number of characters that were written in the buffer.

For a list of valid formatting characters, see

ExceptionErrorMessage creates a string that describes the exception object ExceptObject at address ExceptAddr. It can be used to display exception messages. The string will be stored in the memory pointed to by Buffer, and will at most have Size characters.

The routine checks whether ExceptObject is a object or not, and adapts the output accordingly.

ShowException shows a message stating that a ExceptObject was raised at address ExceptAddr. It uses to create the message, and is aware of the fact whether the application is a console application or a GUI application. For a console application, the message is written to standard error output. For a GUI application, is executed.

FileRec describes a untyped file. This record is made available so it can be used to implement drivers for other than the normal file system file records.

TextRec describes a text file. This record is made available so it can be used to implement drivers for other than the normal file system file records.

To implement a driver, an Assign procedure must be implemented, which fills in the various fields of the record. Most notably, the callback functions must be filled in appropriately. After this, the normal file operations will handle all necessary calls to the various callbacks.

Compares the null-terminated strings S1 and S2. The result is

• A negative Longint when S1<S2.
• 0 when S1=S2.
• A positive Longint when S1>S2.

For an example, see .

Compares maximum L characters of the null-terminated strings S1 and S2. The result is

• A negative Longint when S1<S2.
• 0 when S1=S2.
• A positive Longint when S1>S2.

Compares the null-terminated strings S1 and S2, ignoring case. The result is

• A negative Longint when S1<S2.
• 0 when S1=S2.
• A positive Longint when S1>S2.

Returns a pointer to the last occurrence of the character C in the null-terminated string P. If C does not occur, returns Nil.

For an example, see .

Converts P to an all-uppercase string. Returns P.

For an example, see

Compares maximum L characters of the null-terminated strings S1 and S2, ignoring case. The result is

• A negative Longint when S1<S2.
• 0 when S1=S2.
• A positive Longint when S1>S2.

For an example, see

AnsiCompareFileName compares 2 filenames S1 and S2, and returns

< 0

if S1<S2.

= 0

if S1=S2.

> 0

if S1>S2.

The function actually checks FileNameCaseSensitive and returns the result of or depending on whether FileNameCaseSensitive is True or False

AnsiLowerCaseFileName simply returns the result of

AnsiUpperCaseFileName simply returns the result of

TSearchRec is a search handle description record. It is initialized by a call to and can be used to do subsequent calls to . It contains the result of these function calls. It must be used to close the search sequence with a call to .

GetTempDir returns the temporary directory of the system. If Global is True (the default value) it returns the system temporary directory, if it is False then a directory private to the user is returned. The returned name will end with a directory delimiter character.

These directories may be the same. No guarantee is made that this directory exists or is writeable by the user.

The handler may be set to provide custom handling of this routine: One could implement callbacks which take into consideration frameworks like KDE or GNOME, and return a different value from the default system implementation.

GetTempFileName returns the name of a temporary file in directory Dir. The name of the file starts with Prefix.

If Dir is empty, the value returned by GetTempDir is used, and if Prefix is empty, 'TMP' is used.

The handler may be set to provide custom handling of this routine: One could implement callbacks which take into consideration frameworks like KDE or GNOME, and return a different value from the default system implementation.