mistring.h

Go to the documentation of this file.

/**
 * \file mistring.h <mi32/mistring.h>
 * \brief MISTRING class definition
 *
 * \if NODOC
 * $Id: mistring.h_v 1.69 2004/06/01 16:16:54 mju Exp $
 *
 * $Log: mistring.h_v $
 * Revision 1.69  2004/06/01 16:16:54  mju
 * Add STR_Strip0 operation enum.
 *
 * Revision 1.68  2004/03/31 21:31:52  dwilliss
 * Added Split and Join methods
 *
 * Revision 1.67  2004/02/16 20:58:28  mju
 * Warn on deprecated usage.
 *
 * Revision 1.66  2003/09/25 21:29:07  dwilliss
 * Don't capitalize enum any more. Genitor needed it, doxygen doesn't like it.
 *
 * Revision 1.65  2003/09/15 13:49:56  fileserver!dwilliss
 * Doxygen
 *
 * Revision 1.64  2003/09/10 16:24:11  dwilliss
 * Don't do CHECKSIZE on 64-bit platforms because padding causes it to fail
 *
 * Revision 1.63  2003/09/03 15:21:15  mju
 * Add static GetEmpty method.
 *
 * Revision 1.62  2003/08/15 21:10:19  mju
 * Add ctor/op= from STRUTF8.
 *
 * Revision 1.61  2003/07/02 20:11:59  mju
 * Exclude textid methods when building static library for Windows.
 *
 * Revision 1.60  2003/06/30 16:03:19  mju
 * Remove legacy mttext method.
 *
 * Revision 1.59  2003/05/05 15:22:00  mju
 * Remove format specifier parm from ctors from numerics.
 * Add << operators for INT64 and UINT64.
 * Add STR_FillD and indicate it is default.
 *
 * Revision 1.58  2003/01/28 16:42:00  mju
 * Add STR_FillSubs.
 *
 * Revision 1.56  2002/11/15 15:43:15  mju
 * Add Check/SetLineTermination.
 *
 * Revision 1.55  2002/10/16 17:01:09  mju
 * Add ConvertToDouble.
 *
 * Revision 1.54  2002/09/09 16:35:32  mju
 * Remove retired varargs methods.
 *
 * Revision 1.53  2002/09/03 21:02:11  mju
 * Allow implicit construction from TEXTID.
 *
 * Revision 1.52  2002/06/28 15:58:26  dwilliss
 * Oops.  Search methods should be const
 *
 * Revision 1.51  2002/06/28 15:46:04  dwilliss
 * Added Search methods
 *
 * Revision 1.50  2002/05/30 22:11:08  mju
 * Remove varargs methods unless building mistring module itself.
 *
 * Revision 1.49  2002/05/21 13:24:39  mju
 * Add STR_Pad formatting helper.
 *
 * Revision 1.48  2002/05/17 15:35:47  dwilliss
 * Don't leave dangling commas on the last item of an enum
 *
 * Revision 1.47  2002/05/16 16:24:11  dwilliss
 * Don't bother with the CHECKSIZE on SGI for now.  It fails but we don't care
 * because we don't use shared libs there
 *
 * Revision 1.46  2002/05/14 14:33:30  dwilliss
 * Changed checksize use to not expect sizeof(int) == sizeof(void*).  It's not
 * on the SGI any more
 *
 * Revision 1.45  2002/05/13 16:35:13  mju
 * Remove non-const array operators.
 * Add Replace method for single character.
 *
 * Revision 1.44  2002/04/09 13:05:58  mju
 * Fix parameter type.
 *
 * Revision 1.43  2002/04/08 20:44:26  mju
 * Add STR_Fill, STR_Precision, STR_Width formatting helpers.
 *
 * Revision 1.42  2002/04/08 17:50:35  mju
 * Add STR_FillA/B.
 *
 * Revision 1.41  2002/04/04 16:43:58  mju
 * Add STR_OP values to set bool format.
 *
 * Revision 1.40  2002/04/03 21:08:14  mju
 * Note that width setting only applies to one value.
 *
 * Revision 1.39  2002/04/03 17:05:43  mju
 * Change one of private 'dummy' members back to 'm_string' so can see string contents in debugger.
 *
 * Revision 1.38  2002/04/02 14:31:43  mju
 * Add STR_OPs for Fill and Width.
 *
 * Revision 1.37  2002/03/29 17:29:39  mju
 * Add STR_OP enum and << operator to support.
 *
 * Revision 1.36  2002/03/28 22:38:40  mju
 * Add FmtSet methods.
 *
 * Revision 1.34  2002/03/27 16:55:25  mju
 * Deprecate variable-argument methods.
 *
 * Revision 1.33  2002/03/26 21:16:52  mju
 * Add FmtEnableSubstitution and FmtSetPrecision.
 *
 * Revision 1.32  2002/03/26 17:48:52  mju
 * Move private members into private class pointer.
 * Support TEXTID.
 *
 * Revision 1.31  2002/03/25 21:54:58  mju
 * Add operator<<'s.
 *
 * Revision 1.28  2001/08/17 21:42:21  dwilliss
 * Added an Insert method
 *
 * Revision 1.27  2001/06/29 20:23:32  scowan
 * Added sub string comapre and compare no case methods.
 *
 * Revision 1.26  2001/05/23 20:29:10  scowan
 * Nothing.
 *
 * Revision 1.25  2001/02/15 21:23:37  scowan
 * Added ini read/write ML methods.
 *
 * Revision 1.24  2000/12/04 16:31:36  mju
 * Fix genitor 'end ignore' tag.
 *
 * Revision 1.23  2000/11/22 22:46:14  scowan
 * Added assign method from unicode strings.
 *
 * Revision 1.22  2000/10/13 16:44:13  dwilliss
 * Added array operator overloads taking long on Mac only to avoid stupid
 * ambiguous function overload error
 *
 * Revision 1.21  2000/08/16 16:56:40  mju
 * Add ctor from msg group/key.
 *
 * Revision 1.20  2000/07/11 17:35:28  mju
 * Undef CLASSLIBEXPORT at end.
 *
 * Revision 1.19  2000/07/07 15:12:49  dwilliss
 * Export MISTRINGLIST too
 *
 * Revision 1.18  2000/07/07 14:13:28  dwilliss
 * Use #pragma export to export class methods on the Macintosh
 *
 * Revision 1.17  2000/07/06 13:22:15  mju
 * Add AppendMsg/V.
 *
 * Revision 1.16  2000/06/26 21:17:32  mju
 * Change docs for Sprintf methods.
 *
 * Revision 1.12  2000/05/03 22:10:37  mju
 * Update docs for Genitor.
 *
 * Revision 1.11  2000/04/19 21:31:17  shovland
 * clarify "end" parameter of Replace method
 *
 * Revision 1.4  1999/11/15 16:20:53  scowan
 * Updated for DLL use and added many new methods.
 *
 * Revision 1.3  1999/10/20 14:29:03  mju
 * Initial implementation completed.
 *
 * Revision 1.2  1999/10/01  21:38:44  mju
 * Make more methods inline.
 *
 * Revision 1.1  1999/10/01  16:41:34  mju
 * Initial revision
 * \endif
**/

