SysUtils – String Functions

AnsiCompareStr

function AnsiCompareStr(const S1: string; const S2: string): Integer;

Compares S1 and S2 case-sensitively, taking Ansi (accented) characters into account, and returns a value less than, equal to, or greater than zero depending on their relative order; requires a widestring manager to be installed for correct behavior with non-ASCII character sets.

AnsiCompareText

function AnsiCompareText(const S1: string; const S2: string): Integer;

Compares S1 and S2 case-insensitively, taking Ansi (accented) characters into account, and returns a value less than, equal to, or greater than zero depending on their relative order; requires a widestring manager to be installed for correct behavior with non-ASCII character sets.

AnsiExtractQuotedStr

function AnsiExtractQuotedStr(var Src: PChar; Quote: Char): string;

Extracts the first quoted substring from Src (removing the surrounding Quote characters and collapsing doubled Quote characters to one), removes it from Src, and returns it; this reverses the effect of AnsiQuotedStr.

AnsiLastChar

function AnsiLastChar(const S: string): PChar;

Returns a pointer to the last character of S; without a widestring manager installed this is equivalent to @S[Length(S)].

AnsiLowerCase

function AnsiLowerCase(const s: string): string;

Returns a lowercase version of S, taking the operating system's language settings into account so that accented and special characters are converted correctly; requires a widestring manager for correct behavior with non-ASCII character sets.

AnsiQuotedStr

function AnsiQuotedStr(const S: string; Quote: Char): string;

Wraps S in the Quote character at both ends and doubles every embedded occurrence of Quote; the reverse operation is AnsiExtractQuotedStr.

AnsiStrComp

function AnsiStrComp(S1: PChar; S2: PChar): Integer;

Compares the null-terminated strings S1 and S2 case-sensitively and returns a value less than, equal to, or greater than zero depending on their relative order; requires a widestring manager for correct behavior with non-ASCII character sets.

AnsiStrIComp

function AnsiStrIComp(S1: PChar; S2: PChar): Integer;

Compares the null-terminated strings S1 and S2 case-insensitively and returns a value less than, equal to, or greater than zero depending on their relative order; requires a widestring manager for correct behavior with non-ASCII character sets.

AnsiStrLComp

function AnsiStrLComp(S1: PChar; S2: PChar; MaxLen: SizeUInt): Integer;

Compares at most MaxLen characters of the null-terminated strings S1 and S2 case-sensitively, returning zero if the first MaxLen characters match; embedded null characters are treated as ordinary characters during comparison.

AnsiStrLIComp

function AnsiStrLIComp(S1: PChar; S2: PChar; MaxLen: SizeUInt): Integer;

Compares at most MaxLen characters of the null-terminated strings S1 and S2 case-insensitively and returns a value less than, equal to, or greater than zero depending on their relative order; requires a widestring manager for correct behavior with non-ASCII character sets.

AnsiStrLastChar

function AnsiStrLastChar(Str: PChar): PChar;

Returns a pointer to the last character of the null-terminated string Str; without a widestring manager installed this is equivalent to @S[Length(S)].

AnsiStrLower

function AnsiStrLower(Str: PChar): PChar;

Converts the null-terminated string Str to lowercase in place (modifying Str itself rather than a copy, unlike AnsiLowerCase) and returns Str, taking the operating system's language settings into account.

AnsiStrUpper

function AnsiStrUpper(Str: PChar): PChar;

Converts the null-terminated string Str to uppercase in place (modifying Str itself rather than a copy, unlike AnsiUpperCase) and returns Str, taking the operating system's language settings into account.

AnsiUpperCase

function AnsiUpperCase(const s: string): string;

Returns an uppercase version of S, taking the operating system's language settings into account so that accented and special characters are converted correctly; requires a widestring manager for correct behavior with non-ASCII character sets.

AppendStr

procedure AppendStr(var Dest: string; const S: string);

Appends S to Dest; provided for Delphi compatibility only, as it is entirely equivalent to Dest := Dest + S.

AssignStr

procedure AssignStr(var P: PString; const S: string);

Allocates a new heap string containing S and assigns it to P, disposing of P's previous value; provided for Delphi compatibility only — modern code should prefer AnsiStrings, which are heap-managed automatically.

CompareStr

function CompareStr(const S1: string; const S2: string): Integer; overload;
function CompareStr(const S1: string; const S2: string; LocaleOptions: TLocaleOptions): Integer; overload;

Compares S1 and S2 case-sensitively by raw ASCII/byte value (without taking internationalization or accented characters into account) and returns a value less than, equal to, or greater than zero depending on their relative order.

CompareText

