home *** CD-ROM | disk | FTP | other *** search
/ Shareware Supreme Volume 6 #1 / swsii.zip / swsii / 099 / STRPP300.ZIP / STR.DOC < prev    next >
Text File  |  1993-04-11  |  40KB  |  1,343 lines
  1.  
  2.                            String++ Version 3.0
  3.  
  4.                       Copyright 1993 by Carl Moreland
  5.                                  04/10/93
  6.  
  7. ---------------------------------------------------------------------------
  8.  
  9.     String++ is a String class written for Borland/Turbo C++. It contains a
  10. variety  of  String processing functions such as Insert,  Delete,  Replace,
  11. Find,  Justify, and Trim, as well as  overloaded operators for  assignment,
  12. concatenation, and comparison.  For AWK programmers, there are standard AWK
  13. functions  such  as sub, substr, index, and split, as well as  support  for
  14. regular expressions in many functions.
  15.  
  16.     Some  of  the ways that Strings may be declared or initialized  are  as
  17. follows:
  18.  
  19.     String    str;            // NULL string
  20.         str('H');        // single character
  21.         str("Hello World");    // char*
  22.         str(c, 5);        // make 5 copies of character c
  23.         str(p, 5);        // char* p, begin at p[5]
  24.         str(p, 5, 3);        // begin at p[5], use 3 chars
  25.         str(s);            // another String
  26.         str(s, 5);        // String s, begin at s[5]
  27.         str(s, 5, 3);        // begin at s[5], use 3 chars
  28.         str(45);        // convert an int to a String
  29.         str(1.23);        // convert a float to a String
  30.         str(1.23, "%6.2f");    // convert a float to a String
  31.                     //   using a format specifier
  32.         str = 'H';        // single character
  33.         str = "Hello World";    // char*
  34.                 str = 1.6e-19;        // any number
  35.         str = p;        // char* p
  36.         str = s;        // another String
  37.         str = x;        // any number
  38.  
  39. The following operators are available:
  40.  
  41.     =    assignment - see above
  42.     ()    str() returns the char* of the string
  43.     char    cast operator, returns the first char of the string
  44.     char*    cast operator, returns the char* of the string
  45.     *    *str returns str[0]
  46.     []    str[i] returns the ith character of str; [] can also assign
  47.         the ith character of a string.
  48.     +  +=    concatenates
  49.     <<    concatenates
  50.     *  *=    multiple duplicates
  51.     == !=    comparisons
  52.     <  >    comparisons
  53.     <= >=    comparisons
  54.  
  55. Some binary operators are declared as friend functions. This allows them to
  56. accept char, char*, and String as valid arguments on either side of the op-
  57. erator. Therefore, each of these statements is valid:
  58.  
  59.     s1 = "Hello" + s2;
  60.     s1 = s2 + "World";
  61.     s1 = "Hello" + s2 + "World";
  62.     if(s1 == "Hello World") ...
  63.     if("Hello World" == s1) ...
  64.  
  65. However,
  66.  
  67.     s1 = "Hello " + "World";
  68.  
  69. is not legal because a String object MUST appear on one side of the  opera-
  70. tor.  A more flexible way to assign the contents of a string is to use  the
  71. << operator:
  72.  
  73.     char c;
  74.     String s1, s2;
  75.     ...
  76.     int n = index(s1, c);
  77.  
  78.     s2 << "The location of " << c << " in " << s1 << " is " << n;
  79.  
  80. The << operator  is  overloaded to accept char, char*, String,  int,  long,
  81. float, and double.
  82.  
  83. The  following functions are supported.  Refer to the reference section  of
  84. this document for function syntax and examples.
  85.  
  86.     Copy            Copy a string to a char*
  87.     Delete            Delete a substring
  88.     FindFirst        Find the first occurrence of a substring
  89.     FindLast        Find the last occurrence of a substring
  90.     FindNext        Find the next occurrence of a substring
  91.     FindPrev        Find the previous occurrence of a substring
  92.     gsub            Global substring substitution
  93.     Index, index        Position of a substring
  94.     Insert            Insert a substring
  95.     Justify            Justify the String
  96.     Left, left        Leftmost substring
  97.     Len            Length of the String
  98.     Length, length        Length of the String
  99.     match            Match a regular expression
  100.     Mid, mid        Middle substring
  101.     Minimize        Minimize the buffer space
  102.     ptr            Return the char* of a String
  103.     Replace            Replace a substring
  104.     Right            Rightmost substring
  105.     SetFloatFormat        Set the floating point format specifier
  106.     SetIncLength        Set the buffer increment length
  107.     SetMinLength        Set the buffer minimum length
  108.     SetSize            Set the buffer size
  109.     Split, split        Split a String on a field separator
  110.     Sub, sub        Leftmost substitution
  111.     SubStr, substr        Random substring
  112.     toLower, tolower    Case conversion
  113.     toUpper, toupper    Case conversion
  114.     Trim, trim        Remove outer whitespace
  115.     Value            Numeric value of a numeric String
  116.  
  117. String Buffers
  118. --------------
  119.  
  120.     The contents of a String is stored in a character array.  Although  the
  121. size of the array could be just large enough to hold the String,  the array
  122. would have to be reallocated if a single character is added to the  String.
  123. To improve speed,  this class utilizes a minimum string buffer size and  an
  124. incremental size.
  125.  
  126.     The minimum buffer size is the minimum amount of memory that is  initi-
  127. ally allocated for the character array.  The default size is 16 characters.
  128. Each  newly created String will automatically have a buffer size  equal  to
  129. this  minimum size, plus one extra byte for the NULL terminator. Therfore
  130.  
  131.     String s1;
  132.     String s2 = "Hello";
  133.  
  134. will  both have 17 bytes of memory allocated even though not all  17  bytes
  135. are used.  If the Strings are appended to then the memory does not have  to
  136. be reallocated provided that the new length does not exceed 17 bytes:
  137.  
  138.     s1 = s2;
  139.     s2 += ", World";
  140.  
  141. The  minimum buffer length is stored in the private  variable  strMinLength
  142. You can set this to a new value with the SetMinLength() function:
  143.  
  144.     Str.SetMinLength(24);
  145.  
  146. This  example sets the minimum buffer length to 24 bytes (plus 1)  for  all
  147. subsequently  created  Strings.  Note that the global String  instance  Str
  148. is  used in calling this function even though any String instance could  be
  149. used. This creates the global appearance of SetMinLength().
  150.  
  151.     A second variable is used in determining how a String buffer will grow.
  152. The  private  variable strIncLength specifies the minimum number  of  bytes
  153. that  is  added to the buffer when the String exceeds  the  current  buffer
  154. size.  The  default value is 8 bytes.  Whenever a String  needs  additional
  155. space,  it receives it in multiples of 8 bytes.  In the example  above,  s2
  156. contains "Hello, World". If we add some more:
  157.  
  158.     s2 += ", How are you?;
  159.  
  160. then  s2 will exceed 17 bytes and additional memory must be  allocated.  In
  161. this case,  s2 will need a total of 26 bytes (plus 1 for the NULL  termina-
  162. tor).  The original 17 bytes plus the incremental 8 bytes is not enough, so
  163. another incremental 8 bytes is added for a total of 33 bytes.  This  proce-
  164. dure also works for newly created Strings that exceed strMinLength:
  165.  
  166.     String s3 = "This is a very long string.";
  167.  
  168. s3  requires 28 bytes, so again it will receive 33 bytes (17+8+8).  strInc-
  169. Length can be set using the SetIncLength() function:
  170.  
  171.     Str.SetIncLength(16);
  172.  
  173.     The  reason for using minimum and incremental lengths is to reduce  the
  174. number  of memory allocations, which are time consuming.  The  drawback  is
  175. that each String will waste a small amount of memory;  for a moderate  size
  176. String  this  will  typically be strIncLength/2.  Making  strMinLength  and
  177. strIncLength larger will waste more memory but require fewer memory alloca-
  178. tions.  Setting them equal to 1 will waste no memory but each appendage op-
  179. eration will need to reallocate memory.  This is how older versions of this
  180. class worked (2.12 and prior).
  181.  
  182. Temporary Strings
  183. -----------------
  184.  
  185.     When using Strings,  you should be aware that temporary String  objects
  186. are sometimes created and destroyed, and that they can degrade program per-
  187. formance. For example,
  188.  
  189.     s1 = s2 + "World";
  190.  
  191. creates a temporary String that is the combination of s2 and "World". It is
  192. this temporary String that is assigned to s1 via the = operator. The reason
  193. for  this is because the + operator is defined to accept two const  objects
  194. (in this case a String and a char*) and returns a newly created String. The
  195. = operator is defined to accept a String&, which in this case is the String
  196. that results from the + operation.  The compiler knows that this String  is
  197. temporary  and  will automatically delete it when the assignment to  s1  is
  198. done.
  199.  
  200.     Functions that accept String objects as arguments can also accept  char
  201. and char* objects, as well as other data types that are supported by String
  202. constructors. For example,  even though the index() function is defined  to
  203. accept two String arguments, this is legal:
  204.  
  205.     i = index(s1, "a");
  206.  
  207. The "a" argument  will be converted to a String object by the compiler  be-
  208. cause there is a String constructor that is defined for char*. Like the op-
  209. erator example above, this String object is temporary and is destroyed when
  210. the function returns.
  211.  
  212.     Based  on the above example,  is it necessary for the String  class  to
  213. overload  the various operators to accept data types that are already  sup-
  214. ported by constructors? The answer is no, but the overloaded operators will
  215. reduce  the number of temporary Strings that are created and therefore  im-
  216. prove performance.  In the example above, if the + operator were  only  de-
  217. fined to accept two Strings, then the "World" argument would cause the cre-
  218. ation  of a second temporary String.  Most of the String functions are  not
  219. overloaded  because they typically do not see the kind of repeated use  the
  220. operators get.  If there is a String function that will get heavy  repeated
  221. use  with non-String arguments (such as the index example above)  then  you
  222. might see some speed improvement by overloading the function.
  223.  
  224. Regular Expressions
  225. -------------------
  226.  
  227.     Regular expressions are text patterns that are used for  string  match-
  228. ing. Normally, strings are compared to other strings (or substrings) and we
  229. look for an absolute match. However, there are times when we want to test a
  230. string  in  a more general way.  For example, suppose we want to see  if  a 
  231. string contains any digits.  Using absolute string matching,  we would have
  232. to run 10 comparisons,  one for each digit.  Using regular expressions,  we
  233. can create a character class and make one comparison:
  234.  
  235.     String s1;
  236.     Regexp re = "[0-9]";
  237.  
  238.     if(s1 == re)
  239.       do_something();
  240.  
  241. In the above example, the regular expression contains "[0-9]". The brackets
  242. enclose the character class 0-9 which means match any digit.  Therefore, if 
  243. s1 contains a digit then the comparison with re will be true.
  244.  
  245.     Before a regular expression can be used it must first be declared.  For
  246. example, this will not work:
  247.  
  248.     if(s1 == "[0-9]")
  249.       do_something();
  250.  
  251. because the == operator will compare s1 to the literal string "[0-9]". How-
  252. ever, this will work:
  253.  
  254.     if(s1 == Regexp("[0-9]"))
  255.       do_something();
  256.  
  257.     Several String functions include support for regular expressions.  Like
  258. the other AWK functions included with the String class,  the match function 
  259. returns  the position of the matching substring using C's zero-based  array
  260. offset, and -1 if the match failed. Because the ~ operator is unary in C++,
  261. it could not be overloaded to provide the same functionality as in AWK. In-
  262. stead,  the == operator and the != operator have been overloaded to use re-
  263. gular expressions.
  264.  
  265.     For more information concerning the use of regular expressions, consult
  266. a text on Unix or the AWK language (such as _The AWK Programming Language_,
  267. by Aho, Kernighan, and Weinberger).
  268.  
  269. Using the String Class
  270. ----------------------
  271.  
  272.     To  use the String class in your program,  simply add str.lib  to  your
  273. project  or make file and #include str.h in any module that uses a  String.
  274. To use regular expressions you will also need to #include regexp.h in  mod-
  275. ules  that  use them.  str.lib contains all the functions  in  str.cpp  and
  276. regexp.cpp (as well as parsestr.cpp and filestr.cpp), but the functions are
  277. separated into different object modules for greater efficiency.  Note  that
  278. str.lib is compiled for the large memory model.
  279.  
  280.     If you want to replace the String class in the Borland Container  Class
  281. Library, follow the instructions in strng.doc.  Don't forget to add  "BCCL"
  282. to the Defines list in the Options-Compiler-Code Generation dialog box.
  283.  
  284. ---------------------------------------------------------------------------
  285. ---------------------------------------------------------------------------
  286.  
  287. Class Operators:
  288.  
  289. ---------------------------------------------------------------------------
  290.  
  291. operator =
  292. ----------
  293.  
  294. Syntax:    String& operator=(char c);
  295.     String& operator=(char* p);
  296.     String& operator=(String& s);
  297.     String& operator=(int n);
  298.     String& operator=(long n);
  299.     String& operator=(float n);
  300.     String& operator=(double n);
  301.  
  302. Assigns contents to the String. In the case of float and double, the String
  303. format is determined by the format specifier fpFormat,  which is a  private
  304. member of the String class.  It may be set by either a previous constructor
  305. call or by an explicit call to SetFloatFormat().
  306.  
  307. ---------------------------------------------------------------------------
  308.  
  309. operator +
  310. ----------
  311.  
  312. Syntax:    String operator+(String& s1, char* s2);
  313.     String operator+(char* s1, String& s2);
  314.     String operator+(String& s1, String& s2);
  315.  
  316. Creates a new String by concatenating s2 to s1.
  317.  
  318. ---------------------------------------------------------------------------
  319.  
  320. operator +=
  321. -----------
  322.  
  323. Syntax:    String& operator+=(char c);
  324.     String& operator+=(char* p);
  325.     String& operator+=(String& s);
  326.  
  327. Concatenates the argument to the String.
  328.  
  329. ---------------------------------------------------------------------------
  330.  
  331. operator <<
  332. -----------
  333.  
  334. Syntax:    String& operator<<(char c);
  335.     String& operator<<(char* p);
  336.     String& operator<<(String& s);
  337.     String& operator<<(int n);
  338.     String& operator<<(long n);
  339.     String& operator<<(float n);
  340.     String& operator<<(double n);
  341.  
  342. Concatenates the argument to the String.  In the case of float and  double,
  343. the String format is determined by the format specifier fpFormat, which  is
  344. a  private member of the String class.  It may be set by either a  previous
  345. constructor call or by an explicit call to SetFloatFormat().
  346.  
  347. ---------------------------------------------------------------------------
  348.  
  349. operator *
  350. ----------
  351.  
  352. Syntax:    String operator*(String& s, unsigned n);
  353.     String operator*(unsigned n, String& s);
  354.  
  355. Creates a new String with 'n' duplications of String 's'.
  356.  
  357. ---------------------------------------------------------------------------
  358.  
  359. operator *=
  360. -----------
  361.  
  362. Syntax:    String& operator*=(unsigned n);
  363.  
  364. Adds 'n'-1 duplications of the String to itself.
  365.  
  366. ---------------------------------------------------------------------------
  367.  
  368. operator ==
  369. operator !=
  370. operator <
  371. operator >
  372. operator <=
  373. operator >=
  374. -----------
  375.  
  376. Syntax:    int operator??(String& s1, String& s2);
  377.     int operator??(String& s1, char* s2);
  378.     int operator??(char* s1, String& s2);
  379.     int operator??(String& s1, char c);
  380.  
  381. Compares s1 to s2 and returns 1 if the operation is true,  0 otherwise.  In
  382. the special case of char c, the operator compares s1[0] to c.
  383.  
  384. ---------------------------------------------------------------------------
  385.  
  386. operator ()
  387. -----------
  388.  
  389. Syntax:    const char* operator()();
  390.     const char* operator()(unsigned pos);
  391.     String      operator()(unsigned pos, unsigned len);
  392.  
  393. The  first  case returns the contents of the String (strPtr)  via  a  const
  394. char*. The second method returns strPtr+pos. The third method creates a new
  395. String using the substring beginning at position 'pos' with length 'len' of
  396. String *this.  The  first two methods are considered safe  ways  to  access
  397. strPtr  because  the const modifier protects strPtr from  modification.  In
  398. using  these methods to pass a char* representation of a String to a  func-
  399. tion, be aware that many functions expect a char*, not const char*. In this
  400. case, the safest thing to do is use the Copy() function.
  401.  
  402. ---------------------------------------------------------------------------
  403.  
  404. operator char
  405. operator char*
  406. --------------
  407.  
  408. Syntax:    operator const char();
  409.     operator const char*();
  410.  
  411. These are cast operators that are automatically called when a String object
  412. is  passed where a char or char* is expected.  The const modifier  prevents
  413. the contents of the String object from being unintentionally modified.
  414.  
  415. ---------------------------------------------------------------------------
  416.  
  417. operator *
  418. ----------
  419.  
  420. Syntax:    const char operator *();
  421.  
  422. Returns the first character in the String.
  423.  
  424. ---------------------------------------------------------------------------
  425.  
  426. operator []
  427. -----------
  428.  
  429. Syntax:    char& operator [](unsigned i);
  430.  
  431. Returns the ith character in the String, or assigns the ith character.
  432.  
  433. ---------------------------------------------------------------------------
  434. ---------------------------------------------------------------------------
  435.  
  436. Class Functions:
  437.  
  438. ---------------------------------------------------------------------------
  439.  
  440. Copy
  441. ----
  442.  
  443. Syntax:    char* Copy(char *p);
  444.  
  445. Copies  the  String  contents to a non-const character pointer.  Copy  will
  446. allocate  the memory for the pointer - it is up to you to free (delete) it.
  447. Normally,  the contents of a String are extracted with the  () operator  or
  448. the  char* cast operator.  However, these return a const char* that must be
  449. cast to a non-const char* for some C-style functions (most Borland  library
  450. functions will accept const char*).  Although you could also use the  ptr()
  451. method to return a non-const char*, this is considered unsafe as it comple-
  452. tely strips the inherent protection that the String class offers.
  453.  
  454. Example:
  455.  
  456.     #include "str.h"
  457.  
  458.     char *ptr;
  459.     s1 = "lowercase";
  460.  
  461.     strupr(s1());            // won't work - strupr() expects
  462.                     //   a non-const char*
  463.     strupr((char*)s1());        // cast to char* - this works
  464.     s1.Copy(ptr);            // copy s1 to char *ptr
  465.     strupr(ptr);            // normal C-style
  466.  
  467. See Also: ptr, operator char*, operator ()
  468.  
  469. ---------------------------------------------------------------------------
  470.  
  471. Delete
  472. ------
  473.  
  474. Syntax:    String& Delete(unsigned pos, unsigned len = 1);
  475.  
  476. Deletes a substring beginning at position 'pos' with length 'len'. If 'len'
  477. = 0, then the substring from 'pos' to the end of the String is deleted.
  478.  
  479. Example:
  480.  
  481.     #include "str.h"
  482.  
  483.     String s1 = "This is a test";
  484.     s1.Delete(5, 3);        // s1 = "This a test"
  485.  
  486. See Also: gsub, Replace, sub, Sub, trim, Trim
  487.  
  488. ---------------------------------------------------------------------------
  489.  
  490. Find...
  491. -------
  492.  
  493. Syntax:    int FindFirst(String& s);
  494.     int FindNext(void);
  495.     int FindLast(String& s);
  496.     int FindPrev(void);
  497.  
  498. Finds the substring s in a String.  FindFirst() finds the first occurrence,
  499. and  FindNext()  finds subsequent occurrences.  FindLast() finds  the  last
  500. occurrence,  and FindPrev() finds preceding occurrences.  Note  that  Find-
  501. Next() and FindPrev() will continue to use the substring s from the initial
  502. call to FindFirst() or FindLast().
  503.  
  504. Example:
  505.  
  506.     #include "str.h"
  507.  
  508.     String s1 = "This is a test";
  509.  
  510.     i = s1.FindFirst(" ");
  511.     while(i != -1)
  512.     {
  513.       s1.Delete(i, 1);
  514.       i = s1.FindNext();
  515.     }                // s1 = "Thisisatest"
  516.  
  517. See Also: index, Index, match
  518.  
  519. ---------------------------------------------------------------------------
  520.  
  521. Index
  522. -----
  523.  
  524. Syntax: int Index(String& t);
  525.     int index(Regexp& t);
  526.  
  527. Returns  the position of 't' in the String if it exists,  or -1 if it  does
  528. not. 't' can be a String or a regular expression.
  529.  
  530. Example:
  531.  
  532.     #include "str.h"
  533.  
  534.     int i;
  535.     String s1 = "d:\\prog\\str";
  536.  
  537.     i = s1.Index(":");        // i = 1
  538.  
  539. See Also: FindFirst, FindNext, FindLast, FindPrev, index, match
  540.  
  541. ---------------------------------------------------------------------------
  542.  
  543. Insert
  544. ------
  545.  
  546. Syntax: String& Insert(unsigned pos, String& s);
  547.  
  548. Inserts substring 's' at position 'pos'.
  549.  
  550. Example:
  551.  
  552.     #include "str.h"
  553.  
  554.     String s1 = "This a test";
  555.  
  556.     s1.Insert(5, "is ");        // s1 = "This is a test"
  557.  
  558. See Also: Delete, gsub, justify, Justify, Replace, sub, Sub, trim, Trim
  559.  
  560. ---------------------------------------------------------------------------
  561.  
  562. Justify
  563. -------
  564.  
  565. Syntax: String& Justify(int type, int len, int mode = CLIP|TRIM);
  566.  
  567. Justifies the String by padding it with spaces until it is 'len' long.  The
  568. justification 'type' can be LEFT, CENTER, or RIGHT.  If the String has  any
  569. leading  or trailing whitespaces (spaces or tabs) then they are  first  re-
  570. moved  if 'mode'|=TRIM.  If the String is longer than 'len' (after the  op-
  571. tional removal of white spaces) then it is clipped to len if 'mode'|=CLIP.
  572.  
  573. Example:
  574.  
  575.     #include "str.h"
  576.  
  577.     String s1 = s2 = s3 = "Hello World";
  578.  
  579.     s1.Justify(LEFT, 20);        // s1 = "Hello World         "
  580.     s2.Justify(CENTER, 20);        // s2 = "    Hello World     "
  581.     s3.Justify(RIGHT, 20);        // s3 = "         Hello World"
  582.  
  583. See Also: Insert, justify, trim, Trim
  584.  
  585. ---------------------------------------------------------------------------
  586.  
  587. Left
  588. ----
  589.  
  590. Syntax: String& Left(int len);
  591.  
  592. Reduces the String to the leftmost 'len' characters.
  593.  
  594. Example:
  595.  
  596.     #include "str.h"
  597.  
  598.     String s1 = s2 = s3 = "This is a test";
  599.  
  600.     s1.Left(4);            // s1 = "This"
  601.     s2.Mid(5, 4);            // s2 = "is a"
  602.     s3.Right(4);            // s3 = "test"
  603.  
  604. See Also: left, mid, Mid, right, Right, substr, SubStr
  605.  
  606. ---------------------------------------------------------------------------
  607.  
  608. Len, Length
  609. -----------
  610.  
  611. Syntax: int Len(void)    const;
  612.     int Length(void) const;
  613.  
  614. Returns the length of the String:
  615.  
  616. Example:
  617.  
  618.     #include "str.h"
  619.  
  620.     int i;
  621.     String s1 = "Hello World";
  622.  
  623.     i = s1.Length();        // i = 11
  624.  
  625. See Also: length
  626.  
  627. ---------------------------------------------------------------------------
  628.  
  629. Mid
  630. ---
  631.  
  632. Syntax: String& Mid(int pos, int len);
  633.  
  634. Reduces the String to the substring beginning at position 'pos' with length
  635. 'len'.
  636.  
  637. Example:
  638.  
  639.     #include "str.h"
  640.  
  641.     String s1 = s2 = s3 = "This is a test";
  642.  
  643.     s1.Left(4);            // s1 = "This"
  644.     s2.Mid(5, 4);            // s2 = "is a"
  645.     s3.Right(4);            // s3 = "test"
  646.  
  647. See Also: left, Left, mid, right, Right, substr, SubStr
  648.  
  649. ---------------------------------------------------------------------------
  650.  
  651. Minimize
  652. --------
  653.  
  654. Syntax:    void Minimize(void);
  655.  
  656. Minimizes the allocated buffer space for the String.  Normally, Strings are
  657. allocated memory based on strMinLength and strIncLength,  which are the mi-
  658. nimum and incremental buffer lengths.  Therefore, a String could be alloca-
  659. ted more memory than it is using.
  660.  
  661. Example:
  662.  
  663.     #include "str.h"
  664.  
  665.     String s1 = "Hello World";    // by default, s1 is allocated 17
  666.                     //   bytes of memory
  667.     s1.Minimize();            // now s1 uses 12 bytes
  668.  
  669. See Also: SetIncLength, SetMinLength, SetSize
  670.  
  671. ---------------------------------------------------------------------------
  672.  
  673. ptr
  674. ---
  675.  
  676. Syntax:    char* ptr(void);
  677.  
  678. Returns a non-const char* to the contents of the String. This is considered
  679. extremely  dangerous  because  it bypasses the protection  offered  by  the 
  680. String class. However, there are some cases where a non-const char* must be
  681. used.  A  safer  mechanism for passing a non-const pointer is  to  use  the
  682. Copy() function to create a new char*.
  683.  
  684. Example:
  685.  
  686.     #include "str.h"
  687.  
  688.     s1 = "lowercase";
  689.  
  690.     strupr(s1());        // won't work - strupr() expects char*
  691.     strupr(s1.ptr());    // this works
  692.  
  693. See Also: Copy, operator char*, operator ()
  694.  
  695. ---------------------------------------------------------------------------
  696.  
  697. Replace
  698. -------
  699.  
  700. Syntax:    String& Replace(unsigned pos, unsigned len, String& to);
  701.     int     Replace(String& from, String& to, unsigned count = 10000);
  702.     int     Replace(Regexp& from, String& to, unsigned count = 10000);
  703.  
  704. The  first  case  replaces the substring beginning at  position  'pos'  and
  705. length  'len' with String 'to'.  The other cases replace  substring  'from'
  706. with  String 'to' up to 'count' times and returns the number  of  substitu-
  707. tions. 'from' can be a String or
  708.  a regular expression.
  709.  
  710. Example:
  711.  
  712.     #include "str.h"
  713.  
  714.     int i;
  715.     String s1 = "d:\\prog\\str";
  716.  
  717.     i = s1.Replace("\\", "/");    // i = 2
  718.                     // s1 = "d:/prog/str"
  719.  
  720. See Also: gsub, sub, Sub
  721.  
  722. ---------------------------------------------------------------------------
  723.  
  724. Right
  725. -----
  726.  
  727. Syntax: String& Right(int len);
  728.  
  729. Reduces the String to the rightmost 'len' characters.
  730.  
  731. Example:
  732.  
  733.     #include "str.h"
  734.  
  735.     String s1 = s2 = s3 = "This is a test";
  736.  
  737.     s1.Left(4);            // s1 = "This"
  738.     s2.Mid(5, 4);            // s2 = "is a"
  739.     s3.Right(4);            // s3 = "test"
  740.  
  741. See Also: left, Left, mid, Mid, right, substr, SubStr
  742.  
  743. ---------------------------------------------------------------------------
  744.  
  745. SetFloatFormat
  746. --------------
  747.  
  748. Syntax:    void SetFloatFormat(char* format);
  749.  
  750. Sets the floating point format specifier fpFormat which determines how a
  751. floating point number will be converted to a String. The default specifier
  752. is "%10.4f". Note that the specifier is a static member of the String class
  753. and therefore it will affect all Strings. To give the SetFloatFormat func-
  754. tion the "feel" of being global,  use the global String name Str as the ob-
  755. ject name. Consult the standard C function printf() for information concer-
  756. ning floating point format specifiers.
  757.  
  758. Example:
  759.  
  760.     #include "str.h"
  761.  
  762.     String s1 = 1.23;        // s1 = "    1.2300"
  763.     Str.SetFloatFormat("%1.2f");    // set fpFormat to "%1.2f"
  764.     s1 = 1.23;            // s1 = "1.23"
  765.  
  766. ---------------------------------------------------------------------------
  767.  
  768. SetIncLength
  769. ------------
  770.  
  771. Syntax:    void SetIncLength(unsigned len);
  772.  
  773. Sets the buffer increment size to 'len'. Strings are allocated memory based 
  774. on  strMinLength and strIncLength,  which are the minimum  and  incremental 
  775. buffer lengths.  A newly created String will have a minimum buffer size  of
  776. strMinLength+1,  and Strings that are assigned or appended to will grow in-
  777. crementally by strIncLength.  The default values are strMinLength = 16  and
  778. strIncLength = 8. Note that both variables are static members of the String
  779. class and therefore they will affect all Strings.  To give the SetIncLength
  780. function the "feel" of being global,  use the global String name Str as the
  781. object name.
  782.  
  783. Example:
  784.  
  785.     #include "str.h"
  786.  
  787.     String s1 = "Hello World";    // s1 is initially allocated 17
  788.                     //   bytes of memory
  789.     s1 += ",how are you";        // buffer grows to 17+8 bytes
  790.     Str.SetIncLength(16);        // now all Strings will grow
  791.                     //   incrementally by 16 bytes
  792.  
  793. See Also: Minimize, SetMinLength, SetSize
  794.  
  795. ---------------------------------------------------------------------------
  796.  
  797. SetMinLength
  798. ------------
  799.  
  800. Syntax:    void SetMinLength(unsigned len);
  801.  
  802. Sets the minimum buffer size to 'len'.  Strings are allocated memory  based 
  803. on  strMinLength and strIncLength,  which are the minimum  and  incremental 
  804. buffer lengths.  A newly created String will have a minimum buffer size  of
  805. strMinLength+1,  and Strings that are assigned or appended to will grow in-
  806. crementally by strIncLength.  The default values are strMinLength = 16  and 
  807. strIncLength = 8. Note that both variables are static members of the String
  808. class and therefore they will affect all Strings.  To give the SetMinLength
  809. function the "feel" of being global,  use the global String name Str as the
  810. object name.
  811.  
  812. Example:
  813.  
  814.     #include "str.h"
  815.  
  816.     String s1 = "Hi";        // s1 is initially allocated 17
  817.                     //   bytes of memory
  818.     Str.SetMinLength(8);        // now all Strings will begin with
  819.                     //   a minimum of 9 bytes
  820.  
  821. See Also: Minimize, SetIncLength, SetSize
  822.  
  823. ---------------------------------------------------------------------------
  824.  
  825. SetSize
  826. -------
  827.  
  828. Syntax:    unsigned SetSize(unsigned len);
  829.  
  830. Sets the String's buffer size to 'len'+1. If 'len' is less than the length
  831. of the String, then the buffer is simply minimized.
  832.  
  833. Example:
  834.  
  835.     #include "str.h"
  836.  
  837.     String s1 = "Hi";        // s1 is initially allocated 17
  838.                     //   bytes of memory
  839.     s1.SetSize(8);            // now s1 uses 9 bytes of memory
  840.  
  841. See Also: Minimize, SetMinLength, SetIncLength
  842.  
  843. ---------------------------------------------------------------------------
  844.  
  845. Split
  846. -----
  847.  
  848. Syntax: int Split(String*& a, String& fs);
  849.     int Split(String*& a, Regexp& fs);
  850.  
  851. Splits the String into String array 'a' on field separator 'fs'.  Array 'a'
  852. is  normally declared as an uninitialized pointer in the  calling  function
  853. and a reference to the pointer is passed to Split().  Split() will then al-
  854. locate  memory for the correct array size and return the number of  fields.
  855. 'fs' can be a String or a regular expression.  String *this remains unmodi-
  856. fied.
  857.  
  858. Example:
  859.  
  860.     #include "str.h"
  861.  
  862.     int i;
  863.     String *array;
  864.     String s1 = "d:\\prog\\str";
  865.  
  866.     i = s1.Split(array, "\\");    // i = 3
  867.                     // array[0] = "d:"
  868.                     // array[1] = "prog"
  869.                     // array[2] = "str"
  870.  
  871. See Also: split
  872.  
  873. ---------------------------------------------------------------------------
  874.  
  875. Sub
  876. ---
  877.  
  878. Syntax: int Sub(String& from, String& to, int count = 10000);
  879.     int Sub(Regexp& from, String& to, int count = 10000);
  880.  
  881. Substitutes String 'to' for each substring that is matched by 'from', up to
  882. 'count'  times  and returns the number of substitutions.  'from' can  be  a 
  883. String or a regular expression.
  884.  
  885. Example:
  886.  
  887.     #include "str.h"
  888.  
  889.     int i;
  890.     String s1 = "d:\\prog\\str";
  891.  
  892.     i = s1.Sub("\\", "/");        // i = 2
  893.                     // s1 = "d:/prog/str"
  894.  
  895. See Also: gsub, Replace, sub
  896.  
  897. ---------------------------------------------------------------------------
  898.  
  899. SubStr
  900. ------
  901.  
  902. Syntax: String substr(unsigned pos, unsigned len = 10000);
  903.  
  904. Creates a new String that is the substring of String *this beginning at po-
  905. sition 'pos' with length 'len'. String *this remains unmodified.
  906.  
  907. Example:
  908.  
  909.     #include "str.h"
  910.  
  911.     String s1 = "Don't just stand there...";
  912.     String s1a;
  913.  
  914.     s1a = s1.SubStr(11, 5);        // s1a = "stand"
  915.  
  916. See Also: left, Left, mid, Mid, right, Right, substr
  917.  
  918. ---------------------------------------------------------------------------
  919.  
  920. toLower
  921. -------
  922.  
  923. Syntax: String& toLower(void);
  924.  
  925. Converts the String to lower case, and also returns the converted String.
  926.  
  927. Example:
  928.  
  929.     #include "str.h"
  930.  
  931.     String s1 = "LOWERCASE";
  932.  
  933.     s1.toLower();            // s1 is now "lowercase"
  934.  
  935. See Also: toLower, toupper, toUpper
  936.  
  937. ---------------------------------------------------------------------------
  938.  
  939. toUpper
  940. -------
  941.  
  942. Syntax: String& toUpper(void);
  943.  
  944. Converts the String to upper case, and also returns the converted String.
  945.  
  946. Example:
  947.  
  948.     #include "str.h"
  949.  
  950.     String s1 = "uppercase";
  951.  
  952.     s1.toUpper();            // s1 is now "UPPERCASE"
  953.  
  954. See Also: tolower, toLower, toupper
  955.  
  956. ---------------------------------------------------------------------------
  957.  
  958. Trim
  959. ----
  960.  
  961. Syntax: String& Trim(int mode = CENTER, char ch = WHITESPACE);
  962.  
  963. Trims leading or trailing characters from a String.  The trimmed  character
  964. defaults to WHITESPACE (spaces & tabs) and can be user-defined.
  965.  
  966. Example:
  967.  
  968.     #include "str.h"
  969.  
  970.     String s1 = s2 = s3 = "    Spaces    ";
  971.  
  972.     s1.Trim(LEFT);            // s1 = "Spaces    "
  973.     s2.Trim(RIGHT);            // s2 = "    Spaces"
  974.     s3.Trim();            // s3 = "Spaces"
  975.  
  976. See Also: trim, Delete
  977.  
  978. ---------------------------------------------------------------------------
  979.  
  980. Value
  981. -----
  982.  
  983. Syntax: int&    Value(int& n);
  984.     long&   Value(long& n);
  985.     float&  Value(float& n);
  986.     double& Value(double& n);
  987.  
  988. Returns the value of a numeric String.
  989.  
  990. Example:
  991.  
  992.     #include "str.h"
  993.  
  994.     int n1;
  995.     String s1 = "12345";
  996.  
  997.     s1.Value(n1);            // n1 is now 12345
  998.  
  999. ---------------------------------------------------------------------------
  1000. ---------------------------------------------------------------------------
  1001.  
  1002. Awk-style Functions:
  1003.  
  1004. Note: AWK  begins array indexing at 1, whereas C/C++ begins array  indexing
  1005.       at 0.  Therefore, most of the implemented AWK functions return values
  1006.       that correspond to C-style indexing.  An AWK function that might nor-
  1007.       mally return a 0 as a failure indicator will return a -1 here.
  1008.  
  1009. ---------------------------------------------------------------------------
  1010.  
  1011. gsub
  1012. ----
  1013.  
  1014. Syntax: int gsub(String& from, String& to, String& s, int count = 10000);
  1015.     int gsub(Regexp& from, String& to, String& s, int count = 10000);
  1016.  
  1017. Substitutes  String 'to' for each substring in String s that is matched  by
  1018. 'from',  up to 'count' times.  Returns the number of  substitutions. 'from' 
  1019. can be a String or a regular expression.
  1020.  
  1021. Example:
  1022.  
  1023.     #include "str.h"
  1024.  
  1025.     int i;
  1026.     String s1 = "d:\\prog\\str";
  1027.  
  1028.     i = gsub("\\", "/", s1);    // i = 2
  1029.                     // s1 = "d:/prog/str"
  1030.  
  1031. See Also: Replace, sub, Sub
  1032.  
  1033. ---------------------------------------------------------------------------
  1034.  
  1035. index
  1036. -----
  1037.  
  1038. Syntax: int index(String& s, String& t);
  1039.     int index(String& s, Regexp& t);
  1040.  
  1041. Returns the position of 't' in String s if it exists, or -1 if it does not.
  1042. 't' can be a String or a regular expression.
  1043.  
  1044. Example:
  1045.  
  1046.     #include "str.h"
  1047.  
  1048.     int i;
  1049.     String s1 = "d:\\prog\\str";
  1050.  
  1051.     i = index(s1, ":");        // i = 1
  1052.  
  1053. See Also: FindFirst, FindNext, FindLast, FindPrev, Index
  1054.  
  1055. ---------------------------------------------------------------------------
  1056.  
  1057. length
  1058. ------
  1059.  
  1060. Syntax: int length(String& s);
  1061.  
  1062. Returns the length of String s.
  1063.  
  1064. Example:
  1065.  
  1066.     #include "str.h"
  1067.  
  1068.     int i;
  1069.     String s1 = "Hello World";
  1070.  
  1071.     i = length(s1);            // i = 11
  1072.  
  1073. See Also: Len, Length
  1074.  
  1075. ---------------------------------------------------------------------------
  1076.  
  1077. match
  1078. -----
  1079.  
  1080. Syntax: int match(String& s, Regexp re);
  1081.  
  1082. Returns the position of the leftmost longest substring of s matched by  the
  1083. regular  expression  re if it exists, or -1 if it does not.  Also sets  the
  1084. global variables RSTART and RLENGTH. RSTART is the starting position of the
  1085. matching substring and RLENGTH is the substring length.
  1086.  
  1087. Example:
  1088.  
  1089.     #include "str.h"
  1090.     #include "regexp.h"
  1091.  
  1092.     int i;
  1093.     String s1 = "banana";
  1094.     Regexp r1 = "a[a-z]*a"
  1095.  
  1096.     i = match(s1, r1);        // matched substring is "anana",
  1097.                     //   so i=1, RSTART=1, RLENGTH=5
  1098.  
  1099. See Also: index, Index, FindFirst, FindNext, FindLast, FindPrev
  1100.  
  1101. ---------------------------------------------------------------------------
  1102.  
  1103. split
  1104. -----
  1105.  
  1106. Syntax: int split(String& s, String*& a, String& fs);
  1107.     int split(String& s, String*& a, Regexp& fs);
  1108.  
  1109. Splits String 's' into String array 'a' on field separator 'fs'.  Array 'a'
  1110. is  normally declared as an uninitialized pointer in the  calling  function
  1111. and a reference to the pointer is passed to split().  split() will then al-
  1112. locate  memory for the correct array size and return the number of  fields.
  1113. 'fs' can be a String or a regular expression. String s remains unmodified.
  1114.  
  1115. Example:
  1116.  
  1117.     #include "str.h"
  1118.  
  1119.     int i;
  1120.     String *array;
  1121.     String s1 = "d:\\prog\\str";
  1122.  
  1123.     i = split(s1, array, "\\");    // i = 3
  1124.                     // array[0] = "d:"
  1125.                     // array[1] = "prog"
  1126.                     // array[2] = "str"
  1127.  
  1128. See Also: Split
  1129.  
  1130. ---------------------------------------------------------------------------
  1131.  
  1132. sub
  1133. ---
  1134.  
  1135. Syntax: int sub(String& from, String& to, String& s);
  1136.     int sub(Regexp& from, String& to, String& s);
  1137.  
  1138. Substitutes  String 'to' for the leftmost substring of 's' that is  matched
  1139. by 'from'.  Returns the number of substitutions (0 or 1). 'from' can  be  a
  1140. String or a regular expression.
  1141.  
  1142. Example:
  1143.  
  1144.     #include "str.h"
  1145.  
  1146.     int i;
  1147.     String s1 = "d:\\prog\\str";
  1148.  
  1149.     i = sub("\\", "/", s1);        // i = 1
  1150.                         // s1 = "d:/prog\str"
  1151.  
  1152. See Also: gsub, Replace, Sub
  1153.  
  1154. ---------------------------------------------------------------------------
  1155.  
  1156. substr
  1157. ------
  1158.  
  1159. Syntax: String substr(String& s, unsigned pos, unsigned len = 10000);
  1160.  
  1161. Creates  a new String that is the substring of String s beginning at  posi-
  1162. tion 'pos' with length 'len'. String s remains unmodified.
  1163.  
  1164. Example:
  1165.  
  1166.     #include "str.h"
  1167.  
  1168.     String s1 = "Don't just stand there...";
  1169.     String s1a;
  1170.  
  1171.     s1a = substr(s1, 11, 5);    // s1a = "stand"
  1172.  
  1173. See Also: left, Left, mid, Mid, right, Right, SubStr
  1174.  
  1175. ---------------------------------------------------------------------------
  1176. ---------------------------------------------------------------------------
  1177.  
  1178. C-Style Functions:
  1179.  
  1180. ---------------------------------------------------------------------------
  1181.  
  1182. left
  1183. ----
  1184.  
  1185. Syntax: String left(String& s, int len);
  1186.  
  1187. Creates a new String that is the leftmost substring of String s with length
  1188. 'len'. String s remains unmodified.
  1189.  
  1190. Example:
  1191.  
  1192.     #include "str.h"
  1193.  
  1194.     String s1 = "This is a test";
  1195.     String s1a, s1b, s1c;
  1196.  
  1197.     s1a = left(s1, 4);        // s1a = "This"
  1198.     s1b = mid(s1, 5, 4);        // s1b = "is a"
  1199.     s1c = right(s1, 4);        // s1c = "test"
  1200.  
  1201. See Also: Left, mid, Mid, right, Right, substr, SubStr
  1202.  
  1203. ---------------------------------------------------------------------------
  1204.  
  1205. justify
  1206. -------
  1207.  
  1208. Syntax:    String justify(String& s, int type, int len, int mode = CLIP|TRIM);
  1209.  
  1210. Creates a new String from s and justifies it by padding it with spaces  un-
  1211. til  it  is 'len' long.  The justification 'type' can be LEFT,  CENTER,  or
  1212. RIGHT. If String s had any leading or trailing whitespaces (spaces or tabs)
  1213. then  they are first removed if 'mode'|=TRIM.  If the new String is  longer
  1214. than 'len' (after the optional removal of white spaces) then it is  clipped
  1215. to len if 'mode'|=CLIP, otherwise the trimmed String is returned.  String s
  1216. remains unmodified.
  1217.  
  1218. Example:
  1219.  
  1220.     #include "str.h"
  1221.  
  1222.     String s1 = "Hello World";
  1223.     String s1a, s1b, s1c;
  1224.  
  1225.     s1a = justify(s1, LEFT, 20);    // s1a = "Hello World         "
  1226.     s1b = justify(s1, CENTER, 20);    // s1b = "    Hello World     "
  1227.     s1c = justify(s1, RIGHT, 20);    // s1c = "         Hello World"
  1228.  
  1229. See Also: Justify, trim, Trim
  1230.  
  1231. ---------------------------------------------------------------------------
  1232.  
  1233. mid
  1234. ---
  1235.  
  1236. Syntax: String mid(String& s, int pos, int len);
  1237.  
  1238. Creates a new String that is the substring of String s beginning at posi-
  1239. tion 'pos' with length 'len'. String s remains unmodified.
  1240.  
  1241. Example:
  1242.  
  1243.     #include "str.h"
  1244.  
  1245.     String s1 = "This is a test";
  1246.     String s1a, s1b, s1c;
  1247.  
  1248.     s1a = left(s1, 4);        // s1a = "This"
  1249.     s1b = mid(s1, 5, 4);        // s1b = "is a"
  1250.     s1c = right(s1, 4);        // s1c = "test"
  1251.  
  1252. See Also: left, Left, Mid, right, Right, substr, SubStr
  1253.  
  1254. ---------------------------------------------------------------------------
  1255.  
  1256. right
  1257. -----
  1258.  
  1259. Syntax: String right(String& s, int len);
  1260.  
  1261. Creates  a  new  String that is the rightmost substring of  String  s  with
  1262. length 'len'. String s remains unmodified.
  1263.  
  1264. Example:
  1265.  
  1266.     #include "str.h"
  1267.  
  1268.     String s1 = "This is a test";
  1269.     String s1a, s1b, s1c;
  1270.  
  1271.     s1a = left(s1, 4);        // s1a = "This"
  1272.     s1b = mid(s1, 5, 4);        // s1b = "is a"
  1273.     s1c = right(s1, 4);        // s1c = "test"
  1274.  
  1275. See Also: left, Left, mid, Mid, Right, substr, SubStr
  1276.  
  1277. ---------------------------------------------------------------------------
  1278.  
  1279. tolower
  1280. -------
  1281.  
  1282. Syntax: String tolower(String& s);
  1283.  
  1284. Creates a lowercase version of String s. String s remains unmodified.
  1285.  
  1286. Example:
  1287.  
  1288.     #include "str.h"
  1289.  
  1290.     String s1 = "LOWERCASE";
  1291.     String s1a;
  1292.  
  1293.     s1a = tolower(s1);        // s1a = "lowercase"
  1294.  
  1295. See Also: toLower, toupper, toUpper
  1296.  
  1297. ---------------------------------------------------------------------------
  1298.  
  1299. toupper
  1300. -------
  1301.  
  1302. Syntax: String toupper(String& s);
  1303.  
  1304. Creates an uppercase version of String s. String s remains unmodified.
  1305.  
  1306. Example:
  1307.  
  1308.     #include "str.h"
  1309.  
  1310.     String s1 = "uppercase";
  1311.     String s1a;
  1312.  
  1313.     s1a = toupper(s1);        // s1a = "UPPERCASE"
  1314.  
  1315. See Also: tolower, toLower, toUpper
  1316.  
  1317. ---------------------------------------------------------------------------
  1318.  
  1319. trim
  1320. ----
  1321.  
  1322. Syntax: String trim(String& s, int mode=CENTER, char ch = WHITESPACE);
  1323.  
  1324. Creates  a new String from s with leading and/or trailing characters  trim-
  1325. med.  The trimmed character 'ch' defaults to WHITESPACE (spaces & tabs) and
  1326. can  be user-defined.  The trim 'mode' defaults to CENTER and can  also  be
  1327. RIGHT or LEFT. String s remains unmodified.
  1328.  
  1329. Example:
  1330.  
  1331.     #include "str.h"
  1332.  
  1333.     String s1 = "    Spaces    ";
  1334.     String s1a, s1b, s1c;
  1335.  
  1336.     s1a = trim(s1, LEFT);        // s1a = "Spaces    "
  1337.     s1b = trim(s1, RIGHT);        // s1b = "    Spaces"
  1338.     s1c = trim(s1);            // s1c = "Spaces"
  1339.  
  1340. See Also: Delete, justify, Justify, Trim
  1341.  
  1342. ---------------------------------------------------------------------------
  1343.