name: SysString
synopsis:

>     g++ [flags ...] file ... -l /isip/tools/lib/$ISIP_BINARY/lib_system.a

>     #include <SysString.h>

>     SysString(long capacity = DEF_CAPACITY);
>     SysString(const SysString& arg);
>     SysString(const unichar* data);
>     SysString(byte* data, SysChar::ENCODE encoding = SysChar::DEF_ENCODE);
>     boolean assign(const SysString& arg);
>     boolean insert(const SysString& str, long index);
>     boolean replace(const SysString& str, long index);

quick start:

>     SysString str1((byte*)"This is ISIP");
>     SysString str2(L"software");
>     SysString str3(100);
>     SysString str4(str2);

>     str2.assign(L" software");
>     if (str2.length() != 9) {
>       Console::put(L"Error in re-assign unichar");
>     }

>     str2.assign(str1);
>     str3.assign(L" public-domain ");
>     str4.assign(L" Foundation classes");

>     str2.insert(str3, 99);
>     str2.debug(L"str2");

>     if (str2.ne(L"This is ISIP public-domain ")) {
>       Console::put(L"Error in insert");
>     }

>     str2.insert(str4, 9999);
>     str2.debug(L"str2");

>     if (str2.ne(L"This is ISIP public-domain  Foundation classes")) {
>       Console::put(L"Error in insert");
>     }

description:
The SysString class fills the void found in ANSI C for a very common data type: a string of characters. Our SysString class is inherently multi-lingual. It is a set of SysChar objects. The SysString class abstracts the operating-system-specific wide character functions. It also prevents the programmer from having to manipulate buffers of memory; this is all handled automatically. The user needs only to reference a single SysString object, and passing a SysString object to a method is as simple as passing an Integer.
dependencies:

- SysChar
- File

public constants:

- define the class name:

      static const SysString CLASS_NAME = L"SysString";

- define miscellaneous constants:

      static const long MAX_LENGTH = (long)1024;

      static const long BIG_BUFFER_LENGTH = (long)8192;

      static const long STATIC_BUFFER_SIZE = (long)16;

- define special strings:

      static const unichar NULL_STRING[] = L"";

      static const SysString NULL_PTR = L"NULL";

- define text corresponding to boolean values:

      static const SysString BOOL_TRUE = L"true";

      static const SysString BOOL_FALSE = L"false";

- text corresponding to debug values:

      static const SysString DBG_NONE = L"none";

      static const SysString DBG_BRIEF = L"brief";

      static const SysString DBG_DETAILED = L"detailed";

      static const SysString DBG_ALL = L"all";

- text corresponding to compare values:

      static const SysString CMP_EQUAL = L"equal";

      static const SysString CMP_LESSER = L"lesser";

      static const SysString CMP_GREATER = L"greater";

- text corresponding to file mode values:

      static const SysString MODE_READ_ONLY = L"read only";

      static const SysString MODE_READ_PLUS = L"read plus";

      static const SysString MODE_WRITE_ONLY = L"write only";

      static const SysString MODE_WRITE_PLUS = L"write plus";

      static const SysString MODE_APPEND_ONLY = L"append only";

      static const SysString MODE_APPEND_PLUS = L"append plus";

- text corresponding to file type values:

      static const SysString TYPE_TEXT = L"text";

      static const SysString TYPE_BINARY = L"binary";

- text corresponding to file binary mode values:

      static const SysString BMODE_NATIVE = L"native";

      static const SysString BMODE_SWAP = L"swap";

      static const SysString BMODE_BIG_ENDIAN(L"big_endian");

      static const SysString BMODE_LITTLE_ENDIAN(L"little_endian");

- text corresponding to SysChar encode values:

      static const SysString ENCODE_ASCII = L"ascii";

      static const SysString ENCODE_UTF8 = L"utf8";

      static const SysString ENCODE_UTF16 = L"utf16";

- text corresponding to MemoryManager modes:

      static const SysString MMGR_MODE_OPTIMIZE = L"optimize";

      static const SysString MMGR_MODE_TRACK = L"track";

- define small state machine for symbolPad:

      static const long STATE_PAD_NOSPACE = (long)0;

      static const long STATE_PAD_SPACE = (long)1;

- define format for debug method output:

      static const SysString DBG_FORMAT_0 = L"(";

      static const SysString DBG_FORMAT_1 = L">= ";

      static const SysString DBG_FORMAT_2 = L") \"";

      static const SysString DBG_FORMAT_3 = L"\"";

