/help/Strings.dtx

@@StringManipulation.CharacterSearchandReplace
<GROUP StringManipulation>
<TITLE Character Search and Replace>
<TOPICORDER 100>
--------------------------------------------------------------------------------
@@StringManipulation.CharacterTestRoutines
<GROUP StringManipulation>
<TITLE Character Test Routines>
<TOPICORDER 200>
--------------------------------------------------------------------------------
@@StringManipulation.CharacterTransformationRoutines
<GROUP StringManipulation>
<TITLE Character Transformation Routines>
<TOPICORDER 300>
--------------------------------------------------------------------------------
@@StringManipulation.Miscellaneous
<GROUP StringManipulation>
<TITLE Miscellaneous>
<TOPICORDER 400>
--------------------------------------------------------------------------------
@@StringManipulation.MultiSz
<GROUP StringManipulation>
<TITLE MultiSz>
<TOPICORDER 500>
--------------------------------------------------------------------------------
@@StringManipulation.PCharVector
<GROUP StringManipulation>
<TITLE PCharVector>
<TOPICORDER 600>
--------------------------------------------------------------------------------
@@StringManipulation.StringExtraction
<GROUP StringManipulation>
<TITLE String Extraction>
<TOPICORDER 700>
--------------------------------------------------------------------------------
@@StringManipulation.StringManagement
<GROUP StringManipulation>
<TITLE String Management>
<TOPICORDER 800>
--------------------------------------------------------------------------------
@@StringManipulation.StringSearchandReplaceRoutines
<GROUP StringManipulation>
<TITLE String Search and Replace Routines>
<TOPICORDER 900>
--------------------------------------------------------------------------------
@@StringManipulation.StringTestRoutines
<GROUP StringManipulation>
<TITLE String Test Routines>
<TOPICORDER 1000>
--------------------------------------------------------------------------------
@@StringManipulation.StringTransformationRoutines
<GROUP StringManipulation>
<TITLE String Transformation Routines>
<TOPICORDER 1100>
--------------------------------------------------------------------------------
@@StringManipulation.Tabulation
<GROUP StringManipulation>
<TITLE Tabulation>
<TOPICORDER 1150>
--------------------------------------------------------------------------------
@@StringManipulation.TStringsManipulation
<GROUP StringManipulation>
<TITLE TStrings Manipulation>
<TOPICORDER 1200>
--------------------------------------------------------------------------------
@@StrIsAlpha
<GROUP StringManipulation.StringTestRoutines>
Summary:
  Tests whether S contains only alpha characters.
Description:
  StrIsAlpha tests whether the supplied string consists only of alpha characters.
  That is, whether or not all individual characters come from the ['a'..'z', 'A'..'Z']
  set.
Parameters:
  S - The string to test
Result:
  If S contains only alpha characters the result is True, otherwise the result is False.
Notes:
  If S is an empty string the result is False.
See also:
  StrConsistsOfNumberChars
  StrIsAlphaNum
Donator:
  Nick Hodges
--------------------------------------------------------------------------------
@@StrIsAlphaNum
<GROUP StringManipulation.StringTestRoutines>
Summary:
  Tests whether S contains only alpha-numerical characters.
Description:
  StrIsAlphaNum tests whether the supplied string consists only of alpha-numerical
  characters. That is, whether or not all individual characters come from
  the ['a'..'z', 'A'..'Z', '0'..'9'] set.
Parameters:
  S - The string to test
Result:
  If S contains only alpha-numerical characters the result is True, otherwise the result is False.
Notes:
  If S is an empty string the result is False.
See also:
  StrIsAlpha
  StrConsistsOfNumberChars
  StrIsAlphaNumUnderscore
Donator:
  Marcel van Brakel
--------------------------------------------------------------------------------
@@StrIsAlphaNumUnderscore
<GROUP StringManipulation.StringTestRoutines>
Summary:
  Tests whether S contains only alpha-numerical and underscore characters.
Description:
  StrIsAlphaNum tests whether the supplied string consists only of alpha-numerical
  and underscore characters. That is, whether or not all individual characters come
  from the ['a'..'z', 'A'..'Z', '0'..'9', '_'] set.
Parameters:
  S - The string to test
Result:
  If S contains only alpha-numerical and underscore characters the result is True,
  otherwise the result is False.
Notes:
  If S is an empty string the result is False.
See also:
  StrIsAlpha
  StrConsistsOfNumberChars
Donator:
  Anthony Steele
--------------------------------------------------------------------------------
@@StrContainsChars
<GROUP StringManipulation.StringTestRoutines>
Summary:
  Determines whether a string contains a specified set of characters.
Description:
  StrContainsChars checks whether the specified string contains at least one character
  that matches one of the characters in the Chars set. If CheckAll is True, the
  function checks whether all characters in the Chars set appear at least once in
  the specified string.
Parameters:
  S - The string to test.
  Chars - The characters for which to test.
  CheckAll - If True, all characters from Chars must appear at least once in the specified string. If False, at least one of the characters in Chars must appear at least once in the specified string.
Result:
  Returns True if the condition is met, otherwise it returns False.
Donator:
  Petr Vones
--------------------------------------------------------------------------------
@@StrIsDigit
<GROUP StringManipulation.StringTestRoutines>
Summary:
  Tests whether S contains only numerical characters.
Description:
  StrConsistsOfNumberChars tests whether the supplied string consists only of numerical characters.
  That is, whether or not all individual characters come from the ['0'..'9'] set.
  The test does not include the decimal separator. To include it in the test
  use StrConsistsOfNumberChars instead.
Parameters:
  S - The string to test
Result:
  If S contains only numerical characters the result is True, otherwise the result is False.
Notes:
  If S is an empty string the result is False.
See also:
  StrIsAlpha
  StrIsAlphaNum
  StrConsistsOfNumberChars
Donator:
  Martin Kubecka
--------------------------------------------------------------------------------
@@StrConsistsOfNumberChars
<GROUP StringManipulation.StringTestRoutines>
Summary:
  Tests whether S contains only numerical characters.
Description:
  StrConsistsOfNumberChars tests whether the supplied string consists only of numerical characters.
  That is, whether or not all individual characters come from the ['0'..'9'] set
  including the decimal separator. To test for numerical characters without the
  decimal separator, use StrIsDigit instead;
Parameters:
  S - The string to test
Result:
  If S contains only numerical characters the result is True, otherwise the result is False.
Notes:
  If S is an empty string the result is False.
See also:
  StrIsAlpha
  StrIsAlphaNum
  StrIsDigit
Donator:
  Nick Hodges
--------------------------------------------------------------------------------
@@StrIsSubset
<GROUP StringManipulation.StringTestRoutines>
Summary:
  Tests whether S contains only characters from the supplied set.
Description:
  StrIsSubset tests whether the supplied string contains only characters from the
  supplied character set. Keep in mind that the test is case-sensitive.
Parameters:
  S - The string to test.
  ValidChars - The set of characters allowed in S.
Result:
  If the string contains only characters from the supplied set the result is True,
  otherwise the result is False.
Notes:
  If the supplied string is empty, the result is always True. If the supplied character
  set is empty, the result is always False. Empty string overules empty set.
Donator:
  Marcel van Brakel
--------------------------------------------------------------------------------
@@StrSame
<GROUP StringManipulation.StringTestRoutines>
Summary:
  Tests two strings for equality.
Description:
  StrSame compares the two supplied strings and returns whether or not they are
  identical.
Parameters:
  S1 - First string to compare.
  S2 - Second string to compare.
Result:
  If the two strings are identical the return value is True, if they are not the
  return value is False.
See also:
  StrCompare
Donator:
  Azret Botash
--------------------------------------------------------------------------------
@@StrCenter
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Centers a string.
Description:
  The StrCenter routine takes the specified string and pads it
  on both the left and right side with the specified character
  until the resulting string is of the specified length. While
  doing this the original string is kept centered. That is,
  there is the same amount of padding at the left side as there
  is on the right side.

  If the specified length is smaller than the length of the
  original the string remains unchanged. In cases where an odd
  number of padding chars have to be inserted there is always
  one more padding char on the right side than on the left
  side.
Parameters:
  C - The character to use for padding.
  L - The desired length of the resulting string.
  S - The string to center.
Result:
  Returns the centered string.
Donator:
  Alexander Radchenko
