Z Directory reference manual ("man" pages)

class ref name: string
category-group: strings
layer: 1
header file: z_string.h

synopsis.
the string_o object is perhaps the most common, pervasive, ubiquitious class in the Z Directory. It permeates the system and is used by most of the other components. From it derives several other classes: parameter string, text string, keyword, and others. It is functionally equivalent to the string object in STL. However, it is not template-based. String objects have 2 primary functions - as holders of text, or as generic blocks of data. In the latter case, a string_o can contain a block of binary bytes. It plays a key role in the implemenation of encryption in the Z Directory. All the encryptors (aka "ciphers") - RSA, Rijndael, DES, etc. operate on data contained in the string object.

There are several ways to initialize a string object. The resultant size, capacity, and contents of the object can vary considerably, depending on which constructor is used, whether a user-supplied buffer is provided, or if one of the data buffer modifiers are called:

set(char *, size_t, size_t) : provides the object with a user-supplied buffer, and defines the length and total size;
set_size(const size_t n) : sets the data length to 'n';
force_size(size_t l, size_t b) : "forces" the data size to be of length 'l' and total (block) size 'b'. If 'b' is 0, it will be auto-computed. It is illegal to have both 'l' and 'b' be 0, or l >= b.
resize(size_t l, boolean xs, boolean sc) : resizes the data block size so that its length is 'l'. if 'l' is less than the current data block size, no new block will be allocated. If 'sc' ("Save Contents") is TRUE, and a new block gets allocated, the existing contents will be copied to the new block.
resize(size_t l, size_t b, boolean sc) : sets the object's new length to 'l' and block size to 'b'. Note that if the value of 'b' is less than the current block size, the block size will be unaffected.

Many details of these calls are covered in this page.

description.
There are 2 enumerations in the string class: zSearch_Mode and zString_Case. These are needed to find sub-text within a string object:

size_t idx = s.find ("subtext", &ie0, z_Find_First);

There is a large number of member functions for the string object. Some of them "mimic" layer 0 functions. Those functions are invariably easier to work with rather than their subroutine ('global-scope') counterparts. For example:

string_o a("abc"), z("xyz");
if (a == b)
{
    // ..
}

The above is equivalent to doing this:

string_o a("abc"), z("xyz");
if (a.is_textmode())
    return z_strcmp (a.data(), b.data());
else
    return z_bcmp ((const u_char *) a.data(), (const u_char *) b.data(), a.size());

This principle applies to other member functions, such as trim() (based on z_trim()) or toupper() (based on z_uppercase_line()). Often a string operation you want can be accomplished using a combination of the string object and lower level string functions. Thus it would help you to become familiar with layer 0 and 1 string routines in addition to this class object.

To access a string object's data directly, use the member function data(). In a debugger, this is equivalent to peering into my_data (a character array). Since this is simply an array of chars, it is a lot easier to work with than with STL's strings.

Member function data() returns a const pointer into the data. Directly modifying the contents of this char array can corrupt the string object; you are cautioned not to do that. There are truckloads of member functions for changing the contents of a string object.

When using a string to hold a binary data block, call setmode_binary(). The default mode of a string_o is text. To set it to binary mode, call setmode_binary(). You can also assign it your own data buffer, via the set() member function. This is useful in some applications, such as loading a file into a string instance, or if the application is doing its own memory management. The string update its internal settings and will know that the internal storage buffer is foreign to it. Thus when the object goes out of scope, the internal char buffer will not be de-allocated as it normally would (via delete).

Note: if you assign a fixed buffer to a string object (via set()), and if the string needs to grow to a size greater than its buffer size, it won't. A string_o with an application-assigned buffer is fixed in size (until a reset() is done or the object goes out of scope). A new buffer will not be automatically allocated, as in the normal case for the object:

    char buf[8];
    string_o s1, s2;
    z_strcpy (buf, "hello");
    s2 = " there.";
    s1.set (buf, 8);            // bind 'buf' to the string object
    s1.set_size (5);            // manually set the object's size
    s1 += s2;                   // concat fails: "hello there" size=11
    std::cout << "s1: " << s1 << "\n";        // output: "hello\n"

