interface/wx/ustring.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/ustring.h
   3 // Purpose:     interface of wxUString
   4 // Author:      Robert Roebling
   5 // Copyright:   (c) Robert Roebling
   6 // RCS-ID:      $Id$
   7 // Licence:     wxWindows licence
   8 /////////////////////////////////////////////////////////////////////////////
   9
  10 /**
  11     @class wxUString
  12
  13     wxUString is a class representing a Unicode character string where
  14     each character is stored using a 32-bit value. This is different from
  15     wxString which may store a character either as a UTF-8 or as a UTF-16
  16     sequence and different from @c std::string which stores a string
  17     as a sequence of simple 8-bit characters and also different from
  18     @c std::wstring which stores the string differently depending on
  19     the definition of wchar_t.
  20
  21     The main purpose of wxUString is a to give users a Unicode string
  22     class that has O(1) access to its content, to be identical on all
  23     platforms and to be easily convertable to wxString as well as other
  24     ways to store strings (C string literals, wide character
  25     string literals, character buffer, etc) by providing several overloads
  26     and built-in conversions to and from the various string formats.
  27
  28     wxUString derives from @c std::basic_string<wxChar32> and therefore
  29     offers the complete API of @c std::string.
  30
  31     @library{wxbase}
  32     @category{data}
  33
  34     @see wxString, @ref overview_string "wxString overview", @ref overview_unicode
  35     "Unicode overview"
  36 */
  37
  38
  39 class WXDLLIMPEXP_BASE wxUString: public std::basic_string<wxChar32>
  40 {
  41 public:
  42     /**
  43         Default constructor.
  44     */
  45     wxUString();
  46     /**
  47         Copy constructor.
  48     */
  49     wxUString( const wxUString &str );
  50     /**
  51         Constructs a string from a 32-bit string literal.
  52     */
  53     wxUString( const wxChar32 *str );
  54     /**
  55         Constructs a string from 32-bit string buffer.
  56     */
  57     wxUString( const wxU32CharBuffer &buf );
  58     /**
  59         Constructs a string from C string literal using wxConvLibc to convert it to Unicode.
  60     */
  61     wxUString( const char *str );
  62     /**
  63         Constructs a string from C string buffer using wxConvLibc to convert it to Unicode.
  64     */
  65     wxUString( const wxCharBuffer &buf );
  66     /**
  67         Constructs a string from C string literal using @a conv to convert it to Unicode.
  68     */
  69     wxUString( const char *str, const wxMBConv &conv );
  70     /**
  71         Constructs a string from C string literal using @a conv to convert it to Unicode.
  72     */
  73     wxUString( const wxCharBuffer &buf, const wxMBConv &conv );
  74     /**
  75         Constructs a string from UTF-16 string literal
  76     */
  77     wxUString( const wxChar16 *str );
  78     /**
  79         Constructs a string from UTF-16 string buffer
  80     */
  81     wxUString( const wxU16CharBuffer &buf );
  82     /**
  83         Constructs a string from wxString.
  84     */
  85     wxUString( const wxString &str );
  86     /**
  87         Constructs a string from using wxConvLibc to convert it to Unicode.
  88     */
  89     wxUString( char ch );
  90     /**
  91         Constructs a string from a UTF-16 character.
  92     */
  93     wxUString( wxChar16 ch );
  94     /**
  95         Constructs a string from 32-bit Unicode character.
  96     */
  97     wxUString( wxChar32 ch );
  98     /**
  99         Constructs a string from wxUniChar (returned by wxString's access operator)
 100     */
 101     wxUString( wxUniChar ch );
 102     /**
 103         Constructs a string from wxUniCharRef (returned by wxString's access operator)
 104     */
 105     wxUString( wxUniCharRef ch );
 106     /**
 107         Constructs a string from @a n characters @a ch.
 108     */
 109     wxUString( size_t n, char ch );
 110     /**
 111         Constructs a string from @a n characters @a ch.
 112     */
 113     wxUString( size_t n, wxChar16 ch );
 114     /**
 115         Constructs a string from @a n characters @a ch.
 116     */
 117     wxUString( size_t n, wxChar32 ch );
 118     /**
 119         Constructs a string from @a n characters @a ch.
 120     */
 121     wxUString( size_t n, wxUniChar ch );
 122     /**
 123         Constructs a string from @a n characters @a ch.
 124     */
 125     wxUString( size_t n, wxUniCharRef ch );
 126
 127     /**
 128         Static construction of a wxUString from a 7-bit ASCII string
 129     */
 130     static wxUString FromAscii( const char *str, size_t n );
 131     /**
 132         Static construction of a wxUString from a 7-bit ASCII string
 133     */
 134     static wxUString FromAscii( const char *str );
 135     /**
 136         Static construction of a wxUString from a UTF-8 encoded string
 137     */
 138     static wxUString FromUTF8( const char *str, size_t n );
 139     /**
 140         Static construction of a wxUString from a UTF-8 encoded string
 141     */
 142     static wxUString FromUTF8( const char *str );
 143     /**
 144         Static construction of a wxUString from a UTF-16 encoded string
 145     */
 146     static wxUString FromUTF16( const wxChar16 *str, size_t n );
 147     /**
 148         Static construction of a wxUString from a UTF-16 encoded string
 149     */
 150     static wxUString FromUTF16( const wxChar16 *str );
 151
 152
 153     /**
 154        Assignment from a 7-bit ASCII string literal
 155     */
 156     wxUString &assignFromAscii( const char *str );
 157     /**
 158        Assignment from a 7-bit ASCII string literal
 159     */
 160     wxUString &assignFromAscii( const char *str, size_t n );
 161     /**
 162        Assignment from a UTF-8 string literal
 163     */
 164     wxUString &assignFromUTF8( const char *str );
 165     /**
 166        Assignment from a UTF-8 string literal
 167     */
 168     wxUString &assignFromUTF8( const char *str, size_t n );
 169     /**
 170        Assignment from a UTF-16 string literal
 171     */
 172     wxUString &assignFromUTF16( const wxChar16* str );
 173     /**
 174        Assignment from a UTF-16 string literal
 175     */
 176     wxUString &assignFromUTF16( const wxChar16* str, size_t n );
 177     /**
 178        Assignment from a C string literal using wxConvLibc
 179     */
 180     wxUString &assignFromCString( const char* str );
 181     /**
 182        Assignment from a C string literal using @a conv
 183     */
 184     wxUString &assignFromCString( const char* str, const wxMBConv &conv );
 185
 186     /**
 187         Conversion to a UTF-8 string
 188     */
 189     wxCharBuffer utf8_str() const;
 190     /**
 191         Conversion to a UTF-16 string
 192     */
 193     wxU16CharBuffer utf16_str() const;
 194
 195     /**
 196         Conversion to a wide character string (either UTF-16
 197         or UCS-4, depending on the size of wchar_t).
 198     */
 199     wxWCharBuffer wc_str() const;
 200
 201     /**
 202        Implicit conversion to wxString.
 203     */
 204     operator wxString() const;
 205
 206     /**
 207        wxUString assignment. wxUString additionally provides overloads for
 208        wxString, C string, UTF-16 strings, 32-bit strings, char buffers,
 209        single and repeated characters etc.
 210     */
 211     wxUString &assign( const wxUString &str );
 212
 213     /**
 214        Appending. wxUString additionally provides overloads for
 215        wxString, C string, UTF-16 strings, 32-bit strings, char buffers,
 216        single and repeated characters etc.
 217     */
 218     wxUString &append( const wxUString &s );
 219
 220     /**
 221        Insertion. wxUString additionally provides overloads for
 222        wxString, C string, UTF-16 strings, 32-bit strings, char buffers,
 223        single characters etc.
 224     */
 225     wxUString &insert( size_t pos, const wxUString &s );
 226
 227     /**
 228        Assignment operator. wxUString additionally provides overloads for
 229        wxString, C string, UTF-16 strings, 32-bit strings, char buffers,
 230        single characters etc.
 231     */
 232     inline wxUString& operator=(const wxUString& s);
 233
 234     /**
 235        Concatenation operator. wxUString additionally provides overloads for
 236        wxString, C string, UTF-16 strings, 32-bit strings, char buffers,
 237        single characters etc.
 238     */
 239     inline wxUString& operator+=(const wxUString& s);
 240
 241 };
 242
 243     /**
 244        Concatenation operator. wxUString additionally provides overloads for
 245        wxString, C string, UTF-16 strings, 32-bit strings, char buffers,
 246        single characters etc.
 247     */
 248 inline wxUString operator+(const wxUString &s1, const wxUString &s2);
 249
 250     /**
 251        Equality operator. wxUString additionally provides overloads for
 252        wxString, C string, UTF-16 strings, 32-bit strings, char buffers,
 253        single characters etc.
 254     */
 255 inline bool operator==(const wxUString& s1, const wxUString& s2);
 256     /**
 257        Inequality operator. wxUString additionally provides overloads for
 258        wxString, C string, UTF-16 strings, 32-bit strings, char buffers,
 259        single characters etc.
 260     */
 261 inline bool operator!=(const wxUString& s1, const wxUString& s2);
 262     /**
 263        Comparison operator. wxUString additionally provides overloads for
 264        wxString, C string, UTF-16 strings, 32-bit strings, char buffers,
 265        single characters etc.
 266     */
 267 inline bool operator< (const wxUString& s1, const wxUString& s2);
 268     /**
 269        Comparison operator. wxUString additionally provides overloads for
 270        wxString, C string, UTF-16 strings, 32-bit strings, char buffers,
 271        single characters etc.
 272     */
 273 inline bool operator> (const wxUString& s1, const wxUString& s2);
 274     /**
 275        Comparison operator. wxUString additionally provides overloads for
 276        wxString, C string, UTF-16 strings, 32-bit strings, char buffers,
 277        single characters etc.
 278     */
 279 inline bool operator<=(const wxUString& s1, const wxUString& s2);
 280     /**
 281        Comparison operator. wxUString additionally provides overloads for
 282        wxString, C string, UTF-16 strings, 32-bit strings, char buffers,
 283        single characters etc.
 284     */
 285 inline bool operator>=(const wxUString& s1, const wxUString& s2);