Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

moved many things from wxString reference page to the wxString overview; updated some old/incoherent informations; added some DIA-drawn graphs showing UTF8/UCS2 different representation used by wxString

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@57140 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Francesco Montorsi
2008-12-06 16:24:52 +00:00
parent e215c9959c
commit 727aa9062b
8 changed files with 292 additions and 168 deletions
Download Patch File Download Diff File Expand all files Collapse all files

227
interface/wx/string.h
View File

@@ -6,59 +6,6 @@
// Licence: wxWindows license
/////////////////////////////////////////////////////////////////////////////
/**
@class wxStringBuffer
This tiny class allows you to conveniently access the wxString internal buffer
as a writable pointer without any risk of forgetting to restore the string
to the usable state later.
For example, assuming you have a low-level OS function called
@c "GetMeaningOfLifeAsString(char *)" returning the value in the provided
buffer (which must be writable, of course) you might call it like this:
@code
wxString theAnswer;
GetMeaningOfLifeAsString(wxStringBuffer(theAnswer, 1024));
if ( theAnswer != "42" )
wxLogError("Something is very wrong!");
@endcode
Note that the exact usage of this depends on whether or not wxUSE_STL is
enabled. If wxUSE_STL is enabled, wxStringBuffer creates a separate empty
character buffer, and if wxUSE_STL is disabled, it uses GetWriteBuf() from
wxString, keeping the same buffer wxString uses intact. In other words,
relying on wxStringBuffer containing the old wxString data is not a good
idea if you want to build your program both with and without wxUSE_STL.
@library{wxbase}
@category{data}
*/
class wxStringBuffer
{
public:
/**
Constructs a writable string buffer object associated with the given string
and containing enough space for at least @a len characters.
Basically, this is equivalent to calling wxString::GetWriteBuf() and
saving the result.
*/
wxStringBuffer(const wxString& str, size_t len);
/**
Restores the string passed to the constructor to the usable state by calling
wxString::UngetWriteBuf() on it.
*/
~wxStringBuffer();
/**
Returns the writable pointer to a buffer of the size at least equal to the
length specified in the constructor.
*/
wxStringCharType* operator wxStringCharType *();
};
/**
@class wxString
@@ -68,66 +15,29 @@ public:
version wxWidgets 3.0.
wxString is a class representing a Unicode character string.
wxString uses @c std::string internally to store its content
unless this is not supported by the compiler or disabled
specifically when building wxWidgets and it therefore inherits
many features from @c std::string. Most implementations of
@c std::string are thread-safe and don't use reference counting.
By default, wxString uses @c std::string internally even if
wxUSE_STL is not defined.
wxString uses @c std::basic_string internally (even if @c wxUSE_STL is not defined)
to store its content (unless this is not supported by the compiler or disabled
specifically when building wxWidgets) and it therefore inherits
many features from @c std::basic_string. (Note that most implementations of
@c std::basic_string are thread-safe and don't use reference counting.)
wxString now internally uses UTF-16 under Windows and UTF-8 under
Unix, Linux and OS X to store its content. Note that when iterating
over a UTF-16 string under Windows, the user code has to take care
of surrogate pair handling whereas Windows itself has built-in
support pairs in UTF-16, such as for drawing strings on screen.
Much work has been done to make existing code using ANSI string literals
work as before. If you nonetheless need to have a wxString that uses wchar_t
on Unix and Linux, too, you can specify this on the command line with the
@c configure @c --disable-utf8 switch or you can consider using wxUString
or std::wstring instead.
Accessing a UTF-8 string by index can be very inefficient because
a single character is represented by a variable number of bytes so that
the entire string has to be parsed in order to find the character.
Since iterating over a string by index is a common programming technique and
was also possible and encouraged by wxString using the access operator[]()
wxString implements caching of the last used index so that iterating over
a string is a linear operation even in UTF-8 mode.
It is nonetheless recommended to use iterators (instead of index based
access) like this:
@code
wxString s = "hello";
wxString::const_iterator i;
for (i = s.begin(); i != s.end(); ++i)
{
wxUniChar uni_ch = *i;
// do something with it
}
@endcode
Please see the @ref overview_string and the @ref overview_unicode for more
information about it.
wxString uses the current locale encoding to convert any C string
literal to Unicode. The same is done for converting to and from
@c std::string and for the return value of c_str().
For this conversion, the @a wxConvLibc class instance is used.
See wxCSConv and wxMBConv.
wxString implements most of the methods of the @c std::string class.
These standard functions are only listed here, but they are not
fully documented in this manual. Please see the STL documentation.
These @c std::basic_string standard functions are only listed here, but
they are not fully documented in this manual; see the STL documentation
(http://www.cppreference.com/wiki/string/start) for more info.
The behaviour of all these functions is identical to the behaviour
described there.
You may notice that wxString sometimes has several functions which do
the same thing like Length(), Len() and length() which
all return the string length. In all cases of such duplication the
@c std::string compatible method should be used.
the same thing like Length(), Len() and length() which all return the
string length. In all cases of such duplication the @c std::string
compatible methods should be used.
For informations about the internal encoding used by wxString and
for important warnings and advices for using it, please read
the @ref overview_string.
In wxWidgets 3.0 wxString always stores Unicode strings, so you should
be sure to read also @ref overview_unicode.
@section string_construct Constructors and assignment operators
@@ -229,6 +139,7 @@ public:
original string is not modified and the function returns the extracted
substring.
@li at()
@li substr()
@li Mid()
@li operator()()
@@ -1344,14 +1255,6 @@ public:
STL reference for their documentation.
*/
//@{
size_t length() const;
size_type size() const;
size_type max_size() const;
size_type capacity() const;
void reserve(size_t sz);
void resize(size_t nSize, wxUniChar ch = '\0');
wxString& append(const wxString& str, size_t pos, size_t n);
wxString& append(const wxString& str);
wxString& append(const char *sz, size_t n);
@@ -1366,8 +1269,13 @@ public:
wxString& assign(size_t n, wxUniChar ch);
wxString& assign(const_iterator first, const_iterator last);
wxUniChar at(size_t n) const;
wxUniCharRef at(size_t n);
void clear();
size_type capacity() const;
int compare(const wxString& str) const;
int compare(size_t nStart, size_t nLen, const wxString& str) const;
int compare(size_t nStart, size_t nLen,
@@ -1377,6 +1285,8 @@ public:
int compare(size_t nStart, size_t nLen,
const wchar_t* sz, size_t nCount = npos) const;
wxCStrData data() const;
bool empty() const;
wxString& erase(size_type pos = 0, size_type n = npos);
@@ -1387,6 +1297,28 @@ public:
size_t find(const char* sz, size_t nStart = 0, size_t n = npos) const;
size_t find(const wchar_t* sz, size_t nStart = 0, size_t n = npos) const;
size_t find(wxUniChar ch, size_t nStart = 0) const;
size_t find_first_of(const char* sz, size_t nStart = 0) const;
size_t find_first_of(const wchar_t* sz, size_t nStart = 0) const;
size_t find_first_of(const char* sz, size_t nStart, size_t n) const;
size_t find_first_of(const wchar_t* sz, size_t nStart, size_t n) const;
size_t find_first_of(wxUniChar c, size_t nStart = 0) const
size_t find_last_of (const wxString& str, size_t nStart = npos) const
size_t find_last_of (const char* sz, size_t nStart = npos) const;
size_t find_last_of (const wchar_t* sz, size_t nStart = npos) const;
size_t find_last_of(const char* sz, size_t nStart, size_t n) const;
size_t find_last_of(const wchar_t* sz, size_t nStart, size_t n) const;
size_t find_last_of(wxUniChar c, size_t nStart = npos) const
size_t find_first_not_of(const wxString& str, size_t nStart = 0) const
size_t find_first_not_of(const char* sz, size_t nStart = 0) const;
size_t find_first_not_of(const wchar_t* sz, size_t nStart = 0) const;
size_t find_first_not_of(const char* sz, size_t nStart, size_t n) const;
size_t find_first_not_of(const wchar_t* sz, size_t nStart, size_t n) const;
size_t find_first_not_of(wxUniChar ch, size_t nStart = 0) const;
size_t find_last_not_of(const wxString& str, size_t nStart = npos) const
size_t find_last_not_of(const char* sz, size_t nStart = npos) const;
size_t find_last_not_of(const wchar_t* sz, size_t nStart = npos) const;
size_t find_last_not_of(const char* sz, size_t nStart, size_t n) const;
size_t find_last_not_of(const wchar_t* sz, size_t nStart, size_t n) const;
wxString& insert(size_t nPos, const wxString& str);
wxString& insert(size_t nPos, const wxString& str, size_t nStart, size_t n);
@@ -1397,6 +1329,13 @@ public:
void insert(iterator it, const_iterator first, const_iterator last);
void insert(iterator it, size_type n, wxUniChar ch);
size_t length() const;
size_type max_size() const;
void reserve(size_t sz);
void resize(size_t nSize, wxUniChar ch = '\0');
wxString& replace(size_t nStart, size_t nLen, const wxString& str);
wxString& replace(size_t nStart, size_t nLen, size_t nCount, wxUniChar ch);
wxString& replace(size_t nStart, size_t nLen,
@@ -1423,12 +1362,10 @@ public:
size_t rfind(const wchar_t* sz, size_t nStart = npos, size_t n = npos) const;
size_t rfind(wxUniChar ch, size_t nStart = npos) const;
size_type size() const;
wxString substr(size_t nStart = 0, size_t nLen = npos) const;
void swap(wxString& str);
//@}
};
/**
@@ -1510,3 +1447,55 @@ public:
wxChar* operator wxChar *();
};
/**
@class wxStringBuffer
This tiny class allows you to conveniently access the wxString internal buffer
as a writable pointer without any risk of forgetting to restore the string
to the usable state later.
For example, assuming you have a low-level OS function called
@c "GetMeaningOfLifeAsString(char *)" returning the value in the provided
buffer (which must be writable, of course) you might call it like this:
@code
wxString theAnswer;
GetMeaningOfLifeAsString(wxStringBuffer(theAnswer, 1024));
if ( theAnswer != "42" )
wxLogError("Something is very wrong!");
@endcode
Note that the exact usage of this depends on whether or not @c wxUSE_STL is
enabled. If @c wxUSE_STL is enabled, wxStringBuffer creates a separate empty
character buffer, and if @c wxUSE_STL is disabled, it uses GetWriteBuf() from
wxString, keeping the same buffer wxString uses intact. In other words,
relying on wxStringBuffer containing the old wxString data is not a good
idea if you want to build your program both with and without @c wxUSE_STL.
@library{wxbase}
@category{data}
*/
class wxStringBuffer
{
public:
/**
Constructs a writable string buffer object associated with the given string
and containing enough space for at least @a len characters.
Basically, this is equivalent to calling wxString::GetWriteBuf() and
saving the result.
*/
wxStringBuffer(const wxString& str, size_t len);
/**
Restores the string passed to the constructor to the usable state by calling
wxString::UngetWriteBuf() on it.
*/
~wxStringBuffer();
/**
Returns the writable pointer to a buffer of the size at least equal to the
length specified in the constructor.
*/
wxStringCharType* operator wxStringCharType *();
};