home *** CD-ROM | disk | FTP | other *** search
Text File | 1993-04-10 | 39.0 KB | 1,343 lines |
-
- String++ Version 3.0
-
- Copyright 1993 by Carl Moreland
- 04/10/93
-
- ---------------------------------------------------------------------------
-
- String++ is a String class written for Borland/Turbo C++. It contains a
- variety of String processing functions such as Insert, Delete, Replace,
- Find, Justify, and Trim, as well as overloaded operators for assignment,
- concatenation, and comparison. For AWK programmers, there are standard AWK
- functions such as sub, substr, index, and split, as well as support for
- regular expressions in many functions.
-
- Some of the ways that Strings may be declared or initialized are as
- follows:
-
- String str; // NULL string
- str('H'); // single character
- str("Hello World"); // char*
- str(c, 5); // make 5 copies of character c
- str(p, 5); // char* p, begin at p[5]
- str(p, 5, 3); // begin at p[5], use 3 chars
- str(s); // another String
- str(s, 5); // String s, begin at s[5]
- str(s, 5, 3); // begin at s[5], use 3 chars
- str(45); // convert an int to a String
- str(1.23); // convert a float to a String
- str(1.23, "%6.2f"); // convert a float to a String
- // using a format specifier
- str = 'H'; // single character
- str = "Hello World"; // char*
- str = 1.6e-19; // any number
- str = p; // char* p
- str = s; // another String
- str = x; // any number
-
- The following operators are available:
-
- = assignment - see above
- () str() returns the char* of the string
- char cast operator, returns the first char of the string
- char* cast operator, returns the char* of the string
- * *str returns str[0]
- [] str[i] returns the ith character of str; [] can also assign
- the ith character of a string.
- + += concatenates
- << concatenates
- * *= multiple duplicates
- == != comparisons
- < > comparisons
- <= >= comparisons
-
- Some binary operators are declared as friend functions. This allows them to
- accept char, char*, and String as valid arguments on either side of the op-
- erator. Therefore, each of these statements is valid:
-
- s1 = "Hello" + s2;
- s1 = s2 + "World";
- s1 = "Hello" + s2 + "World";
- if(s1 == "Hello World") ...
- if("Hello World" == s1) ...
-
- However,
-
- s1 = "Hello " + "World";
-
- is not legal because a String object MUST appear on one side of the opera-
- tor. A more flexible way to assign the contents of a string is to use the
- << operator:
-
- char c;
- String s1, s2;
- ...
- int n = index(s1, c);
-
- s2 << "The location of " << c << " in " << s1 << " is " << n;
-
- The << operator is overloaded to accept char, char*, String, int, long,
- float, and double.
-
- The following functions are supported. Refer to the reference section of
- this document for function syntax and examples.
-
- Copy Copy a string to a char*
- Delete Delete a substring
- FindFirst Find the first occurrence of a substring
- FindLast Find the last occurrence of a substring
- FindNext Find the next occurrence of a substring
- FindPrev Find the previous occurrence of a substring
- gsub Global substring substitution
- Index, index Position of a substring
- Insert Insert a substring
- Justify Justify the String
- Left, left Leftmost substring
- Len Length of the String
- Length, length Length of the String
- match Match a regular expression
- Mid, mid Middle substring
- Minimize Minimize the buffer space
- ptr Return the char* of a String
- Replace Replace a substring
- Right Rightmost substring
- SetFloatFormat Set the floating point format specifier
- SetIncLength Set the buffer increment length
- SetMinLength Set the buffer minimum length
- SetSize Set the buffer size
- Split, split Split a String on a field separator
- Sub, sub Leftmost substitution
- SubStr, substr Random substring
- toLower, tolower Case conversion
- toUpper, toupper Case conversion
- Trim, trim Remove outer whitespace
- Value Numeric value of a numeric String
-
- String Buffers
- --------------
-
- The contents of a String is stored in a character array. Although the
- size of the array could be just large enough to hold the String, the array
- would have to be reallocated if a single character is added to the String.
- To improve speed, this class utilizes a minimum string buffer size and an
- incremental size.
-
- The minimum buffer size is the minimum amount of memory that is initi-
- ally allocated for the character array. The default size is 16 characters.
- Each newly created String will automatically have a buffer size equal to
- this minimum size, plus one extra byte for the NULL terminator. Therfore
-
- String s1;
- String s2 = "Hello";
-
- will both have 17 bytes of memory allocated even though not all 17 bytes
- are used. If the Strings are appended to then the memory does not have to
- be reallocated provided that the new length does not exceed 17 bytes:
-
- s1 = s2;
- s2 += ", World";
-
- The minimum buffer length is stored in the private variable strMinLength
- You can set this to a new value with the SetMinLength() function:
-
- Str.SetMinLength(24);
-
- This example sets the minimum buffer length to 24 bytes (plus 1) for all
- subsequently created Strings. Note that the global String instance Str
- is used in calling this function even though any String instance could be
- used. This creates the global appearance of SetMinLength().
-
- A second variable is used in determining how a String buffer will grow.
- The private variable strIncLength specifies the minimum number of bytes
- that is added to the buffer when the String exceeds the current buffer
- size. The default value is 8 bytes. Whenever a String needs additional
- space, it receives it in multiples of 8 bytes. In the example above, s2
- contains "Hello, World". If we add some more:
-
- s2 += ", How are you?;
-
- then s2 will exceed 17 bytes and additional memory must be allocated. In
- this case, s2 will need a total of 26 bytes (plus 1 for the NULL termina-
- tor). The original 17 bytes plus the incremental 8 bytes is not enough, so
- another incremental 8 bytes is added for a total of 33 bytes. This proce-
- dure also works for newly created Strings that exceed strMinLength:
-
- String s3 = "This is a very long string.";
-
- s3 requires 28 bytes, so again it will receive 33 bytes (17+8+8). strInc-
- Length can be set using the SetIncLength() function:
-
- Str.SetIncLength(16);
-
- The reason for using minimum and incremental lengths is to reduce the
- number of memory allocations, which are time consuming. The drawback is
- that each String will waste a small amount of memory; for a moderate size
- String this will typically be strIncLength/2. Making strMinLength and
- strIncLength larger will waste more memory but require fewer memory alloca-
- tions. Setting them equal to 1 will waste no memory but each appendage op-
- eration will need to reallocate memory. This is how older versions of this
- class worked (2.12 and prior).
-
- Temporary Strings
- -----------------
-
- When using Strings, you should be aware that temporary String objects
- are sometimes created and destroyed, and that they can degrade program per-
- formance. For example,
-
- s1 = s2 + "World";
-
- creates a temporary String that is the combination of s2 and "World". It is
- this temporary String that is assigned to s1 via the = operator. The reason
- for this is because the + operator is defined to accept two const objects
- (in this case a String and a char*) and returns a newly created String. The
- = operator is defined to accept a String&, which in this case is the String
- that results from the + operation. The compiler knows that this String is
- temporary and will automatically delete it when the assignment to s1 is
- done.
-
- Functions that accept String objects as arguments can also accept char
- and char* objects, as well as other data types that are supported by String
- constructors. For example, even though the index() function is defined to
- accept two String arguments, this is legal:
-
- i = index(s1, "a");
-
- The "a" argument will be converted to a String object by the compiler be-
- cause there is a String constructor that is defined for char*. Like the op-
- erator example above, this String object is temporary and is destroyed when
- the function returns.
-
- Based on the above example, is it necessary for the String class to
- overload the various operators to accept data types that are already sup-
- ported by constructors? The answer is no, but the overloaded operators will
- reduce the number of temporary Strings that are created and therefore im-
- prove performance. In the example above, if the + operator were only de-
- fined to accept two Strings, then the "World" argument would cause the cre-
- ation of a second temporary String. Most of the String functions are not
- overloaded because they typically do not see the kind of repeated use the
- operators get. If there is a String function that will get heavy repeated
- use with non-String arguments (such as the index example above) then you
- might see some speed improvement by overloading the function.
-
- Regular Expressions
- -------------------
-
- Regular expressions are text patterns that are used for string match-
- ing. Normally, strings are compared to other strings (or substrings) and we
- look for an absolute match. However, there are times when we want to test a
- string in a more general way. For example, suppose we want to see if a
- string contains any digits. Using absolute string matching, we would have
- to run 10 comparisons, one for each digit. Using regular expressions, we
- can create a character class and make one comparison:
-
- String s1;
- Regexp re = "[0-9]";
-
- if(s1 == re)
- do_something();
-
- In the above example, the regular expression contains "[0-9]". The brackets
- enclose the character class 0-9 which means match any digit. Therefore, if
- s1 contains a digit then the comparison with re will be true.
-
- Before a regular expression can be used it must first be declared. For
- example, this will not work:
-
- if(s1 == "[0-9]")
- do_something();
-
- because the == operator will compare s1 to the literal string "[0-9]". How-
- ever, this will work:
-
- if(s1 == Regexp("[0-9]"))
- do_something();
-
- Several String functions include support for regular expressions. Like
- the other AWK functions included with the String class, the match function
- returns the position of the matching substring using C's zero-based array
- offset, and -1 if the match failed. Because the ~ operator is unary in C++,
- it could not be overloaded to provide the same functionality as in AWK. In-
- stead, the == operator and the != operator have been overloaded to use re-
- gular expressions.
-
- For more information concerning the use of regular expressions, consult
- a text on Unix or the AWK language (such as _The AWK Programming Language_,
- by Aho, Kernighan, and Weinberger).
-
- Using the String Class
- ----------------------
-
- To use the String class in your program, simply add str.lib to your
- project or make file and #include str.h in any module that uses a String.
- To use regular expressions you will also need to #include regexp.h in mod-
- ules that use them. str.lib contains all the functions in str.cpp and
- regexp.cpp (as well as parsestr.cpp and filestr.cpp), but the functions are
- separated into different object modules for greater efficiency. Note that
- str.lib is compiled for the large memory model.
-
- If you want to replace the String class in the Borland Container Class
- Library, follow the instructions in strng.doc. Don't forget to add "BCCL"
- to the Defines list in the Options-Compiler-Code Generation dialog box.
-
- ---------------------------------------------------------------------------
- ---------------------------------------------------------------------------
-
- Class Operators:
-
- ---------------------------------------------------------------------------
-
- operator =
- ----------
-
- Syntax: String& operator=(char c);
- String& operator=(char* p);
- String& operator=(String& s);
- String& operator=(int n);
- String& operator=(long n);
- String& operator=(float n);
- String& operator=(double n);
-
- Assigns contents to the String. In the case of float and double, the String
- format is determined by the format specifier fpFormat, which is a private
- member of the String class. It may be set by either a previous constructor
- call or by an explicit call to SetFloatFormat().
-
- ---------------------------------------------------------------------------
-
- operator +
- ----------
-
- Syntax: String operator+(String& s1, char* s2);
- String operator+(char* s1, String& s2);
- String operator+(String& s1, String& s2);
-
- Creates a new String by concatenating s2 to s1.
-
- ---------------------------------------------------------------------------
-
- operator +=
- -----------
-
- Syntax: String& operator+=(char c);
- String& operator+=(char* p);
- String& operator+=(String& s);
-
- Concatenates the argument to the String.
-
- ---------------------------------------------------------------------------
-
- operator <<
- -----------
-
- Syntax: String& operator<<(char c);
- String& operator<<(char* p);
- String& operator<<(String& s);
- String& operator<<(int n);
- String& operator<<(long n);
- String& operator<<(float n);
- String& operator<<(double n);
-
- Concatenates the argument to the String. In the case of float and double,
- the String format is determined by the format specifier fpFormat, which is
- a private member of the String class. It may be set by either a previous
- constructor call or by an explicit call to SetFloatFormat().
-
- ---------------------------------------------------------------------------
-
- operator *
- ----------
-
- Syntax: String operator*(String& s, unsigned n);
- String operator*(unsigned n, String& s);
-
- Creates a new String with 'n' duplications of String 's'.
-
- ---------------------------------------------------------------------------
-
- operator *=
- -----------
-
- Syntax: String& operator*=(unsigned n);
-
- Adds 'n'-1 duplications of the String to itself.
-
- ---------------------------------------------------------------------------
-
- operator ==
- operator !=
- operator <
- operator >
- operator <=
- operator >=
- -----------
-
- Syntax: int operator??(String& s1, String& s2);
- int operator??(String& s1, char* s2);
- int operator??(char* s1, String& s2);
- int operator??(String& s1, char c);
-
- Compares s1 to s2 and returns 1 if the operation is true, 0 otherwise. In
- the special case of char c, the operator compares s1[0] to c.
-
- ---------------------------------------------------------------------------
-
- operator ()
- -----------
-
- Syntax: const char* operator()();
- const char* operator()(unsigned pos);
- String operator()(unsigned pos, unsigned len);
-
- The first case returns the contents of the String (strPtr) via a const
- char*. The second method returns strPtr+pos. The third method creates a new
- String using the substring beginning at position 'pos' with length 'len' of
- String *this. The first two methods are considered safe ways to access
- strPtr because the const modifier protects strPtr from modification. In
- using these methods to pass a char* representation of a String to a func-
- tion, be aware that many functions expect a char*, not const char*. In this
- case, the safest thing to do is use the Copy() function.
-
- ---------------------------------------------------------------------------
-
- operator char
- operator char*
- --------------
-
- Syntax: operator const char();
- operator const char*();
-
- These are cast operators that are automatically called when a String object
- is passed where a char or char* is expected. The const modifier prevents
- the contents of the String object from being unintentionally modified.
-
- ---------------------------------------------------------------------------
-
- operator *
- ----------
-
- Syntax: const char operator *();
-
- Returns the first character in the String.
-
- ---------------------------------------------------------------------------
-
- operator []
- -----------
-
- Syntax: char& operator [](unsigned i);
-
- Returns the ith character in the String, or assigns the ith character.
-
- ---------------------------------------------------------------------------
- ---------------------------------------------------------------------------
-
- Class Functions:
-
- ---------------------------------------------------------------------------
-
- Copy
- ----
-
- Syntax: char* Copy(char *p);
-
- Copies the String contents to a non-const character pointer. Copy will
- allocate the memory for the pointer - it is up to you to free (delete) it.
- Normally, the contents of a String are extracted with the () operator or
- the char* cast operator. However, these return a const char* that must be
- cast to a non-const char* for some C-style functions (most Borland library
- functions will accept const char*). Although you could also use the ptr()
- method to return a non-const char*, this is considered unsafe as it comple-
- tely strips the inherent protection that the String class offers.
-
- Example:
-
- #include "str.h"
-
- char *ptr;
- s1 = "lowercase";
-
- strupr(s1()); // won't work - strupr() expects
- // a non-const char*
- strupr((char*)s1()); // cast to char* - this works
- s1.Copy(ptr); // copy s1 to char *ptr
- strupr(ptr); // normal C-style
-
- See Also: ptr, operator char*, operator ()
-
- ---------------------------------------------------------------------------
-
- Delete
- ------
-
- Syntax: String& Delete(unsigned pos, unsigned len = 1);
-
- Deletes a substring beginning at position 'pos' with length 'len'. If 'len'
- = 0, then the substring from 'pos' to the end of the String is deleted.
-
- Example:
-
- #include "str.h"
-
- String s1 = "This is a test";
- s1.Delete(5, 3); // s1 = "This a test"
-
- See Also: gsub, Replace, sub, Sub, trim, Trim
-
- ---------------------------------------------------------------------------
-
- Find...
- -------
-
- Syntax: int FindFirst(String& s);
- int FindNext(void);
- int FindLast(String& s);
- int FindPrev(void);
-
- Finds the substring s in a String. FindFirst() finds the first occurrence,
- and FindNext() finds subsequent occurrences. FindLast() finds the last
- occurrence, and FindPrev() finds preceding occurrences. Note that Find-
- Next() and FindPrev() will continue to use the substring s from the initial
- call to FindFirst() or FindLast().
-
- Example:
-
- #include "str.h"
-
- String s1 = "This is a test";
-
- i = s1.FindFirst(" ");
- while(i != -1)
- {
- s1.Delete(i, 1);
- i = s1.FindNext();
- } // s1 = "Thisisatest"
-
- See Also: index, Index, match
-
- ---------------------------------------------------------------------------
-
- Index
- -----
-
- Syntax: int Index(String& t);
- int index(Regexp& t);
-
- Returns the position of 't' in the String if it exists, or -1 if it does
- not. 't' can be a String or a regular expression.
-
- Example:
-
- #include "str.h"
-
- int i;
- String s1 = "d:\\prog\\str";
-
- i = s1.Index(":"); // i = 1
-
- See Also: FindFirst, FindNext, FindLast, FindPrev, index, match
-
- ---------------------------------------------------------------------------
-
- Insert
- ------
-
- Syntax: String& Insert(unsigned pos, String& s);
-
- Inserts substring 's' at position 'pos'.
-
- Example:
-
- #include "str.h"
-
- String s1 = "This a test";
-
- s1.Insert(5, "is "); // s1 = "This is a test"
-
- See Also: Delete, gsub, justify, Justify, Replace, sub, Sub, trim, Trim
-
- ---------------------------------------------------------------------------
-
- Justify
- -------
-
- Syntax: String& Justify(int type, int len, int mode = CLIP|TRIM);
-
- Justifies the String by padding it with spaces until it is 'len' long. The
- justification 'type' can be LEFT, CENTER, or RIGHT. If the String has any
- leading or trailing whitespaces (spaces or tabs) then they are first re-
- moved if 'mode'|=TRIM. If the String is longer than 'len' (after the op-
- tional removal of white spaces) then it is clipped to len if 'mode'|=CLIP.
-
- Example:
-
- #include "str.h"
-
- String s1 = s2 = s3 = "Hello World";
-
- s1.Justify(LEFT, 20); // s1 = "Hello World "
- s2.Justify(CENTER, 20); // s2 = " Hello World "
- s3.Justify(RIGHT, 20); // s3 = " Hello World"
-
- See Also: Insert, justify, trim, Trim
-
- ---------------------------------------------------------------------------
-
- Left
- ----
-
- Syntax: String& Left(int len);
-
- Reduces the String to the leftmost 'len' characters.
-
- Example:
-
- #include "str.h"
-
- String s1 = s2 = s3 = "This is a test";
-
- s1.Left(4); // s1 = "This"
- s2.Mid(5, 4); // s2 = "is a"
- s3.Right(4); // s3 = "test"
-
- See Also: left, mid, Mid, right, Right, substr, SubStr
-
- ---------------------------------------------------------------------------
-
- Len, Length
- -----------
-
- Syntax: int Len(void) const;
- int Length(void) const;
-
- Returns the length of the String:
-
- Example:
-
- #include "str.h"
-
- int i;
- String s1 = "Hello World";
-
- i = s1.Length(); // i = 11
-
- See Also: length
-
- ---------------------------------------------------------------------------
-
- Mid
- ---
-
- Syntax: String& Mid(int pos, int len);
-
- Reduces the String to the substring beginning at position 'pos' with length
- 'len'.
-
- Example:
-
- #include "str.h"
-
- String s1 = s2 = s3 = "This is a test";
-
- s1.Left(4); // s1 = "This"
- s2.Mid(5, 4); // s2 = "is a"
- s3.Right(4); // s3 = "test"
-
- See Also: left, Left, mid, right, Right, substr, SubStr
-
- ---------------------------------------------------------------------------
-
- Minimize
- --------
-
- Syntax: void Minimize(void);
-
- Minimizes the allocated buffer space for the String. Normally, Strings are
- allocated memory based on strMinLength and strIncLength, which are the mi-
- nimum and incremental buffer lengths. Therefore, a String could be alloca-
- ted more memory than it is using.
-
- Example:
-
- #include "str.h"
-
- String s1 = "Hello World"; // by default, s1 is allocated 17
- // bytes of memory
- s1.Minimize(); // now s1 uses 12 bytes
-
- See Also: SetIncLength, SetMinLength, SetSize
-
- ---------------------------------------------------------------------------
-
- ptr
- ---
-
- Syntax: char* ptr(void);
-
- Returns a non-const char* to the contents of the String. This is considered
- extremely dangerous because it bypasses the protection offered by the
- String class. However, there are some cases where a non-const char* must be
- used. A safer mechanism for passing a non-const pointer is to use the
- Copy() function to create a new char*.
-
- Example:
-
- #include "str.h"
-
- s1 = "lowercase";
-
- strupr(s1()); // won't work - strupr() expects char*
- strupr(s1.ptr()); // this works
-
- See Also: Copy, operator char*, operator ()
-
- ---------------------------------------------------------------------------
-
- Replace
- -------
-
- Syntax: String& Replace(unsigned pos, unsigned len, String& to);
- int Replace(String& from, String& to, unsigned count = 10000);
- int Replace(Regexp& from, String& to, unsigned count = 10000);
-
- The first case replaces the substring beginning at position 'pos' and
- length 'len' with String 'to'. The other cases replace substring 'from'
- with String 'to' up to 'count' times and returns the number of substitu-
- tions. 'from' can be a String or
- a regular expression.
-
- Example:
-
- #include "str.h"
-
- int i;
- String s1 = "d:\\prog\\str";
-
- i = s1.Replace("\\", "/"); // i = 2
- // s1 = "d:/prog/str"
-
- See Also: gsub, sub, Sub
-
- ---------------------------------------------------------------------------
-
- Right
- -----
-
- Syntax: String& Right(int len);
-
- Reduces the String to the rightmost 'len' characters.
-
- Example:
-
- #include "str.h"
-
- String s1 = s2 = s3 = "This is a test";
-
- s1.Left(4); // s1 = "This"
- s2.Mid(5, 4); // s2 = "is a"
- s3.Right(4); // s3 = "test"
-
- See Also: left, Left, mid, Mid, right, substr, SubStr
-
- ---------------------------------------------------------------------------
-
- SetFloatFormat
- --------------
-
- Syntax: void SetFloatFormat(char* format);
-
- Sets the floating point format specifier fpFormat which determines how a
- floating point number will be converted to a String. The default specifier
- is "%10.4f". Note that the specifier is a static member of the String class
- and therefore it will affect all Strings. To give the SetFloatFormat func-
- tion the "feel" of being global, use the global String name Str as the ob-
- ject name. Consult the standard C function printf() for information concer-
- ning floating point format specifiers.
-
- Example:
-
- #include "str.h"
-
- String s1 = 1.23; // s1 = " 1.2300"
- Str.SetFloatFormat("%1.2f"); // set fpFormat to "%1.2f"
- s1 = 1.23; // s1 = "1.23"
-
- ---------------------------------------------------------------------------
-
- SetIncLength
- ------------
-
- Syntax: void SetIncLength(unsigned len);
-
- Sets the buffer increment size to 'len'. Strings are allocated memory based
- on strMinLength and strIncLength, which are the minimum and incremental
- buffer lengths. A newly created String will have a minimum buffer size of
- strMinLength+1, and Strings that are assigned or appended to will grow in-
- crementally by strIncLength. The default values are strMinLength = 16 and
- strIncLength = 8. Note that both variables are static members of the String
- class and therefore they will affect all Strings. To give the SetIncLength
- function the "feel" of being global, use the global String name Str as the
- object name.
-
- Example:
-
- #include "str.h"
-
- String s1 = "Hello World"; // s1 is initially allocated 17
- // bytes of memory
- s1 += ",how are you"; // buffer grows to 17+8 bytes
- Str.SetIncLength(16); // now all Strings will grow
- // incrementally by 16 bytes
-
- See Also: Minimize, SetMinLength, SetSize
-
- ---------------------------------------------------------------------------
-
- SetMinLength
- ------------
-
- Syntax: void SetMinLength(unsigned len);
-
- Sets the minimum buffer size to 'len'. Strings are allocated memory based
- on strMinLength and strIncLength, which are the minimum and incremental
- buffer lengths. A newly created String will have a minimum buffer size of
- strMinLength+1, and Strings that are assigned or appended to will grow in-
- crementally by strIncLength. The default values are strMinLength = 16 and
- strIncLength = 8. Note that both variables are static members of the String
- class and therefore they will affect all Strings. To give the SetMinLength
- function the "feel" of being global, use the global String name Str as the
- object name.
-
- Example:
-
- #include "str.h"
-
- String s1 = "Hi"; // s1 is initially allocated 17
- // bytes of memory
- Str.SetMinLength(8); // now all Strings will begin with
- // a minimum of 9 bytes
-
- See Also: Minimize, SetIncLength, SetSize
-
- ---------------------------------------------------------------------------
-
- SetSize
- -------
-
- Syntax: unsigned SetSize(unsigned len);
-
- Sets the String's buffer size to 'len'+1. If 'len' is less than the length
- of the String, then the buffer is simply minimized.
-
- Example:
-
- #include "str.h"
-
- String s1 = "Hi"; // s1 is initially allocated 17
- // bytes of memory
- s1.SetSize(8); // now s1 uses 9 bytes of memory
-
- See Also: Minimize, SetMinLength, SetIncLength
-
- ---------------------------------------------------------------------------
-
- Split
- -----
-
- Syntax: int Split(String*& a, String& fs);
- int Split(String*& a, Regexp& fs);
-
- Splits the String into String array 'a' on field separator 'fs'. Array 'a'
- is normally declared as an uninitialized pointer in the calling function
- and a reference to the pointer is passed to Split(). Split() will then al-
- locate memory for the correct array size and return the number of fields.
- 'fs' can be a String or a regular expression. String *this remains unmodi-
- fied.
-
- Example:
-
- #include "str.h"
-
- int i;
- String *array;
- String s1 = "d:\\prog\\str";
-
- i = s1.Split(array, "\\"); // i = 3
- // array[0] = "d:"
- // array[1] = "prog"
- // array[2] = "str"
-
- See Also: split
-
- ---------------------------------------------------------------------------
-
- Sub
- ---
-
- Syntax: int Sub(String& from, String& to, int count = 10000);
- int Sub(Regexp& from, String& to, int count = 10000);
-
- Substitutes String 'to' for each substring that is matched by 'from', up to
- 'count' times and returns the number of substitutions. 'from' can be a
- String or a regular expression.
-
- Example:
-
- #include "str.h"
-
- int i;
- String s1 = "d:\\prog\\str";
-
- i = s1.Sub("\\", "/"); // i = 2
- // s1 = "d:/prog/str"
-
- See Also: gsub, Replace, sub
-
- ---------------------------------------------------------------------------
-
- SubStr
- ------
-
- Syntax: String substr(unsigned pos, unsigned len = 10000);
-
- Creates a new String that is the substring of String *this beginning at po-
- sition 'pos' with length 'len'. String *this remains unmodified.
-
- Example:
-
- #include "str.h"
-
- String s1 = "Don't just stand there...";
- String s1a;
-
- s1a = s1.SubStr(11, 5); // s1a = "stand"
-
- See Also: left, Left, mid, Mid, right, Right, substr
-
- ---------------------------------------------------------------------------
-
- toLower
- -------
-
- Syntax: String& toLower(void);
-
- Converts the String to lower case, and also returns the converted String.
-
- Example:
-
- #include "str.h"
-
- String s1 = "LOWERCASE";
-
- s1.toLower(); // s1 is now "lowercase"
-
- See Also: toLower, toupper, toUpper
-
- ---------------------------------------------------------------------------
-
- toUpper
- -------
-
- Syntax: String& toUpper(void);
-
- Converts the String to upper case, and also returns the converted String.
-
- Example:
-
- #include "str.h"
-
- String s1 = "uppercase";
-
- s1.toUpper(); // s1 is now "UPPERCASE"
-
- See Also: tolower, toLower, toupper
-
- ---------------------------------------------------------------------------
-
- Trim
- ----
-
- Syntax: String& Trim(int mode = CENTER, char ch = WHITESPACE);
-
- Trims leading or trailing characters from a String. The trimmed character
- defaults to WHITESPACE (spaces & tabs) and can be user-defined.
-
- Example:
-
- #include "str.h"
-
- String s1 = s2 = s3 = " Spaces ";
-
- s1.Trim(LEFT); // s1 = "Spaces "
- s2.Trim(RIGHT); // s2 = " Spaces"
- s3.Trim(); // s3 = "Spaces"
-
- See Also: trim, Delete
-
- ---------------------------------------------------------------------------
-
- Value
- -----
-
- Syntax: int& Value(int& n);
- long& Value(long& n);
- float& Value(float& n);
- double& Value(double& n);
-
- Returns the value of a numeric String.
-
- Example:
-
- #include "str.h"
-
- int n1;
- String s1 = "12345";
-
- s1.Value(n1); // n1 is now 12345
-
- ---------------------------------------------------------------------------
- ---------------------------------------------------------------------------
-
- Awk-style Functions:
-
- Note: AWK begins array indexing at 1, whereas C/C++ begins array indexing
- at 0. Therefore, most of the implemented AWK functions return values
- that correspond to C-style indexing. An AWK function that might nor-
- mally return a 0 as a failure indicator will return a -1 here.
-
- ---------------------------------------------------------------------------
-
- gsub
- ----
-
- Syntax: int gsub(String& from, String& to, String& s, int count = 10000);
- int gsub(Regexp& from, String& to, String& s, int count = 10000);
-
- Substitutes String 'to' for each substring in String s that is matched by
- 'from', up to 'count' times. Returns the number of substitutions. 'from'
- can be a String or a regular expression.
-
- Example:
-
- #include "str.h"
-
- int i;
- String s1 = "d:\\prog\\str";
-
- i = gsub("\\", "/", s1); // i = 2
- // s1 = "d:/prog/str"
-
- See Also: Replace, sub, Sub
-
- ---------------------------------------------------------------------------
-
- index
- -----
-
- Syntax: int index(String& s, String& t);
- int index(String& s, Regexp& t);
-
- Returns the position of 't' in String s if it exists, or -1 if it does not.
- 't' can be a String or a regular expression.
-
- Example:
-
- #include "str.h"
-
- int i;
- String s1 = "d:\\prog\\str";
-
- i = index(s1, ":"); // i = 1
-
- See Also: FindFirst, FindNext, FindLast, FindPrev, Index
-
- ---------------------------------------------------------------------------
-
- length
- ------
-
- Syntax: int length(String& s);
-
- Returns the length of String s.
-
- Example:
-
- #include "str.h"
-
- int i;
- String s1 = "Hello World";
-
- i = length(s1); // i = 11
-
- See Also: Len, Length
-
- ---------------------------------------------------------------------------
-
- match
- -----
-
- Syntax: int match(String& s, Regexp re);
-
- Returns the position of the leftmost longest substring of s matched by the
- regular expression re if it exists, or -1 if it does not. Also sets the
- global variables RSTART and RLENGTH. RSTART is the starting position of the
- matching substring and RLENGTH is the substring length.
-
- Example:
-
- #include "str.h"
- #include "regexp.h"
-
- int i;
- String s1 = "banana";
- Regexp r1 = "a[a-z]*a"
-
- i = match(s1, r1); // matched substring is "anana",
- // so i=1, RSTART=1, RLENGTH=5
-
- See Also: index, Index, FindFirst, FindNext, FindLast, FindPrev
-
- ---------------------------------------------------------------------------
-
- split
- -----
-
- Syntax: int split(String& s, String*& a, String& fs);
- int split(String& s, String*& a, Regexp& fs);
-
- Splits String 's' into String array 'a' on field separator 'fs'. Array 'a'
- is normally declared as an uninitialized pointer in the calling function
- and a reference to the pointer is passed to split(). split() will then al-
- locate memory for the correct array size and return the number of fields.
- 'fs' can be a String or a regular expression. String s remains unmodified.
-
- Example:
-
- #include "str.h"
-
- int i;
- String *array;
- String s1 = "d:\\prog\\str";
-
- i = split(s1, array, "\\"); // i = 3
- // array[0] = "d:"
- // array[1] = "prog"
- // array[2] = "str"
-
- See Also: Split
-
- ---------------------------------------------------------------------------
-
- sub
- ---
-
- Syntax: int sub(String& from, String& to, String& s);
- int sub(Regexp& from, String& to, String& s);
-
- Substitutes String 'to' for the leftmost substring of 's' that is matched
- by 'from'. Returns the number of substitutions (0 or 1). 'from' can be a
- String or a regular expression.
-
- Example:
-
- #include "str.h"
-
- int i;
- String s1 = "d:\\prog\\str";
-
- i = sub("\\", "/", s1); // i = 1
- // s1 = "d:/prog\str"
-
- See Also: gsub, Replace, Sub
-
- ---------------------------------------------------------------------------
-
- substr
- ------
-
- Syntax: String substr(String& s, unsigned pos, unsigned len = 10000);
-
- Creates a new String that is the substring of String s beginning at posi-
- tion 'pos' with length 'len'. String s remains unmodified.
-
- Example:
-
- #include "str.h"
-
- String s1 = "Don't just stand there...";
- String s1a;
-
- s1a = substr(s1, 11, 5); // s1a = "stand"
-
- See Also: left, Left, mid, Mid, right, Right, SubStr
-
- ---------------------------------------------------------------------------
- ---------------------------------------------------------------------------
-
- C-Style Functions:
-
- ---------------------------------------------------------------------------
-
- left
- ----
-
- Syntax: String left(String& s, int len);
-
- Creates a new String that is the leftmost substring of String s with length
- 'len'. String s remains unmodified.
-
- Example:
-
- #include "str.h"
-
- String s1 = "This is a test";
- String s1a, s1b, s1c;
-
- s1a = left(s1, 4); // s1a = "This"
- s1b = mid(s1, 5, 4); // s1b = "is a"
- s1c = right(s1, 4); // s1c = "test"
-
- See Also: Left, mid, Mid, right, Right, substr, SubStr
-
- ---------------------------------------------------------------------------
-
- justify
- -------
-
- Syntax: String justify(String& s, int type, int len, int mode = CLIP|TRIM);
-
- Creates a new String from s and justifies it by padding it with spaces un-
- til it is 'len' long. The justification 'type' can be LEFT, CENTER, or
- RIGHT. If String s had any leading or trailing whitespaces (spaces or tabs)
- then they are first removed if 'mode'|=TRIM. If the new String is longer
- than 'len' (after the optional removal of white spaces) then it is clipped
- to len if 'mode'|=CLIP, otherwise the trimmed String is returned. String s
- remains unmodified.
-
- Example:
-
- #include "str.h"
-
- String s1 = "Hello World";
- String s1a, s1b, s1c;
-
- s1a = justify(s1, LEFT, 20); // s1a = "Hello World "
- s1b = justify(s1, CENTER, 20); // s1b = " Hello World "
- s1c = justify(s1, RIGHT, 20); // s1c = " Hello World"
-
- See Also: Justify, trim, Trim
-
- ---------------------------------------------------------------------------
-
- mid
- ---
-
- Syntax: String mid(String& s, int pos, int len);
-
- Creates a new String that is the substring of String s beginning at posi-
- tion 'pos' with length 'len'. String s remains unmodified.
-
- Example:
-
- #include "str.h"
-
- String s1 = "This is a test";
- String s1a, s1b, s1c;
-
- s1a = left(s1, 4); // s1a = "This"
- s1b = mid(s1, 5, 4); // s1b = "is a"
- s1c = right(s1, 4); // s1c = "test"
-
- See Also: left, Left, Mid, right, Right, substr, SubStr
-
- ---------------------------------------------------------------------------
-
- right
- -----
-
- Syntax: String right(String& s, int len);
-
- Creates a new String that is the rightmost substring of String s with
- length 'len'. String s remains unmodified.
-
- Example:
-
- #include "str.h"
-
- String s1 = "This is a test";
- String s1a, s1b, s1c;
-
- s1a = left(s1, 4); // s1a = "This"
- s1b = mid(s1, 5, 4); // s1b = "is a"
- s1c = right(s1, 4); // s1c = "test"
-
- See Also: left, Left, mid, Mid, Right, substr, SubStr
-
- ---------------------------------------------------------------------------
-
- tolower
- -------
-
- Syntax: String tolower(String& s);
-
- Creates a lowercase version of String s. String s remains unmodified.
-
- Example:
-
- #include "str.h"
-
- String s1 = "LOWERCASE";
- String s1a;
-
- s1a = tolower(s1); // s1a = "lowercase"
-
- See Also: toLower, toupper, toUpper
-
- ---------------------------------------------------------------------------
-
- toupper
- -------
-
- Syntax: String toupper(String& s);
-
- Creates an uppercase version of String s. String s remains unmodified.
-
- Example:
-
- #include "str.h"
-
- String s1 = "uppercase";
- String s1a;
-
- s1a = toupper(s1); // s1a = "UPPERCASE"
-
- See Also: tolower, toLower, toUpper
-
- ---------------------------------------------------------------------------
-
- trim
- ----
-
- Syntax: String trim(String& s, int mode=CENTER, char ch = WHITESPACE);
-
- Creates a new String from s with leading and/or trailing characters trim-
- med. The trimmed character 'ch' defaults to WHITESPACE (spaces & tabs) and
- can be user-defined. The trim 'mode' defaults to CENTER and can also be
- RIGHT or LEFT. String s remains unmodified.
-
- Example:
-
- #include "str.h"
-
- String s1 = " Spaces ";
- String s1a, s1b, s1c;
-
- s1a = trim(s1, LEFT); // s1a = "Spaces "
- s1b = trim(s1, RIGHT); // s1b = " Spaces"
- s1c = trim(s1); // s1c = "Spaces"
-
- See Also: Delete, justify, Justify, Trim
-
- ---------------------------------------------------------------------------
-