#ifndef  INC_MI32_MISTRING_H
#define  INC_MI32_MISTRING_H

#ifndef INC_MI32_UCSTRING_H
#include <mi32/ucstring.h>
#endif

#ifndef INC_MI32_MILIST_H
#include <mi32/milist.h>
#endif

#include <mi32/stdansic.h>

#ifdef MISYSTEMDLL
   #define CLASSLIBEXPORT MI_DLLCLASSEXPORT
#else
   #define CLASSLIBEXPORT MI_DLLCLASSIMPORT
#endif


#ifndef GENERATING_DOXYGEN_OUTPUT
class STRUTF8;
class UCREGEXP;
#endif //!< GENERATING_DOXYGEN_OUTPUT


//! Convenience MISTRING operation and formatting enumerations for use with << operator.
enum STR_OP {
   STR_Clear = 0,             //!< Clear the string
   STR_BoolL = 1,             //!< Format bool as localized no/yes (default)
   STR_BoolM = 2,             //!< Format bool as localized No/Yes
   STR_BoolU = 3,             //!< Format bool as localized NO/YES
   STR_FillA = 4,             //!< Fill/pad AFTER value if width more than needed
   STR_FillB = 5,             //!< Fill/pad BEFORE value if width more than needed
   STR_FillD = 6,             //!< Fill/pad default (after strings, before numerics) (default)
   STR_Strip0 = 9,            //!< Strip trailing 0's after decimal point for next formatted value ('fixed' and 'general')
   STR_FillSubs = 10,         //!< Fill substitution placeholders with '???' to avoid unwanted formatting.
   STR_FltE = 11,             //!< Set floating format to 'exponential'
   STR_FltF = 12,             //!< Set floating format to 'fixed'
   STR_FltG = 13,             //!< Set floating format to 'general'
   STR_Bin = 14,              //!< Set integer base to 'binary' (2)
   STR_Dec = 15,              //!< Set integer base to 'decimal' (10)
   STR_Hex = 16,              //!< Set integer base to 'hexadecimal' (16)
   STR_FillSp = 17,           //!< Set fill character to ' ' (space)
   STR_Fill0 = 18,            //!< Set fill character to '0'
   STR_PrecA = 19,            //!< Set floating precision to 'automatic'
   STR_Prec0 = 20,            //!< Set floating precision to 0
   STR_Prec1 = 21,            //!< Set floating precision to 1
   STR_Prec2 = 22,
   STR_Prec3 = 23,
   STR_Prec4 = 24,
   STR_Prec5 = 25,
   STR_Prec6 = 26,
   STR_Prec7 = 27,
   STR_Prec8 = 28,
   STR_Prec9 = 29,
   STR_Prec10 = 30,
   STR_Prec11 = 31,
   STR_Prec12 = 32,
   STR_Prec13 = 33,
   STR_Prec14 = 34,
   STR_Prec15 = 35,
   STR_Prec16 = 36,           //!< Set floating precision to 16
   STR_Width0 = 40,           //!< Set width to minimum
   STR_Width1 = 41,           //!< Set minimum width to 1 for next formatted value only
   STR_Width2 = 42,           //!< Set minimum width to 2 for next formatted value only
   STR_Width3 = 43,
   STR_Width4 = 44,
   STR_Width5 = 45,
   STR_Width6 = 46,
   STR_Width7 = 47,
   STR_Width8 = 48,
   STR_Width9 = 49,
   STR_Width10 = 50,
   STR_Width11 = 51,
   STR_Width12 = 52,
   STR_Width13 = 53,
   STR_Width14 = 54,
   STR_Width15 = 55
   };


