mirror of
https://gitlab.com/freepascal.org/fpc/source.git
synced 2025-11-04 15:59:28 +01:00
2815 lines
86 KiB
TeX
2815 lines
86 KiB
TeX
%
|
|
% $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{S1<S2}.
|
|
\item[0] if \var{S1=S2}.
|
|
\item[>0] 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{S1<S2}.
|
|
\item[0] if \var{S1=S2}.
|
|
\item[>0] 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{S1<S2}.
|
|
\item[0] if \var{S1=S2}.
|
|
\item[>0] 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{S1<S2}.
|
|
\item[0] if \var{S1=S2}.
|
|
\item[>0] 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{S1<S2}.
|
|
\item[0] if \var{S1=S2}.
|
|
\item[>0] 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{S1<S2}.
|
|
\item[0] if \var{S1=S2}.
|
|
\item[>0] 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{S1<S2}.
|
|
\item[0] if \var{S1=S2}.
|
|
\item[>0] 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{S1<S2}.
|
|
\item[0] if \var{S1=S2}.
|
|
\item[>0] 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}
|
|
|
|
|