- define format for debugStr output:

      static const SysString DBGS_FORMAT_0 = L"<";

      static const SysString DBGS_FORMAT_1 = L"::";

      static const SysString DBGS_FORMAT_2 = L"> ";

      static const SysString DBGS_FORMAT_3 = L"= ";

- define 8-bit version of the default format strings (for efficiency):

      static const char DEF_FMT_VOIDP_8BIT[] = "%p";

      static const char DEF_FMT_ULONG_8BIT[] = "%lu";

      static const char DEF_FMT_ULLONG_8BIT[] = "%llu";

      static const char DEF_FMT_LONG_8BIT[] = "%ld";

      static const char DEF_FMT_LLONG_8BIT[] = "%lld";

      static const char DEF_WFMT_FLOAT_8BIT[] = "%.6g";

      static const char DEF_RFMT_FLOAT_8BIT[] = "%g";

      static const char DEF_RFMT_DOUBLE_8BIT[] = "%lg";

      static const char DEF_WFMT_DOUBLE_8BIT[] = "%.17le";

- define the default value(s) of the class data:

      static const long DEF_CAPACITY = 0;

      static const SysString DEF_VALUE = L"";

- define default arguments to methods:

      static const SysString DEF_FMT_VOIDP = L"%p";

      static const byte DEF_TERM_BYTE = (byte)NULL;

      static const unichar DEF_TERM = (unichar)NULL;

      static const long DEF_POS = Integral::NO_POS;

error codes:

- error code indicating SysString class general error:

      static const long ERR = 1300;

protected data:

- array of SysString characters:

      unichar* value_d;

- capacity of ths SysString:

      long capacity_d;

- debug level:

      static Integral::DEBUG debug_level_d;

required public methods:

- static methods:

      static const SysString& name();

      static boolean diagnose(Integral::DEBUG debug_level);

- debug methods:

      static boolean setDebug(Integral::DEBUG level);

      boolean debug(const unichar* msg) const;

- destructor/constructor(s):

      ~SysString();

      SysString(long capacity = DEF_CAPACITY);

      SysString(const SysString& arg);

- assign methods:

      boolean assign(const SysString& arg);

- operator= methods:

      SysString& operator=(const SysString& arg);

- i/o methods:

      i/o methods are omitted because SysString can not write itself to
      an sof file

- equality methods:

      boolean eq(const SysString& value, boolean case_sensitive = true) const;

- memory management methods: the new and delete methods are omitted here since only classes at the math library level and above are required to overide new and delete

      boolean clear(Integral::CMODE ctype = Integral::DEF_CMODE);

class-specific public methods:

- constructors:

      SysString(const unichar* data);

      SysString(const byte* data, SysChar::ENCODE encoding = SysChar::DEF_ENCODE);

- assign methods:

      boolean assign(const unichar* data);

      boolean assign(const byte* data, long max_size = BIG_BUFFER_LENGTH, SysChar::ENCODE encoding = SysChar::DEF_ENCODE);

- numeric conversion assignment methods:

      boolean assign(const void* arg);

      boolean assign(boolean arg);

      boolean assign(const byte arg);

      boolean assign(unichar arg);

      boolean assign(const ushort arg);

      boolean assign(const ulong arg);

      boolean assign(const ullong arg);

      boolean assign(const short arg);

      boolean assign(const long arg);

      boolean assign(const llong arg);

      boolean assign(const float arg);

      boolean assign(const double arg);

      template <class TIntegral> boolean assign(const SysComplex<TIntegral>& arg);

- define versions of the assign methods that take format strings:

      boolean assign(const SysString& data, const unichar* fmt);

      boolean assign(const unichar* data, const unichar* fmt);

      boolean assign(const byte* data, const unichar* fmt, long max_size = BIG_BUFFER_LENGTH, SysChar::ENCODE encoding = SysChar::DEF_ENCODE);

- numeric conversion assignment methods:

      boolean assign(const void* arg, unichar* fmt);

      boolean assign(boolean arg, const unichar* fmt);

      boolean assign(const byte arg, unichar* fmt);

      boolean assign(unichar arg, const unichar* fmt);

      boolean assign(const ushort arg, unichar* fmt);

      boolean assign(const ulong arg, unichar* fmt);

      boolean assign(const ullong arg, unichar* fmt);

      boolean assign(const short arg, unichar* fmt);

      boolean assign(const long arg, unichar* fmt);

      boolean assign(const llong arg, unichar* fmt);

      boolean assign(const float arg, unichar* fmt);

      boolean assign(const double arg, unichar* fmt);

      template <class TIntegral> boolean assign(const SysComplex<TIntegral>& arg, const unichar* fmt);