--------------------------------------------------------------------------------
@@StrDoubleQuote
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Returns a double-quoted version of the string.
Description:
  StrDoubleQuote returns a copy of the string encapsulated in double quotes (").
  That is, if you pass in 'Project JEDI' you'll get '"Project JEDI"' back. If double
  quotes (") are already at the beginning and the end of the string they are added again.
  If they should be added only if they are not already there use StrQuote instead.
Parameters:
  S - The string to encapsulate in quotes. Even an empty string.
Result:
  The double-quoted version of the string.
See also:
  StrQuote
  StrSingleQuote
  StrTrimQuotes
Donator:
  Anthony Steele
--------------------------------------------------------------------------------
@@StrEnsurePrefix
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Forces Text to start with Prefix.
Description:
  StrEnsurePrefix tests whether the supplied text start with the supplied prefix.
  If it doesn't then the prefix is prepended to the string otherwise the function
  does nothing. Note that if Text is an empty string then the result will be Prefix.
Parameters:
  Prefix - The prefix to test for and apply.
  Text - The string which must be forced to have a prefix.
Result:
  The function result is a copy of the supplied Text, prefixed with Prefix.
See also:
  StrEnsureNoPrefix
  StrEnsureSuffix
Donator:
  Nick Hodges
--------------------------------------------------------------------------------
@@StrEnsureNoPrefix
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Eventually removes Prefix from Text.
Description:
  StrEnsureNoPrefix tests whether the supplied text start with the supplied prefix.
  If it does then the prefix is deleted from the string otherwise the function
  does nothing.
Parameters:
  Prefix - The prefix to test for and apply.
  Text - The string which must not have a prefix.
Result:
  The function result is a copy of the supplied Text, eventually minus the prefix.
See also:
  StrEnsurePrefix
  StrEnsureNoSuffix
Donator:
  Olivier Sannier
--------------------------------------------------------------------------------
@@StrEnsureSuffix
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Forces Text to end with Suffix.
Description:
  StrEnsureSuffix tests whether the supplied text ends in the supplied suffix.
  If it doesn't then the suffix is appended to the string otherwise the function
  does nothing. Note that if Text is an empty string then the result will be Suffix.
Parameters:
  Suffix - The suffix to test for and apply.
  Text - The string which must be forced to have a suffix.
Result:
  The function result is a copy of the supplied Text, with the suffix.
See also:
  StrEnsureNoSuffix
  StrEnsurePrefix
Donator:
  Marcel van Brakel
--------------------------------------------------------------------------------
@@StrEnsureNoSuffix
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Eventually removes Suffix from Text.
Description:
  StrEnsureSuffix tests whether the supplied text ends in the supplied suffix.
  If it does then the suffix is deleted from the string otherwise the function
  does nothing.
Parameters:
  Suffix - The suffix to test for and apply.
  Text - The string which must not have a suffix.
Result:
  The function result is a copy of the supplied Text, eventually minus the suffix.
See also:
  StrEnsureSuffix
  StrEnsureNoPrefix
Donator:
  Olivier Sannier
--------------------------------------------------------------------------------
@@StrEscapedToString
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Converts an escaped string to a string.
Description:
  StrEscapedToString converts a string which contains escape characters to a string
  without escape characters by replacing all escape characters with their string
  counterparts. For example, a string which contains a '\a' sequence will
  have the '\a' sequence replaced with the BELL character #7.
  The supported escape characters are:
   <TABLE>
Character  Value  Constant   Description
---------  -----  ---------  ------------------
\a         #7     BELL       Bell
\b         #8     BACKSPACE  Backspace
\f         #12    FF         Form Feed
\n         #10    LR         Line Feed
\r         #13    CR         Carrage Return
\t         #9     TAB        Tabulator
\v         #11    VT         Vertical Tabulator
\\         N/A    N/A        Backslash
\"         N/A    N/A        Double quotes
</TABLE>

  In addition it supports hexadecimal escape sequences (sequences that start with \x)
  and octal escape sequences (sequences starting with '\0', '\1' ... '\9').
  The StrStringToEscaped is the "inverse" of this function.
Parameters:
  S - The "escaped" string to convert to a "normal" string.
Result:
  The string with all escape characters replaced with their string counterparts.
See also:
  StrStringToEscaped
Donator:
  Robert Marquardt
--------------------------------------------------------------------------------
@@StrLower
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Lowercases all characters in a string.
Description:
  StrLower returns a copy of the string, converted to lowercase. That is, if you pass in 'Project JEDI' you'll get 'project jedi'.
Parameters:
  S - String to convert to lowercase.
See also:
  StrLowerInPLace
  StrLowerBuff
  StrUpper
  StrUpperInPlace
  StrUpperBuff
Donator:
  Pelle F. S. Liljendal
--------------------------------------------------------------------------------
@@StrLowerInPlace
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Lowercases all characters in a string.
Description:
  StrLower converts all characters in the supplied string to lowercase.
Parameters:
  S - String to convert to lowercase.
See also:
  StrLower
  StrLowerBuff
  StrUpper
  StrUpperInPlace
  StrUpperBuff
Donator:
  Azret Botash
--------------------------------------------------------------------------------
@@StrLowerBuff
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Lowercases all characters in a string.
Description:
  StrLowerBuff converts all characters in the supplied string to lowercase.
Parameters:
  P - String to convert to lowercase.
See also:
  StrLower
  StrLowerInPlace
  StrUpper
  StrUpperInPlace
  StrUpperBuff
Donator:
  Azret Botash
--------------------------------------------------------------------------------
@@StrMove
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Copies a sub-string from one string to another.
Description:
  StrMove copies Count characters starting at FromIndex in the source string to
  the destination string starting at ToIndex. The function checks the passed
  parameters and if any is illegal the function does nothing. This includes
  illegal indices and, for example, a zero-length destination string.
Parameters:
  Dest - The destination string which the sub-string is copied to.
  Source - The source string from which the sub-string is copied.
  ToIndex - The index into the destination string at which the sub-string is copied.
  FromIndex - The starting index into the source string from which count characters are copied.
  Count - Length of the sub-string to copy in characters.
Donator:
  Azret Botash
--------------------------------------------------------------------------------
@@StrPadLeft
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Left pads a string with characters.
Description:
  StrPadLeft left pads a string with the specified character until the resulting
  string is Len characters long. If the source string is already greater than or
  equal in length to Len the function does nothing.
Parameters:
  S - Source string to left pad.
  Len - The length of the resulting string.
  C - The character to pad the string with.
Result:
  The string left padded with the specified character.
See also:
  StrPadRight
  StrCenter
Donator:
  Marcel van Brakel
--------------------------------------------------------------------------------
@@StrPadRight
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Right pads a string with characters.
Description:
  StrPadRight right pads a string with the specified character until the resulting
  string is Len characters long. If the source string is already greater than or equal
  in length to Len the function does nothing.
Parameters:
  S - Source string to right pad.
  Len - The length of the resulting string.
  C - The character to pad the string with.
Result:
  The string right padded with the specified character.
See also:
  StrPadLeft
  StrCenter
Donator:
  Marcel van Brakel
--------------------------------------------------------------------------------
@@StrProper
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Lowercases the supplied string and uppercases the first character.
Description:
  The StrProper routine lowercases the entire string and subsequently uppercases
  the first character.
Parameters:
  S - The string to transform.
Result:
  The transformed string.
Donator:
  Azret Botash
--------------------------------------------------------------------------------
@@StrProperBuff
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Lowercases the supplied string and uppercases the first character.
Description:
  The StrProper routine lowercases the entire string and subsequently uppercases
  the first character.
Parameters:
  S - The string to transform.
Donator:
  Azret Botash
--------------------------------------------------------------------------------
@@StrQuote
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Quotes a string with a specific character.
Description:
  StrQuote quotes the string with a specified character. Upon return the string is
  guarenteed to begin and end with the specified character. Note that if the string
  already starts or ends with this character, it is not added again.
Parameters:
  S - The string to quote.
  C - The character with which to quote the string.
Result:
  The quoted string.
Donator:
  Azret Botash
--------------------------------------------------------------------------------
@@StrRemoveChars
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Removes a set of characters from a string.
Description:
  StrRemoveChars removes all instances of the characters in the set from the source
  string. For example, if you pass in 'Joint Endeavour of Delphi Innovators' and
  specify ['e', 'a', 'o', 'u', 'i'] the resulting string will be 'Jnt Endvr f Dlph Innvtrs'.
Parameters:
  S - The source string from which to remove the characters.
  Chars - The set of characters which are removed from S.
Result:
  The string with all characters from the supplied set removed.
Notes:
  The function is case sensitive. That is, specifying 'e' will not remove 'E'.
Donator:
  Marcel van Brakel
--------------------------------------------------------------------------------
@@StrRepeat
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Repeats a string Count number of times.
Description:
  The StrRepeat routine returns a string consisting of the specified string, repeated
  Count number of times. For example, StrRepeat('He', 3) returns 'HeHeHe'.
Parameters:
  S - The string to repeat.
  Count - The number of times to repeat the specified string.
Result:
  The specified string, repeated Count number of times.
Donator:
  Marcel van Brakel
--------------------------------------------------------------------------------
@@StrReverse
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Reverses a string.
Description:
  StrReverse returns a reversed copy of S. That is, if you pass in 'Delphi' the
  function result will be 'ihpleD'. Note that the original string remains unmodified,
  as the const modifier indicates. If you don't need the original string after
  reversing it, then do not write code like S := StrReverse(S) but instead use
  the StrReverseInPlace function because it's much faster.
Parameters:
  S - The string to reverse.
Result:
  A reversed copy of the supplied string.
See also:
  StrReverseInPlace
Donator:
  Marcel van Brakel
--------------------------------------------------------------------------------
@@StrReverseInPlace
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Reverses a string.
Description:
  StrReverse reverses S. That is, if you pass in 'Delphi' then after the function
  returns S contains the string 'ihpleD'. If you need to retain the original
  string then use the StrReverse function instead.
Parameters:
  S - The string to reverse.
See also:
  StrReverse
Donator:
  Marcel van Brakel
--------------------------------------------------------------------------------
@@StrSingleQuote
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Returns a single-quoted version of the string.
Description:
  StrSingleQuote returns a copy of the string encapsulated in single quotes (').
  That is, if you pass in 'Project JEDI' you'll get ''Project JEDI'' back.
Parameters:
  S - The string to encapsulate in quotes. Even an empty string.
Result:
  The single-quoted version of the string.
See also:
  StrDoubleQuote
  StrTrimQuotes
Donator:
  Anthony Steele
--------------------------------------------------------------------------------
@@StrSmartCase
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Converts a string to 'smartcase' or 'camelcase'.
Description:
  StrSmartCase converts specified characters within the supplied source string to
  uppercase. The characters that are uppercased are determined by the Delimiters
  character set. Each time the function finds a character in the source string that
  is also present in the Delimiters set it uppercases the next character
  in the source string. In addition, the function always converts the first character
  to uppercase. For example, if you call StrSmartCase('project jedi rules', [' '])
  the function returns 'Project Jedi Rules'. As you can see, all characters that
  immediately follow a space (as specified by Delimiters) are uppercased.
Parameters:
  S - Source string.
  Delimiters - Set of characters to use as delimiters. These characters determine which other
  characters are uppercased. If you supply an empty set the function assumes you want to use a
  space only. That is, it sets Delimiters to [' '].
Result:
  The string converted to smart case.
Notes:
  Original author is John C Molyneux (jaymol@hotmail.com). Function was rewritten by
  Marcel van Brakel.
Donator:
  Marcel van Brakel
--------------------------------------------------------------------------------
@@StrStringToEscaped
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Converts a string to an escaped string.
Description:
  StrStringToEscaped converts a string to an escaped string by replacing non-visual
  character sequences with their escape characters. For example, if a string contains
  the character #7 the resulting string will have the #7 character replaced with the '\a'
  sequence. This function is the inverse of StrEscapedToString.
  The function supports the following escape characters:
   <TABLE>
Character  Value  Constant   Description
---------  -----  ---------  ------------------
\a         #7     BELL       Bell
\b         #8     BACKSPACE  Backspace
\f         #12    FF         Form Feed
\n         #10    LR         Line Feed
\r         #13    CR         Carrage Return
\t         #9     TAB        Tabulator
\v         #11    VT         Vertical Tabulator
\\         N/A    N/A        Backslash
\"         N/A    N/A        Double quotes
</TABLE>

  All other characters whose ordinal value are smaller than Ord(' ') are escaped
  as a hexadecimal sequence like '\x01'. The StrEscapedToString is the "inverse"
  of this function.
Parameters:
  S - The string to convert to an escaped string.
Result:
  The "escaped" string.
See also:
  StrEscapedToString
Donator:
  Robert Marquardt
--------------------------------------------------------------------------------
@@StrStripNonNumberChars
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Removes all non-number characters from a string.
Description:
  StrStripNonNumberChars removes all non-number characters from the specified string.
  Hence the resulting string will contain only number characters. Testing whether
  the individual characters are numbers is done using the CharIsNumberChar routine and
  therefore characters that qualify are all digits (0..9), signs (+, -) and decimal
  separators.
Parameters:
  S - The string from which to remove non-number characters.
Result:
  The string after all non-number characters are removed.
Donator:
  Anthony Steele
--------------------------------------------------------------------------------
@@StrTrimQuotes
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Removes surrounding quotes from the supplied string.
Description:
  StrTrimQuotes removes surrounding quotes, either single or double-quotes, from
  the string. For example if you pass in ''Project JEDI'' you'll get 'Project JEDI'
  back. Note that this function only removes quotes if the string both begins and
  ends with the same quote character.
Parameters:
  S - The string to unquote.
Result:
  The unquoted string.
See also:
  StrSingleQuote
  StrDoubleQuote
Donator:
  Anthony Steele
--------------------------------------------------------------------------------
@@StrToHex
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Converts a string of hex digit pairs to the corresponding bytes.
Description:
  The Source string is expected to contain pairs of hex digit
  characters ['0'..'9', 'a'..'f', 'A'..'F']. Each pair is converted to a single
  byte thus converting '40' to '@'. Any character not from the hex set
  results in an empty string. If the string length of the Source is odd
  then a '0' is prepended internally to make up the first byte.
Parameters:
  S - A string of hex digit pairs to be converted.
Result:
  The string of converted bytes.
Donator:
  Azret Botash
--------------------------------------------------------------------------------
@@StrTrimCharLeft
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Removes leading characters from a string.
Description:
  The StrTrimCharLeft routine removes leading characters from the specified string.
  For example, StrTrimCharLeft('000123', '0') returns '123'.
Parameters:
  S - The source string from which the leading characters need to be removed.
  C - The character to remove.
Result:
  The function returns the source string S without any leading characters C.
See also:
  StrTrimCharRight
Donator:
  Jack N.A. Bakker
--------------------------------------------------------------------------------
@@StrTrimCharRight
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Removes trailing characters from a string.
Description:
  The StrTrimCharRight routine removes trailing characters from the specified string.
  For example, StrTrimCharRight('123000', '0') returns '123'.
Parameters:
  S - The source string from which the trailing characters need to be removed.
  C - The character to remove.
Result:
  The function returns the source string S without any trailing characters C.
See also:
  StrTrimCharLeft
Donator:
  Jack N.A. Bakker
--------------------------------------------------------------------------------
@@StrUpper
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Uppercases all characters in a string
Description:
  StrUpper returns a copy of the string, converted to uppercase. That is, if you pass
  in 'Project JEDI' you'll get 'PROJECT JEDI'.
Parameters:
  S - String to convert to uppercase.
See also:
  StrUpperInPlace
  StrUpperBuff
  StrLower
  StrLowerInPlace
  StrLowerBuff
Donator:
  Azret Botash
--------------------------------------------------------------------------------
@@StrUpperInPlace
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Uppercases all characters in a string.
Description:
  StrUpper converts all characters in the supplied string to uppercase.
Parameters:
  S - String to convert to uppercase.
See also:
  StrUpper
  StrUpperBuff
  StrLower
  StrLowerInPlace
  StrLowerBuff
Donator:
  Azret Botash
--------------------------------------------------------------------------------
@@StrUpperBuff
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Uppercases all characters in a string.
Description:
  StrUpper converts all characters in the supplied string to uppercase.
Parameters:
  S - String to convert to uppercase.
See also:
  StrUpper
  StrUpperInPlace
  StrLower
  StrLowerInPlace
  StrLowerBuff
Donator:
  Azret Botash
--------------------------------------------------------------------------------
@@StrAddRef
<GROUP StringManipulation.StringManagement>
Summary:
  Increments the reference count of a long string.
Description:
  The StrAddRef routine increments the reference count of the specified long string.
  Explicitly incrementing a strings reference count forces Delphi to keep the string
  in memory even if the variable itself goes out of scope and all other references
  were removed already. Note that if the string points to a string constant this
  routine will call UniqueString on it forcing a string copy, after which the
  reference count becomes 1.
Parameters:
  S - The long string whose reference count to increment.
See also:
  StrDecRef
Donator:
  Marcel van Brakel
--------------------------------------------------------------------------------
@@StrAllocSize
<GROUP StringManipulation.StringManagement>
Summary:
  Returns the memory allocated to store the string.
Description:
  A long string variable is a 4 byte pointer to a dynamically allocated block of
  memory. This block of memory holds the actual string data, including a NULL
  character. In addition this block of memory has, at a negative offset, a number
  of 32 bit values used to manage the string. The StringAllocSize function looks
  at this negative offset to determine the total amount of dynamic memory reserved
  to hold the string and management data.
  Note that this function will always return 0 for string literals, string constants
  and string variables that are assigned to string constants, but haven't been
  modified yet. This is not a bug but a result of the way in which Delphi manages
  string constants.
Parameters:
  S - The string for which to determine the total amount of used memory.
Result:
  The amount of dynamic memory allocated for the string or 0 in the exceptions noted
  above. Note that, at least in Delphi 5, the result will always be a multiple of 4.
Notes:
  This function relies on pseudo-undocumented knowledge and should only be used for
  debugging purposes.
See also:
  StrRefCount
Donator:
  Marcel van Brakel
--------------------------------------------------------------------------------
@@StrDecRef
<GROUP StringManipulation.StringManagement>
Summary:
  Decrements the reference count of a long string.
Description:
  The StrDecRef routine decrements the reference count of the specified long string.
  Note that if decrementing the reference count will set it to 0 the string is
  released and the string pointer is set to nil. Therefore the string may be
  inaccessible after calling this routine.
Parameters:
  S - The long string whose reference count to increment. Upon return the string may
  have been freed.
See also:
  StrDecRef
Donator:
  Marcel van Brakel
--------------------------------------------------------------------------------
@@StrLen
<GROUP StringManipulation.StringManagement>
Summary:
  Returns the length of the supplied string.
Description:
  StrLen returns the length of the supplied string, in characters, excluding the
  null terminating character. This function is identical to the StrLen routine from
  SysUtils.pas except that it is much faster.
Parameters:
  S - Pointer to the null terminated string for which to determine the length.
Result:
  The length of the string, in characters.
Donator:
  Robert Lee
--------------------------------------------------------------------------------
@@StrLength
<GROUP StringManipulation.StringManagement>
Summary:
  Returns the length of the supplied string.
Description:
  StrLength returns the length of the supplied string. This is a duplication of the
  standard Delphi Length function and is only supplied for completeness. You should
  prefer the Length function over StrLength.
Parameters:
  S - The string for which to determine the length.
Result:
  The length of the string in characters.
Notes:
  This function relies on pseudo undocumented knowledge.
See also:
  StrAllocSize
  StrRefCount
Donator:
  Marcel van Brakel
--------------------------------------------------------------------------------
@@StrRefCount
<GROUP StringManipulation.StringManagement>
Summary:
  Returns the reference count of the supplied string.
Description:
  StrRefCount returns the reference count of the string. Note that this function
  will always return -1 for string literals, string constants and string variables
  that are assigned to string constants, but haven't been modified yet. This is
  not a bug but a result of the way in which Delphi manages string constants.
Parameters:
  S - String for which to determine the reference count.
Result:
  The reference count of the string or -1 if the string ultimately points to a
  string constant.
Notes:
  This function relies on pseudo-undocumented knowledge and should only be used for
  debugging purposes.
See also:
  StrAllocSize
Donator:
  Marcel van Brakel
--------------------------------------------------------------------------------
@@StrResetLength
<GROUP StringManipulation.StringManagement>
Summary:
  Resets the length of the supplied string.
Description:
  StrResetLength resets the length of the string to encompass only the actual number
  of used characters. This is particularly useful when passing strings to API
  functions which accept PChar's. These kind of functions do modify the string but
  since they are unaware of how Delphi manages strings, the length is not changed
  on return. Depending on how you use the string from that point on the results
  may be incorrect if you do not apply StrResetLength.
  The function resets the length to the C string length, i. e. the length up to the first #0 byte.
Parameters:
  S - The string whose length to reset.
Donator:
  Marcel van Brakel
--------------------------------------------------------------------------------
@@StrCharCount
<GROUP StringManipulation.StringSearchandReplaceRoutines>
Summary:
  Counts the occurrences of a character in a string.
Description:
  StrCharCount returns the number of occurrences of the specified character in the
  supplied string.
Parameters:
  S - Source string.
  C - The character whose occurrences to count.
Result:
  The number of occurrences of C in S.
Donator:
  Massimo Maria Ghisalberti
--------------------------------------------------------------------------------
@@StrCompare
<GROUP StringManipulation.StringTestRoutines>
Summary:
  Compares two strings.
Description:
  StrCompare implements a case-insensitive comparison between the two supplied
  strings. If the two strings match the function returns 0 otherwise it returns
  the number of different characters. If the supplied strings are of equal length
  but are not identical the function returns the difference of the first mismatched
  character. The table below demonstrates this:
   <TABLE>
S1            S2            Result
------------  ------------  ------------------------------
jedi          jedi          0
jedi          je            2
di            jedi          -2
project jedi  jedi          8
jedi          project jedi  -8
jedi          judi          Ord('e') - Ord('u')
JEDI          Judi          Ord(LowerCase('E')) - Ord('u')
</TABLE>

Parameters:
  S1 - First string to compare.
  S2 - Second string to compare.
Result:
  StrCompare returns 0 if the two strings match or the number of different characters
  in case of a mismatch.
Donator:
  Azret Botash
--------------------------------------------------------------------------------
@@StrCompareRange
<GROUP StringManipulation.StringSearchandReplaceRoutines>
Description:
  StrCompareRange compares, case-sensitive, a sub-string from the
  first supplied string with the second string. If the two
  strings are identical the function returns 0 otherwise it
  returns an indication of difference between the two strings,
  The result is equal to the result returned by StrCompare. This
  function is particularly useful to avoid code such as: "if
  Copy(S, 1, 4) = 'JEDI' then ..." which is quite inefficient.
  This code would be rewritten to: "if StrCompareRange(S1,
  'JEDI', 1, 4) = 0 then ...".
Summary:
  Compares two (sub) strings.
Parameters:
  Count - Number of characters of the sub-string in S1 to compare to S2.
  Index - Starting index of sub-string in S1 to.
  S1 - First string to compare.
  S2 - Second string to compare.
Result:
  StrCompareRange returns 0 if the two strings match or the
  number of different characters in case of a mismatch.
See also:
  StrCompare
Donator:
  Azret Botash
--------------------------------------------------------------------------------
@@StrFillChar
<GROUP StringManipulation.StringSearchandReplaceRoutines>
Summary:
  Creates a string consisting of the specified character repeated Count times.
Description:
  The StrFillChar routine returns a string consisting of the specified character
  repeated Count number of times.
Parameters:
  C - The character to repeat.
  Count - The number of times to repeat the character.
Result:
  A string consisting of the specified character repeated Count times.
Donator:
  Marcel van Brakel
--------------------------------------------------------------------------------
@@StrFind
<GROUP StringManipulation.StringSearchandReplaceRoutines>
Summary:
  Returns the index of the first character in a specified sub-string that occurs in a given string.
Description:
  StrFind returns the index of the first character in a specified sub-string that
  occurs in a given string. The search starts at the supplied index and is case-insensitive.
Parameters:
  Substr - The sub-string to search for.
  Str - The string in which to search.
  Index - The index in Str at which to start the search.
Result:
  One-based index of the first character of SubStr in Str or 0 if SubStr does not
  occur in the supplied string.
See also:
  StrSearch
Donator:
  Azret Botash
--------------------------------------------------------------------------------
@@StrHasPrefix
<GROUP StringManipulation.StringSearchandReplaceRoutines>
Summary:
  Returns whether a string is prefixed by one of the supplied strings.
Description:
  StrHasPrefix returns whether the string is prefixed with at least one of the strings
  supplied in the Prefixes array. In other words, for each string in the Prefixes
  array it's determined if the supplied string starts with that prefix. Note that
  the routine exits as soon as a match is found and matching is case-sensitive (use
  StrIHasPrefix for a case-insensitive matching version).
Parameters:
  S - The string to test.
  Prefixes - Array of prefixes to test for.
Result:
  If the supplied string is prefixed with one of the supplied prefixes the routine
  returns True, otherwise it returns False.
See also:
  StrIHasPrefix, StrPrefixIndex
Donator:
  Anthony Steele
--------------------------------------------------------------------------------
@@StrIHasPrefix
<GROUP StringManipulation.StringSearchandReplaceRoutines>
Summary:
  Returns whether a string is prefixed by one of the supplied strings.
Description:
  StrHasPrefix returns whether the string is prefixed with at least one of the strings
  supplied in the Prefixes array. In other words, for each string in the Prefixes
  array it's determined if the supplied string starts with that prefix. Note that
  the routine exits as soon as a match is found and matching is case-insensitive (use
  StrHasPrefix for a case-sensitive matching version).
Parameters:
  S - The string to test.
  Prefixes - Array of prefixes to test for.
Result:
  If the supplied string is prefixed with one of the supplied prefixes the routine
  returns True, otherwise it returns False.
See also:
  StrHasPrefix, StrIPrefixIndex
Donator:
  Anthony Steele
--------------------------------------------------------------------------------
@@StrIndex
<GROUP StringManipulation.StringSearchandReplaceRoutines>
Summary:
  Returns the index of a string in an array of strings.
Description:
  StrIndex returns the index into the List array at which S is positioned. This is
  particularly useful to create a case statement based on string labels. For example:

    case StrIndex(S, ['zero', 'one', 'two']) of
      0: // handle case where S = 'zero'
      1: // handle case where S = 'one'
      2: // handle case where S = 'two'
    else
      //
    end;
    
Parameters:
  S - The string to test.
  List - Array of strings to search in.
Result:
  If the supplied string exists in the List array the zero based index of the position
  at which it appears is returned. If the string doesn't exist in the array -1 is
  returned. Note that the string comparison is case insensitive but is based on the
  current locale (ie it uses AnsiSameText).
Donator:
  Anthony Steele
--------------------------------------------------------------------------------
@@StrILastPos
<GROUP StringManipulation.StringSearchandReplaceRoutines>
Summary:
  Returns the index of the last occurrence of SubStr in S.
Description:
  StrILastPos scans the supplied string and returns the index of the first character
  of the last occurrence of the supplied sub-string. The comparison is case-insensitive.
Parameters:
  SubStr - The sub-string to find the last occurrence of.
  S - The string in which to search.
Result:
  The index of the last occurrence of SubStr in S. If the sub-string does not exist
  at all the result is 0.
See also:
  StrLastPos
Donator:
  Anthony Steele
--------------------------------------------------------------------------------
@@StrLastPos
<GROUP StringManipulation.StringSearchandReplaceRoutines>
Summary:
  Returns the index of the last occurrence of SubStr in S.
Description:
  StrLastPos scans the supplied string and returns the index of the first character
  of the last occurrence of the supplied sub-string. The comparison is case-sensitive.
Parameters:
  SubStr - The sub-string to find the last occurrence of.
  S - The string in which to search.
Result:
  The index of the last occurrence of SubStr in S. If the sub-string does not exist
  at all the result is 0.
See also:
  StrILastPos
Donator:
  Marcel van Brakel
--------------------------------------------------------------------------------
@@StrIPos
<GROUP StringManipulation.StringSearchandReplaceRoutines>
Summary:
  Returns the index of the first occurrence of SubStr in S.
Description:
  StrIPos scans the supplied string and returns the index of the first character
  of the first occurrence of the supplied sub-string. The comparison is case-insensitive.
Parameters:
  SubStr - The sub-string to find the first occurrence of.
  S - The string in which to search.
Result:
  The index of the first occurrence of SubStr in S. If the sub-string does not exist
  at all the result is 0.
Donator:
  Anthony Steele
--------------------------------------------------------------------------------
@@StrIPrefixIndex
<GROUP StringManipulation.StringSearchandReplaceRoutines>
Summary:
  Returns the index at which a string appears which is used as a prefix.
Description:
  StrPrefixIndex returns the index into the prefixes array at which a string appears
  with which the supplied string is prefixed. For example,
  StrPrefixIndex('banana', ['call', 'ban', 'bana']) will return 1. Note that as
  can be seen from the example, as soon as a prefix is found the routine stops and
  doesn't attempt to find a better (longer) match. Matching is case-insensitive; use
  StrPrefixIndex for a case-insensitive version.
Parameters:
  S - The string to test.
  Prefixes - The list of prefixes.
Result:
  The zero based index into Prefixes at which the first string appears that is used
  as a prefix in the supplied string. If none of the Prefixes array strings qualifies
  the result is -1.
See Also
  StrIHasPrefix, StrPrefixIndex
Donator:
  Anthony Steele
--------------------------------------------------------------------------------
@@StrIsOneOf
<GROUP StringManipulation.StringSearchandReplaceRoutines>
Summary:
  Tests whether the supplied string exists in the list of strings.
Description:
  StrIsOneOf tests whether the supplied string exists in the list of strings. Note
  that the comparison is case-insensitive.
Parameters:
  S - The string to test.
  List - The list of string in which to search.
Result:
  If the string exists in the supplied list the result is True, otherwise it's False.
Donator:
  Anthony Steele
--------------------------------------------------------------------------------
@@StrNPos
<GROUP StringManipulation.StringSearchandReplaceRoutines>
Summary:
  Returns the position of the N-th occurence of a sub-string within a string.
Description:
  StrNPos returns the index into S of the N-th occurence of the specified sub-string.
  This function is case-sensitive and does not work with multibyte character sets.
  If the specified sub-string does not have N occurence in S the function returns 0.
Parameters:
  S - The string in which to search for N occurences of SubStr.
  SubStr - The sub-string to search for.
  Index - The number of occurences of sub-string in S.
Result:
  Index into S where the N-th occurence of SubStr is located. If SubStr has less
  than N occurences in S the result is 0.
Notes:
  This function was inspired by code submitted by George Tasker
See also:
  StrNIPos
Donator:
  Team JCL
--------------------------------------------------------------------------------
@@StrNIPos
<GROUP StringManipulation.StringSearchandReplaceRoutines>
Summary:
  Returns the position of the N-th occurence of a sub-string within a string.
Description:
  StrNPos returns the index into S of the N-th occurence of the specified sub-string.
  This function is case-insensitive and does not work with multibyte character sets.
  If the specified sub-string does not have N occurence in S the function returns 0.
Parameters:
  S - The string in which to search for N occurences of SubStr.
  SubStr - The sub-string to search for.
  N - The number of occurences of sub-string in S.
Result:
  Index into S where the N-th occurence of SubStr is located. If SubStr has less
  than N occurences in S the result is 0.
Notes:
  This function was inspired by code submitted by George Tasker
See also:
  StrNPos
Donator:
  Team JCL
--------------------------------------------------------------------------------
@@StrMatch
<GROUP StringManipulation.StringSearchandReplaceRoutines>
Summary:
  Returns the index of the first character in a specified sub-string that occurs in a given string.
Description:
  StrMatch returns the index of the first character in a specified sub-string that
  occurs in a given string. The search starts at the supplied index and is case-insensitive.
  The specified sub-string may contain wildcards. The '?' wildcard matches 1 character
  while the '*' wildcard matches 0 or more occurrences of a character. For example, 'J?DI'
  will find 'JEDI', 'JZDI' and 'JODI' (and more) while 'J*I' will find 'JEDI' and 'JI'.
Parameters:
  Substr - The sub-string to search for. May contain wildcards.
  Str - The string in which to search.
  Index - The index in Str at which to start the search.
Result:
  One-based index of the first character of SubStr in Str or 0 if SubStr does not
  occur in the supplied string.
Notes:
  The '*' wildcard currently doesn't work correctly, it produces the same result as '?'.
See also:
  StrSearch
Donator:
  Azret Botash
--------------------------------------------------------------------------------
@@StrPrefixIndex
<GROUP StringManipulation.StringSearchandReplaceRoutines>
Summary:
  Returns the index at which a string appears which is used as a prefix.
Description:
  StrPrefixIndex returns the index into the prefixes array at which a string appears
  with which the supplied string is prefixed. For example,
  StrPrefixIndex('banana', ['call', 'ban', 'bana']) will return 1. Note that as
  can be seen from the example, as soon as a prefix is found the routine stops and
  doesn't attempt to find a better (longer) match. Matching is case-sensitive; use
  StrIPrefixIndex for a case-insensitive version.
Parameters:
  S - The string to test.
  Prefixes - The list of prefixes.
Result:
  The zero based index into Prefixes at which the first string appears that is used
  as a prefix in the supplied string. If none of the Prefixes array strings qualifies
  the result is -1.
See Also
  StrHasPrefix, StrIPrefixIndex
Donator:
  Anthony Steele
--------------------------------------------------------------------------------
@@StrSearch
<GROUP StringManipulation.StringSearchandReplaceRoutines>
Summary:
  Returns the index of the first character in a specified sub-string that occurs in a given string.
Description:
  StrSearch returns the index of the first character in a specified sub-string that
  occurs in a given string. The search starts at the supplied index and is case-sensitive.
Parameters:
  Substr - The sub-string to search for.
  Str - The string in which to search.
  Index - The index in Str at which to start the search.
Result:
  One-based index of the first character of SubStr in Str or 0 if SubStr does not
  occur in the supplied string.
See also:
  StrFind
Donator:
  Azret Botash
--------------------------------------------------------------------------------
@@StrAfter
<GROUP StringManipulation.StringExtraction>
Summary:
  Returns the portion of the string after a specific sub-string.
Description:
  The StrAfter routine returns that portion of the specified string that appears
  after a specified sub-string. For example, StrAfter('Hello', 'Hello world') returns
  the string ' world'.
Parameters:
  SubStr - The sub-string to search for.
  S - The source string.
Result:
  The portion of the string after the specified sub-string. If the sub-string does
  not appear in the source string the result is an empty string.
See also:
  StrBefore
Donator:
  Anthony Steele
--------------------------------------------------------------------------------
@@StrBefore
<GROUP StringManipulation.StringExtraction>
Summary:
  Returns the portion of the string before a specific sub-string.
Description:
  The StrBefore routine returns that portion of the specified string that appears
  before a specified sub-string. For example, StrBefore('world', 'Hello world') returns
  the string 'Hello '.
Parameters:
  SubStr - The sub-string to search for.
  S - The source string.
Result:
  The portion of the string before the specified sub-string. If the sub-string does
  not appear in the source string the result is the source string.
See also:
  StrAfter
Donator:
  Anthony Steele
--------------------------------------------------------------------------------
@@StrBetween
<GROUP StringManipulation.StringExtraction>
Summary:
  Returns the sub-string between the first occurences of Start and Stop.
Description:
  The StrBetween routine returns the that portion of the string that appears between
  the first occurences of the Start and Stop characters. For example,
  StrBetween('Hello world', 'e', 'r') returns 'llo wo'. Note that if the position
  of Start is greater than Stop, or either of these characters is not found in the
  source string, the result is an empty string. If the Start and Stop symbols are
  equal StrBetween returns the string between the first and second occurence of
  that particular symbol. 
Parameters:
  S - The source string from which to extract the sub-string
  Start - The character which denotes the start of the sub-string to extract.
  Stop - The character which denotes the end of the sub-string to extract.
Result:
  If the function succeeds, it returns the sub-string between the first occurence of
  Start and Stop, not including either of these characters. If the function fails
  it returns an empty string, for example if the Start and/or Stop character doesn't
  appear in the sources string.
Donator:
  Anthony Steele
--------------------------------------------------------------------------------
@@StrChopRight
<GROUP StringManipulation.StringExtraction>
Summary:
  Removes the last N characters from the string.
Description:
  StrChopRight removes the last N characters from the specified string and returns
  the resulting string.
Parameters:
  S - The source string from which the characters are removed.
  N - The number of characters to remove from the end of the string.
Result:
  The string with the last N characters cut off. Note that when N is larger than
  the string length, the result is an empty string.
Donator:
  Anthony Steele
--------------------------------------------------------------------------------
@@StrLeft
<GROUP StringManipulation.StringExtraction>
Summary:
  Returns the Count leftmost characters from the string.
Description:
  StrLeft returns the Count number of leftmost characters from the supplied string.
  Note that if the supplied string contains fewer than Count characters, the function
  returns the entire string.
Parameters:
  S - The string from which to copy.
  Count - The number of characters to copy.
Result:
  The Count leftmost characters from S.
See also:
  StrRight
Donator:
  Anthony Steele
--------------------------------------------------------------------------------
@@StrMid
<GROUP StringManipulation.StringExtraction>
Summary:
  Copies part of a string.
Description:
  StrMid copies the part of the source string defined by Start and Count.
  If Start exceeds the length of the string then an empty string is returned.
  The extracted sub-string can be shorter than Count if Start+Count exceed the string length.
Parameters:
  S - Source string.
  Start - Index of the first character to copy.
  Count - Number of characters to copy.
Result:
  The string copied from S starting at offset Start and with length Count.
Donator:
  John C Molyneux
--------------------------------------------------------------------------------
@@StrRestOf
<GROUP StringManipulation.StringExtraction>
Summary:
  Returns the remainder of a string starting at the specified index.
Description:
  StrRestOf returns the remainder of the the string starting at index N. For example,
  StrRestOf('Project JEDI', 9) returns 'JEDI' (index 9 through Length(S)).
Parameters:
  S - The source string from which to copy.
  N - The starting index of the characters to copy.
Result:
  The remainder of the string starting at the specified index.
Donator:
  Anthony Steele
--------------------------------------------------------------------------------
@@StrRight
<GROUP StringManipulation.StringExtraction>
Summary:
  Returns the Count rightmost characters from the string.
Description:
  StrRight returns the Count number of rightmost characters from the supplied string.
  Note that if the supplied string contains fewer than Count characters, the function
  returns the entire string.
Parameters:
  S - The string from which to copy.
  Count - The number of characters to copy.
Result:
  The Count of rightmost characters from S.
See also:
  StrLeft
Donator:
  Anthony Steele
--------------------------------------------------------------------------------
@@CharEqualNoCase
<GROUP StringManipulation.CharacterTestRoutines>
Summary:
  Test whether two characters are equal except possibly for case.
Description:
  CharEqualNoCase determines whether two characters are equal except possibly for
  case differences. For example, 'a' and 'a' are obviously equal but so are 'a' and 'A'.
Parameters:
  C1 - The first character to test.
  C1 - The second character to test.
Result:
  If the supplied characters are equal except for case, the result is True, otherwise
  the result is False.
Donator:
  Anthony Steele
--------------------------------------------------------------------------------
@@CharIsAlpha
<GROUP StringManipulation.CharacterTestRoutines>
Summary:
  Tests whether C is an alpha character.
Description:
  CharIsAlpha returns whether or not the supplied character is an alpha character.
  That is, if C comes from the ['a'..'z', 'A'..'Z'] set.
Parameters:
  C - The character to test
Result:
  If C is an alpha character the return value is True, otherwise the return value is False.
See also:
  CharIsDigit
  CharIsNumberChar
  CharIsAlphaNum
Donator:
  Marcel van Brakel
--------------------------------------------------------------------------------
@@CharIsAlphaNum
<GROUP StringManipulation.CharacterTestRoutines>
Summary:
  Test whether C is an alphanumeric character.
Description:
  CharIsAlphaNum returns whether or not C is an alphanumerical character. That is,
  if C comes from the ['a'..'z', 'A'..'Z', '0'..'9'] set.
Parameters:
  C - The character to test.
Result:
  If C is an alphanumerical character the return value is True, otherwise the return value is False.
See also:
  CharIsAlpha
  CharIsNumberChar
  CharIsDigit
Donator:
  Anthony Steele
--------------------------------------------------------------------------------
@@CharIsBlank
<GROUP StringManipulation.CharacterTestRoutines>
Summary:
  Test whether C is a blank character.
Description:
  CharIsBlank returns whether or not C is a blank character.
Parameters:
  C - The character to test.
Result:
  If C is a blank character the return value is True, otherwise the return value is False.
Donator:
  Azret Botash
--------------------------------------------------------------------------------
@@CharIsControl
<GROUP StringManipulation.CharacterTestRoutines>
Summary:
  Tests whether C is a control character.
Description:
  CharIsControl tests whether C is a control character. That is, if it has an
  ordinal value smaller than 32.
Parameters:
  C - Character to test.
Result:
  If C is a control character the result is True, otherwise the result is False.
Donator:
  Anthony Steele
--------------------------------------------------------------------------------
@@CharIsDelete
<GROUP StringManipulation.CharacterTestRoutines>
Summary:
  Tests whether C is a delete character.
Description:
  CharIsDelete tests whether C is a delete character. That is, if it has an
  ordinal value of 8.
Parameters:
  C - Character to test.
Result:
  If C is a delete character the result is True, otherwise the result is False.
Donator:
  Anthony Steele
--------------------------------------------------------------------------------
@@CharIsDigit
<GROUP StringManipulation.CharacterTestRoutines>
Summary:
  Test whether C is a digit.
Description:
  CharIsDigit returns whether or not C is a digit. That is, if C comes from
  the ['0'..'9'] set.
Parameters:
  C - The character to test.
Result:
  If C is a digit the return value is True, otherwise the return value is False.
See also:
  CharIsAlpha
  CharIsNumberChar
  CharIsAlphaNum
Donator:
  Marcel van Brakel
--------------------------------------------------------------------------------
@@CharIsLower
<GROUP StringManipulation.CharacterTestRoutines>
Summary:
  Tests whether a character is lowercase.
Description:
  CharIsLower returns whether the specified character is lowercase.
Parameters:
  C - The character to test.
Result:
  If C is lowercase the return value is True, otherwise the return value is False.
Donator:
  Azret Botash
--------------------------------------------------------------------------------
@@CharIsNumberChar
<GROUP StringManipulation.CharacterTestRoutines>
Summary:
  Tests whether C is a number.
Description:
  CharIsNumberChar returns whether or not the supplied character can occur in a number. That is,
  if it comes from the ['0'..'9', '+', '-', '.'] set where the dot is replaced by the
  system's decimal separator character.
Parameters:
  C - Character to test.
Result:
  If C is a number the result is True, otherwise the result is False.
See also:
  CharIsAlpha
  CharIsAlphaNum
  CharIsDigit
Platforms:
  Windows NT/2000: Requires Windows NT 4 or later.
  Windows 95/98: Requires Windows 95 or later.
Requirements:
  Shell32 Version 4.00 or later.
Donator:
  Anthony Steele
--------------------------------------------------------------------------------
@@CharIsPrintable
<GROUP StringManipulation.CharacterTestRoutines>
Summary:
  Tests whether a character is printable.
Description:
  CharIsPrintable returns whether the specified character is
  printable. A printable character is any character which is
  not a control character and as such has an ordinal value
  larger than 31.
Parameters:
  C - The character to test.
Result:
  If C is printable the return value is True, otherwise the return value is False.
Donator:
  Azret Botash
--------------------------------------------------------------------------------
@@CharIsPunctuation
<GROUP StringManipulation.CharacterTestRoutines>
Summary:
  Tests whether a character is a punctuation character.
Description:
  CharIsPunctuation returns whether the specified character is a punctuation character.
  An example would be '.'.
Parameters:
  C - The character to test.
Result:
  If C is a punctuation character the return value is True, otherwise the return
  value is False.
Donator:
  Azret Botash
--------------------------------------------------------------------------------
@@CharIsReturn
<GROUP StringManipulation.CharacterTestRoutines>
Summary:
  Tests whether C is a return character.
Description:
  CharIsReturn returns whether C is a return character. In this context both the
  carriage return (#13) as well as the linefeed (#10) are considered return.
  characters.
Parameters:
  C - Character to test.
Result:
  If C is a return character the result is True, otherwise the result is False.
Donator:
  Anthony Steele
--------------------------------------------------------------------------------
@@CharIsSpace
<GROUP StringManipulation.CharacterTestRoutines>
Summary:
  Tests whether C represents space.
Description:
  CharIsSpace returns whether or not the C character represents
  space(s). In this context that means the character is tested
  against the space (' '), tab (#9), line feed (#10), vertical tab
  (#11), form feed (#12) and carriage return (#13) characters.
Parameters
  C - Character to test.
Result:
  If the character represents a space the result is True,
  otherwise the result is False.
See also:
  CharIsWhiteSpace
Donator:
  Anthony Steele
--------------------------------------------------------------------------------
@@CharIsUpper
<GROUP StringManipulation.CharacterTestRoutines>
Summary:
  Tests whether a character is uppercase.
Description:
  CharIsUpper returns whether the specified character is uppercase.
Parameters:
  C - The character to test.
Result:
  If C is uppercase the return value is True, otherwise the return value is False.
Donator:
  Azret Botash
--------------------------------------------------------------------------------
@@CharIsWhiteSpace
<GROUP StringManipulation.CharacterTestRoutines>
Summary:
  Tests whether C represents space.
Description:
  CharIsWhiteSpace returns whether or not the C character represents a space.
  Unlike CharIsSpace this function returns True if the specified
  character comes from the AnsiWhiteSpace set which is defined as: 
  AnsiWhiteSpace = [AnsiTab, AnsiLineFeed, AnsiVerticalTab, AnsiFormFeed, AnsiCarriageReturn,
  AnsiSpace];
Parameters:
  C - Character to test.
Result:
  If the character represents a space the result is True, otherwise the result is False.
See also:
  CharIsSpace
Donator:
  Anthony Steele
--------------------------------------------------------------------------------
@@CharType
<GROUP StringManipulation.CharacterTestRoutines>
Summary:
  Returns character type information.
Description:
  The CharType function returns character type information about the specified
  character. This routine returns the same information as routines such as IsCharControl.
  For further information about character type information see the documentation for
  the GetStringTypeEx routine in the Platform SDK.
Parameters:
  C - The character for which to retriev type information.
Result:
  The type of the character, this can be one of the following values.
<TABLE>
Name       Value   Meaning
---------  ------  ---------------------------------------------------------------
C1_UPPER   0x0001  Uppercase
C1_LOWER   0x0002  Lowercase
C1_DIGIT   0x0004  Decimal digits
C1_SPACE   0x0008  Space characters
C1_PUNCT   0x0010  Punctuation
C1_CNTRL   0x0020  Control characters
C1_BLANK   0x0040  Blank characters
C1_XDIGIT  0x0080  Hexadecimal digits
C1_ALPHA   0x0100  Any linguistic character: alphabetic, syllabary, or ideographic
</TABLE>
Notes:
  In a future Linux version the values may differ.
Donator:
  Azret Botash
--------------------------------------------------------------------------------
@@CharHex
<GROUP StringManipulation.CharacterTransformationRoutines>
Summary:
  Converts a hex digit character to its binary value.
Description:
  Converts a hex digit character to its binary value, ie $0 to $f.
  If the character is no hex digit then $ff is returned.
Parameters:
  C - A hex digit to convert
Result:
  The binary value of the hex digit or $ff if it was no hex digit.
Donator:
  Azret Botash
--------------------------------------------------------------------------------
@@CharLower
<GROUP StringManipulation.CharacterTransformationRoutines>
Summary:
  Lowercases a character.
Description:
  CharLower converts the supplied character to lowercase. For example 'A' becomes
  'a'. If the character is already lowercase the function does nothing.
Parameters:
  C - Character to convert to lowercase.
Result:
  Copy of character converted to lowercase.
See also:
  CharUpper
  CharToggleCase
Donator:
  Azret Botash
--------------------------------------------------------------------------------
@@CharUpper
<GROUP StringManipulation.CharacterTransformationRoutines>
Summary:
  Uppercases a character.
Description:
  CharUpper converts the supplied character to uppercase. For example 'a' becomes
  'A'. If the character is already uppercase the function does nothing.
Parameters:
  C - The character to convert to upper case.
Result:
  Copy of the character converted to uppercase.
See also:
  CharLower
  CharToggleCase
Donator:
  Azret Botash
--------------------------------------------------------------------------------
@@CharToggleCase
<GROUP StringManipulation.CharacterTransformationRoutines>
Summary:
  Reverses the case of a character.
Description:
  CharToggleCase reverses the case of the supplied character. That is, if you pass an
  uppercase character the function converts it to lowercase, if you pass a lowercase
  character the function converts it to uppercase.
Parameters:
  C - Character whose case to reverse.
Result:
  Copy of the character with the case reversed.
Donator:
  Azret Botash
--------------------------------------------------------------------------------
@@CharPos
<GROUP StringManipulation.CharacterSearchandReplace>
Summary:
  Finds the position of a character in a string.
Description:
  CharPos returns the 1-based index of the first occurrence of the supplied character
  in the string. The search starts at the supplied index and is case sensitive.
Parameters:
  S - String to search.
  C - The character to search for.
  Index - The character index where CharPos begins searching.
Result:
  The 1-based index of the first occurrence found, or 0 if the character was not found.
Donator:
  Azret Botash
--------------------------------------------------------------------------------
@@CharIPos
<GROUP StringManipulation.CharacterSearchandReplace>
Summary:
  Finds the position of a character in a string.
Description:
  CharPos returns the 1-based index of the first occurrence of the supplied character
  in the string. The search starts at the supplied index and is case insensitive.
Parameters:
  S - String to search.
  C - The character to search for.
  Index - The character index where CharPos begins searching.
Result:
  The 1-based index of the first occurrence found, or 0 if the character was not found.
Donator:
  Azret Botash
--------------------------------------------------------------------------------
@@CharReplace
<GROUP StringManipulation.CharacterSearchandReplace>
Summary:
  Replaces all occurrences of a character in a string.
Description:
  CharReplace replaces all occurrences of the specified search character with the
  supplied replace character. It returns the number of replacements performed.
  Note that the replacement is case-sensitive.
Parameters:
  S - The string in which to replace characters.
  Search - The character to replace.
  Replace - The character to use as a replacement of Search.
Result:
  CharReplace returns the number of replacements performed.
Donator:
  Azret Botash
--------------------------------------------------------------------------------
@@StringsToPCharVector
<GROUP StringManipulation.PCharVector>
Summary:
  Converts a stringlist into a PCharVector.
Description:
  A PCharVector is an array of PChar's where each PChar points to a null terminated
  string. The array is delimited by a nil (NULL) pointer. In the Windows API this is
  usually typed as a PPSTR. This function takes a string list and builds a
  PCharVector from it. The memory allocated to store the PCharVector must eventually
  be released by the caller, preferably using FreePCharVector.
Parameters:
  Dest - On return receives a pointer to the PCharVector.
  Source - String list to convert to a PCharVector.
Result:
  The value placed in Dest to allow using the function on parameter position.
See also:
  PCharVectorToStrings
  PCharVectorCount
  FreePCharVector
Donator:
  Marcel van Brakel
--------------------------------------------------------------------------------
@@PCharVectorCount
<GROUP StringManipulation.PCharVector>
Summary:
  Returns the number of elements in a PCharVector.
Description:
  PCharVectorCount returns the number of items, PChar's, in the supplied PCharVector
  excluding the NULL terminator.
Parameters:
  PCharVector - The PCharVector to count the elements in.
Result:
  The number of elements in the PCharVector excluding the NULL terminator.
See also:
  PCharVectorToStrings
  StringsToPCharVector
  FreePCharVector
Donator:
  Marcel van Brakel
--------------------------------------------------------------------------------
@@PCharVectorToStrings
<GROUP StringManipulation.PCharVector>
Summary:
  Converts a PCharVector to a stringlist.
Description:
  A PCharVector is an array of PChar's where each PChar points to a null terminated
  string. The array is delimited by a nil (NULL) pointer. In the Windows API this is
  usually typed as a PPSTR. This function takes such a PCharVector and converts it
  to a stringlist. Note that the memory for the PCharVector is not freed by this
  function.
Parameters:
  Dest - List which recieves the elements in the PCharVector.
  Source - PCharVector from which to retrieve the elements.
See also:
  PCharVectorCount
  StringsToPCharVector
  FreePCharVector
Donator:
  Marcel van Brakel
--------------------------------------------------------------------------------
@@FreePCharVector
<GROUP StringManipulation.PCharVector>
Summary:
  Frees a PCharVector
Description:
  FreePCharVector frees the memory pointed to by Dest and sets Dest to nil.
  Only hand in memory allocated by StringsToPCharVector.
  Freeing a PCharVector allocated by a Windows API function will crash your program.
Parameters:
  Dest - The PCharVector whose memory to free.
See also:
  PCharVectorCount
  StringsToPCharVector
  PCharVectorToStrings
Donator:
  Marcel van Brakel
--------------------------------------------------------------------------------
@@StringsToMultiSz
<GROUP StringManipulation.MultiSz>
Summary:
  Converts a stringlist to a list of null terminated strings.
Description:
  StringsToMultiSz concatenates the strings in Source into a single PChar string,
  terminating each individual string with a NULL character and the last string with
  a double NULL character. For example, if Source contains the items 'Project',
  'JEDI' and 'Rules' Dest will point to a string with the contents 'Project#0JEDI#0Rules#0#0'
Parameters:
  Dest - PChar receives a pointer to the resulting string.
  Source - List of strings to pack into a single string. This list may not contain empty items
  (items with the value '') or an EJclStringError is raised.
Result:
  On success the function returns the value of Dest. If the function fails to allocate
  memory for the result string it (implicitly) raises an EOutOfMemory exception. The
  caller is responsible for releasing the memory pointed to by Dest.
See also:
  MultiSzToStrings
  FreeMultiSz
Donator:
  Marcel van Brakel
--------------------------------------------------------------------------------
@@MultiSzToStrings
<GROUP StringManipulation.MultiSz>
Summary:
  Converts a list of null terminated strings to a string list.
Description:
  Source is assumed to be a list of strings, separated by a NULL character, terminated
  by a double NULL character. For example 'Project#0JEDI#0Rules#0#0'. The function
  takes this string and copies the individual strings to the string list. Thus,
  after executing this function with the above string the Dest list will contain
  the items 'Project', 'JEDI' and 'Rules'.
Parameters:
  Dest - The string list to receive the individual strings.
  Source - The source string to extract the items from.
Notes:
  This function does not release the memory associated with Source.
See also:
  StringsToMultiSz
  FreeMultiSz
Donator:
  Marcel van Brakel
--------------------------------------------------------------------------------
@@FreeMultiSz
<GROUP StringManipulation.MultiSz>
Summary:
  Frees the memory pointed to by Dest.
Description:
  FreeMultiSz frees the memory pointed to by Dest which is assumed to be a list
  of strings, each terminated by a NULL character, terminated by a double NULL
  character.
Parameters:
  Dest - The memory to free. Is set to nil before return.
See also:
  StringsToMultiSz
  MultiSzToStrings
Donator:
  Marcel van Brakel
--------------------------------------------------------------------------------
@@StringsToMultiString
<GROUP StringManipulation.MultiSz>
Summary:
  Assembles a single string from multiple strings
Description:
  StringsToMultiString concatenates the strings in Value into a single ANSI string,
  terminating each individual string with a NULL character and the last string with
  a double NULL character. For example, if Source contains the items 'Project',
  'JEDI' and 'Rules' the result will be a string with the contents 'Project#0JEDI#0Rules#0#0'.
Parameters:
  Value - List resp. array of strings to pack into a single string. If assertions are enabled, an
  EAssertionFailed exception is raised when an empty string is encountered; otherwise it will be
  skipped.
Result:
  The string concatenated from the list or array of strings.
See also:
  StringsToMultiWideString
  StringsToMultiSz
  MultiStringToStrings
Donator:
  Anonymous
--------------------------------------------------------------------------------
@@StringsToMultiWideString
<GROUP StringManipulation.MultiSz>
Summary:
  Assembles a single string from multiple strings
Description:
  StringsToMultiWideString concatenates the strings in Value into a single wide string,
  terminating each individual string with a NULL character and the last string with
  a double NULL character. For example, if Source contains the items 'Project',
  'JEDI' and 'Rules' the result will be a string with the contents 'Project#0JEDI#0Rules#0#0'.
Parameters:
  Value - List resp. array of strings to pack into a single string. If assertions are enabled, an
  EAssertionFailed exception is raised when an empty string is encountered; otherwise it will be
  skipped.
Result:
  The string concatenated from the list or array of strings.
See also:
  StringsToMultiString
  StringsToMultiSz
  MultiWideStringToStrings
Donator:
  Anonymous
--------------------------------------------------------------------------------
@@MultiStringToStrings
<GROUP StringManipulation.MultiSz>
Summary:
  Parses a string by separating into substrings whenever a NULL character is encountered.
Description:
  Value is assumed to be a list of strings, separated by a NULL character, terminated
  by a double NULL character. For example 'Project#0JEDI#0Rules#0#0'. The function
  takes this string and copies the individual strings to Dest. Thus, after executing
  this function with the above string the Dest list/array will contain the items
  'Project', 'JEDI' and 'Rules'.
Parameters:
  Dest - The string list resp. dynamic array to receive the individual strings.
  Value - The source string to extract the items from.
See also:
  MultiWideStringToStrings
  StringsToMultiString
Donator:
  Anonymous
--------------------------------------------------------------------------------
@@MultiWideStringToStrings
<GROUP StringManipulation.MultiSz>
Summary:
  Parses a string by separating into substrings whenever a NULL character is encountered.
Description:
  Value is assumed to be a list of strings, separated by a NULL character, terminated
  by a double NULL character. For example 'Project#0JEDI#0Rules#0#0'. The function
  takes this string and copies the individual strings to Dest. Thus, after executing
  this function with the above string the Dest list/array will contain the items
  'Project', 'JEDI' and 'Rules'.
Parameters:
  Dest - The string list resp. dynamic array to receive the individual strings.
  Value - The source string to extract the items from.
See also:
  MultiStringToStrings
  StringsToMultiWideString
Donator:
  Anonymous
--------------------------------------------------------------------------------
@@StrToStrings
<GROUP StringManipulation.TStringsManipulation>
Summary:
  Converts a string into a list of strings using the specified
  separator character.
Description:
  StrToStrings converts the supplied string, which supposedly is
  a list of strings packed into a single string variable, to a
  TStrings. The function uses the supplied separator string to
  separate the string into its individual elements.

  For example, if you call the function like this:
  StrToStrings('Project JEDI Rules', ' ', List) then on return
  list will contain three items, namely 'Project', 'JEDI', and
  'Rules'. As this example shows, the last string doesn't have
  to be terminated by the separator string although it is
  allowed.
Notes:
  The list will be cleared by this function before adding the
  elements.
Parameters:
  List - A TStrings derivative that receives the individual elements.
  S - The string to split into elements.
  Sep - The string that separates the individual elements.
See also:
  StringsToStr
Donator:
  Anthony Steele
--------------------------------------------------------------------------------
@@StringsToStr
<GROUP StringManipulation.TStringsManipulation>
Summary:
  Converts a stringlist to a single string.
Description:
  StringsToStr concatenates the items in List, separating them with the specified
  separator string and returns the resulting string. The last element is not terminated
  with the separator (its a separator not a terminator after all).
Parameters:
  List - Stringlist which contains the strings to concatenate.
  Sep - String to separate the individual strings with.
See also:
  StrToStrings
Donator:
  Marcel van Brakel
--------------------------------------------------------------------------------
@@TrimStrings
<GROUP StringManipulation.TStringsManipulation>
Summary:
  Trims all strings in a string list.
Description:
  TrimStrings trims all strings in the specified stringlist using the standard
  Delphi Trim procedure. If an entry in the list is empty or trimming it causes
  it to become empty, the entry is optionally deleted from the list depending the
  DeleteIfEmpty parameter.
Parameters:
  List - The stringlist whose contents to trim.
  DeleteIfEmpty - If True and a list entry is empty, or trimming it results in an empty string, the entry is deleted from the list.
See also:
  TrimStringsRight
  TrimStringsLeft
Donator:
  Anthony Steele
--------------------------------------------------------------------------------
@@TrimStringsRight
<GROUP StringManipulation.TStringsManipulation>
Summary:
  Right trims all strings in a stringlist.
Description:
  TrimStringsRight right trims all strings in the specified stringlist using the
  standard Delphi TrimRight procedure. If an entry in the list is empty or trimming
  it causes it to become empty, the entry is optionally deleted from the list
  depending on the DeleteIfEmpty parameter.
Parameters:
  List - The stringlist whose contents to right trim.
  DeleteIfEmpty - If True and a list entry is empty, or trimming it results in an empty string, the entry is deleted from the list.
See also:
  TrimStrings
  TrimStringsLeft
Donator:
  Anthony Steele
--------------------------------------------------------------------------------
@@TrimStringsLeft
<GROUP StringManipulation.TStringsManipulation>
Summary:
  Left trims all strings in a stringlist.
Description:
  TrimStringsLeft left trims all strings in the specified stringlist using the
  standard Delphi TrimLeft procedure. If an entry in the list is empty or trimming
  it causes it to become empty, the entry is optionally deleted from the list
  depending on the DeleteIfEmpty parameter.
Parameters:
  List - The stringlist whose contents to left trim.
  DeleteIfEmpty - If True and a list entry is empty, or trimming it results in an empty string, the entry is deleted from the list.
See also:
  TrimStrings
  TrimStringsRight
Donator:
  Anthony Steele
--------------------------------------------------------------------------------
@@StrTokenToStrings
<GROUP StringManipulation.Miscellaneous>
Summary:
  Breaks apart S using a specified delimiter into a StringList.
Description:
  Use StrTokenToStrings for breaking apart a string with parts delimited by a
  separator. For example, if you passed 'C:\Windows;C:\Delphi;C:\JEDI;' List would
  contain 'C:\Windows', 'C:\Delphi', 'C:\JEDI'.
  You must create the StringList prior to passing it to StrTokenToString and
  Free the StringList once finished with it.
Parameters:
  S - A string which contains one or more Separators (see List parameter).
  Separator - Any character you want to use to separate S.
  List - Returns separated parts or the entire string if no separator occurs.
See also:
  StrToken
Donator:
  Huanlin Tsai
--------------------------------------------------------------------------------
@@StrToken
<GROUP StringManipulation.Miscellaneous>
Summary:
  Returns a sub-string from S which is followed by Separator and deletes the sub-string from S including the separator.
Description:
  Splits a string into the part preceding the separator, which is returned
  as function result, and the part following the separator which is placed
  in S.
  If no separator is contained in the string then the string is returned
  as the function result and S becomes an empty string.
Parameters:
  S - The string you want to return the part after the Separator.
  Separator - A character which determines where to break the string up at.
Result:
  Any part of S in front of Separator, or the original string if Separator
  was not located in S.
  S returns the remaining portion of the string after (but not including) Separator.
  If Separator was not found, S is an empty string.
See also:
  StrTokenToStrings
Donator:
  Huanlin Tsai
--------------------------------------------------------------------------------
@@StrTokens
<GROUP StringManipulation.Miscellaneous>
Summary:
  TODO
Description:
  TODO
Parameters:
  S - TODO
  List - TODO
Result:
  TODO
Donator:
  Azret Botash
--------------------------------------------------------------------------------
@@StrWord
<GROUP StringManipulation.Miscellaneous>
Summary:
  TODO
Description:
  TODO
Parameters:
  TODO
Result:
  TODO
Donator:
  Azret Botash
--------------------------------------------------------------------------------
@@FileToString
<GROUP StringManipulation.Miscellaneous>
Summary:
  Reads the contents of a file into a string.
Description:
  The FileToString routine reads the contents of the specified file into a string
  and returns it as the function result. Note that the function doesn't care about
  the contents of the file, it simply treats the string as a buffer and copies the
  entire file contents into it.
Parameters:
  FileName - Full qualified name of the file whose contents to read.
Result:
  The contents of the file as a string buffer. Note that if the file contains
  null terminating characters, the string will contain the entire contents but
  for example displaying the string will only show the part of the string up to
  the first null terminator.
See also:
  StringToFile
Donator:
  Anthony Steele
--------------------------------------------------------------------------------
@@StringToFile
<GROUP StringManipulation.Miscellaneous>
Summary:
  Writes a string to a file.
Description:
  The StringToFile routine writes the contents of the specified string to a file.
  Note that the full content is written to the file, including any null terminating
  characters. The string is considered a generic buffer and can contains anything.
Parameters:
  FileName - Fully qualified name of the file.
  Contents - The string whose contents to write to the file.
See also:
  FileToString
Donator:
  Anthony Steele
--------------------------------------------------------------------------------
@@StrRepeatLength@AnsiString@Integer
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Repeats a string until a specified length L has been reached.
Description:
  The StrRepeatLength routine returns a string consisting of
  the specified string, repeated until the length of the string
  is exactly L. For example StrRepeatLength('JEDI!', 12) returns
  'JEDI!JEDI!JE'.
Parameters:
  S - The string to repeat.
  L - Length of the resulting string.
Returns:
  A string consisting of the specified string, repeated until
  the length of the string is exactly L.
Donator:
  Anonymous
--------------------------------------------------------------------------------
@@StrCharPosLower@AnsiString@Integer
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Lowercases a character within a string.
Description:
  The StrCharPosLower routine returns a string with the specified character in lowercase.
  If the character is already lowercase the function does nothing.
Parameters:
  S - The string which contains the character.
  CharPos - The position of the character within the string to convert.
Donator:
  Jean-Fabien Connault
--------------------------------------------------------------------------------
@@StrCharPosUpper@AnsiString@Integer
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Uppercases a character within a string.
Description:
  The StrCharPosUpper routine returns a string with the specified character in uppercase.
  If the character is already uppercase the function does nothing.
Parameters:
  S - The string which contains the character.
  CharPos - The position of the character within the string to convert.
Donator:
  Jean-Fabien Connault
--------------------------------------------------------------------------------
@@StrTrimCharsLeft
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Removes characters from the left side of supplied string.
Description:
  StrTrimCharsLeft removes all characters defined in the "Chars" set from
  the left side of the string.
Parameters:
  S - The string to trim.
Result:
  The trimmed string.
Donator:
  Leonard Wennekers
--------------------------------------------------------------------------------
@@StrTrimCharsRight
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Removes characters from the right side of supplied string.
Description:
  StrTrimCharsLeft removes all characters defined in the "Chars" set from
  the right side of the string.
Parameters:
  S - The string to trim.
Result:
  The trimmed string.
Donator:
  Leonard Wennekers
--------------------------------------------------------------------------------
@@AnsiSameText
<GROUP StringManipulation.Miscellaneous>
Summary:
 AnsiSameText compares two strings.
Description:
  AnsiSameText compares the two supplied ANSI strings and returns whether or not they are
  identical. AnsiSameText is case insensitive and uses the users local settings for
  comparisation. For more information please refer to the Windows API CompareString function.
Parameters:
  S1 - First string to compare.
  S2 - Second string to compare.
Result:
  AnsiSameText returns 0 (CSTR_EQUAL) if the two strings match.
Donator:
  Team JCL
--------------------------------------------------------------------------------
@@StrCharsCount
<GROUP StringManipulation.StringTransformationRoutines>
Summary:
  Counts the occurrences of characters in a string.
Description:
  StrCharsCount returns the number of occurrences of the specified characters in the
  supplied string.
Parameters:
  S - Source string.
  Chars - The characters which occurrences to count.
Result:
  The number of occurrences of Chars in S.
Donator:
  Anonymous
--------------------------------------------------------------------------------
@@StrKeepChars
<GROUP StringManipulation.StringSearchandReplaceRoutines>
Summary:
  Keeps all occurences of specified characters within a string and removes the
  others.
Description:
  StrKeepChars keeps all occurences of the characters specified in the Chars set
  and removes any other characters from the string.
  For example, if you pass in 'Joint Endeavour of Delphi Innovators' and specify
  ['e', 'a', 'o', 'u', 'i', ' '] the resulting string will be 'oi eaou o ei oao'.
Parameters:
  S - The source string from which to remove the characters.
  Chars - The set of characters to keep within S.
Result:
  A string containing only characters which are within Chars.
Donator:
  Anonymous
--------------------------------------------------------------------------------
@@StrReplace
<GROUP StringManipulation.StringSearchandReplaceRoutines>
Summary:
  StrReplace replaces one or all occurrences of the specified search pattern with
  the supplied replace string.
Description:
  StrReplace replaces one or all occurrences of the specified search pattern with
  the supplied replace string. The flags determine how the search is done and if
  only one or if all occurrences should be replaced.

  TReplaceFlags = [rfIgnoreCase, rfReplaceAll]

  If rfIgnoreCase is is within the flags the search is performed case insenitive, otherwise
  it is case sensitive. If rfReplaceAll is specified StrReplace replaces all occurrences otherwise
  only the first one.
Parameters:
  S - The source string.
  Search - The substring to replace.
  Replace - The string to use as a replacement of Search.
Donator:
  Robert Lee
Contributor:
  Robert Rossmair
--------------------------------------------------------------------------------
@@StrReplaceChar
<GROUP StringManipulation.StringSearchandReplaceRoutines>
Summary:
  Replaces all occurrences of a character with another character
Description:
  StrReplaceChar replaces all occurrences of the specified search character with the supplied
  replace character. Note that the replacement is case-sensitive.
Parameters:
  S - The source string.
  Search - The character to replace.
  Replace - The character to use as a replacement of Search.
Result:
  The string with all replacements performed.
Donator:
  Anonymous
--------------------------------------------------------------------------------
@@StrReplaceChars
<GROUP StringManipulation.StringSearchandReplaceRoutines>
Summary:
  Replaces all occurrences of one or more characters with another character.
Description:
  StrReplaceChars replaces all occurrences of the specified search character(s) with the
  supplied replace character. Note that the replacement is case-sensitive.
Parameters:
  S - The string in which to replace characters.
  Chars - The character(s) to replace.
  Replace - The character to use as a replacement of the characters definied in Chars.
Result:
  The string with all replacements performed.
Donator:
  Anonymous
--------------------------------------------------------------------------------
@@StrReplaceButChars
<GROUP StringManipulation.StringSearchandReplaceRoutines>
Summary:
  Replaces all occurrences of one or more characters with another character.
Description:
  StrReplaceButChars replaces all occurrences of characters which are not within the specified
  search character(s) with the supplied replace character. Note that the replacement is case-sensitive.
Parameters:
  S - The string in which to replace characters.
  Chars - The characters which should not be replaced.
  Replace - The character to use as replacement.
Result:
  The string with all replacements performed.
Donator:
  Anonymous
--------------------------------------------------------------------------------
@@StrMatches
<GROUP StringManipulation.StringTestRoutines>
Summary:
  Compares two strings.
Description:
  StrMatches compares two given strings. The search starts at the supplied index and is case-sensitive.
  The specified sub-string may contain wildcards. The '?' wildcard matches 1 character
  while the '*' wildcard matches 0 or more occurrences of a character. For example, 'J?DI'
  will find 'JEDI', 'JZDI' and 'JODI' (and more) while 'J*I' will find 'JEDI' and 'JI'.
Parameters:
  Substr - The sub-string to search for. May contain wildcards.
  Str - The string in which to search.
  Index - The index in Str at which to start the search.
Result:
  True if Str and Substr are equal.
See also:
  StrSearch
Donator:
  Michael Winter
--------------------------------------------------------------------------------
@@StrNormIndex
<GROUP StringManipulation.Miscellaneous>
Summary:
  Normalizes Index and count parameter.
Description:
  StrNormIndex is a auxiliary function for normalizations of Index
  and Count parameters transfered in string functions.
  Index and Count parameters are normalized as in standard Delphi
  function System.Delete.

  Str     Index Count => Index Count
  '12345' 2     3        2     3
  '12345' 2     <0       2     0
  '12345' 2     >4       2     4
  '12345' <1    3        1     3
  '12345' <1    <0       1     0
  '12345' <1    >5       1     5
  '12345' >5    Any      6     0

Donator:
  Alexander Radchenko
--------------------------------------------------------------------------------
@@StrStrCount
<GROUP StringManipulation.StringSearchandReplaceRoutines>
Summary:
  Counts the occurrences of a substring in a string.
Description:
  StrStrCount returns the number of occurrences of the specified substring in the
  supplied string.
Parameters:
  S - Source string.
  SubS - The character whose occurrences to count.
Result:
  The number of occurrences of SubS in S.
Donator:
  Anonymous
--------------------------------------------------------------------------------
@@AnsiNull

JclStrings defines several often used character definitions. They are symbolic
representations of their corresponding ANSI character. They can, for instance,
be used to achieve self explaining code.

<TABLE>
Symbol                   Description                   Char
---------------------    ----------------------------  ------
AnsiNull                 No character                      #0
AnsiSoh                  Start of header                   #1
AnsiStx                  Start of Text                     #2
AnsiEtx                  End of Text                       #3
AnsiEot                  End of Transmission               #4
AnsiEnq                  Enquiry                           #5
AnsiAck                  Acknowledgment                    #6
AnsiBell                 Bell                              #7
AnsiBackspace            Backspace                         #8
AnsiTab                  Horizontal Tab                    #9
AnsiLineFeed             Line Feed                        #10
AnsiVerticalTab          Vertical Tab                     #11
AnsiFormFeed             Form Feed                        #12
AnsiCarriageReturn       Carriage Return                  #13
AnsiCrLf                 Carriage Return and LineFeed   #1310
AnsiSo                   Shift Out                        #14
AnsiSi                   Shift In                         #15
AnsiDle                  Data Link Escape                 #16
AnsiDc1                  Device Control 1                 #17
AnsiDc2                  Device Control 2                 #18
AnsiDc3                  Device Control 3                 #19
AnsiDc4                  Device Control 4                 #20
AnsiNak                  Negative Acknowledgement         #21
AnsiSyn                  Synchronous Idle                 #22
AnsiEtb                  End of Transmission Block        #23
AnsiCan                  Cancel                           #24
AnsiEm                   End of Medium                    #25
AnsiEndOfFile            Substitute                       #26
AnsiEscape               Escape                           #27
AnsiFs                   File Separator                   #28
AnsiGs                   Group Separator                  #29
AnsiRs                   Request to Send                  #30
AnsiUs                   Unit Separator                   #31
AnsiSpace                Space                            #32
AnsiComma                Comma                            #44
AnsiBackslash            Backslash                        #92
AnsiForwardSlash         Forward Slash                    #47
AnsiDoubleQuote          Double Quote                     #34
AnsiSingleQuote          Single Quote                     #39
</TABLE>
--------------------------------------------------------------------------------
@@AnsiSoh
<ALIAS AnsiNull>
@@AnsiStx
<ALIAS AnsiNull>
@@AnsiEtx
<ALIAS AnsiNull>
@@AnsiEot
<ALIAS AnsiNull>
@@AnsiEnq
<ALIAS AnsiNull>
@@AnsiAck
<ALIAS AnsiNull>
@@AnsiBell
<ALIAS AnsiNull>
@@AnsiBackspace
<ALIAS AnsiNull>
@@AnsiTab
<ALIAS AnsiNull>
@@AnsiLineFeed
<ALIAS AnsiNull>
@@AnsiVerticalTab
<ALIAS AnsiNull>
@@AnsiFormFeed
<ALIAS AnsiNull>
@@AnsiCarriageReturn
<ALIAS AnsiNull>
@@AnsiCrLf
<ALIAS AnsiNull>
@@AnsiSo
<ALIAS AnsiNull>
@@AnsiSi
<ALIAS AnsiNull>
@@AnsiDle
<ALIAS AnsiNull>
@@AnsiDc1
<ALIAS AnsiNull>
@@AnsiDc2
<ALIAS AnsiNull>
@@AnsiDc3
<ALIAS AnsiNull>
@@AnsiDc4
<ALIAS AnsiNull>
@@AnsiNak
<ALIAS AnsiNull>
@@AnsiSyn
<ALIAS AnsiNull>
@@AnsiEtb
<ALIAS AnsiNull>
@@AnsiCan
<ALIAS AnsiNull>
@@AnsiEm
<ALIAS AnsiNull>
@@AnsiEndOfFile
<ALIAS AnsiNull>
@@AnsiEscape
<ALIAS AnsiNull>
@@AnsiFs
<ALIAS AnsiNull>
@@AnsiGs
<ALIAS AnsiNull>
@@AnsiRs
<ALIAS AnsiNull>
@@AnsiUs
<ALIAS AnsiNull>
@@AnsiSpace
<ALIAS AnsiNull>
@@AnsiComma
<ALIAS AnsiNull>
@@AnsiBackslash
<ALIAS AnsiNull>
@@AnsiForwardSlash
<ALIAS AnsiNull>
@@AnsiDoubleQuote
<ALIAS AnsiNull>
@@AnsiSingleQuote
<ALIAS AnsiNull>
@@AnsiLineBreak
<ALIAS AnsiNull>
--------------------------------------------------------------------------------
@@StrToFloatSafe@string
Summary:
  The function StrToFloatSafe attempts to convert the
  string passed as a parameter to its float value.
Description:
  The function StrToFloatSafe attempts to convert the
  string passed as a parameter to its float value. It handles
  correctly decimal and float separators as well as negative
  sign. Function also handles national settings for thousand
  separator (see ThousandSeparator variable).
Parameters:
  S - String to be converted to float value.
Result:
  Returns the float value of the string S passed as a parameter.
  If error occurs, the function returns 0.00.
Donator:
  Azret Botash
Contributor:
  Robert Rossmair
--------------------------------------------------------------------------------
@@StrIToStrings@string@string@TStrings@Boolean
Summary:
  Converts a string into a list of strings using the specified
  separator character.
Description:
  StrIToStrings converts the supplied string, which
  supposedly is a list of strings packed into a single string
  variable, to a TStrings. The function uses the supplied
  separator string to separate the string into its individual
  elements.

  For example, if you call the function like this:
  StrIToStrings('Project JEDI Rules', ' ', List) then on return
  list will contain three items, namely 'Project', 'JEDI', and
  'Rules'. As this example shows, the last string doesn't have
  to be terminated by the separator string although it is
  allowed.
Notes:
  The function differs from StrToString since it does not
  perform any case conversion of the string passed as the
  parameter.

  The list will be cleared by this function before adding the
  elements.
Parameters:
  S - The string to split into elements.
  Sep - The string that separates the individual elements.
  List - A TStrings derivative that receives the individual elements.
  AllowEmptyString - Specifies whether empty strings can be added to the list or not.
See also:
 StrToStrings
Donator:
  Anthony Steele
--------------------------------------------------------------------------------
@@StrToIntSafe@string
Summary:
  The function StrToIntSafe attempts to convert the
  string passed as a parameter to its integer value.
Description:
  The function StrToIntSafe attempts to convert the
  string passed as a parameter to its integer value. The
  function handles correctly national settings ofr thousand
  separator (see ThousandSeparator variable) as well as
  negative sign.
Parameters:
  S - String to be converted to integer value.
Result:
  Integer value of the string S passed as a parameter.
  If error occurs, the function returns 0.
Donator:
  Azret Botash
--------------------------------------------------------------------------------
@@EJclStringError
Summary:
  Class of exceptions that are risen by JclStrings unit's routines.
--------------------------------------------------------------------------------
@@PCharVector
Summary:
  PCharVector type represents an array of pointers to PChars.
Description:
  A PCharVector is an array of PChar's where each PChar points
  to a null terminated string. The array is delimited by a nil
  (NULL) pointer. In the Windows API this is usually typed as a
  PPSTR.
See also:
  StringsToPCharVector
  PCharVectorCount
  PCharVectorToStrings
  FreePCharVector
Donator:
  Marcel van Brakel
--------------------------------------------------------------------------------
@@AnsiDecDigits
Summary:
  Specifies the enumeration type containing digits from 0 to 9.
Description:
  The enumeration AnsiDecDigits contains all valid
  digits for decimal number representation.
--------------------------------------------------------------------------------
@@AnsiHexDigits
Summary:
  Specifies enumeration typcontaining all valid characters for
  hexadecimal numbers representation.
Description:
  The enumeration AnsiHexDigits contains all valid
  digits from 0 to 9 and letters of latin alphabet from A to F
  in both lower and upper cases for hexadecimal numbers
  representation.
--------------------------------------------------------------------------------
@@AddStringToStrings@string@TStrings@Boolean
Summary:
  Add a string to TStrings instance if conditions met.
Description:
  Add a string to an object of TStrings. If a string already
  exists in the list and there is a uniqueness requirement in
  place, the string is not added.
Parameters:
  S - String to be added.
  Strings - TStrings object to which the string specified by S should be added.
  Unique - Determines whether the the uniqueness check should be performed before adding the string.
Result:
  The function returns True if the string was added, False otherwise.
Platforms:
  Windows NT/2000/Vista: Requires Windows NT 3.1 or later.
  Windows 95/98: Requires Windows 95 or later.
Donator:
  Jean-Fabien Connault
--------------------------------------------------------------------------------
@@StrExpandTabs@string
<GROUP StringManipulation.Tabulation>
Summary:
  Expands tabs to spaces in the provided string.
Description:
  StrExpandTabs expands tab characters in the provided string into sequences of
  spaces while preserving the formatting. StrExpandTabs will assume a tab width
  of 2.

  Multi-line strings, ie. strings containing one or more newline sequences (eg.
  CrLf, but also single Cr of Lf characters are treated as newlines), are
  handled properly.

  The reverse operation (collapse sequences of spaces into tab characters) can
  be achieved by the <LINK StrOptimizeTabs@string, StrOptimizeTabs> method.
Parameters:
  S - The string to expand tabs in.
Result:
  If S contains tabs, they will have been converted to 1 or more space characters,
  depending on the column the tab character is in. Otherwise, the string is
  unmodified.
Example:
  <code>x := StrExpandTabs('Abc'#9'de'#9'fg');</code>
  The above call will result in <i>x</i> containing the string (? represents a
  space character): <code>Abc?????de??????fg</code>. In this case the first tab
  character (ASCII code 9) was  transformed into a single space and the second
  tab character into two spaces.
See also:
  TJclTabSet
  StrExpandTabs@string@Integer
  StrExpandTabs@string@TJclTabSet
Donator:
  Marcel Bestebroer
--------------------------------------------------------------------------------
@@StrExpandTabs@string@Integer
<GROUP StringManipulation.Tabulation>
Summary:
  Expands tabs to spaces in the provided string.
Description:
  StrExpandTabs expands tab characters in the provided string into sequences of
  spaces while preserving the formatting. StrExpandTabs will use the provided
  tab width.

  Multi-line strings, ie. strings containing one or more newline sequences (eg.
  CrLf, but also single Cr of Lf characters are treated as newlines), are
  handled properly.

  The reverse operation (collapse sequences of spaces into tab characters) can
  be achieved by the <LINK StrOptimizeTabs@string@Integer, StrOptimizeTabs>
  method.
Parameters:
  S - The string to expand tabs in.
  TabWidth - The width of each tab.
Result:
  If S contains tabs, they will have been converted to 1 or more space characters,
  depending on the column the tab character is in. Otherwise, the string is
  unmodified.
Example:
  <code>x := StrExpandTabs('Abc'#9'de'#9'fg', 8);</code>
  The above call will result in <i>x</i> containing the string (? represents a
  space character): <code>Abc?????de??????fg</code>. In this case the first tab
  character (ASCII code 9) was transformed into five spaces and the second tab
  character into six spaces.
See also:
  TJclTabSet
  StrExpandTabs@string
  StrExpandTabs@string@TJclTabSet
Donator:
  Marcel Bestebroer
--------------------------------------------------------------------------------
@@StrExpandTabs@string@TJclTabSet
<GROUP StringManipulation.Tabulation>
Summary:
  Expands tabs to spaces in the provided string.
Description:
  StrExpandTabs expands tab characters in the provided string into sequences of
  spaces while preserving the formatting. StrExpandTabs will use the provided
  tab set.

  Multi-line strings, ie. strings containing one or more newline sequences (eg.
  CrLf, but also single Cr of Lf characters are treated as newlines), are
  handled properly.

  The reverse operation (collapse sequences of spaces into tab characters) can
  be achieved by the <LINK StrOptimizeTabs@string@TJclTabSet, StrOptimizeTabs>
  method.
Parameters:
  S - The string to expand tabs in.
  TabSet - The tab set to use.
Result:
  If S contains tabs, they will have been converted to 1 or more space characters,
  depending on the column the tab character is in. Otherwise, the string is
  unmodified.
Example:
<code>
  <i>// initiate a tab set with (zero-based) stops at 15, 20 and 30, and a tab width of 2 for
  // tabs beyond the column 30</i>
  tabs := TJclTabSet.Create([15, 20, 30], True, 2);
  <b>try</b>
    x := StrExpandTabs('MyLabel:'#9'LD'#9'A,(HL)'#9'; Initialize A register', tabs);
  <b>finally</b>
    tabs.Free;
  <b>end</b>;
</code>
  The above snippet will result in <i>x</i> containing the string (? represents a
  space character): <code>MyLabel:???????LD???A,(HL)????;?Initialize?A?register</code>.
  In this case the first tab character (ASCII code 9) was transformed into seven
  spaces, the second tab character into three spaces and the third tab character
  into four spaces.
See also:
  TJclTabSet
  StrExpandTabs@string
  StrExpandTabs@string@Integer
Donator:
  Marcel Bestebroer
--------------------------------------------------------------------------------
@@StrOptimizeTabs@string
<GROUP StringManipulation.Tabulation>
Summary:
  Collapses a string to the optimal tab and space character sequences.
Description:
  StrOptimizeTabs reduces tab and space character sequences in the provided
  string into an optimized (shortest) sequences of tab and space characters
  while preserving the formatting. A tab width of 2 is assumed.

  Multi-line strings, ie. strings containing one or more newline sequences (eg.
  CrLf, but also single Cr of Lf characters are treated as newlines), are
  handled properly.

  The reverse operation (expand sequences of tab characters into spaces) can
  be achieved by the <LINK StrExpandTabs@string, StrExpandTabs> method.
Parameters:
  S - The string to collapse tabs and spaces in.
Result:
  Any tab and/or space character sequences in S will have been reduced to their
  shortest form; no other item in the string is modified.
See also:
  TJclTabSet
  StrOptimizeTabs@string@Integer
  StrOptimizeTabs@string@TJclTabSet
Donator:
  Marcel Bestebroer
--------------------------------------------------------------------------------
@@StrOptimizeTabs@string@Integer
<GROUP StringManipulation.Tabulation>
Summary:
  Collapses a string to the optimal tab and space character sequences.
Description:
  StrOptimizeTabs reduces tab and space character sequences in the provided
  string into an optimized (shortest) sequences of tab and space characters
  while preserving the formatting. The provided tab width is used.

  Multi-line strings, ie. strings containing one or more newline sequences (eg.
  CrLf, but also single Cr of Lf characters are treated as newlines), are
  handled properly.

  The reverse operation (expand sequences of tab characters into spaces) can
  be achieved by the <LINK StrExpandTabs@string@Integer, StrExpandTabs> method.
Parameters:
  S - The string to collapse tabs and spaces in.
  TabWidth - The tab width to use
Result:
  Any tab and/or space character sequences in S will have been reduced to their
  shortest form; no other item in the string is modified.
See also:
  TJclTabSet
  StrOptimizeTabs@string
  StrOptimizeTabs@string@TJclTabSet
Donator:
  Marcel Bestebroer
--------------------------------------------------------------------------------
@@StrOptimizeTabs@string@TJclTabSet
<GROUP StringManipulation.Tabulation>
Summary:
  Collapses a string to the optimal tab and space character sequences.
Description:
  StrOptimizeTabs reduces tab and space character sequences in the provided
  string into an optimized (shortest) sequences of tab and space characters
  while preserving the formatting. The provided tab width is used.

  Multi-line strings, ie. strings containing one or more newline sequences (eg.
  CrLf, but also single Cr of Lf characters are treated as newlines), are
  handled properly.

  The reverse operation (expand sequences of tab characters into spaces) can
  be achieved by the <LINK StrExpandTabs@string@TJclTabSet, StrExpandTabs>
  method.
Parameters:
  S - The string to collapse tabs and spaces in.
  TabSet - The tab set to use
Result:
  Any tab and/or space character sequences in S will have been reduced to their
  shortest form; no other item in the string is modified.
See also:
  TJclTabSet
  StrOptimizeTabs@string
  StrOptimizeTabs@string@Integer
Donator:
  Marcel Bestebroer
--------------------------------------------------------------------------------
@@TabSetFormattingOptions
<GROUP StringManipulation.Tabulation>
<TITLE TJclTabSet string formatting options>
<ALIASOF TabSetFormatting_SurroundStopsWithBrackets,TabSetFormatting_EmptyBracketsIfNoStops>
<ALIASOF TabSetFormatting_NoTabStops,TabSetFormatting_NoTabWidth,TabSetFormatting_AlwaysUseBrackets>
<ALIASOF TabSetFormatting_Default,TabSetFormatting_StopsWithoutBracketsAndTabWidth>
<ALIASOF TabSetFormatting_StopsOnly,TabSetFormatting_TabWidthOnly>
<ALIASOF TabSetFormatting_Full,TabSetFormatting_AutoTabWidth>
Summary:
  Available formatting options for the
  <LINK TJclTabSet.ToString@Integer, TJclTabSet.ToString> method.
Description
  The <LINK TJclTabSet.ToString@Integer, TJclTabSet.ToString@Integer> method
  allows for a number of formatting options to be specified. Options can be
  or'd with each other to specify exact formatting. Below is the list of
  available formatting options:

  <TABLE>
    Constant                                          Meaning
    --------                                          -------
    TabSetFormatting_SurroundStopsWithBrackets        The fixed tabulation positions are surrounded with brackets
    TabSetFormatting_EmptyBracketsIfNoStops           If no fixed tabulation positions are specified, but the
                                                        TabSetFormatting_SurroundStopsWithBrackets option is specified,
                                                        output the opening and closing brackets anyway.
    TabSetFormatting_NoTabStops                       Do not output the fixed tabulation positions.
    TabSetFormatting_NoTabWidth                       Do not output the additional tab width.
    TabSetFormatting_AutoTabWidth                     Include tab width even if its determined by the tabulation
                                                        positions.
    ?
    TabSetFormatting_AlwaysUseBrackets                Combines the TabSetFormatting_SurroundStopsWithBrackets and
                                                        TabSetFormatting_EmptyBracketsIfNoStops options.
    TabSetFormatting_Default                          Specifies none of the formatting options.
    TabSetFormatting_Full                             Combines the TabSetFormatting_SurroundStopsWithBrackets,
                                                        TabSetFormatting_EmptyBracketsIfNoStops and
                                                        TabSetFormatting_AutoTabWidth options.
    ?
    TabSetFormatting_StopsWithoutBracketsAndTabWidth  An alias for the TabSetFormatting_Default option.
    TabSetFormatting_StopsOnly                        An alias for the TabSetFormatting_NoTabWidth option.
    TabSetFormatting_TabWidthOnly                     An alias for the TabSetFormatting_NoTabStops option.
  </TABLE>
--------------------------------------------------------------------------------
@@TJclTabSet
<GROUP StringManipulation.Tabulation>
Summary:
  Represents a tab set that can be used to expand tabs to spaces, or vice versa.
Description:
  The TJclTabSet class represents tabulation information. Each instance can
  specify:
  * Whether the column positions are <LINK TJclTabSet.ZeroBased, zero-based>
  * Individual <LINK TJclTabSet.TabStops, tabulation positions>
  * <LINK TJclTabSet.TabWidth, Tabulation width> for columns beyond those
    specified by the individual tabulation positions.

  The class then provides functionality to:
  * Determine the <LINK TJclTabSet.TabFrom, next tabulation position> from a
    given starting column
  * Determine the
    <LINK TJclTabSet.OptimalFillInfo, optimal tab and space characters needed>
    to get from one column to another
  * <LINK TJclTabSet.Expand@string, Expand> tab characters into a sequence of
    spaces, optionally
    <LINK TJclTabSet.Expand@string@Integer, starting at an arbitrary column>
  * <LINK TJclTabSet.Optimize@string, Collapse> a sequence of space and tab
    characters into an optimized sequence of tab and space characters,
    optionally
    <LINK TJclTabSet.Optimize@string@Integer, starting at an arbitrary column>

  The class contains logic to allow automatic tab width determination by setting
  the <LINK TJclTabSet.TabWidth, tabulation width> to zero or a negative value;
  in this case the tab width is determined by the provided
  <LINK TJclTabSet.TabStops, tabulation positions> in the following manner:

  <TABLE>
  Situation                                 ActualTabWidth
  ----------                                --------------------------
  No tabulation positions defined           2
  One tabulation position defined           the defined tabulation position
  Two or more tabulation positions defined  the distance between the last
                                              two tabulation positions
  </TABLE>

* nil - safety *
  The public methods and properties that do not modify the tab set are
  <i><b>nil</b>-safe</i>, meaning they will work when used on a <b>nil</b>
  reference. A <b>nil</b> tab set will behave as if explicitly set to:

  * assume <LINK TJclTabSet.ZeroBased, zero-based> column positions
  * no defined <LINK TJclTabSet.TabStops, tabulation positions>
  * a <LINK TJclTabSet.TabWidth, tabulation width> of 2

  Note that reading any of the public properties on a <b>nil</b> instance will
  work properly.
Example:
<code>
  <i>// initiate a tab set with (zero-based) stops at 15, 20 and 30, and a tab width of 2 for
  // tabs beyond the column 30</i>
  tabs := TJclTabSet.Create([15, 20, 30], True, 2);
  <b>try</b>
    x := tabs.Expand('MyLabel:'#9'LD'#9'A,(HL)'#9'; Initialize A register');
  <b>finally</b>
    tabs.Free;
  <b>end;</b>
</code>
  The above snippet will result in <i>x</i> containing the string (? represents a
  space character): <code>MyLabel:???????LD???A,(HL)????;?Initialize?A?register</code>.
  In this case the first tab character (ASCII code 9) was transformed into seven
  spaces, the second tab character into three spaces and the third tab character
  into four spaces.
Donator:
  Marcel Bestebroer
--------------------------------------------------------------------------------
@@TJclTabSet.ActualTabWidth
Summary:
  Indicates the actual tabulation width being used.
Description:
  ActualTabWidth indicates the actual tabulation width being used for columns
  beyond those specified by the <LINK TJclTabSet.TabStops, TabStops> property.

  If the <LINK TJclTabSet.TabWidth, TabWidth> property is set to a positive,
  non-zero value, ActualTabWidth will hold the same value as TabWidth; otherwise
  it will hold a value calculated according to the following table:

  <TABLE>
  Situation                                 ActualWidthActualTabWidth
  ----------                                --------------------------
  No tabulation positions defined           2
  One tabulation position defined           the defined tabulation position
  Two or more tabulation positions defined  the distance between the last
                                              two tabulation positions
  </TABLE>
Notes:
  This property is <i><b>nil</b>-safe</i>; when read from on a
  <b>nil</b>-reference, this property will return 2.
See also:
  TJclTabSet.Count
  TJclTabSet.TabStops
  TJclTabSet.TabWidth
Donator:
  Marcel Bestebroer
--------------------------------------------------------------------------------
@@TJclTabSet.Add@SizeInt
Summary:
  Adds a fixed tabulation position.
Description:
  Add will add a fixed tabulation position to the tab set. The provided
  tabulation position is inserted at the correct index in the TabStops array.

  Duplicate tabulation positions are not allowed and will result in an
  EJclStringError.
Parameters:
  Column - The column to add to the tab set.
Result:
  The index at which the tabulation position was inserted into the TabStops
  array
Exceptions:
  <TABLE>
  NullReferenceException  Add was called on a <b>nil</b>-reference.
  EJclStringError         The specified Column already existed in the TabStops
                            array.
  </TABLE>
See also:
  TJclTabSet
  TJclTabSet.Delete
  TJclTabSet.TabStops
Donator:
  Marcel Bestebroer
--------------------------------------------------------------------------------
@@TJclTabSet.Clone
Summary:
  Initializes a new tab set instance equal to the current instance.
Description:
  The Clone method initializes a new instance of the TJclTabSet class and
  copies the contents of the current instance to the new one.
Result:
  <b>nil</b> if Clone is called on a <b>nil</b> instance<p>
  <i>- or -</i><p>
  A new TJclTabSet instance identical to the instance Close was called on
Notes:
  This method is <i><b>nil</b>-safe</i>; when invoked on a
  <b>nil</b>-reference, this method will return <b>nil</b>.
See Also
  NewReference
Donator:
  Marcel Bestebroer
--------------------------------------------------------------------------------
@@TJclTabSet.Count
Summary:
  Indicates the number of tabulation positions specified.
Description:
  Count indicates the number of <LINK TJclTabSet.TabStops, tabulation positions>
  that are defined on this instance.
Notes:
  This property is <i><b>nil</b>-safe</i>. When read from on a
  <b>nil</b>-reference, this property will return 0.
See also:
  TJclTabSet.TabStops
Donator:
  Marcel Bestebroer
--------------------------------------------------------------------------------
@@TJclTabSet.Create
Summary:
  Initializes a new, empty tab set instance.
Description:
  The constructor initializes a new instance of the TJclTabSet class. The
  parameterless overload simply initializes it to a zero-based tab set, with
  automatic tab width calculation.
Donator:
  Marcel Bestebroer
--------------------------------------------------------------------------------
@@TJclTabSet.Create@SizeInt
Summary:
  Initializes a new tab set instance with the specified tab width.
Description:
  The constructor initializes a new instance of the TJclTabSet class, setting the
  TabWidth property to the specified tab width.
Parameters:
  \TabWidth - The value to initialize the TabWidth property to.
Donator:
  Marcel Bestebroer
--------------------------------------------------------------------------------
@@TJclTabSet.Create@array of SizeInt@Boolean
Summary:
  Initializes a new tab set instance with the specified fixed tabulation
  positions and automatic tab width calculation.
Description:
  The constructor initializes a new instance of the TJclTabSet class, adding the
  specified tab stops to the TabStops array.
Parameters:
  \Tabstops - The fixed tabulation position(s) to initialize the tab set to.
  \ZeroBased - The value to initialize the ZeroBased property to.
Donator:
  Marcel Bestebroer
--------------------------------------------------------------------------------
@@TJclTabSet.Create@array of SizeInt@Boolean@SizeInt
Summary:
  Initializes a new tab set instance with the specified fixed tabulation
  positions and tab width.
Description:
  The constructor initializes a new instance of the TJclTabSet class, adding the
  specified tab stops to the TabStops array and setting the TabWidth property to
  the specified tab width.
Parameters:
  \Tabstops - The fixed tabulation position(s) to initialize the tab set to.
  \ZeroBased - The value to initialize the ZeroBased property to.
  \TabWidth - The value to initialize the TabWidth property to.
Donator:
  Marcel Bestebroer
--------------------------------------------------------------------------------
@@TJclTabSet.Delete@SizeInt
Summary:
  Removes a fixed tabulation position.
Description:
  Delete will remove the specified column from the list of fixed tabulation
  positions.
Parameters:
  Column - The column to remove from the tab set.
Result:
  The index from which the tabulation position was removed from the TabStops
  array<p>
  ?<i>- or -</i><p>
  A negative value if the tabulation position was not found
Exceptions:
  <TABLE>
  NullReferenceException  Delete was called on a <b>nil</b>-reference.
  </TABLE>
See also:
  TJclTabSet
  TJclTabSet.Add
  TJclTabSet.TabStops
Donator:
  Marcel Bestebroer
--------------------------------------------------------------------------------
@@TJclTabSet.Expand@string
Summary:
  Expands tabs to spaces in the provided string.
Description:
  Expand expands tab characters in the provided string into sequences of
  spaces while preserving the formatting. Expand will assume the string starts
  at column 0 (<LINK TJclTabSet.ZeroBased, zero-based> set to <code>True</code>) or 1
  (<LINK TJclTabSet.ZeroBased, zero-based> set to <code>False</code>).

  Multi-line strings, ie. strings containing one or more newline sequences (eg.
  CrLf, but also single Cr of Lf characters are treated as newlines), are
  handled properly, with each line starting at column 0
  (<LINK TJclTabSet.ZeroBased, zero-based> set to <code>True</code>) or 1
  (<LINK TJclTabSet.ZeroBased, zero-based> set to <code>False</code>).

  The reverse operation (collapse sequences of spaces into tab characters) can
  be achieved by the <LINK TJclTabSet.Optimize@string, Optimize> method.
Parameters:
  S - The string to expand tabs in.
Result:
  If S contains tabs, they will have been converted to 1 or more space characters,
  depending on the column the tab character is in. Otherwise, the string is
  unmodified.
Notes:
  This method is <i><b>nil</b>-safe</i>; when invoked on a
  <b>nil</b>-reference, this method will assume a tab width of two on a
  zero-based tab set.
Example:
  See the <LINK TJclTabSet, TJclTabSet> help for an example.
See also:
  TJclTabSet
  TJclTabSet.Expand@string@SizeInt
Donator:
  Marcel Bestebroer
--------------------------------------------------------------------------------
@@TJclTabSet.Expand@string@SizeInt
Summary:
  Expands tabs to spaces in the provided string.
Description:
  Expand expands tab characters in the provided string into sequences of
  spaces while preserving the formatting. Expand will assume the string starts
  at the provided column.

  Multi-line strings, ie. strings containing one or more newline sequences (eg.
  CrLf, but also single Cr of Lf characters are treated as newlines), are
  handled properly, with all but the first line starting at column 0
  (<LINK TJclTabSet.ZeroBased, zero-based> set to <code>True</code>) or 1
  (<LINK TJclTabSet.ZeroBased, zero-based> set to <code>False</code>).

  The reverse operation (collapse sequences of spaces into tab characters) can
  be achieved by the <LINK TJclTabSet.Optimize@string@SizeInt, Optimize> method.
Parameters:
  S - The string to expand tabs in.
  Column - The starting column to use when expanding the tabs.
Result:
  If S contains tab character, they will have been converted to 1 or more space
  characters, depending on the column the tab character is in. Otherwise, the
  string is unmodified.
Notes:
  This method is <i><b>nil</b>-safe</i>; when invoked on a
  <b>nil</b>-reference, this method will assume a tab width of two on a
  zero-based tab set.
Example:
  See the <LINK TJclTabSet, TJclTabSet> help for an example.
See also:
  TJclTabSet
  TJclTabSet.Expand@string
  TJclTabSet.TabFrom
Donator:
  Marcel Bestebroer
--------------------------------------------------------------------------------
@@TJclTabSet.FindStop
Summary:
  Locates a tabulation position in the TabStops array.
Description:
  FindStop returns the index in the TabStops array of the specified column. If
  the specified column does not exist the 2-complement of the index at which
  it should've been found will be returned, resulting in a negative value. You
  could use the <b>not</b>-operator to determine the actual index.
Parameters:
  Column - The tabulation column to locate.
Returns:
  The index of the column specified by the <i>Column</i> parameter in the
  TabStops array<p>
  ?<i>- or -</i><p>
  <b>A negative value</b> if the specified column could not be found. Use the
  <b>not</b>-operator to retrieve the index at which it should've been found.
Exceptions:
  <TABLE>
    ArgumentOutOfRangeException   The <i>Column</i> parameter is less than
                                    0 (<LINK TJclTabSet.ZeroBased, zero-based>)
                                    or 1 (not zero-based).
  </TABLE>
Donator:
  Marcel Bestebroer
--------------------------------------------------------------------------------
@@TJclTabSet.FromString
Summary
  Converts a string into a tab set.
Description
  The FromString class method returns a tab set setup according to the provided
  string represention.

  The string should be formatted according to the same rules as outlined in the
  <LINK TJclTabSet.ToString, ToString> method documentation:
  <TABLE>
    '0'                             Optional: flag to set the tab set to
                                      zero-based mode.
    '['                             Optional: opening bracket for the fixed
                                      tabulation positions. When present, the
                                      closing bracket must be present or an
                                      exception will be raised.
    comma-separated list of         Optional: The individual fixed tabulation
      tabulation positions            positions of this tab set. <b>Note:</b>
                                      if the zero-based flag is present but no
                                      opening bracket, an exception will be
                                      raised.
    ']'                             Closing bracket for the fixed tabulation
                                      positions. Required if an opening bracket
                                      is present earlier.
    '+'                             Optional: indicates the following number as
                                      the tab width property.
    tab width                       Optional: the tab width property. Required if
                                      the plus character is present.
  </TABLE>
Parameters
  S -  A string describing the tab set. It should be formatted according to the
        rules outlined in the <LINK TJclTabSet.ToString, ToString>
        documentation. 
Returns:
  A TJclTabSet representated by the string parameter.
--------------------------------------------------------------------------------
@@TJclTabSet.InternalTabStops
Summary:
  Provides <b>nil</b>-safe access to the tab stops array.
Description:
  InternalTabStops provides <b>nil</b>-safe access to the actual tab stops
  array.
Returns:
  A TDynSizeIntArray holding each individual tab position<p>
  ?<i>- or -</i><p>
  <b>nil</b> if the method is called on a <b>nil</b>-reference
Donator:
  Marcel Bestebroer
--------------------------------------------------------------------------------
@@TJclTabSet.InternalTabWidth
Summary:
  Provides <b>nil</b>-safe access to the specified tab width.
Description:
  InternalTabWidth provides <b>nil</b>-safe access to the specified tab width
  (not to be confused with the actual tab width).
Returns:
  The value of the TabWidth property<p>
  ?<i>- or -</i><p>
  <b>2</b> if the method is called on a <b>nil</b>-reference
Donator:
  Marcel Bestebroer
--------------------------------------------------------------------------------
@@TJclTabSet.NewReference
Summary:
  Initializes a new tab set instance referencing the current instance.
Description:
  The NewReference method initializes a new instance of the TJclTabSet class and
  sets a reference in the new instance to the current instance.

  NewReference allows several tabset instances to hold the same tab set
  settings, regardless of which instance changes them. Only when the last
  tab set instance is destroyed, will the actual tab set data be disposed of.

  Contrast this to Clone, which will simply copy the data from the original
  instance to the new one. Whenever you change the settings in one instance,
  the other will remain unaffected.
Result:
  <b>nil</b> if NewReference is called on a <b>nil</b> instance<p>
  <i>- or -</i><p>
  A new TJclTabSet instance identical to the instance Close was called on
Notes:
  This method is <i><b>nil</b>-safe</i>; when invoked on a
  <b>nil</b>-reference, this method will return <b>nil</b>.
See Also
  Clone
Donator:
  Marcel Bestebroer
--------------------------------------------------------------------------------
@@TJclTabSet.OptimalFillInfo
Summary:
  Determines the optimal number of tab and space characters needed to fill the
  room between two columns.
Description:
  OptimalFillInfo will determine the ideal amount of tab characters and/or
  space characters required to get from the first provided column to the second.
Parameters:
  \StartColumn -  The starting column to use.
  TargetColumn -  The required column to end at.
  TabsNeeded -    Will hold the amount of tab characters needed to get to the
                  destination column.
  SpacesNeeded -  Will hold the amount of space characters needed to get to the
                  destination column.
Exceptions:
  <TABLE>
    ArgumentOutOfRangeException   The <i>\StartColumn</i> parameter is less than
                                    0 (<LINK TJclTabSet.ZeroBased, zero-based>)
                                    or 1 (not zero-based).<p>
                                    <i>?- or -</i><p>                                    
                                    The <i>TargetColumn</i> parameter is less
                                    than the <i>\StartColumn</i> parameter.
  </TABLE>
Example:
  <b>Note:</b>This example assumes a tab set instance set up as in the example
  given in the <LINK TJclTabSet, TJclTabSet> help.

<CODE>
  tabs.OptimalFillInfo(5, 21, TabsNeeded, SpacesNeeded);
  <i>// TabsNeeded will be 2 (taking us only to column 20), SpacesNeeded will be 1.</i>
</CODE>
See also:
  TJclTabSet
  TJclTabSet.Optimize@string
Donator:
  Marcel Bestebroer
--------------------------------------------------------------------------------
@@TJclTabSet.Optimize@string
Summary:
  Collapses a string to the optimal tab and space character sequences.
Description:
  Optimize reduces tab and space character sequences in the provided string into
  an optimized (shortest) sequences of tab and space characters while preserving
  the formatting. Optimize will assume the string starts at column 0
  (<LINK TJclTabSet.ZeroBased, zero-based> set to <code>True</code>) or 1
  (<LINK TJclTabSet.ZeroBased, zero-based> set to <code>False</code>).

  Multi-line strings, ie. strings containing one or more newline sequences (eg.
  CrLf, but also single Cr of Lf characters are treated as newlines), are
  handled properly, with each line starting at column 0
  (<LINK TJclTabSet.ZeroBased, zero-based> set to <code>True</code>) or 1
  (<LINK TJclTabSet.ZeroBased, zero-based> set to <code>False</code>).

  The reverse operation (expand sequences of tab characters into spaces) can
  be achieved by the <LINK TJclTabSet.Expand@string, Expand> method.
Parameters:
  S - The string to collapse tabs and spaces in.
Result:
  Any tab and/or space character sequences in S will have been reduced to their
  shortest form; no other item in the string is modified.
Notes:
  This method is <i><b>nil</b>-safe</i>; when invoked on a
  <b>nil</b>-reference, this method will assume a tab width of two on a
  zero-based tab set.
See also:
  TJclTabSet
  TJclTabSet.OptimalFillInfo
  TJclTabSet.Optimize@string@SizeInt
Donator:
  Marcel Bestebroer
--------------------------------------------------------------------------------
@@TJclTabSet.Optimize@string@SizeInt
Summary:
  Expands tabs to spaces in the provided string.
Description:
  Optimize reduces tab and space character sequences in the provided string into
  an optimized (shortest) sequences of tab and space characters while preserving
  the formatting. Optimize will assume the string starts at the provided column.

  Multi-line strings, ie. strings containing one or more newline sequences (eg.
  CrLf, but also single Cr of Lf characters are treated as newlines), are
  handled properly, with all but the first line starting at column 0
  (<LINK TJclTabSet.ZeroBased, zero-based> set to <code>True</code>) or 1
  (<LINK TJclTabSet.ZeroBased, zero-based> set to <code>False</code>).

  The reverse operation (expand sequences of tab characters into spaces) can
  be achieved by the <LINK TJclTabSet.Expand@string@SizeInt, Expand> method.
Parameters:
  S - The string to expand tabs in.
  Column - The starting column to use when expanding the tabs.
Result:
  Any tab and/or space character sequences in S will have been reduced to their
  shortest form; no other item in the string is modified.
Notes:
  This method is <i><b>nil</b>-safe</i>; when invoked on a
  <b>nil</b>-reference, this method will assume a tab width of two on a
  zero-based tab set.
See also:
  TJclTabSet
  TJclTabSet.OptimalFillInfo
  TJclTabSet.Optimize@string
Donator:
  Marcel Bestebroer
--------------------------------------------------------------------------------
@@TJclTabSet.StartColumn
Summary:
  Indicates the starting column used when none is specified.
Description:
  StartColumn indicates which column is used as the start of a line.
Returns:
  <b>0</b> if ZeroBased is set to <code>True</code> or if this method is called on a
  <b>nil</b>-reference
  ?<i>- or -</i><p>
  <b>1</b> if ZeroBased is set to <code>False</code>
Donator:
  Marcel Bestebroer
--------------------------------------------------------------------------------
@@TJclTabSet.TabFrom
Summary:
  Determines the next column when tabbing from the specified column.
Description:
  TabFrom will determine the next column if a tab character would occur at the
  specified column.
Parameters:
  Column - The starting column to use when determine the next column.
Result:
  An Integer representing the next tabulation position.
Exceptions:
  <TABLE>
    ArgumentOutOfRangeException   The <i>Column</i> parameter is less than
                                    0 (<LINK TJclTabSet.ZeroBased, zero-based>)
                                    or 1 (not zero-based).
  </TABLE>
Example:
  <b>Note:</b>This example assumes a tab set instance set up as in the example
  given in the <LINK TJclTabSet, TJclTabSet> help.

<CODE>
  a := tabs.TabFrom(0);   <i>// a will be 15</i>
  b := tabs.TabFrom(24);  <i>// b will be 30</i>
  c := tabs.TabFrom(34);  <i>// c will be 36</i>
  d := tabs.TabFrom(35);  <i>// d will be 36</i>
</CODE>
See also:
  TJclTabSet
  TJclTabSet.Expand@string
Donator:
  Marcel Bestebroer
--------------------------------------------------------------------------------
@@TJclTabSet.TabStops
Summary:
  Specifies the tabulation positions to use.
Description:
  TabStops indicates which fixed tabulation positions this set will use. The
  array is guaranteed in column order, with the smallest tabulation position
  being at index 0. As a consequence, writing a new value at any index of the
  array is internally handled as a <LINK TJclTabSet.Delete, delete>, followed
  by an <TLINK TJclTabSet.Add, add> operation, to preserve this ordered
  property.
Notes:
  This property is <i><b>nil</b>-safe</i>. However, since a <b>nil</b> tab set
  has no fixed tabulation positions, any read or write operation will result in
  an EJclStringError (argument out of range).
See also:
  TJclTabSet.ActualTabWidth
  TJclTabSet.Count
  TJclTabSet.TabStops
  TJclTabSet.TabWidth
Donator:
  Marcel Bestebroer
--------------------------------------------------------------------------------
@@TJclTabSet.TabWidth
Summary:
  Specifies the tabulation width this instance will use.
Description:
  TabWidth indicates the tabulation width to use for columns beyond those
  specified by the <LINK TJclTabSet.TabStops, TabStops> property.

  If this property is set to zero or a negative value, the instance will
  calculate the <LINK TJclTabSet.ActualTabWidth, actual tabulation width> to use
  according to the following table:

  <TABLE>
  Situation                                 ActualTabWidth
  ----------                                --------------------------
  No tabulation positions defined           2
  One tabulation position defined           the defined tabulation position
  Two or more tabulation positions defined  the distance between the last
                                              two tabulation positions
  </TABLE>
Notes:
  This property is <i><b>nil</b>-safe</i>. When read from on a
  <b>nil</b>-reference, this property will return 2. When written to on a
  <b>nil</b>-reference, a NullReferenceException will be raised.
See also:
  TJclTabSet.ActualTabWidth
  TJclTabSet.Count
  TJclTabSet.TabStops
Donator:
  Marcel Bestebroer
--------------------------------------------------------------------------------
@@TJclTabSet.ToString
Summary
  Converts the tab set into its string representation.
Description
  The ToString method returns a string representing this tab set, containing
  each individual tabulation position and the tab width used beyond those
  fixed positions.

  Using this overload is the same as using the one with the
  <LINK TJclTabSet.ToString@SizeInt, formatting options>, specifying the
  TabSetFormatting_Full option.

  The resulting string will be composed of the following items:
  <TABLE>
    '0'                             Outputted only when the tabset is zero-based.
    0 or more whitespaces           Used to separate the zero-based flag from
                                      the tabulation positions; at least one
                                      whitespace is used if no opening bracket is
                                      used.
    '['                             Opening bracket for the fixed tabulation
                                      positions.
    comma-separated list of         The individual fixed tabulation positions of
      tabulation positions            this tab set.
    ']'                             Closing bracket for the fixed tabulation
                                      positions.
    0 or more whitespaces           Used to separate the zero-based flag and/or
                                      tabulation positions from the tab width.
    '+'                             Outputted to mark the tab width property.
    Value of ActualTabWidth         The tab width.
  </TABLE>
Returns:
  A string representation of this tab set.
Notes:
  This method is <i><b>nil</b>-safe</i>.
--------------------------------------------------------------------------------
@@TJclTabSet.ToString@SizeInt
Summary
  Converts the tab set into its string representation using the specified
  formatting.
Description
  The ToString method returns a string representing this tab set, containing
  each individual tabulation position and the tab width used beyond those
  fixed positions.

  The FormattingOptions parameter indicates whether and how the tabulation
  positions are handled and whether the tab width will be in the string.

  The resulting string will be composed of the following items:
  <TABLE>
    '0'                             Outputted only when the tabset is zero-based.
    0 or more whitespaces           Used to separate the zero-based flag from
                                      the tabulation positions; at least one
                                      whitespace is used if no opening bracket is
                                      used.
    '['                             Opening bracket for the fixed tabulation
                                      positions, outputted when the formatting
                                      options specify it.
    comma-separated list of         The individual fixed tabulation positions of
      tabulation positions            this tab set, outputted when tab stops are
                                      not disabled by the options.
    ']'                             Closing bracket for the fixed tabulation
                                      positions, outputted when the formatting
                                      options specify it.
    0 or more whitespaces           Used to separate the zero-based flag and/or
                                      tabulation positions from the tab width.
    '+'                             Outputted to mark the tab width property.
    Value of ActualTabWidth         The tab width.
  </TABLE>
Parameters:
  FormattingOptions - the formatting options to use. See
  <LINK TabSetFormattingOptions, TJclTabSet formatting options> for the
  available options.
Returns:
  A string representation of this tab set, formatted according to the provided
  formatting options.
Notes:
  This method is <i><b>nil</b>-safe</i>.
--------------------------------------------------------------------------------
@@TJclTabSet.UpdatePosition@string
Summary:
  Calculates the ending column after expanding tabs in the provided
  string.
Description:
  Calculate will simulate the Expand method, calculating the ending column
  only.

  Multi-line strings, ie. strings containing one or more newline sequences (eg.
  CrLf, but also single Cr of Lf characters are treated as newlines), are
  handled properly, with all but the first line starting at column 0
  (<LINK TJclTabSet.ZeroBased, zero-based> set to <code>True</code>) or 1
  (<LINK TJclTabSet.ZeroBased, zero-based> set to <code>False</code>).
Parameters:
  S - The string to expand tabs in.
Result:
  The ending column after expanding tabs in the provided string.
Notes:
  This method is <i><b>nil</b>-safe</i>; when invoked on a
  <b>nil</b>-reference, this method will assume a tab width of two on a
  zero-based tab set.
Example:
  See the <LINK TJclTabSet, TJclTabSet> help for an example.
See also:
  TJclTabSet
  TJclTabSet.Expand@string@SizeInt
  TJclTabSet.TabFrom
Donator:
  Marcel Bestebroer
--------------------------------------------------------------------------------
@@TJclTabSet.UpdatePosition@string@SizeInt
Summary:
  Calculates the ending column after expanding tabs in the provided
  string.
Description:
  Calculate will simulate the Expand method, calculating the ending column
  only.

  Multi-line strings, ie. strings containing one or more newline sequences (eg.
  CrLf, but also single Cr of Lf characters are treated as newlines), are
  handled properly, with all but the first line starting at column 0
  (<LINK TJclTabSet.ZeroBased, zero-based> set to <code>True</code>) or 1
  (<LINK TJclTabSet.ZeroBased, zero-based> set to <code>False</code>).
Parameters:
  S - The string to expand tabs in.
  Column - The starting column to use when expanding the tabs.
Result:
  The ending column after expanding tabs in the provided string.
Notes:
  This method is <i><b>nil</b>-safe</i>; when invoked on a
  <b>nil</b>-reference, this method will assume a tab width of two on a
  zero-based tab set.
Example:
  See the <LINK TJclTabSet, TJclTabSet> help for an example.
See also:
  TJclTabSet
  TJclTabSet.Expand@string@SizeInt
  TJclTabSet.TabFrom
Donator:
  Marcel Bestebroer
--------------------------------------------------------------------------------
@@TJclTabSet.UpdatePosition@string@SizeInt@SizeInt
Summary:
  Calculates the ending line and column after expanding tabs in the provided
  string.
Description:
  Calculate will simulate the Expand method, updating the line and column
  variables only. For convenience, the ending column is also the method's result
  value.

  Multi-line strings, ie. strings containing one or more newline sequences (eg.
  CrLf, but also single Cr of Lf characters are treated as newlines), are
  handled properly, with all but the first line starting at column 0
  (<LINK TJclTabSet.ZeroBased, zero-based> set to <code>True</code>) or 1
  (<LINK TJclTabSet.ZeroBased, zero-based> set to <code>False</code>).
Parameters:
  S - The string to expand tabs in.
  Column - On entry: The starting column to use when expanding the tabs.
            On return: The ending column after expanding the tabs.
  Line - On entry: The starting line to use when expanding the tabs.
          On return: The ending line after expanding the tabs.
Result:
  The ending column after expanding tabs in the provided string.
Notes:
  This method is <i><b>nil</b>-safe</i>; when invoked on a
  <b>nil</b>-reference, this method will assume a tab width of two on a
  zero-based tab set.
Example:
  See the <LINK TJclTabSet, TJclTabSet> help for an example.
See also:
  TJclTabSet
  TJclTabSet.Expand@string@SizeInt
  TJclTabSet.TabFrom
Donator:
  Marcel Bestebroer
--------------------------------------------------------------------------------
@@TJclTabSet.ZeroBased
Summary:
  Specifies whether the columns are zero-based.
Description:
  ZeroBased indicates whether specified
  <LINK TJclTabSet.TabStops, tabulation positions> and other column references
  are zero based.

  If this property is set to <code>True</code>, all columns are considered to be
  zero-based (the first column index is zero); otherwise columns references are
  one-based (the first column index is one).

  If this flag is toggled, any stored
  <LINK TJclTabSet.TabStops, tabulation positions> are automatically converted
  to the new state (ie. values are incremented when setting to <code>False</code> or
  decremented when setting to <code>True</code>).
Notes:
  This property is <i><b>nil</b>-safe</i>. When read from on a
  <b>nil</b>-reference, this property will return <code>True</code>. When written to
  on a <b>nil</b>-reference, a NullReferenceException will be raised.
See also:
  TJclTabSet.Expand@string@SizeInt
  TJclTabSet.TabStops
  TJclTabSet.TabFrom
Donator:
  Marcel Bestebroer
--------------------------------------------------------------------------------
@@AnsiCompareNaturalStr
<GROUP StringManipulation.StringTestRoutines>
Summary:
  Compares strings based on the current locale with case sensitivity and using a
  'natural order' algorithm.
Description:
  AnsiCompareNaturalStr implements a case-sensitive, 'natural' comparison
  between the two supplied strings. It performs identical to the AnsiCompareStr
  function but compares number components numerically, instead of
  alphabetically.

  Leading spaces are ignored when comparing numbers, but leading zeroes aren't.
  This gives more sensible order when comparing and sorting fractional numbers.

  The table below shows the behaviour of both AnsiCompareNaturalStr and
  AnsiCompareStr:
   <TABLE>
S1                  S2                  AnsiCompareNaturalStr   AnsiCompareStr
------------        ------------        ---------------------   --------------
Delphi 5            Delphi 2005         negative                positive
Delphi    5         Delphi 2005         negative                negative
Delphi    5         Delphi   6          negative                negative
Delphi   5          Delphi    6         negative                positive
Delphi Highlander   Delphi 2005         positive                positive
Delphi Highlander   Delphi  Highlander  positive                positive
Foobar v0.9.4       Foobar v0.10.3      negative                positive
Foobar v0.9.4       Foobar V0.9.4       negative                negative
?
0002                1                   negative                negative
1.5                 1.06                positive                negative
?
0                   -5                  positive                positive
-5                  +2                  negative                positive
</TABLE>

Parameters:
  S1 - First string to compare.
  S2 - Second string to compare.
Result:
  <code>0</code> if S1 is identical to S2
  ?<i>- or -</i><p>
  <code>a negative value</code> if S1 is less than S2
  ?<i>- or -</i><p>
  <code>a positive value</code> if S1 is greater than S2
Donator:
  Marcel Bestebroer
--------------------------------------------------------------------------------
@@AnsiCompareNaturalText
<GROUP StringManipulation.StringTestRoutines>
Summary:
  Compares strings based on the current locale with case insensitivity and using
  a 'natural order' algorithm.
Description:
  AnsiCompareNaturalText implements a case-insensitive, 'natural' comparison
  between the two supplied strings. It performs identical to the AnsiCompareText
  function but compares number components numerically, instead of
  alphabetically.

  Leading spaces are ignored when comparing numbers, but leading zeroes aren't.
  This gives more sensible order when comparing and sorting fractional numbers.

  The table below shows the behaviour of both AnsiCompareNaturalText and
  AnsiCompareText:
<TABLE>
S1                  S2                  AnsiCompareNaturalText  AnsiCompareText
------------        ------------        ----------------------  ---------------
Delphi 5            Delphi 2005         negative                positive
Delphi    5         Delphi 2005         negative                negative
Delphi    5         Delphi   6          negative                negative
Delphi   5          Delphi    6         negative                positive
Delphi Highlander   Delphi 2005         positive                positive
Delphi Highlander   Delphi  Highlander  positive                positive
Foobar v0.9.4       Foobar v0.10.3      negative                positive
Foobar v0.9.4       Foobar V0.9.4       zero                    zero
?
0002                1                   negative                negative
1.5                 1.06                positive                negative
?
0                   -5                  positive                positive
-5                  +2                  negative                positive
</TABLE>
Parameters:
  S1 - First string to compare.
  S2 - Second string to compare.
Result:
  <code>0</code> if S1 is identical to S2
  ?<i>- or -</i><p>
  <code>a negative value</code> if S1 is less than S2
  ?<i>- or -</i><p>
  <code>a positive value</code> if S1 is greater than S2
Donator:
  Marcel Bestebroer
--------------------------------------------------------------------------------