Commonly Used Routines for AnsiStrings

Go Up to Working with Strings

The string handling routines in SysUtils handle both UnicodeString and AnsiString types. Within their functional areas, some routines are used for the same purpose, the differences being whether they use a particular criterion in their calculations.

The AnsiStrings unit's functions offer the same capabilities as the SysUtils unit's routines. AnsiStrings functions provide better performance for AnsiString than SysUtils functions, because SysUtils functions convert an AnsiString to a UnicodeString. AnsiStrings functions work only with AnsiString, so there is no conversion.

The following tables list these routines by these functional areas:

• Length
• Comparison
• Case conversion
• Modification
• Sub-string
• Information

Where appropriate, the tables also provide columns indicating whether a routine satisfies the following criteria:

• Uses case sensitivity: If locale settings are used, it determines the definition of case. If the routine does not use locale settings, analyses are based upon the ordinal values of the characters. If the routine is case-insensitive, there is a logical merging of upper and lower case characters that is determined by a predefined pattern.
• Uses locale settings: Locale settings allow you to customize your application for specific locales, in particular, for Asian language environments. Most locale settings consider lowercase characters to be less than the corresponding uppercase characters. This is in contrast to ASCII order, in which lowercase characters are greater than uppercase characters. Routines that use the system locale are typically prefaced with Ansi (that is, AnsiXXX).
• Supports the multi-byte character set (MBCS): MBCSs are used when writing code for far eastern locales. Multi-byte characters are represented by one or more character codes, so the length in bytes does not necessarily correspond to the length of the string. The routines that support MBCS parse one- and multibyte characters.

ByteType and StrByteType determine whether a particular byte is the lead byte of a multi-byte character. Be careful when using multi-byte characters not to truncate a string by cutting a character in half. Do not pass characters as a parameter to a function or procedure, since the size of a character cannot be predetermined. Pass, instead, a pointer to a character or string. For more information about MBCS, see Enabling Application Code to Work for Different Locales.

String Length Routines

Routine	Uses locale settings	Supports MBCS	Returns
System.Length	yes	yes	Number of elements in string. Does not account for MBCS or Unicode surrogate pair "characters".
System.SizeOf	yes	yes	Number of bytes required to represent type or variable.

Note that Length and SizeOf give different results for all strings except for short strings. SizeOf equals the number of bytes in a pointer, since non-short strings are pointers.

String Comparison Routines

Routine	Case-sensitive	Uses locale settings	Supports MBCS
System.AnsiStrings.AnsiCompareStr System.SysUtils.AnsiCompareStr	yes	yes	yes
System.AnsiStrings.AnsiCompareText System.SysUtils.AnsiCompareText	no	yes	yes
System.AnsiStrings.AnsiCompareFileName System.SysUtils.AnsiCompareFileName	no	yes	yes
System.AnsiStrings.AnsiMatchStr System.StrUtils.AnsiMatchStr	yes	yes	yes
System.AnsiStrings.AnsiMatchText System.StrUtils.AnsiMatchText	no	yes	yes
System.AnsiStrings.AnsiContainsStr System.StrUtils.AnsiContainsStr	yes	yes	yes
System.AnsiStrings.AnsiContainsText System.StrUtils.AnsiContainsText	no	yes	yes
System.AnsiStrings.AnsiStartsStr System.StrUtils.AnsiStartsStr	yes	yes	yes
System.AnsiStrings.AnsiStartsText System.StrUtils.AnsiStartsText	no	yes	yes
System.AnsiStrings.AnsiEndsStr System.StrUtils.AnsiEndsStr	yes	yes	yes
System.AnsiStrings.AnsiEndsText System.StrUtils.AnsiEndsText	no	yes	yes
System.AnsiStrings.AnsiEndsStr System.StrUtils.AnsiEndsStr	yes	yes	yes
System.AnsiStrings.AnsiIndexText System.StrUtils.AnsiIndexText	no	yes	yes
System.AnsiStrings.CompareStr System.SysUtils.CompareStr	yes	no	no
System.AnsiStrings.CompareText System.SysUtils.CompareText	no	no	no
System.StrUtils.AnsiResemblesText	no	no	no

Case Conversion Routines

Routine	Uses locale settings	Supports MBCS
System.AnsiStrings.AnsiLowerCase System.SysUtils.AnsiLowerCase	yes	yes
System.AnsiStrings.AnsiUpperCaseFileName System.SysUtils.AnsiUpperCaseFileName	yes	yes
System.AnsiStrings.AnsiUpperCase System.SysUtils.AnsiUpperCase	yes	yes
System.AnsiStrings.LowerCase System.SysUtils.LowerCase	no	no. Works for A to Z only, not European accented characters.
System.AnsiStrings.UpperCase System.SysUtils.UpperCase	no	no. Works for a to z only, not European accented characters.

Note: The routines used for string file names: AnsiCompareFileName, AnsiLowerCaseFileName, and AnsiUpperCaseFileName all use the system locale. You should always use file names that are portable because the locale (character set) used for file names can and might differ from the default user interface.

String Modification Routines

Routine	Case-sensitive	Supports MBCS
System.SysUtils.AdjustLineBreaks	NA	yes
System.AnsiStrings.AnsiQuotedStr System.SysUtils.AnsiQuotedStr	NA	yes
System.AnsiStrings.AnsiReplaceStr System.StrUtils.AnsiReplaceStr	yes	yes
System.AnsiStrings.AnsiReplaceText System.StrUtils.AnsiReplaceText	no	yes
System.AnsiStrings.StringReplace System.SysUtils.StringReplace	optional by flag	yes
System.AnsiStrings.ReverseString System.StrUtils.ReverseString	NA	no
System.AnsiStrings.StuffString System.StrUtils.StuffString	NA	no
System.FillChar	NA	no
System.SysUtils.StrPCopy	yes	yes
System.AnsiStrings.Trim System.SysUtils.Trim	NA	yes
System.AnsiStrings.TrimLeft System.SysUtils.TrimLeft	NA	yes
System.AnsiStrings.TrimRight System.SysUtils.TrimRight	NA	yes
System.SysUtils.WrapText	NA	yes

Sub-string Routines

Routine	Case-sensitive	Supports MBCS
System.SysUtils.AnsiExtractQuotedStr	NA	yes
System.AnsiStrings.AnsiPos System.SysUtils.AnsiPos	yes	yes
System.AnsiStrings.IsDelimiter System.SysUtils.IsDelimiter	yes	yes
System.AnsiStrings.IsPathDelimiter System.SysUtils.IsPathDelimiter	yes	yes
System.AnsiStrings.LastDelimiter System.SysUtils.LastDelimiter	yes	yes
System.StrUtils.LeftStr	NA	no
System.StrUtils.RightStr	NA	no
System.StrUtils.MidStr	NA	no
System.AnsiStrings.QuotedStr System.SysUtils.QuotedStr	no	no
System.StringOfChar	NA	yes

String Information Routines

Routine	Returns
System.StringCodePage	Code page
System.StringElementSize	Element size
System.StringRefCount	Reference count

Note: It is not safe to directly manipulate the internal structures of strings, since these change with product versions.

See Also

• Wide Character Routines
• Commonly Used Routines for Null-terminated Strings
• Unicode in RAD Studio
• Enabling Applications for Unicode