//! General string class.
//! Supports internationalization, Unicode and various character set encodings.
//!
//! MISTRING supports use of '<<' to 'put' values into the string similar to iostream.
//! When using '<<' the current MISTRING is first searched for a formatting code or
//! a substitution placeholder.  Formatting codes in the form %d, %s, %f, etc. are
//! searched for first.  The first code compatible with the value being put into
//! the string will be used.  Thus, if a number is being put then any %d, %u, %f,
//! etc code will be used.  These formatting codes can also specify the width and
//! precision if desired.  Thus, '%.8f' may be used to specify 8 decimal places of
//! precision.  These settings only apply to the current value being put into the
//! string.  If no width, precision, etc is specified then any previously set formatting
//! state settings will apply.  If no %-style formatting code is found then a search
//! is made for substitution placeholders in the form $1, $2, etc.  The lowest numbered
//! placeholder will be replaced with the value being put into the string.  Finally,
//! if no placeholder is found then the value being put will be appended to the end of
//! the string.
class CLASSLIBEXPORT MISTRING {
   public:

      enum FLOATFMT {
         FLOATFMT_General =      0,    //!< General (equivalent to "%G")
         FLOATFMT_Fixed =        1,    //!< Fixed (equivalent to "%f")
         FLOATFMT_Scientific =   2     //!< Scientific (equivalent to "%E")
         };

      enum LINETERM {
         LINETERM_LF =           0,    //!< Terminate lines with '\\n'
         LINETERM_CR =           1,    //!< Terminate lines with '\\r'
         LINETERM_CRLF =         2     //!< Terminate lines with '\\r\\n'
         };

      //! Default constructor.
      MISTRING (
         );

      //! Copy constructor.
      MISTRING (
         const MISTRING& rhs
         );

      //! Construct from UNICODE* string (implicit).
      MISTRING (
         const UNICODE *ustr
         );
      
      //! Construct from char* string.
      explicit MISTRING (
         const char *str
         );

      //! Construct from STRUTF8 string (implicit).
      MISTRING (
         const STRUTF8& rhs
         );

   #ifndef NODLLLINKAGE
      //! Construct from TEXTID (implicit).
      MISTRING (
         TEXTID textid                       //!< Messsage text ID
         );
   #endif

   #if !defined(DEPRECATE_GROUPKEY) || defined(MISTRING_DLL)
      //! Construct from message file group and key.
      //! Deprecated, use TEXTID instead.
      DEPRECATED MISTRING (
         const char *msggroup,               //!< Message file group
         const char *msgkey                  //!< Message file key
         );
   #endif

   #if 0    // Systems where wchar_t is not same as UINT16(UNICODE)
      #ifndef GENERATING_DOXYGEN_OUTPUT
      //! Construct from wchar_t* string using Unicode encoding.
      explicit MISTRING (
         const wchar_t *str
         );
      #endif //!< GENERATING_DOXYGEN_OUTPUT
   #endif