function CompareText(const S1: string; const S2: string): Integer; overload;
function CompareText(const S1: string; const S2: string; LocaleOptions: TLocaleOptions): Integer; overload;

Compares S1 and S2 case-insensitively by raw ASCII/byte value (without taking internationalization or accented characters into account) and returns a value less than, equal to, or greater than zero depending on their relative order.

DisposeStr

procedure DisposeStr(S: PString); overload;
procedure DisposeStr(S: PShortString); overload;

Frees the dynamically allocated string S from the heap; provided for Delphi compatibility only — modern code should prefer AnsiStrings, which are heap-managed automatically.

IsValidIdent

function IsValidIdent(const Ident: string; AllowDots: Boolean = False; StrictDots: Boolean = False): Boolean;

Returns True if Ident could be used as a Pascal component/identifier name, i.e. it starts with a letter or underscore followed only by letters, digits, or underscores (with AllowDots/StrictDots controlling whether dot-separated qualified names are also accepted).

LastDelimiter

function LastDelimiter(const Delimiters: string; const S: string): SizeInt;

Returns the position of the last occurrence, within S, of any character contained in the Delimiters set.

LeftStr

function LeftStr(const S: string; Count: Integer): string;

Returns the Count leftmost characters of S; equivalent to Copy(S, 1, Count).

LoadStr

function LoadStr(Ident: Integer): string;

Intended to load a string identified by Ident from the resource tables; not yet implemented in FreePascal, since resource strings are not yet supported.

LowerCase

function LowerCase(const s: string): string; overload;
function LowerCase(const s: string; LocaleOptions: TLocaleOptions): string; overload;
function LowerCase(const V: variant): string; overload;
function LowerCase(const s: UnicodeString): UnicodeString; overload;

Returns a lowercase version of S, converting only ASCII codes below 127 (Ansi/accented characters are not affected); equivalent to the System unit's lowercase function and provided for compatibility. Does not change the length of the string.

NewStr

function NewStr(const S: string): PString; overload;

Allocates a new string on the heap, copies S into it, and returns a pointer to it; considered obsolete — modern code should prefer AnsiStrings, which are heap-managed automatically. Raises an EOutOfMemory exception if insufficient memory is available.

RightStr

function RightStr(const S: string; Count: Integer): string;

Returns the Count rightmost characters of S, equivalent to Copy(S, Length(S)+1-Count, Count); if Count exceeds the actual length of S, the whole string is returned.

StrAlloc

function StrAlloc(Size: Cardinal): PChar;

Reserves heap memory for a null-terminated string of Size bytes (including the terminating #0) and returns a pointer to it; it additionally allocates 4 extra bytes to store the buffer's size, which makes it binary incompatible with the StrAlloc function of the Strings unit.

StrBufSize

function StrBufSize(Str: PChar): Cardinal;
function StrBufSize(str: pwidechar): Cardinal;

Returns the size, in bytes, of the heap memory allocated for Str; this only gives a correct result if Str was allocated with StrAlloc.

StrDispose

procedure StrDispose(Str: PChar);
procedure StrDispose(str: pwidechar);

Frees the heap memory allocated for Str; this only works correctly if Str was allocated on the heap via StrAlloc or StrNew, and passing an invalid or differently-allocated pointer may cause an error.

StrPas

function StrPas(Str: PChar): string; overload;
function StrPas(Str: PWideChar): UnicodeString; overload;

Converts the null-terminated string Str into an Ansistring (or UnicodeString for the PWideChar overload) and returns it; unlike the System unit's version, the result is not truncated at 255 characters.

StrPCopy

function StrPCopy(Dest: PChar; const Source: string): PChar; overload;
function StrPCopy(Dest: PWideChar; const Source: UnicodeString): PWideChar; overload;

Converts the (Ansi)string in Source to a null-terminated string and copies it into Dest, which needs room for Length(Source)+1 bytes; no bounds checking is performed.

StrPLCopy

function StrPLCopy(Dest: PChar; const Source: string; MaxLen: SizeUInt): PChar; overload;
function StrPLCopy(Dest: PWideChar; const Source: UnicodeString; MaxLen: SizeUInt): PWideChar; overload;

Converts at most MaxLen characters of the string in Source to a null-terminated string and copies them into Dest; no checking is performed to ensure Dest has enough room.

UpperCase

function UpperCase(const s: string): string; overload;
function UpperCase(const s: string; LocaleOptions: TLocaleOptions): string; overload;
function UpperCase(const s: UnicodeString): UnicodeString; overload;

Returns an uppercase version of S, converting only ASCII codes below 127 (Ansi/accented characters are not affected); equivalent to the System unit's UpCase function and provided for compatibility.