Readme for wxString class in 'contrib\wxstring'
-----------------------------------------------
Last update: 16.04.95


Introduction
------------
Strings are used very frequently in most programs. There is no direct support in
the C++ language for strings. Therefore a string class can be useful in many
situations. It not only makes the code shorter and easier to read, it also
provides more security, because we don't have to deal with pointer acrobatics.

In former versions of wxWindows we had a 'little' string class which was useful,
but not very elaborate and efficient. Therefore I have included a much more
powerful and very efficient string class with this release of wxWindows.

The new wxString class is a 'port' and minor extension of the GNU 'String' class from
libg++. It can be compiled under MSW, UNIX and VMS (see below for compilers). 

The reasons for not using the GNU string class directly are:
- It is not available on all systems (mostly its only available on some UNIX systems).
- We can make changes and extensions to the string class as needed and are not
  forced to use only the functionality of the GNU string class.


Copyright of the original code
------------------------------
Copyright (C) 1988 Free Software Foundation
    written by Doug Lea (dl@rocky.oswego.edu)

This file is part of the GNU C++ Library.  This library is free
software; you can redistribute it and/or modify it under the terms of
the GNU Library General Public License as published by the Free
Software Foundation; either version 2 of the License, or (at your
option) any later version.  This library 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.  See the GNU Library General Public License for more details.
You should have received a copy of the GNU Library General Public
License along with this library; if not, write to the Free Software
Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.

  
Features
--------
The wxString class offers many string handling functions and a support for
regular expression. With this help pattern matching can be made much
easier.
I'm preparing a help file for the wxString class. For the moment I would
like to refer you to the headerfile 'wxstring.h' which shows all memberfunctions
and is somewhat selfexplanatory.


Additions
---------
As stated above, I have done some minor extensions to the wxString class.
In the following I list the memberfunctions which were added by me:

- formatted assignment:
  void sprintf(const char *fmt, ...);

  we do not use the 'sprintf' constructor of the old wxString class anymore, 
  because with that constructor, every initialisation with a string would 
  go through sprintf and this is not desireable, because sprintf interprets
  some characters. with the above function we can write i.e.:

  wxString msg; msg.sprintf("Processing item %d\n",count);
  
- strip chars at the front and/or end:
  enum              stripType {leading = 0x1, trailing = 0x2, both = 0x3};
  wxSubString       strip(stripType s=trailing, char c=' ');
  
  This can be useful for trimming strings.
  
- This function can be sometimes useful:
  void              removelast() { del((int)(length()-1),(int)1); } 
  
  It removes the last character of a string.
  
- Line input:  
  friend int        readline(FILE *f, wxString& x, 
                             char terminator = '\n',
                             int discard_terminator = 1);
                             
  Besides the stream I/O functions this function can be used for non-standard
  formatted I/O with arbitrary line terminators.                            

- The GNU String class lacks some classification functions:
  int               isAscii() const;
  int               isWord() const;
  int               isNumber() const;
  int               isNull() const;
  int               isDefined() const { return(! isNull()); }

- IMPORTANT!!!!!!!!!!!!!
// here is a very, very, very ugly macro, but it makes things more
// transparent in cases, where a library function requires a 
// (char *) argument. this is especially the case in wxWindows,
// where most char-arguments are (char *) and not (const char *).
// this macro should only be used in such cases and NOT to
// modify the internal data. The standard type conversion function
// of wxString returns a '(const char *)'.
// the conventional way would be 'function((char *)string.chars())'.
// with the macro this can be achieved by 'function(wxCHARARG(string))'.
// this makes it better clear, that the usage should be confined
// to arguments!

#define wxCHARARG(s) ((char *)(s).chars())  


Function calls
--------------
When using wxString objects as parameters to other functions you should
note the following:

void f1(const char *s){}
void f2(char *s){}

main(){
  wxString aString;
  f1(aString); // ok
  f2(aString); // error
  f2(wxCHARARG(aString)); // ok
  printf("%s",aString); // NO compilation error, but a runtime error.
  printf("%s",aString.chars()); // ok
  printf("%s",wxCHARARG(aString)); // ok
}
  

Headerfiles
-----------
For DOS and UNIX we use a stub-headerfile '\wxw161\include\base\wxstring.h'
which includes the two headerfiles in the '\wxw161\contrib\wxstring' directory.

For VMS we use another approach due to the bad inclusion mechanism.
We must DELETE the file '\wxw161\include\base\wxstring.h'. In the
VMS-Makefile, the include-file search path is augmented with the 
'\wxw161\contrib\wxstring' directory, so that the correct headerfiles 
can be included.

So you have only to specify '#define USE_WXSTRING 1' in
'\wxw161\include\base\wx_setup.h' to use the wxString class.


Testprogram
-----------
I have included a small testprogram 'test.cc' for some features
of wxString and wxRegex. It will be extended in the future.


Compilers
---------
I have compiled the wxString and wxRegex class successfully with the following
compilers (it should work on nearly every compiler):

PC    MS-Visual C++ 1.0
UNIX  gcc v2.*
VMS   DEC C++ compiler

Warnings about type conversion or assignments can be ignored.

I haven't tested the actual makefile for UNIX yet, because I currently have no
UNIX system, but I hope, that it will be correct.

VMS
---
Some things are special for VMS compilation. I have integrated them
into all necessary files.


This work was done by Stefan Hammes (stefan.hammes@urz.uni-heidelberg.de).

If you have problems, please send an E-mail to me. I wish you success,

Stefan Hammes