      //! Construct from string in specified encoding.
      MISTRING (
         const void *str,
         CHAR_ENCODING encoding
         );

      //! Construct from integer with default formatting.
      explicit MISTRING (
         int value
         );

      //! Construct from unsigned integer with default formatting.
      explicit MISTRING (
         unsigned int value
         );

      //! Construct from floating-point with default formatting.
      explicit MISTRING (
         double value
         );

      ~MISTRING (
         );

      //! Assignment from MISTRING.
      MISTRING& operator= (
         const MISTRING& rhs
         );

      //! Assignment from STRUTF8.
      MISTRING& operator= (
         const STRUTF8& rhs
         );

   #ifndef NODLLLINKAGE
      //! Assignment from TEXTID.
      MISTRING& operator= (
         TEXTID textid
         );
   #endif

      //! Assignment from UNICODE* string.
      MISTRING& operator= (
         const UNICODE* rhs
         );

      //! Assignment from char* (ASCII/ISO-Latin1).
      MISTRING& operator= (
         const char* rhs
         );

   #if 0    //!< Systems where wchar_t is not same as UINT16(UNICODE)
      #ifndef GENERATING_DOXYGEN_OUTPUT
      //! Assignment from wchar_t* using Unicode encoding.
      MISTRING& operator= (
         const wchar_t* rhs
         );
      #endif //!< GENERATING_DOXYGEN_OUTPUT
   #endif

      //! Concatenation from MISTRING.
      MISTRING& operator+= (
         const MISTRING& rhs
         );

      //! Concatenation from UNICODE* string.
      MISTRING& operator+= (
         const UNICODE* rhs
         );

      //! Concatenation from char* (ASCII/ISO-Latin1).
      MISTRING& operator+= (
         const char* rhs
         );

   #if 0    // Systems where wchar_t is not same as UINT16(UNICODE)
      #ifndef GENERATING_DOXYGEN_OUTPUT
      //! Concatenation from wchar_t* using Unicode encoding
      MISTRING& operator+= (
         const wchar_t* rhs
         );
      #endif //!< GENERATING_DOXYGEN_OUTPUT
   #endif

      //! Append single character (Unicode or ASCII).
      MISTRING& operator+= (
         UNICODE c
         );

      //! Perform operation on string.
      MISTRING& operator<< (STR_OP op);

      //! Format and put 'bool' value into string.
      MISTRING& operator<< (bool b);

      //! Format and put single character into string.
      MISTRING& operator<< (char c);

      //! Format and put INT8 (signed char) numeric value into string.
      MISTRING& operator<< (signed char n);

      //! Format and put UINT8 (unsigned char) numeric value into string.
      MISTRING& operator<< (unsigned char n);

      //! Format and put INT16 (short) value into string.
      MISTRING& operator<< (short n);

      //! Format and put INT32 (int) value into string.
      MISTRING& operator<< (int n);

      //! Format and put (long) value into string.
      MISTRING& operator<< (long n);

   #ifndef LONGS_ARE_64_BIT
      //! Format and put (INT64) value into string.
      MISTRING& operator<< (INT64 n);
   #endif

      //! Format and put UINT16 (unsigned short) value into string.
      //! Warning, use of UNICODE will result in numeric value being put into string.
      MISTRING& operator<< (unsigned short n);

      //! Format and put UINT32 (unsigned int) value into string.
      MISTRING& operator<< (unsigned int n);

      //! Format and put (unsigned long) value into string.
      MISTRING& operator<< (unsigned long n);

   #ifndef LONGS_ARE_64_BIT
      //! Format and put (UINT64) value into string.
      MISTRING& operator<< (UINT64 n);
   #endif

      //! Format and put (float) value into string.
      MISTRING& operator<< (float f);

      //! Format and put (double) value into string.
      MISTRING& operator<< (double f);

      //! Format and put ASCII string into string.
      MISTRING& operator<< (const char *s);

      //! Format and put UNICODE string into string.
      MISTRING& operator<< (const UNICODE *s);

   #ifndef NODLLLINKAGE
      //! Format and text from TEXTID put into string.
      MISTRING& operator<< (TEXTID textid);
   #endif

      //! Read array element.
      const UNICODE& operator[] (
         int idx
         ) const;

      //! Cast to (const UNICODE *).
      //! Cast to non-const is not supported as destruction cannot be enforced for temporaries.
      //! Cast to UINT8* or char* is not permitted as encoding cannot be specified.
      operator const UNICODE* (
         ) const;

