Commonly Used Routines for AnsiStrings

From RAD Studio
Jump to: navigation, search

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:

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