Copyright (C) 2001 Günter Woigk
    kio@little-bat.de

    This file is free software

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  

    Permission to use, copy, modify, distribute, and sell this software and
    its documentation for any purpose is hereby granted without fee, provided
    that the above copyright notice appear in all copies and that both that
    copyright notice and this permission notice appear in supporting
    documentation, and that the name of the copyright holder not be used
    in advertising or publicity pertaining to distribution of the software
    without specific, written prior permission.  The copyright holder makes no
    representations about the suitability of this software for any purpose.
    It is provided "as is" without express or implied warranty.

    THE COPYRIGHT HOLDER DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
    INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
    EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY SPECIAL, INDIRECT OR
    CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
    DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
    TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
    PERFORMANCE OF THIS SOFTWARE.


    ---------------------------------------------------------------------------


    Kio's final° String Library        version 0.92    last modified 2001-11-17
    ---------------------------

    °) up to now, all my string libraries (~5 to 10 of them) were final <:-]
    


    Description
    -----------

  o No tags before or behind the text
    => full substring capability 
    => Assignments to substrings possible; e.g.:  a$[10..15] = "anton"

  o Max. text length = 0x7FFFFFFE characters

  o All character codes [0...255] allowed

  o Text sharing for fast passing of text values to/from functions

  o Ad-hoc string descriptors for const. text literals for fast passing of text values



    Quirks
    ------

  o Due to text sharing and ad-hoc string descriptors, strings can be 'shared' or 'dirty'.
    Then the contents of the text must not me modified. => use String::MakeWritable()
    This only applies to writing to the text as in a$[123]="x" oder a$[10..15] = "anton"
    It does not apply to overwriting the string itself as in a$="anton"; a$=b$; or a$=LeftString(b$,n).

  o Ad-hoc string descriptors do not protect their text contents, which still can be modified from 
    'outside' easily:
  
    char b[]="anton";
    String a(b);            // =>  a = "anton"
    b[0]="X";               // =>  a = "Xnton"
 


    Member Functions - Overview (simplified)
    ----------------------------------------

  o String Creators
        String ( )                                  empty String
        String ( void*, length )                    String from arbitrary data
        String ( length )                           String of given length, not cleared
        String ( length, fillchar )                 String of given length, cleared
        
  o Automatic Type Conversion Creators
        String ( char* )                            String from c-style string
        String ( uchar* )                           String from Pascal-style string
        String ( char )                             String from char

  o Operators
        String& operator=   ( text )                Assignment;         text = string, c-string, int, char, etc.
        String  operator+   ( text )                Text concatenation; text = string, c-string, int, char, etc.
        String& operator+=  ( text )
        String  operator*   ( times )               Text repetition
        String  operator*=  ( times )
        bool    operator==  ( text )                Comparison; also: <, >, <=, >=, !=

  o Functions
        String  SubString   ( long a, long e )      Substring; indexes start with 0
        String  MidString   ( long a, long n )      n characters from the middle
        String  MidString   ( long a )              trailing string starting at position a
        String  LeftString  ( long n )              n characters from the left
        String  RightString ( long n )              n characters from the right

        String  NumString   ( number )              String from integer or float
        String  HexString   ( number, digits )
        String  SpaceString ( length, fillchar )

        long    Len         ( ) 
        uchar&  operator[]  ( index )               note: indexes start with 0

        bool    IsWritable  ( )                     test, whether text is writable; that is: not shared and not dirty
        void    MakeWritable( )                     make text writable

        void    ToUpper     ( )
        void    ToLower     ( )
        void    Replace     ( oldchar, newchar )

        uchar*  PString     ( )                     get Pascal-style string from String
        char*   CString     ( )                     get C-style string from String

        long    Find        ( searchstring, startidx )  search for text starting at startidx; returns -1 if not found
        long    RFind       ( searchstring, startidx )  search backwards
        long    Find        ( searchchar, startidx )    search for single character
        long    RFind       ( searchchar, startidx )    search backwards



    Global Function Redefinitions for Convenience - Overview (simplified)
    ---------------------------------------------------------------------

        String  emptyString                         global constant
        String  SpaceString ( length, fillchar )
        String  CharString  ( char )

        uchar*  PString     ( String )
        char*   CString     ( String )

        String  SubString   ( String, long a, long e )
        String  MidString   ( String, long a, long n )
        String  MidString   ( String, long a )
        String  LeftString  ( String, long n )      
        String  RightString ( String, long n )      

        String  HexString   ( number, digits )
        String  NumString   ( number )

        String  UpperString ( String )                  
        String  LowerString ( String )                  
        String  ReplaceString(String, oldchar, newchar )

        long    FindString  ( targetstring, searchstring, startidx )
        long    RFindString ( targetstring, searchstring, startidx )
        long    FindChar    ( targetstring, searchchar, startidx )
        long    RFindChar   ( targetstring, searchchar, startidx )

        String  Using       ( Formatstring, ... );



    Technical Details
    -----------------
    
o   Strings consist of 3 components:
    
  o uchar*  text    a pointer to the text
  o long    len     length of text
  o StrMem* strmem  NULL or address of an administration block for dynamically allocated memory
  
o   Strings may have one of three states:

  o 'dirty'         strmem==NULL && len>0. 
                    The referenced text lies somewhere outside the control of the String class.
  o 'shared'        strmem!=NULL und strmem.count!=1. 
                    The referenced text is dynamically allocated and shared between multiple Strings.
  o 'writable'      strmem!=NULL und strmem.count==1. 
                    The referenced text is dynamically allocated and is exclusively used.

o   Most String operators create 'dirty' strings for the sake of speed.
    e.g.: String("abcde") creates a descriptor which directly points to the text constant "abcde" itself.
    Before you can overwrite some characters within this text you must use MakeWritable().

o   The copy creator does not create a copy of the source text but shares the source text between source and copy.
    The copy of a 'dirty' String is itself 'dirty'.
    After copying a 'writable' String both (!) become 'shared'.
    Before you can overwrite some characters within this text you must use MakeWritable().
    
o   The assignment operator creates a new, 'writable' String from a 'dirty' source.
    This prevents storing a reference to short-lived text in a long-living String.
    After assigning a 'writable' String both (!) source and target become 'shared'.
    Before you can overwrite some characters within this text you must use MakeWritable().
    
o   Before you can overwrite some characters within a String's text you must make shure that it is 'writable'.
    This is what the Functions IsWritable() and of course MakeWritable() are for.



    Changes
    -------

2001-11-09 kio: mod:    changed behaviour of RightString(a) to SubString(a,len)
2001-11-17 kio: mod:    changed behaviour of RightString(n) back to SubString(len-n,len)