      //! Append from MISTRING.
      void Append (
         const MISTRING& str,                //!< String to append
         int start = 0,                      //!< Starting position in 'str' to append to this string
         int end = INT32_MAX                 //!< Ending position in 'str' to append to this string
         );

      //! Assign from MISTRING.
      void Assign (
         const MISTRING& str,                //!< Buffer holding MISTRING
         int start = 0,                      //!< Starting position in 'str' to assign to this string
         int end = INT32_MAX                 //!< Ending position in 'str' to assign to this string
         );

      //! Assign from UNICODE string.
      void Assign (
         const UNICODE *str,                 //!< Buffer holding UNICODE string
         int start = 0,                      //!< Starting position in 'str' to assign to this string
         int end = INT32_MAX                 //!< Ending position in 'str' to assign to this string
         );

      //! Assign from string in specified encoding.
      //! Assign from partial char string is not supported due to character encoding
      void Assign (
         const void *str,                    //!< Buffer holding appropriately-terminated string
         CHAR_ENCODING encoding              //!< Encoding of string
         );

      //! Determine if string consistently uses specified line termination.
      //! @return true if specified termination used, false if not.
      bool CheckLineTermination (
         LINETERM lineterm                   //!< Line termination
         ) const;

      //! Clear the string.
      void Clear (
         );

      //! Case-sensitive comparison (similar to strcmp).
      //! @return 0 if strings equal, -1 if this < str, 1 if this > str.
      int Compare (
         const MISTRING& str                 //!< String to compare to
         ) const;

      //! Case-sensitive comparison, length limited (similar to strncmp).
      //! @return 0 if strings equal, -1 if this < str, 1 if this > str.
      int Compare (
         const MISTRING& str,                //!< String to compare to
         int len                             //!< Maximum number of characters to compare
         ) const;

      //! Case-sensitive comparison, length limited (similar to strncmp).
      //! @return 0 if strings equal, -1 if this < str, 1 if this > str.
      int Compare (
         int SrcStart,                       //!< Start position of 'this' string
         const MISTRING& str,                //!< String to compare to
         int OtherStart,                     //!< Start position of 'str'
         int len                             //!< Maximum number of characters to compare
         ) const;

      //! Case-insensitive comparison (similar to stricmp).
      //! @return 0 if strings equal, -1 if this < str, 1 if this > str.
      int CompareNoCase (
         const MISTRING& str                 //!< String to compare to
         ) const;

      //! Case-insensitive comparison, length limited (similar to strnicmp).
      //! @return 0 if equal, -1 if this < str, 1 if this > str.
      int CompareNoCase (
         const MISTRING& str,                //!< String to compare to
         int len                             //!< Maximum number of characters to compare
         ) const;

      //! Case-insensitive comparison, length limited (similar to strnicmp).
      //! @return 0 if equal, -1 if this < str, 1 if this > str.
      int CompareNoCase (
         int SrcStart,                       //!< Start position of 'this' string
         const MISTRING& str,                //!< String to compare to
         int OtherStart,                     //!< Start position of 'str'
         int len                             //!< Maximum number of characters to compare
         ) const;

      //! Convert string to double-precision numeric value.
      //! @return Converted value or 0.0 if unable to convert.
      double ConvertToDouble (
         ) const;

      //! Find next occurrence in given set of characters (similar to strpbrk).
      //! @return Character position or -1 if not found.
      int FindNextInSet (
         const MISTRING& chars,              //!< Characters to search for
         int start = 0                       //!< Starting position, default is start of string
         ) const;

      //! Find next occurrence not in given set of characters.
      //! @return Character position or -1 if not found.
      int FindNextNotInSet (
         const MISTRING& chars,              //!< Characters to search for
         int start = 0                       //!< Starting position, default is start of string
         ) const;

      //! Find next occurrence of given string (similar to strstr).
      //! @return Starting position of substring or -1 if not found.
      int FindNextOf (
         const MISTRING& str,                //!< String to search for
         int start = 0                       //!< Starting position, default is start of string
         ) const;

      //! Find next occurrence of given character (similar to strchr).
      //! @return Position of character or -1 if not found.
      int FindNextOf (
         UNICODE c,                          //!< Character to search for
         int start = 0                       //!< Starting position, default is start of string
         ) const;

      //! Find previous occurrence in given set of characters.
      //! @return Position or -1 if not found.
      int FindPrevInSet (
         const MISTRING& chars,              //!< Characters to search for
         int start = INT32_MAX               //!< Starting position, default is end of string
         ) const;

