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