- enum assignment methods:

      boolean assign(Integral::DEBUG arg);

      boolean assign(Integral::COMPARE arg);

      boolean assign(File::MODE arg);

      boolean assign(File::BMODE arg);

      boolean assign(File::TYPE arg);

      boolean assign(SysChar::ENCODE arg);

      boolean assign(MemoryManager::MODE arg);

- special assignment methods:

      boolean swap(SysString& arg);

- relational and logical methods:

      Integral::COMPARE compare(const SysString& str) const;

      Integral::COMPARE compare(const SysString& str1, const SysString str2) const;

      Integral::COMPARE compare(const unichar* str) const;

      Integral::COMPARE comparePartial(const SysString& arg, long arg_offset, long num_elements, long offset) const;

      Integral::COMPARE comparePartial(const unichar* arg, long arg_offset, long num_elements, long offset) const;

      boolean eq(const unichar* value, boolean case_sensitive = true) const;

      boolean ne(const SysString& vector, boolean case_sensitive = true) const;

      boolean ne(const unichar* value, boolean case_sensitive = true) const;

      boolean gt(const SysString& vector) const;

      boolean gt(const unichar* value) const;

      boolean lt(const SysString& vector) const;

      boolean lt(const unichar* value) const;

      boolean ge(const SysString& vector) const;

      boolean ge(const unichar* value) const;

      boolean le(const SysString& vector) const;

      boolean le(const unichar* value) const;

      long numEqual(unichar test_value) const;

      long numNotEqual(unichar test_value) const;

- indexing methods:

      unichar& operator()(long index);

      const unichar& operator()(long index) const;

- automatic type conversion methods:

      operator byte*() const;

      operator unichar*() const;

- numeric conversion methods:

      boolean get(void*& arg) const;

      boolean get(boolean& arg) const;

      boolean get(byte& arg) const;

      boolean get(unichar& arg) const;

      boolean get(ushort& arg) const;

      boolean get(ulong& arg) const;

      boolean get(ullong& arg) const;

      boolean get(short& arg) const;

      boolean get(long& arg) const;

      boolean get(llong& arg) const;

      boolean get(float& arg) const;

      boolean get(double& arg) const;

      template <class TIntegral> boolean get(SysComplex<TIntegral>& arg) const;

      boolean get(SysChar& arg) const;

- size-related methods:

      long length() const;

      long memSize() const;

      boolean setCapacity(long cap);

- array-oriented methods:

      long getBuffer(unichar* buffer, long max) const;

      long getBuffer(byte* buffer, long max, SysChar::ENCODE encoding = SysChar::DEF_ENCODE) const;

      boolean substr(SysString& str, long offset, long num_elements = Integral::NO_POS) const;

- insert/replace a substring into the string methods:

      boolean insert(const SysString& str, long index);

      boolean insert(const unichar* str, long index);

      boolean replace(const SysString& str, long index);

      boolean replace(const unichar* str, long index);

      boolean replace(const SysString& pattern, const SysString& new_stuff);

      boolean replaceAll(const SysString& pattern, const SysString& new_stuff);

      boolean deleteRange(long offset, long num_elements);

- append to the end of the string methods:

      boolean concat(const SysString& str);

      boolean concat(const SysString& str1, const SysString& str2);

      boolean concat(const unichar* buf);

      boolean concat(unichar character);

- numeric concatenation methods:

      boolean concat(const void* arg);

      boolean concat(boolean arg);

      boolean concat(const byte arg);

      boolean concat(const ushort arg);

      boolean concat(const ulong arg);

      boolean concat(const ullong arg);

      boolean concat(const short arg);

      boolean concat(const long arg);

      boolean concat(const llong arg);

      boolean concat(const float arg);

      boolean concat(const double arg);

      template <class TIntegral> boolean concat(const SysComplex<TIntegral>& arg);

- append to the end of the string methods with print format:

      boolean concat(const SysString& str, const unichar* fmt);

      boolean concat(const unichar* buf, const unichar* fmt);

      boolean concat(unichar character, const unichar* fmt);