      //! Find previous occurrence not in given set of characters.
      //! @return Position or -1 if not found.
      int FindPrevNotInSet (
         const MISTRING& chars,              //!< Characters to search for
         int start = INT32_MAX               //!< Starting position, default is end of string
         ) const;

      //! Find previous occurrence of given character (similar to strrchr).
      //! @return Position of character or -1 if not found.
      int FindPrevOf (
         UNICODE c,                          //!< Character to search for
         int start = INT32_MAX               //!< Starting position, default is end of string
         ) const;

      //! Enable substitution during formatting.
      //! Initial default is enabled.
      void FmtEnableSubstitution (
         bool enable = true                  //!< 'true' to enable, 'false' to disable
         );

      //! Set integer base.
      void FmtSetBase (
         int base                            //!< Integer base 2-36
         );

      //! Set fill character for padding.
      void FmtSetFill (
         UNICODE fill                        //!< Fill character
         );

      //! Set floating point formatting mode
      void FmtSetFloat (
         FLOATFMT floatmode                  //!< Floating point formatting mode
         );

      //! Set precision (number of decimal places) for floating-point output.
      void FmtSetPrecision (
         int precision                       //!< Floating-point precision
         );

      //! Set whether to shown sign for positive numbers.
      //! Sign is only shown if integer base is 10.
      void FmtSetSign (
         bool sign                           //!< True to show sign, false to not
         );

      //! Set minimum width for next formatted value.
      //! Note that at width setting only applies to one value after which
      //! time it will reset to 0 (minimum).
      void FmtSetWidth (
         int width                           //!< Minimum width
         );

      //! Get string in specified encoding.
      //! @return Encoded string caller must free.
      void *GetEncoded (
         CHAR_ENCODING encoding              //!< Encoding
         ) const;

      //! Get reference to empty string.
      static const MISTRING& GetEmpty (
         );

      //! Get length in characters.
      //! @return Length in characters.
      int GetLength (
         ) const;

      //! Get string reference.  Used to avoid static_cast<const UNICODE*>(MISTRING).
      //! @return Pointer to internal string, do not free!
      const UNICODE *GetReference (
         ) const;

      //! Get allocated string.
      //! @return Pointer to string, caller must free
      UNICODE *GetString (
         ) const;

      //! Retrieve sub-string.
      //! @return Substring from position to end of string.
      MISTRING GetSubString (
         int start                           //!< Starting position
         ) const;

      //! Retrieve sub-string.
      //! @return Substring from position up to specified length.
      MISTRING GetSubString (
         int start,                          //!< Starting position
         int end                             //!< Ending position (inclusive)
         ) const;

      //! Read string from .ini file.
      //! @return true if entry in file, false if not
      bool IniRead (
         INIHANDLE handle,                   //!< Ini Handle created by IniOpen()
         const char *group,                  //!< Group to look for ini entry, App Name if =0
         const char *field                   //!< Field to read string from
         );

      //! Read multi-line string from .ini file.
      //! @return true if entry in file, false if not
      bool IniReadML (
         INIHANDLE handle,                   //!< Ini Handle created by IniOpen()
         const char *group,                  //!< Group to look for ini entry, App Name if =0
         const char *field                   //!< Field to read string from
         );

      //! Write string to .ini file.
      void IniWrite (
         INIHANDLE handle,                   //!< Ini Handle created by IniOpen()
         const char *group,                  //!< Group to write ini entry, App Name if =0
         const char *field                   //!< Field to write string to
         ) const;

      //! Write multi-line string to .ini file.
      void IniWriteML (
         INIHANDLE handle,                   //!< Ini Handle created by IniOpen()
         const char *group,                  //!< Group to write ini entry, App Name if =0
         const char *field                   //!< Field to write string to
         ) const;

      //! Determine if string is empty.
      //! @return true if string is empty, false if not.
      bool IsEmpty (
         ) const;

      //! Insert all or part of another string at specified position.
      void Insert (
         int start,                          //!< Position to insert before
         const MISTRING& str,                //!< String to insert
         int strstart = 0,                   //!< Start of replace string
         int strend = INT32_MAX              //!< End of replace string
         );


      //! Join all the strings in an MISTRINGLIST into one string
      void Join (
         const MILIST<MISTRING>& list,
         const UNICODE* sep
         );

      //! Join all the strings in an MISTRINGLIST into one string
      //! The char* variant of this function exists because most often, you
      //! want to join the strings together with simple whitespace or commas.
      void Join (
         const MILIST<MISTRING>& list,
         const char* sep = ""
         );

      //! Pad with specified character.
      void Pad (
         UNICODE c,                          //!< Character to pad with
         int numchars                        //!< Number of characters to pad
         );

