I've added the following functions to StringUtils. If someone has any comments (possible interface changes, etc.), please let me know. (Most of them have been used in my IDE PENG for some time.)
{ Returns the number of disjoint occurences of SubStr in s. Returns 0 if SubStr is empty. } function StrCount (const SubStr : String; s : String) : Integer;
{ Returns s, with all disjoint occurences of Source replaced by Dest. } function StrReplace (const s, Source, Dest : String) : TString;
{ Converts a digit character to its numeric value. Handles every base up to 36 (0 .. 9, a .. z, upper and lower case recognized). Returns -1 if the character is not a digit at all. If you want to use it for a base < 36, you have to check if the result is smaller than the base and not equal to -1. } function Char2Digit (ch : Char) : Integer;
{ Encode a string in a printable format (quoted printable and surrounded with `"'). All occurences of `"' within the string are encoded, so the result string contains exactly two `"' characters (at the beginning and ending). This is useful to store arbitrary strings in text files while keeping them as readable as possible (which is the goal of the quoted printable encoding in general, RFC 1521, section 5.1) and being able to read them back losslessly (with UnQuoteString). } function QuoteString (const s : String) : TString;
{ Decode a string encoded by QuoteString (removing the `"' and expanding quoted printable encoded characters). Returns True if successful and False if the string has an invalid form. A string returned by QuoteString is always valid. } function UnQuoteString (var s : String) : Boolean;
{ Replaces all tab characters in s with the appropriate amount of spaces, assuming tab stops at every TabSize columns. Returns True if successful and False if the expanded string would exceed the capacity of s. In the latter case, some, but not all of the tabs in s may have been expanded. } function ExpandTabs (var s : String; TabSize : Integer) : Boolean;
{ Returns s, with all occurences of C style escape sequences (e.g. `\n') replaced by the characters they mean. If AllowOctal is True, also octal character specifications (e.g. `\007') are replaced. If RemoveQuoteChars is True, any other backslashes are removed (e.g. `*' -> `*' and `\' -> `'), otherwise they are kept, and also `\' is left as two backslashes then. } function ExpandCEscapeSequences (const s : String; RemoveQuoteChars, AllowOctal : Boolean) : TString;
I'm also planning to add the following routines for parsing strings (again, comments welcome):
{ Sets of characters accepted for `True' and `False' by Char2Boolean and StrReadBoolean. } var CharactersTrue : CharSet = ['Y', 'y']; CharactersFalse : CharSet = ['N', 'n'];
{ If ch is an element of CharactersTrue, Dest is set to True, otherwise if it is an element of CharactersFalse, Dest is set to False. In both cases True is returned. If ch is not an element of either set, Dest is set to False and False is returned. } function Char2Boolean (ch : Char; var Dest : Boolean) : Boolean;
{ All the following StrReadFoo functions behave similarly. They read items from a string s, starting at index i, to a variable Dest. They skip any space characters (spaces and tabs) by incrementing i first. They return True if successful, False otherwise. i is incremented accordingly if successful, otherwise i is left unchanged, apart from the skipping of space characters, and Dest is undefined. This behaviour makes it easy to use the functions in a row like this: i := 1; if StrReadInt (s, i, Size) and StrReadComma (s, i) and StrReadQuoted (s, i, Name) and StrReadComma (s, i) and ... }
{ Just skip any space characters as described above. } procedure StrSkipSpaces (const s : String; var i : Integer);
{ Read a quoted string (as produced by QuoteString) from a string and unquote the result using UnQuoteString. It is considered failure if the result (unquoted) would be longer than the capacity of Dest.} function StrReadQuoted (const s : String; var i : Integer; var Dest : String) : Boolean;
{ Read a string delimited with Delimiter from a string and return the result with the delimiters removed. It is considered failure if the result (without delimiters) would be longer than the capacity of Dest. } function StrReadDelimited (const s : String; var i : Integer; var Dest : String; Delimiter : Char) : Boolean;
{ Read a word (consisting of anything but space characters and commas) from a string. It is considered failure if the result would be longer than the capacity of Dest. } function StrReadWord (const s : String; var i : Integer; var Dest : String) : Boolean;
{ Check that a certain string is contained in s (after possible space characters). } function StrReadConst (const s : String; var i : Integer; const Expected : String) : Boolean;
{ A simpler to use version of StrReadConst that expects a `,'. } function StrReadComma (const s : String; var i : Integer) : Boolean;
{ Read an integer number from a string. } function StrReadInt (const s : String; var i : Integer; var Dest : Integer) : Boolean;
{ Read a real number from a string. } function StrReadReal (const s : String; var i : Integer; var Dest : Real) : Boolean;
{ Read a Boolean value, represented by a single character from CharactersTrue or CharactersFalse (cf. Char2Boolean), from a string. } function StrReadBoolean (const s : String; var i : Integer; var Dest : Boolean) : Boolean;
{ Read an enumerated value, i.e., one of the entries of IDs, from a string, and stores the ordinal value, i.e., the index in IDs (always zero-based) in Dest. } function StrReadEnum (const s : String; var i : Integer; var Dest : Integer; var IDs : array of PString) : Boolean;
Frank