- numeric concatenation methods with print format:

      boolean concat(const void* arg, const unichar* fmt);

      boolean concat(boolean arg, const unichar* fmt);

      boolean concat(const byte arg, const unichar* fmt);

      boolean concat(const ushort arg, const unichar* fmt);

      boolean concat(const ulong arg, const unichar* fmt);

      boolean concat(const ullong arg, const unichar* fmt);

      boolean concat(const short arg, const unichar* fmt);

      boolean concat(const long arg, const unichar* fmt);

      boolean concat(const llong arg, const unichar* fmt);

      boolean concat(const float arg, const unichar* fmt);

      boolean concat(const double arg, const unichar* fmt);

      template <class TIntegral> boolean concat(const SysComplex<TIntegral>& arg, const unichar* fmt = DEF_FMT_DOUBLE);

- trim away characters from string methods:

      boolean trim();

      boolean trim(const SysString& chars);

      boolean trim(const unichar* chars);

      boolean trimLeft();

      boolean trimLeft(const SysString& chars);

      boolean trimLeft(const unichar* chars);

      boolean trimRight();

      boolean trimRight(const SysString& chars);

      boolean trimRight(const unichar* chars);

- string case conversion methods:

      boolean toUpper();

      boolean toLower();

      boolean toMixed();

      boolean toMixed(const SysString& sep_chrs);

- string search methods:

      long firstStr(const unichar* str, long start = Integral::NO_POS) const;

      long firstStr(const SysString& str, long start = Integral::NO_POS) const;

      long lastStr(const unichar* str, long end = Integral::NO_POS) const;

      long lastStr(const SysString& str, long end = Integral::NO_POS) const;

      long firstChr(const unichar* chrs, long start = Integral::NO_POS) const;

      long firstChr(const SysString& chrs, long start = Integral::NO_POS) const;

      long firstChr(unichar chr, long start = Integral::NO_POS) const;

      long lastChr(const unichar* chrs, long end = Integral::NO_POS) const;

      long lastChr(const SysString& chrs, long end = Integral::NO_POS) const;

      long lastChr(unichar chr, long end = Integral::NO_POS) const;

      long firstNotChr(const SysString& chrs, long start = Integral::NO_POS) const;

      long firstNotChr(unichar chr, long start = Integral::NO_POS) const;

      long lastNotChr(const SysString& chrs, long end = Integral::NO_POS) const;

      long lastNotChr(unichar chr, long end = Integral::NO_POS) const;

      long firstAlnum(long start = Integral::NO_POS) const;

      long firstAlpha(long start = Integral::NO_POS) const;

      long firstDigit(long start = Integral::NO_POS) const;

      long firstLower(long start = Integral::NO_POS) const;

      long firstPrint(long start = Integral::NO_POS) const;

      long firstPunct(long start = Integral::NO_POS) const;

      long firstSpace(long start = Integral::NO_POS) const;

      long firstUpper(long start = Integral::NO_POS) const;

      long lastAlnum(long end = Integral::NO_POS) const;

      long lastAlpha(long end = Integral::NO_POS) const;

      long lastDigit(long end = Integral::NO_POS) const;

      long lastLower(long end = Integral::NO_POS) const;

      long lastPrint(long end = Integral::NO_POS) const;

      long lastPunct(long end = Integral::NO_POS) const;

      long lastSpace(long end = Integral::NO_POS) const;

      long lastUpper(long end = Integral::NO_POS) const;

      long firstNotAlnum(long start = Integral::NO_POS) const;

      long firstNotAlpha(long start = Integral::NO_POS) const;

      long firstNotDigit(long start = Integral::NO_POS) const;

      long firstNotLower(long start = Integral::NO_POS) const;

      long firstNotPrint(long start = Integral::NO_POS) const;

      long firstNotPunct(long start = Integral::NO_POS) const;

      long firstNotSpace(long start = Integral::NO_POS) const;

      long firstNotUpper(long start = Integral::NO_POS) const;

      long lastNotAlnum(long end = Integral::NO_POS) const;

      long lastNotAlpha(long end = Integral::NO_POS) const;

      long lastNotDigit(long end = Integral::NO_POS) const;

      long lastNotLower(long end = Integral::NO_POS) const;

      long lastNotPrint(long end = Integral::NO_POS) const;

      long lastNotPunct(long end = Integral::NO_POS) const;

      long lastNotSpace(long end = Integral::NO_POS) const;

      long lastNotUpper(long end = Integral::NO_POS) const;

- count tokens methods:

      long countTokens() const;

      long countTokens(unichar delimiter = SysChar::SPACEC) const;

      long countTokens(const SysString& delimiters) const;

- count delimiters methods:

      long countDelimiters() const;

      long countDelimiters(unichar delimiter = SysChar::SPACEC) const;

      long countDelimiters(const SysString& delimiters) const;