      //! Pad with specified character to given length.
      void PadToLength (
         UNICODE c,                          //!< Character to pad with
         int length                          //!< Length to pad to
         );

      //! Remove a section of the string.
      void Remove (
         int start,                          //!< Starting index to remove sub-string
         int end                             //!< Ending index to remove sub-string
         );

      //! Replace single character at specified position.
      //! This cannot be used to truncate or extend the string, attempts to do so will be ignored.
      void Replace (
         int index,                          //!< Index from start of string, must be from 0 to GetLength()-1
         UNICODE c                           //!< Character value to replace with, will ignore if 0
         );

      //! Replace a section of a string with another sub-string.
      void Replace (
         int start,                          //!< Start of string section to replace
         int end,                            //!< End of string section to replace
         const MISTRING& str,                //!< String to replace with
         int strstart = 0,                   //!< Start of replace string
         int strend = INT32_MAX              //!< End of replace string
         );

      //! Reserve enough memory for specified number of characters.
      ERRVALUE Reserve (
         int numchars                        //!< Number of characters
         );

      //! Search for a regular expression.
      //!
      //! Returns true if the given regular expression could be found,
      //! false if not.  MatchStart/MatchEnd values returned are only
      //! meaningful if a match was found.
      //! 
      //! If you plan to search multiple strings for the same expression,
      //! it's more effecient to use the version of Search that takes
      //! a reference to a UCREGEXP.
      //! 
      //! Note: If the string to search for is just a simple string, you're
      //! better off calling FindNextOf() instead.
      //!
      //! For details of RE syntax, see mi32/ucregexp.h or the documentation
      //! for the class UCREGEXP.
      bool Search (
         const UNICODE* str,        //!< Regular expression to search for
         UINT32& MatchStart,        //!< Start of match RETURNED
         UINT32& MatchEnd,          //!< End of match RETURNED
         bool bIgnoreCase = false,  //!< Ignore case if true
         UINT32 Start = 0           //!< Where to start in source string
         ) const;
      
      //! Search for a regular expression.
      //!
      //! Returns true if the given regular expression could be found,
      //! false if not.  MatchStart/MatchEnd values returned are only
      //! meaningful if a match was found.
      //! 
      //! Note, this version doesn't have the bIgnoreCase parameter because
      //! that is specified when you create the UCREGEXP that you pass in.
      //!
      //! For details of RE syntax, see mi32/ucregexp.h or the documentation
      //! for the class UCREGEXP.
      bool Search (
         const UCREGEXP& regex,     //!< Regular expression to search for
         UINT32& MatchStart,        //!< Start of match RETURNED
         UINT32& MatchEnd,          //!< End of match RETURNED
         UINT32 Start = 0           //!< Where to start in source string
         ) const;
      
      //! Set string to use specified line termination.
      //! Note, this does not affect future additions to the string.
      //! @return true if string changed, false if not.
      bool SetLineTermination (
         LINETERM lineterm                   //!< Line termination
         );

      //! Set all characters to lowercase.
      void SetLowerCase (
         int start = 0                       //!< Starting position to lowercase string
         );

      //! Set all characters to uppercase.
      void SetUpperCase (
         int start = 0                       //!< Starting position to uppercase string
         );

      //! Split a string up into a list of strings
      //!
      //! @param ch Delimiter
      //! @param list The list of strings returned
      //! @param maxitems The maximum number of items to split out.  If 0 (the
      //!   default), it will split all items.  
      //! @return number of strings in list 
      int Split (
         UNICODE ch,             
         MILIST<MISTRING>& list, 
         int maxitems = 0        
         ) const;

      //! Split a string up into a list of strings
      //!
      //! @param regexp Regular Expression to match delimiters
      //! @param list The list of strings returned
      //! @param maxitems The maximum number of items to split out.  If 0 (the
      //!   default), it will split all items.  
      //! @return number of strings in list 
      int Split (
         const UNICODE *regexp,              
         MILIST<MISTRING>& list, 
         int maxitems = 0        
         ) const;

      //! Truncate to specified number of characters.
      void Truncate (
         int length                          //!< Length to truncate to
         );

      #ifndef GENERATING_DOXYGEN_OUTPUT
      class PRIV;
      #endif //!< GENERATING_DOXYGEN_OUTPUT

   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT
      static const UNICODE s_zero;        //!< Used when read array element out of range
      static UNICODE s_dummy;             //!< Used when write array element out of range

      const UNICODE *m_string;
      int dummy2;
      PRIV *m_pPriv;

