home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 4 / FreshFish_May-June1994.bin / bbs / gnu / libg++-2.5.3-bin.lha / info / libg++.info-3 (.txt) < prev    next >
GNU Info File  |  1994-02-27  |  50KB  |  1,048 lines
  1. This is Info file libg++.info, produced by Makeinfo-1.55 from the input
  2. file ./libg++.texi.
  3. START-INFO-DIR-ENTRY
  4. * Libg++::                      The g++ class library.
  5. END-INFO-DIR-ENTRY
  6.    This file documents the features and implementation of The GNU C++
  7. library
  8.    Copyright (C) 1988, 1991, 1992 Free Software Foundation, Inc.
  9.    Permission is granted to make and distribute verbatim copies of this
  10. manual provided the copyright notice and this permission notice are
  11. preserved on all copies.
  12.    Permission is granted to copy and distribute modified versions of
  13. this manual under the conditions for verbatim copying, provided also
  14. that the section entitled "GNU Library General Public License" is
  15. included exactly as in the original, and provided that the entire
  16. resulting derived work is distributed under the terms of a permission
  17. notice identical to this one.
  18.    Permission is granted to copy and distribute translations of this
  19. manual into another language, under the above conditions for modified
  20. versions, except that the section entitled "GNU Library General Public
  21. License" and this permission notice may be included in translations
  22. approved by the Free Software Foundation instead of in the original
  23. English.
  24. File: libg++.info,  Node: String,  Next: Integer,  Prev: AllocRing,  Up: Top
  25. The String class
  26. ****************
  27.    The `String' class is designed to extend GNU C++ to support string
  28. processing capabilities similar to those in languages like Awk.  The
  29. class provides facilities that ought to be convenient and efficient
  30. enough to be useful replacements for `char*' based processing via the C
  31. string library (i.e., `strcpy, strcmp,' etc.) in many applications.
  32. Many details about String representations are described in the
  33. Representation section.
  34.    A separate `SubString' class supports substring extraction and
  35. modification operations. This is implemented in a way that user
  36. programs never directly construct or represent substrings, which are
  37. only used indirectly via String operations.
  38.    Another separate class, `Regex' is also used indirectly via String
  39. operations in support of regular expression searching, matching, and the
  40. like.  The Regex class is based entirely on the GNU Emacs regex
  41. functions.  *Note Syntax of Regular Expressions: (emacs.info)Regexps,
  42. for a full explanation of regular expression syntax.  (For
  43. implementation details, see the internal documentation in files
  44. `regex.h' and `regex.c'.)
  45. Constructors
  46. ============
  47.    Strings are initialized and assigned as in the following examples:
  48. `String x;  String y = 0; String z = "";'
  49.      Set x, y, and z to the nil string. Note that either 0 or "" may
  50.      always be used to refer to the nil string.
  51. `String x = "Hello"; String y("Hello");'
  52.      Set x and y to a copy of the string "Hello".
  53. `String x = 'A'; String y('A');'
  54.      Set x and y to the string value "A"
  55. `String u = x; String v(x);'
  56.      Set u and v to the same string as String x
  57. `String u = x.at(1,4); String v(x.at(1,4));'
  58.      Set u and v to the length 4 substring of x starting at position 1
  59.      (counting indexes from 0).
  60. `String x("abc", 2);'
  61.      Sets x to "ab", i.e., the first 2 characters of "abc".
  62. `String x = dec(20);'
  63.      Sets x to "20". As here, Strings may be initialized or assigned
  64.      the results of any `char*' function.
  65.    There are no directly accessible forms for declaring SubString
  66. variables.
  67.    The declaration `Regex r("[a-zA-Z_][a-zA-Z0-9_]*");' creates a
  68. compiled regular expression suitable for use in String operations
  69. described below. (In this case, one that matches any C++ identifier).
  70. The first argument may also be a String.  Be careful in distinguishing
  71. the role of backslashes in quoted GNU C++ char* constants versus those
  72. in Regexes. For example, a Regex that matches either one or more tabs
  73. or all strings beginning with "ba" and ending with any number of
  74. occurrences of "na" could be declared as `Regex r =
  75. "\\(\t+\\)\\|\\(ba\\(na\\)*\\)"' Note that only one backslash is needed
  76. to signify the tab, but two are needed for the parenthesization and
  77. virgule, since the GNU C++ lexical analyzer decodes and strips
  78. backslashes before they are seen by Regex.
  79.    There are three additional optional arguments to the Regex
  80. constructor that are less commonly useful:
  81. `fast (default 0)'
  82.      `fast' may be set to true (1) if the Regex should be
  83.      "fast-compiled". This causes an additional compilation step that
  84.      is generally worthwhile if the Regex will be used many times.
  85. `bufsize (default max(40, length of the string))'
  86.      This is an estimate of the size of the internal compiled
  87.      expression. Set it to a larger value if you know that the
  88.      expression will require a lot of space. If you do not know, do not
  89.      worry: realloc is used if necessary.
  90. `transtable (default none == 0)'
  91.      The address of a byte translation table (a char[256]) that
  92.      translates each character before matching.
  93.    As a convenience, several Regexes are predefined and usable in any
  94. program. Here are their declarations from `String.h'.
  95.      extern Regex RXwhite;      // = "[ \n\t]+"
  96.      extern Regex RXint;        // = "-?[0-9]+"
  97.      extern Regex RXdouble;     // = "-?\\(\\([0-9]+\\.[0-9]*\\)\\|
  98.                                 //    \\([0-9]+\\)\\|
  99.                                 //    \\(\\.[0-9]+\\)\\)
  100.                                 //    \\([eE][---+]?[0-9]+\\)?"
  101.      extern Regex RXalpha;      // = "[A-Za-z]+"
  102.      extern Regex RXlowercase;  // = "[a-z]+"
  103.      extern Regex RXuppercase;  // = "[A-Z]+"
  104.      extern Regex RXalphanum;   // = "[0-9A-Za-z]+"
  105.      extern Regex RXidentifier; // = "[A-Za-z_][A-Za-z0-9_]*"
  106. Examples
  107. ========
  108.    Most `String' class capabilities are best shown via example.  The
  109. examples below use the following declarations.
  110.          String x = "Hello";
  111.          String y = "world";
  112.          String n = "123";
  113.          String z;
  114.          char*  s = ",";
  115.          String lft, mid, rgt;
  116.          Regex  r = "e[a-z]*o";
  117.          Regex  r2("/[a-z]*/");
  118.          char   c;
  119.          int    i, pos, len;
  120.          double f;
  121.          String words[10];
  122.          words[0] = "a";
  123.          words[1] = "b";
  124.          words[2] = "c";
  125. Comparing, Searching and Matching
  126. =================================
  127.    The usual lexicographic relational operators (`==, !=, <, <=, >, >=')
  128. are defined. A functional form `compare(String, String)' is also
  129. provided, as is `fcompare(String, String)', which compares Strings
  130. without regard for upper vs. lower case.
  131.    All other matching and searching operations are based on some form
  132. of the (non-public) `match' and `search' functions.  `match' and
  133. `search' differ in that `match' attempts to match only at the given
  134. starting position, while `search' starts at the position, and then
  135. proceeds left or right looking for a match.  As seen in the following
  136. examples, the second optional `startpos' argument to functions using
  137. `match' and `search' specifies the starting position of the search: If
  138. non-negative, it results in a left-to-right search starting at position
  139. `startpos', and if negative, a right-to-left search starting at
  140. position `x.length() + startpos'. In all cases, the index returned is
  141. that of the beginning of the match, or -1 if there is no match.
  142.    Three String functions serve as front ends to `search' and `match'.
  143. `index' performs a search, returning the index, `matches' performs a
  144. match, returning nonzero (actually, the length of the match) on success,
  145. and `contains' is a boolean function performing either a search or
  146. match, depending on whether an index argument is provided:
  147. `x.index("lo")'
  148.      returns the zero-based index of the leftmost occurrence of
  149.      substring "lo" (3, in this case).  The argument may be a String,
  150.      SubString, char, char*, or Regex.
  151. `x.index("l", 2)'
  152.      returns the index of the first of the leftmost occurrence of "l"
  153.      found starting the search at position x[2], or 2 in this case.
  154. `x.index("l", -1)'
  155.      returns the index of the rightmost occurrence of "l", or 3 here.
  156. `x.index("l", -3)'
  157.      returns the index of the rightmost occurrence of "l" found by
  158.      starting the search at the 3rd to the last position of x,
  159.      returning 2 in this case.
  160. `pos = r.search("leo", 3, len