- string tokenize methods:

      boolean tokenize(SysString& sub, long& pos) const;

      boolean tokenize(SysString& sub, long& pos, unichar delim) const;

      boolean tokenize(SysString& sub_a, long& pos, const SysString& delim) const;

      boolean symbolPad(const SysString& symbols);

- debug string creation methods:

      boolean debugStr(const SysString& class_name, const unichar* message_a, const unichar* variable_name, const SysString& variable_value);

      boolean debugStr(const SysString& class_name, const unichar* message_a, const unichar* variable_name);

      boolean debugStrPrefix(const SysString& class_name, const unichar* message_a);

- empty string creation methods:

      static const SysString& getEmptyString();

private methods:

- general string search methods:

      long firstChar(long start, boolean (SysChar::*method) (void) const) const();

      long lastChar(long end, boolean (SysChar::*method) (void) const) const();

      long firstNotChar(long start, boolean (SysChar::*method) (void) const) const();

      long lastNotChar(long end, boolean (SysChar::*method) (void) const) const();

- memory allocation methods:

      boolean allocateMem();

      boolean freeMem();

      boolean growMem(long new_size);

- wrap the system wchar methods:

      static ulong isip_wcslen(const unichar* ws);

      static long isip_wcscmp(const unichar* ws1, const unichar* ws2);

      static long isip_wcsncmp(const unichar* ws1, const unichar* ws2, ulong n);

      static unichar* isip_wcschr(const unichar* haystack, const unichar needle);

      static unichar* isip_wcscat(unichar* ws1, const unichar* ws2);

      static unichar* isip_wcscpy(unichar* ws1, const unichar* ws2);

      static unichar* isip_wcsncpy(unichar* ws1, const unichar* ws2, ulong n);

      static int isip_wctomb(char* s, const unichar wchar);

      static unichar* isip_wcsstr(const unichar* haystack, const unichar* needle);

      static unichar* isip_wcstok(unichar* ws, const unichar* delim,unichar** ptr);

      static unichar* isip_fgetws(unichar* s, int n, FILE* stream);

      static long isip_fputws(const unichar* s, FILE* stream);

      static wint_t isip_fgetwc(FILE* stream);

      static wint_t isip_fputwc(wint_t wc, FILE* stream);

- friend functions:

      friend boolean File::put(const SysString& str);

      friend boolean File::put(const SysChar chr);

      friend boolean File::get(SysString& str, long len);

      friend boolean File::get(SysChar& chr);

examples:

- This example shows how to do numeric conversion assignments:

      SysString num;

      // setup temporary variables
      //
      byte dbyte = (long)27;
      byte dbyte_v;

      short dshort = (long)27;
      short dshort_v;

      void* dvoidp = (void*)27;
      void* dvoidp_v;

      // test the byte conversions
      //
      num.assign(dbyte);
      num.get(dbyte_v);

      if (dbyte != dbyte_v) {
        Console::put(L"Error in assign(byte)");
      }

      // test the short conversions
      //
      num.assign(dshort);
      num.get(dshort_v);

      if (dshort != dshort_v) {
        Console::put(L"Error in assign(short)");
      }

      // test the pointer conversions
      //
      num.assign(dvoidp);
      num.get(dvoidp_v);

      if (dvoidp != dvoidp_v) {
        Console::put(L"Error in assign(void*)");
      }

- This example shows how to tokenize a string and count the number of tokens:

      // declare a string
      //
      SysString str;

      // assign value
      //
      str.assign(L"   oscar had a heap of apples ");

      // declare local variable
      //
      long pos = 0;

      // declare a delimiter string
      //
      SysString delim(L" ");

      // tokenize the string into sub strings
      //
      SysString sub_str;
      while (str.tokenize(sub_str, pos, delim)) {
        sub_str.debug(L"token");
      }

      // count the number of tokens
      //
      long tok = str.countTokens(L" ");

      if (tok != 6) {
        Console::put(L"Error in countTokens");
      }

notes:

- The SysString class is modeled after Java's StringBuffer class. The capacity parameter is stored within the SysString object. It is automatically managed by all these methods, but the programmer can exert direct control if desired. The getChars methods are provided as a crutch, they should not be used in most circumstances. All methods in this class operate on the string itself - input SysString objects are left unchanged.
- While friend functions are generally discouraged in the ISIP environment, they are used in the SysString class to isolate implementation details. Currently, wide character support varies greatly between different operating systems, so we abstract a core group of wide character functions in this class as private methods. The file class also needs to access these wrappers directly for I/O purposes, though, so the friend directive is used.