      void GetExclusive ();

#if !defined(SGI) && !defined(LONGS_ARE_64_BIT)
      //! This fails on SGI because it ends up padding between dummy2 and m_pPriv
      //! but we don't use shared libs there, so we don't care
      //! Also fails on any 64-bit platforms
      CHECKSIZE(sizeof(int) + 2*sizeof(void*));
#endif

      friend class MISTRING::PRIV;
      #endif // GENERATING_DOXYGEN_OUTPUT
   };

#if defined(WIN32)
#if !defined(MISYSTEMDLL) && !defined(NODLLLINKAGE)
#pragma warning(disable:4231) /* the extern before template is a non-standard extension */

extern template class CLASSLIBEXPORT MILIST<MISTRING>;      //! Template instantiation

#pragma warning(default:4231) /* restore previous warning */
#endif      //!< _DLL
#endif      //!< WIN32

typedef MILIST<MISTRING> MISTRINGLIST;


//! Concatenation of MISTRINGs.
inline MISTRING operator+ (
   const MISTRING& lhs,
   const MISTRING& rhs
   ) {
   MISTRING result(lhs);
   result += rhs;
   return (result);
   }

//! Equality.
inline bool operator== (
   const MISTRING& lhs,
   const MISTRING& rhs
   ) {
   return (lhs.Compare(rhs) == 0);
   }

//! Inequality.
inline bool operator!= (
   const MISTRING& lhs,
   const MISTRING& rhs
   ) {
   return (lhs.Compare(rhs) != 0);
   }

//! Less than.
inline bool operator< (
   const MISTRING& lhs,
   const MISTRING& rhs
   ) {
   return (lhs.Compare(rhs) < 0);
   }

//! Less than or equal.
inline bool operator<= (
   const MISTRING& lhs,
   const MISTRING& rhs
   ) {
   return (lhs.Compare(rhs) <= 0);
   }

//! Greater than.
inline bool operator> (
   const MISTRING& lhs,
   const MISTRING& rhs
   ) {
   return (lhs.Compare(rhs) > 0);
   }

//! Greater than or equal.
inline bool operator>= (
   const MISTRING& lhs,
   const MISTRING& rhs
   ) {
   return (lhs.Compare(rhs) >= 0);
   }


//! Formatting manipulators.

#ifndef GENERATING_DOXYGEN_OUTPUT

struct STR_FILL {
   UNICODE m_fill;
   STR_FILL (UNICODE fill) : m_fill(fill) { }
   };

inline MISTRING& operator<< (
   MISTRING& lhs,
   const STR_FILL& rhs
   ) { lhs.FmtSetFill(rhs.m_fill); return (lhs); }

struct STR_PAD {
   UNICODE m_c;
   int m_n;
   STR_PAD (UNICODE c, int n) : m_c(c), m_n(n) { }
   };

inline MISTRING& operator<< (
   MISTRING& lhs,
   const STR_PAD& rhs
   ) { lhs.Pad(rhs.m_c,rhs.m_n); return (lhs); }

struct STR_PREC {
   int m_precision;
   STR_PREC (int precision) : m_precision(precision) { }
   };

inline MISTRING& operator<< (
   MISTRING& lhs,
   const STR_PREC& rhs
   ) { lhs.FmtSetPrecision(rhs.m_precision); return (lhs); }

struct STR_WIDTH {
   int m_width;
   STR_WIDTH (int width) : m_width(width) { }
   };

inline MISTRING& operator<< (
   MISTRING& lhs,
   const STR_WIDTH& rhs
   ) { lhs.FmtSetWidth(rhs.m_width); return (lhs); }

#endif //!< GENERATING_DOXYGEN_OUTPUT

//! String formatting helper to set fill character via << operator.
//! Use as str << STR_Fill(fill).
inline STR_FILL STR_Fill (
   UNICODE fill
   ) { return (STR_FILL(fill)); }

//! String formatting helper to pad specified number of characters.
//! Use as str << STR_Pad(c,numchars).
inline STR_PAD STR_Pad (
   UNICODE c,                                //!< Character to pad with
   int numchars                              //!< Number of characters to pad
   ) { return (STR_PAD(c,numchars)); }

//! String formatting helper to set precision via << operator.
//! Use as str << STR_Prec(precision).
inline STR_PREC STR_Prec (
   int precision
   ) { return (STR_PREC(precision)); }

//! String formatting helper to set width via << operator.
//! Use as str << STR_Width(width).
inline STR_WIDTH STR_Width (
   int width
   ) { return (STR_WIDTH(width)); }

#undef   CLASSLIBEXPORT

#endif   //!< INC_MI32_MISTRING_H

---