Z Directory strings that are not bound to an application-supplied buffer automatically resize. Assigning a long string to a short one is no worry: the short string will resize to accomodate the new data. 2 main metrics of string_o sizes are:

the capacity - the actual size of the data buffer allocated; and the size - the logical size of the string, which is normally null-terminated (eg '\0'), and is always less than the capacity. These two values can be obtained by calling member functions size() and capacity().

Here is a typical sequence necessary for reading the contents of a binary file into a string object:

int ie, ie2; size_t n;                  // various work vars
u_char slab[4096];                      // file is to go into here
string_o sb;                            // set up a special string obj
sb.setmode_binary();                    // must be done for .exe files
sb.set ((char *) slab, 4096+2);         // bind char[] buff to object
file_o f ("program.exe");               // create file object
f.set_binarymode ();                    // important! set to binary
do                                      // loop until EOF
{
    ie = f.get_bytes (sb, &n, &ie2);    // loads 4,096 bytes -> "sb"
    // 
} while (n == 4096);    // there will be 1 unprocessed block remaining

Concatenation of strings is done via the "+" operator (and "+=). Although some other languages or libraries use other symbols (eg perl's "."), "+" is the most obvious (and again, the most obvious choice is the most correct choice).

Reference counting and copy-on-write is not done in this class. Although it may appear to be, any internal data members for this methodology are dormant. The theory of sharing the data is cute, but Vettrasoft believes that shared strings are not prevalent in real-world applications, and the added complexity negates the benefits of reference counting.

There are a variety of support/convenience/utility functions, including a set of search-based operations, such as:

function name	type/group	notes
isfound()	searching	a variation of find(); searches for a character or string in the strings' contents.
find()	searching	the workhorse function of finding a string inside the object's text-contents. Has several options (find first, "find next", find last; and starting from an offset).
cmp_nchars()	searching	a specialized search - compares only the first 'n' characters (or by default, the search string's size).
search_destroy()	search & modify	does a search, and if found, removes the search text from the item's text.
search_replace()	search & modify	does a search and replace. it can do the 1st, the last, or all occurances.
trim(), pre_trim(), full_trim()	beaufification	these functions delete any whitespace (including newlines and carriage-returns) at the front of the text, at the end, or both.
tolower(), toupper()	beautification	these functions change the "case" of the text (to upper or lower case).

member functions (primary)

string_o()
SIGNATURE: string_o ()
SYNOPSIS: creates a a new string object, completely devoid of contents. internal data pointer will be null.

string_o(string_o)
SIGNATURE: string_o (const string_o &rhs)
SYNOPSIS:
creates a a new string object, based on the string represented by string object "rhs". The contents of string "rhs" will be copied (deep copy).

operator = (string_o)
SIGNATURE: const string_o &operator = (const string_o &rhs)
SYNOPSIS:
an existing string object's contents is replaced with that of "rhs". the current object will probably have a new data block. Thus the pointer value "m_s" will be different, if a new allocation is required. If "rhs" is smaller than the current object, the data block will [probably] be the same.
TRAITS: this is an inline function

destructor
SIGNATURE: ~string_o ()
SYNOPSIS:
virtual destructor: this destroys the class object instance. If the string object allocated the internal buffer via new, delete will be used to de-allocate it.
TRAITS: this is a virtual function

string_o(<args>)
SIGNATURE: string_o (const char *s)
SYNOPSIS: make a string from a char array
DESCRIPTION:
this c'tor is equivalent to "string_o((const string_o) s)". it creates a new string object and copies the contents of s into it.

string_o(<args>)
SIGNATURE: string_o (char *rhs, const size_t n, boolean istext = FALSE)
SYNOPSIS: create a string instance; controlled buffer address and size
PARAMETERS

rhs: pointer to a user-supplied buffer. can be null. if null, the string object will allocate a new buffer of the specified size.

n: size of the buffer "rhs", or if null, the size of the buffer to allocate

istext: flag, puts the object into either text mode or binary mode. default is binary mode (this function is expected to be used for loading binary data)

DESCRIPTION:
this sets up a buffer of the desired length, specified by "n". If "rhs" is null, a new buffer is allocated; otherwise, the one supplied is used, and it is assumed that it is of length "n" (or greater). if "istext" is true (text mode), there is a cursory computation of the length of the inputted buffer (if it is not null!). You must make sure that the length of the text (eg via z_strlen()) does not exceed "n".

string_o(<args>)
SIGNATURE: string_o (const size_t n)
SYNOPSIS: create a string object. allocates an internal data buffer of size 'n'.

data()
SIGNATURE: const char *data() const
SYNOPSIS: returns a handle to the internal data buffer
DESCRIPTION:
this is for applications that need to work directly with the character string. it is not recommended to change this data, particularly to lengthen or shorten it by inserting or deleting '\0' (terminators). Hence, the return type is "const".

endchar()
SIGNATURE: const char endchar() const
SYNOPSIS: returns the last character of the string (or '\0')
RETURNS:
c: 'c' is the last character in the string, if there is one;
'\0': if string is empty

operator []()
SIGNATURE: const char &operator [] (size_t i) const
SYNOPSIS: return a single character (with bounds checks)
DESCRIPTION:
returns the character found at position "i". if "i" is out of bounds, a "bad character" is returned.
Here is an example of how to test for out-of-bounds:
string_o s("this is only a test.");
const char &c = s[3];
if (&c == &badchar)
    std::cout << "invalid access\n";
RETURNS:
{ch} - character at position "i", if valid
{badchar} - reference to internal, global "error character". the bad character can be tested for

operator []()
SIGNATURE: char &operator [] (size_t idx)
SYNOPSIS:
return a reference single character (with bounds checks); this is the non-const version of its twin function with the same signiture (sans "const" at the end)
DESCRIPTION:
the compiler should automatically figure out which version of this member function to use, depending on the const context:
string_o s("this is a test.");
const char &c = s[80];
..calls the other [const] function
string_o s("this is a test.");
char &c = s[80];
..calls this [non-const] function

operator ==()
SIGNATURE: int operator == (const string_o &that) const
SYNOPSIS: compare 2 strings for equality
DESCRIPTION:
if the strings are different in any way, this returns 0 (unequal). This function-comparision is case-sensitive; "abc" and "Abc" are different strings. if one string is longer than the other, they are different.
RETURNS:
1: equal (identical) strings
0: strings are different

operator !=()
SIGNATURE: int operator != (const string_o &that) const
SYNOPSIS: compare 2 strings; return 1 if they are different
DESCRIPTION: the inverse of "operator =="

operator >= , <=, <, >()
SIGNATURE: int operator >= (const string_o &that) const
SYNOPSIS:
test if current string object is lexigraphy:
(>=) greater than or equal to "that";
(<=) less than or equal to "that";
(>) greater than "that";
(<) less than "that";
DESCRIPTION:
the definition of a string being greater or less than another is implementation-dependent. Generally, the traditional rules based on ASCII values are used: 'a' is "less than" 'b'; 'C' is "less than" 'c', etc.
RETURNS:
1: this object is [compare-operation] to "that"
0: otherwise

size()
SIGNATURE: size_t size () const
SYNOPSIS: return the size (length) of the string
DESCRIPTION:
returns # of characters up to the terminating '\0'. in this object, 1 character maps to 1 byte. The size of the buffer allocated to hold the text may be (and usually is) bigger than the number of characters stored.

capacity()
SIGNATURE: size_t capacity () const
SYNOPSIS: returns the total # of bytes available in the string object
DESCRIPTION: the capacity of a string is usually greater than the length of a string, as buffer allocation is in 8-byte chunks

is_set()
SIGNATURE: boolean is_set () const
SYNOPSIS: returns TRUE if the string object has been set to something; FALSE otherwise
DESCRIPTION:
if you instantiate a string object without setting its value:
  string_o s0;
  if (s0.is_set()) return;       // this will return
  string_o s1 = "";
  if (s1.is_set()) return;       // this will NOT return
this will return FALSE, until you assign a string value to the object.

is_textmode()
SIGNATURE: boolean is_textmode () const
SYNOPSIS: returns TRUE if string object is in "text" mode; FALSE otherwise
DESCRIPTION: the default is "text" mode.

is_sticky()
SIGNATURE: boolean is_sticky () const
SYNOPSIS: [WIP]

contains()
SIGNATURE: boolean contains (const string_o &s) const
SYNOPSIS: tell if the string contains "s"
DESCRIPTION: this is an alias for find().
TRAITS: not sure why this member function exists. noted for termination; don't use

cmp_nchars()
SIGNATURE: int cmp_nchars (const string_o &s, const count_t n = -1, boolean use_case = TRUE) const
SYNOPSIS:
this compares the first 'n' characters of 's' to the start of the objects' text contents. by default ('n' == -1), the full contents of 's' will be used. otherwise, only the first 'n' characters (up to the # of chars in 's') will be used. if 'n' exceeds the size (# of characters) in 's', 'n' will be set to that size. if 'use_case' is TRUE (the default), the comparison will be case-sensitive.
RETURNS:
0: a match
-1, +1: strings don't match (either lexographically greater than (1) or less than (-1)

isfound()
SIGNATURE: boolean isfound (char c, size_t &idx, enum search_mode mode = z_Find_First, const size_t n = 0) const
SYNOPSIS:
search for character 'c' in the string. This function is in reality a simple wrapper around the find() function. It provides a simplified interface compared to 'find()':
string_o s = "I do, what I have to do.";
size_t idx;
if (s.isfound(',', idx))
    std::cout << "comma (',') found at pos.: " << idx << "\n";
Instead of:
string_o s = "I am a man, that's what I say, I am!\n";
size_t idx;
int ie;
idx = s.find(',', &ie, string_o::z_Find_First);
if (ie)
    std::cout << "comma (',') found at pos.: " << idx << "\n";
PARAMETERS

c: the character to hunt for

idx: the offset into the current object where 'c' is found. this value is valid only if the function returns TRUE. Since the variable is a reference, it acts essentially as a pointer, and is an output variable. If isfound() returns FALSE, the value is undeterminate.

mode: search direction. This can be:
string_o::z_Find_First - finds the first occurance of "c" in the string
string_o::z_Find_Next - finds the nth occurance of "c" in the string (based on parameter "n")
string_o::z_Find_Last - finds the last occurance of "c" in the string

n: find the nth occurance (first one, n = 0). This is applicable only for z_Find_Next mode.

RETURNS:
TRUE: the character 'c' was found in the current string object
FALSE: the character 'c' is not in the current string object

isfound()
SIGNATURE: boolean isfound (const string_o &s, size_t &idx, enum search_mode mo = z_Find_First, const size_t n = 0) const
SYNOPSIS:
search for [substring] 's' in the current string object. This function is basically a simple wrapper around the find() function to make it simpler and more convenient to use.
PARAMETERS

s: the sub-string to hunt for

idx: the offset into the current object where 's' is found. this value is valid only if the function returns TRUE. Since the variable is a reference, it acts essentially as a pointer, and is an output variable. If isfound() returns FALSE, the value is undeterminate.

mode: search direction. This can be:
string_o::z_Find_First - finds the first occurance of "c" in the string
string_o::z_Find_Next - finds the nth occurance of "c" in the string (based on parameter "n")
string_o::z_Find_Last - finds the last occurance of "c" in the string

n: find the nth occurance (first one, n = 0). This is applicable only for z_Find_Next mode.

DESCRIPTION:
see "isfound(char, ..)" member function for details pertaining to this function, or "find(string_o, ..)" member function for an overview of how the "find()" operations work. Most of the parameters to this family of functions are identical.
RETURNS:
TRUE: the [sub]string 's' was found in the current string object
FALSE: the string 's' is not in the current string object

find()
SIGNATURE: size_t find (char c, int *pe, enum search_mode mode = z_Find_First, const size_t n = 0) const
SYNOPSIS:
search for character 'c' in the string. The first 2 parameters are mandatory. you can search for the first occurance of 'c' or the last occurance ('z_Find_Next' is being phased out). returns a character (ie byte) offset if found. if found, 'pe' is 0; if not, it is 1.
PARAMETERS

c: character to hunt for

pe: error [output] indicator flag. values:
0: found
-1: not found

mode: search direction. can be:
string_o::z_Find_First - finds the first occurance of "c" in the string
string_o::z_Find_Next - finds the nth occurance of "c" in the string (based on parameter "n") [WARNING: OBSOLETE]
string_o::z_Find_Last - finds the last occurance of "c" in the string

n: if mode is 'z_Find_First' or 'z_Find_Last': start at character offset 'n' in the object.
if mode is 'z_Find_Last', find the nth occurance (first one, n = 0). This interpretation of the variable is applicable only for z_Find_Next mode.

RETURNS:
[idx] offset into the data (starting from 0) where "c" was found (if found)
0: not found (check value of "pe" for possible error)

find()
SIGNATURE: size_t find (const string_o &s, int *ie, enum search_mode = z_Find_First, const size_t n = 0) const
SYNOPSIS: search for [sub] string "s" in the current string object.
DESCRIPTION:
see "find(char, ..)" member function [above] for usage and semantics of this function. all behaviours are the same, except that it searches for a string instead of a single character.

setmode_binary()
SIGNATURE: void setmode_binary ()
SYNOPSIS: sets the mode of the current object to "binary".
DESCRIPTION:
this is used for: comparing strings - the internal length parameter is used, instead of using a terminating '\0' sentinel;
string searches ["find()" function] are not dependent on a terminating '\0' sentinel;
string concatenation is done using internal length value

setmode_text()
SIGNATURE: void setmode_text ()
SYNOPSIS: sets the string to [normal] "text" mode.
DESCRIPTION:
the mode affects string concatenation, substring searches, and how string comparisions is done. such operations normally require a terminator: '\0'.

setmode_sticky()
SIGNATURE: void setmode_sticky (boolean ison = TRUE)
SYNOPSIS: [TBD]

use_flag_object()
SIGNATURE: int use_flag_object (boolean = TRUE)
TRAITS: obscure function. not recommended

set_size()
SIGNATURE: int set_size (const size_t n)
SYNOPSIS: allow for manually defining the size of the string.
DESCRIPTION:
this function sets the size of the string to "n", which must be less than or equal to the capacity size of the string. it puts a '\0' at the end of the new size. Here is an example of its usage:
string_o s (80);
s = "Los ";
char *ptr = (char *) ((const char *) s);
z_bcopy ((u_char *) ptr, (const u_char *) "Angeles", 7);
s.set_size (11);
TRAITS: should be used sparingly, only when absolutely necessary

force_size()
SIGNATURE: int force_size (size_t nbytes)
SYNOPSIS:
resizes the internal data buffer to "nbytes". this does a "resize(nbytes, TRUE, TRUE);", then, if the string is in binary mode, sets the internal size value to nbytes. This allows the user to manually control the size of the string, overriding any internal checks.
This is often useful if the string object is in binary mode. If so, it is almost impossible to append a null-terminator symbol ('\0') to the string.
EXAMPLE:
string_o s; s.setmode_binary(); s = ""; s += "AB"; s.force_size(3); s[2] = '\0'; // without force_size(), this does nothing

resize()
SIGNATURE: int resize (const size_t new_size, boolean use_exact = FALSE, boolean save_data = TRUE)
SYNOPSIS: resizes the internal data buffer to "new_size", if the new size is different from the existing size.
PARAMETERS

new_size: the size of the data buffer the string object is to have. there is no guarantee that resize() will make it this size exactly. "new_size" should be a power of 2 (eg, 2, 4, 8, 16, ..). If this function succeeds, the new buffer size will be at least the value "new_size".

use_exact: use exactly the number of bytes specified by "new_size" (even so, there is an extra pad of 4 bytes). if this is FALSE, "new_size" will be used as the basis for the new buffer size, which can be up to double that specified.

save_data: if TRUE, the current contents are preserved. if FALSE, it will be lost.

DESCRIPTION:
this is an auxiliary function that is intended to be used internally by other string class member functions. The current contents of the object is preserved (copied to the new buffer).

reset()
SIGNATURE: int reset ()
SYNOPSIS:
sets the string object to at-construction state (default c'tor). all internal data is wiped out and all flags reset.

set()
SIGNATURE: int set (char *ptr, const size_t n)
SYNOPSIS:
sets the internal buffer to "ptr",a and the size and capacity to "n". see the constructor "string_o (char *rhs, const size_t n, boolean istext = FALSE)" for more information
DESCRIPTION: this is mainly for setting up the string object to recieve binary data.

set_char()
SIGNATURE: int set_char (const size_t, const char)
SYNOPSIS: set a value in the data buffer to the input char
DESCRIPTION: this is equivalent to the "[]" operator.

int_to_str()
SIGNATURE: int int_to_str (long int n, int base, int *pi)
SYNOPSIS:
converts a number of integer type to a string. The resultant string is stored into the current object. This routine is partially patterned after the layer-00 "z_xxxint_to_str()" series of functions. It was made in response to the need for an easy (easier) way to convert a number to a string_o, on Wed Aug 1, 2012.
PARAMETERS

n: the number to convert to a string. Note that base is irrelevant to an int type - the internal format is "baseless".

base: the 'base' to use:
2: binary
8: octal
10: decimal (the default)
16: hexadecimal
Only base 10 is currently supported. This parameter, as of this writing (2012), is a placeholder for future implementation.

pi: [optional] error indicator [output] variable. values:
0: success

TRAITS: only base 10 is currently (2012) implemented (sorry).

set_char()
SIGNATURE: int set_char (const char c, int *pi = NULL)
SYNOPSIS: set the data buffer to the input char
PARAMETERS

c: the character to convert as a string. It can have any

value a character can hold [1..255].

pi: [optional] error indicator [output] variable. values:
0: success
zErr_Param_BadVal: 'c' is '&bs;0'

DESCRIPTION: this function provides a quick and easy way to convert a single character to a Z Directory string object.
RETURNS:
0: success
-1: error (c is '&bs;0')

append_char()
SIGNATURE: int append_char (const char c, int *pi = NULL)
SYNOPSIS: append character 'c' to end of the string
PARAMETERS

c: the character to append to the object's contents. cannot be '&bs;0'.

pi: [optional] error indicator [output] variable. values:
0: success
zErr_Param_BadVal: 'c' is '&bs;0'
zErr_NotInitialized: the string object has not been set to anything.
zErr_Resource_TooSmall: there is no room in the buffer to add a character

DESCRIPTION:
the string must have the capacity to recieve another character. after this operation, the length of the string is increased by 1. a '&bs;0' capping character is added at the end of the string.
RETURNS:
0: character successfully added;
-1: failure (no room in the buffer to add it)

toupper()
SIGNATURE: void toupper ()
SYNOPSIS: convert entire string to upper-case
DESCRIPTION: this is a convenience function

tolower()
SIGNATURE: void tolower ()
SYNOPSIS: conversion of all characters in the string to lowercase
DESCRIPTION: this is a convenience function

trim()
SIGNATURE: int trim ()
SYNOPSIS: removes trailing spaces, tabs, newlines from the current data (the internal text-contents)

pre_trim()
SIGNATURE: int pre_trim ()
SYNOPSIS: cull all preceding whitespace
DESCRIPTION: this sucks out like a vacuum cleaner any ' ', '\t', '\n', or '\r' characters at the start of the string.

full_trim()
SIGNATURE: int full_trim ()
SYNOPSIS: does a trim() and a pre_trim().
DESCRIPTION: this function is simply a convenience, 2 functions rolled into 1.

enclose()
SIGNATURE: int enclose (char ch_beg, char ch_end = '\0', int *pi = NULL)
SYNOPSIS:
wraps the current text in starting and ending characters specified by input parameters "ch_beg" and "ch_end", respectfully.
DESCRIPTION:
this routine allows you to wrap the current contents of the string object (which must be set!) with any pair of characters. if the characters are part of an approved standard set of "wrapper characters" (does not include 2Pac), you can omit the 2nd parameter, and it will default to the correct closing value. if you do not select an ending char, and the starting character is out of the list below, the ending character will be automatically supplied (use '\0' if you want to use the "pi" ooutput error var and hence need to supply something for the 2nd parameter). here's our choice of official starting and ending chars: | |
/ /
> <
< >
" "
( )
[ ]
{ }
' '
: :
- -
$ $
RETURNS:
0: success
-1: error: either bad input character[s], or string object is not initted

substring()
SIGNATURE: string_o substring (const size_t a, const size_t b) const
SYNOPSIS: return a string-within-a-string
DESCRIPTION:
finds and returns a sub-string given by the specified index offsets, from position "a" to position "b". note that "b" is not a length specifier, but an actual index into the character array. example:
"substring(0,0)" gets the first character (as a string)
"substring(2,5)" gets the 3rd through 6th characters (inclusive)
RETURNS:
[string_o] - copy of the specified string, if success;
"badstring" - error: 'b' < 'a', or 'a' & 'b' both 0

search_destroy()
SIGNATURE: int search_destroy (const string_o &s, int *pe, enum search_mode = mode z_Find_First, const size_t n = 0)
SYNOPSIS: find and delete the string specified by "s" (if found)
DESCRIPTION:
this member function looks for the nth occurance of a sub-string, and if found, extracts it. The function's return value indicates success (0) or failure (-1). the parameters are the same as used in "find()".
RETURNS:
0: success
1: not found [/no occurances found]
-1: error

search_replace()
SIGNATURE: int search_replace (const string_o &target, const string_o &repl, enum search_mode = z_Find_First, int *pi = NULL, const size_t nb = 0)
SYNOPSIS: search for a given string and replace it with another string (if found).
PARAMETERS

target: the block of text (the "substring") to search for in the current string object.

repl: the text that is to replace any ocurrance(s) of "target" in the current object, if 'target' is found.

search_mode: "search mode" - defines from where the search is to start and how many ocurrances are to be updated. the choices:
z_Find_First - replace the first ocurrance. At most only the first item will be replaced (if found). Any and all subsequent matches will be ignored.
z_Find_Next
z_Find_Last - replace only the last ocurrance. At most only the last item will be replaced (if found). Thus the number of updated matches witll be 0 or 1. Any and all other matches (before the last) will be ignored.
z_Find_All

pi: [optional] error indicator [output] variable. values:
0: success
1: user input parameter error
2: memory allocation error (internal)

nb: index-position where a search is to start. This is used if 'search_mode' is "z_Find_Next". This will replace any matches after 'nb' characters.

DESCRIPTION:
this is simiar to "search_destroy()". For example:
#include "z_string.h"
void main ()
{
    int ie;
    string_o s = "I want to meet her.\n";
    s.search_replace ("meet", "kiss", string_o::z_Find_First, &ie);
    std::cout << s << std::endl;
}


This would print:

I want to kiss her.
extract()
SIGNATURE: int extract (const size_t idx0, const size_t idx1)
SYNOPSIS: deletes characters between the specified positions
PARAMETERS

idx0: starting index of the string to extract (inclusive)

idx1: ending index of the string to extract (inclusive)

DESCRIPTION:
surgery. this takes out the characters at the position given specified input parameters. the position of the characters must exist; e.g., if there are characters beyond the end of the buffer, this entire operation fails and the string is unaffected.

operator +=()
SIGNATURE: int operator += (const string_o &that)
SYNOPSIS: add (concatenate) "that" to the current object

operator +()
SIGNATURE: string_o operator + (const string_o &rhs)
SYNOPSIS: concatenate 2 string objects
DESCRIPTION: this adds "rhs" to the current object. the result is returned as a new string instance

operator == (string_o)
SIGNATURE: int operator == (const string_o &me, const char *s)
DESCRIPTION:
this is a "friend" function (not a member of the string_o class). it compares "me" with char array "s". see the "==" operator member function for details.

operator == (string_o)
SIGNATURE: int operator == (const char *, const string_o &)
SYNOPSIS: compares a character array to a string object
DESCRIPTION: this global-scope friend function is provided for ease of writing code to compare strings

operator == (string_o)
SIGNATURE: int operator != (const string_o &me, const char *s)
SYNOPSIS: compare string object "me" to char array "s" for inequality
DESCRIPTION: this global-scope friend function is provided for ease of writing code to compare strings

operator +()
SIGNATURE: string_o operator + (const char *s, const string_o &me)
SYNOPSIS: concatenates char buffer "s" with string object "me"
DESCRIPTION: provides commutative string concatenatation capability ([char *] + string_o; string_o + [char *])

bad_reference()
SIGNATURE: static const string_o &bad_reference ()
SYNOPSIS: standard "funtion" for testing if function succeeded
DESCRIPTION:
this is used to compare a string_o return value from any string_o member function that returns a string object. by comparing the address of the return object to that of bad reference, if they are the same, the member function failed.

note.
The following note section is OLD and MAY BE OBSOLETE:
[BEGIN DEPRECATED ASPECT]
A problem with manually setting the mode is that when you copy one string into another, the recieving string settings inherit that of the copied string. This is particularly annoying when you need a string in binary mode, then initialize it to empty:

    string_o s;
    s.setmode_binary();
    s = "";                 // now s set to text mode

To prevent this, set the sticky mode, so that whatever mode the string is in, it stays there (unless you explictily call another setmode..() function). If in "sticky mode" (zSTRF_STICKY is TRUE), then once you set it to [say] binary mode, it stays in that mode. With stickyness on, assignment operators will only copy the data:

    string_o s;
    s.setmode_sticky();     // don't allow automatic mode changes
    s.setmode_binary();     // this still works - now in binary mode
    s = "";                 // s stays in binary  mode; length is 0

[END DEPRECATED ASPECT]

limitations.
This class does not support locales or multi-byte format, nor multiple-font sections.

bugs.
the interface for doing "string_o.find ([item], [int *], string_o::z_Find_Next)" is awkward, and can probably be improved upon.

history.

Fri 02/14/1992: incorporating ideas from NIH string class
Tue 06/20/1995: cleaning up for const correctness, canonical-ness
Sat 06/24/1995: more cleanup; build extended main test driver
Sun 06/25/1995: current test driver fixed up
Thu 11/16/1995: adding substring searches
??? 11/17/1995: operator >> created
Tue 11/28/1995: string_o::setup() - changed input parameter 'rhs'
??? 06/11/1996: size_t string_o::find() created
??? 06/12/1996: string_o c'tor bug; forgot to check if 'rhs' could be null
Tue 06/25/1996: string_o::search_destroy() - created
Mon 09/02/1996: 14:41: file got corrupted due to careless editing
Sun 11/17/1996: added "resize()"
Sat 11/16/1996: string_o::set(): 'n' type sig changed, u_int -> size_t
Thu 11/28/1996: string_o::set(): changing semantics; file restored
Sun 12/15/1996: string_o::cmp() created
Fri 12/06/1997: {10:45:40 EST} created member function set_size()
Tue 12/09/1997: speed optimization
??? 12/10/1997: compute_bufsize(), set_char() - created
Thu 12/11/1997: string_o::append_char() created; big clean-up operation
Fri 12/12/1997: compute_bufsize() changed return value; resize() - added flag
Thu 12/18/1997: c'tor: added "rhs_alloc" var; init() created; core dumps on HP-UX
Wed 12/24/1997: simplifying: no more separate "binary mode" code
Sun 01/04/1998: string_o::search_destroy() added "z_Find_All" case
Mon 01/05/1998: string_o::search_replace() created
??? 01/20/1998: compute_bufsize() upped the # bytes for a trailer, from 2 to 4
Fri 03/20/1998: 09:43:53 EST: "string_o::cmp_nchars()" - created
??? 04/04/1998: implmented "find last" mode
Fri 11/06/1998: copy(): check for "that.m_s" buffer == null
Thu 05/30/2002: new #define naming conventions ("zos_", "zcc_")
Thu 06/06/2002: new validation code (for find, extract, compare, etc.); bug fixes
??? 09/05/2002: bug fixed in string_o::find(.. z_Find_Last) {--AG}
??? 01/21/2003: string_o::search_replace() bug fix {--AG}
Sun 09/14/2003: added "z_numstr()" & "z_realstr()"
Fri 09/19/2003: string_o::search_replace() bug patch, when "replacement" == ""
Sun 04/04/2011: improving searches for binary mode
Mon 04/11/2011: added member function setmode_sticky()
Wed 08/31/2011: added member function enclose()
Wed 12/14/2011: renamed find_n_extract() -> search_destroy()