kstring - A String Object  (version 3.3a)

kstring is a C++ class that implements a string object.

General:

  kstring objects consist of zero to MAX_SIZE characters.
    MAX_SIZE defaults to 1000; change via kstring::MAX_SIZE = 80;
  Elements of kstring are numbered starting at zero, i.e. s[0] is the
    first element of the kstring, s.
  In any sample code below, presume identifiers that start with:
    s are of type kstring
    p are of type char *
    c are of type char
    n,i,j are of type unsigned
  The following global definitions are in kstring.h
    typedef char bool;
    enum {false, true};
    enum {ON_LEFT, ON_RIGHT}; // for pad function

kstring has six constructor functions:
  1. A constructor with no arg; creates a zero length string; prototype:
       kstring();
     Sample declaration:
       kstring s1;
  2. A constructor with a c style string as an initial value; prototype:
       kstring(const char * s,
         unsigned pos = 0,       // optional starting char
         unsigned n_chars = 0);  // optional # of chars
     Sample declarations:
       kstring s2a("ABC");
       kstring s2b(p);
       kstring s2c(p, 5, 2); // init with the contents of p at pos 5 & 6
  3. A constructor with a kstring as an initial value; prototype:
       kstring(const kstring &s,
         unsigned pos = 0,       // optional starting char
         unsigned n_chars = 0);  // optional # of chars
     Sample declarations:
       kstring s3a(s);
       kstring s3b(s, 5, 2); // init with the contents of s at pos 5 & 6
  4. A constructor with a char as an initial value; prototype:
       kstring(char ch, unsigned n = 1); // n is reptition count
     Sample declarations:
       char ch = '*';
       kstring s4(ch);       // init with "*"
       kstring s4(ch, 6);    // init with "******"
  5. A constructor with a long as an initial value; width=0 means no pad
       kstring(long val, unsigned width = 0, char pad_ch = ' ');
     Sample declarations:
       kstring s5a(456, 0);      // init with "456"
       kstring s5b(456, 6);      // init with "   456"
       kstring s5c(456, 6, '*'); // init with "***456" using pad char
  6. A constructor with a double as init val; d decimal digits, width=w
       kstring(double val,unsigned d=2, unsigned w=0, char pad_ch=' ');
     Sample declarations:
       double x = 1.2345;
       kstring s6a(x);           // init with "1.23"
       kstring s6a(x, 3, 7);     // init with "  1.235"
       kstring(double val, unsigned d=2, unsigned w=0, char pad_ch=' ');

There is a destructor:
  ~kstring(void);

There are many member functions:
  length - unsigned length(void);
    n = s1.length(); // number if characters in kstring
  c_str - const char * c_str(void);
    f.open(s1.c_str()); // c_str() is a pointer to the contents of s1
  [] - char & operator[](unsigned pos);
    ch = s1[i]; // get the ith char of a kstring, s[0] is 1st char
    s1[i] = ch; // change the ith char (via reference)
  contains - int contains(kstring & s);
    if (s1.contains(s2)) doit(); // is s2 in s1?
  pos - int pos(kstring &s);
    i = s1.pos(s2);  // position of s2 in s1; -1 if not found
    j = s1.pos(' '); // position of ch in s1
  = - kstring& operator =  (const kstring &s);
    s1 = s2; // copy contents od s2 to s1; old value of s1 is deleted
  += - kstring& operator += (const kstring &s);
    s1 += s2; // s1 has s2 concatenated to the end; s2 is unchanged
  + - friend kstring operator + (const kstring &s1, const kstring &s2);
      friend kstring operator + (const kstring &s1, const char * s2);
      friend kstring operator + (const char * s1,   const kstring &s2);
    s1 = s2 + s3; // s1 replaced with contents of s2 and s3 concatenated
    s1 = s2 + p;
    s1 = p + s2;
    s1 = p1 + p2; // does not work
    s1 = kstring(p1) + p2; // does work
  relationship operators, == != > >= < <= - 18 functions of the form:
      friend int operator == (const kstring &s1, const kstring &s2);
      friend int operator == (const kstring &s1, const char * s2);
      friend int operator == (const char * s1, const kstring &s2);
    if (s1 == s2) doit();
    if (s1 < p) doit();
    if (p >= s1) doit();
    if (p1 == p2) doit(); // do not do this; it will compare pointers
    if (kstring(p1) == kstring(p2)) doit(); // works
  << - friend ostream& operator << (ostream &st, const kstring &s);
    cout << "s1 = " << s1 << endl;
  >> - friend istream& operator >> (istream &st, kstring &s2); // see Note 1
    cin >> s1; // read_line into s1; same as s1.read_line(cin);
  read_line - istream& kstring::read_line(istream & f); // see Note 1
    s1.read_line(f); // read a line from the file f; same as f >> s1;
  cvt_long - two functions:
    bool cvt_long(unsigned & i, long & val);
      // converts value at position i to a number; updates i to nonblank
      // char after the number; returns true if there was a number
      ok = s1.cvt_long(i, long_val1);         // get one value
      if (ok) ok = s1.cvt_long(i, long_val2); // get the next value
    bool cvt_long(long & val);
      // converts the first nonblank chars in string to a number;
      // returns true if there was a number
      ok = s1.cvt_long(long_val);
  cvt_double - two functions:
    bool cvt_double(unsigned & i, double & val);
      // converts value at position i to a number; updates i to nonblank
      // char after the number; returns true if there was a number
      ok = s1.cvt_double(i, double_val);
    bool cvt_double(double & val);
      // converts the first nonblank chars in string to a number;
      // returns true if there was a number
      ok = s1.cvt_double(double_val);
  trim_lead - void trim_lead();
    s1.trim_lead();  // trim leading spaces
  trim_trail - void trim_trail();
    s1.trim_trail(); // trim trailing spaces
  trim - void trim();
    s1.trim();       // trim leading and trailing spaces
  pad - unsigned pad(unsigned width, char pad_ch=' ', int side=ON_LEFT);
    s1.pad(6); // pad with blanks ON_LEFT to a width of 6
    s2.pad(80, '*', ON_RIGHT); // pad ON_RIGHT with '*' to a width of 80
  r_just - void r_just(unsigned n);
    s1.r_just(n);  // right justify to a width of n
  l_just - void l_just(unsigned n);
    s1.l_just(n);  // left justify first nonblank char to position n
  center - void center(unsigned n);
    s1.center(n);  // center the string at position n
  to_upper - void to_upper();
    s1.to_upper(); // convert string to upper case
  to_lower - void to_upper();
    s1.to_lower(); // convert string to lower case
  token - kstring token(int n, bool to_eos = false);
    // returns the n'th token; n = 0 for 1st token; if to_eos is true,
    // returns the remainder of the string, starting at token n.
    newone->part_num = line.token(0);
    line.token(1).cvt_long(newone->qoh);
    newone->part_name = line.token(2, true /* to_eos */);
  num_tokens - int num_tokens();
    n = s1.num_tokens(); // returns the number of tokens in string

Notes:
  1.