From 99f09bc1b9cbc93a6cc952ec2c777d999d5483d0 Mon Sep 17 00:00:00 2001 From: Vadim Zeitlin Date: Wed, 24 Feb 1999 23:53:40 +0000 Subject: [PATCH] wxString docs are nearly complete (but don't compile :-( ), a brief threads overview git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@1781 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/latex/wx/ignore.txt | 3 +- docs/latex/wx/log.tex | 4 +- docs/latex/wx/tstring.tex | 263 +++++++++++++++++- docs/latex/wx/tthreads.tex | 36 ++- docs/latex/wx/wxstring.tex | 531 +++++++++++++++++++++++++++++++++---- 5 files changed, 783 insertions(+), 54 deletions(-) diff --git a/docs/latex/wx/ignore.txt b/docs/latex/wx/ignore.txt index 20069ee692..2d5a620e5e 100644 --- a/docs/latex/wx/ignore.txt +++ b/docs/latex/wx/ignore.txt @@ -3,4 +3,5 @@ wxCursorRefData wxCursor::SetHCURSOR wxCursor::GetHCURSOR -wxCursor::FreeResource \ No newline at end of file +wxCursor::FreeResource +wxStringData \ No newline at end of file diff --git a/docs/latex/wx/log.tex b/docs/latex/wx/log.tex index 8d3a6e6e4f..08cfb53714 100644 --- a/docs/latex/wx/log.tex +++ b/docs/latex/wx/log.tex @@ -28,7 +28,7 @@ No base class \membersection{Static functions} The functions in this section work with and manipulate the active log target. -The {\it OnLog()} is called by the {\it wxLogXXX()} functions and invokes the +The {\it OnLog()} is called by the {\it wxLogXXX()} functions and invokes the {\it DoLog()} of the active log target if any. Get/Set methods are used to install/query the current active target and, finally, {\it DontCreateOnDemand()} disables the automatic creation of a standard log target @@ -78,7 +78,7 @@ As for the (real) trace messages, they come in different kinds: The trace mask is a bit mask which tells which (if any) of these trace messages are going to be actually logged. For the trace message to appear -somewhere, all the bits in the mask used in the call to {\it wxLogTrace()} +somewhere, all the bits in the mask used in the call to {\it wxLogTrace()} function must be set in the current trace mask. For example, \begin{verbatim} wxLogTrace(wxTraceRefCount | wxTraceOle, "Active object ref count: %d", nRef); diff --git a/docs/latex/wx/tstring.tex b/docs/latex/wx/tstring.tex index 41b70d34bf..52bbe3af9e 100644 --- a/docs/latex/wx/tstring.tex +++ b/docs/latex/wx/tstring.tex @@ -1,6 +1,265 @@ \section{wxString overview}\label{wxstringoverview} -Classes: \helpref{wxString}{wxstring} +Classes: \helpref{wxString}{wxstring}, \helpref{wxArrayString}{wxarray}, \helpref{wxStringTokenizer}{wxstringtokenizer} -TODO. +\subsection{Introduction} + +wxString is a class which represents a character string of arbitrary (limited by +{\it MAX\_INT} which is usually 2147483647 on 32 bit machines) length and containing +arbitrary characters (i.e. ASCII NUL character is allowed, although care should be +taken when passing strings containing it to other functions). + +wxString only works with ASCII (8 bit characters) strings as of this release, +however support for UNICODE (16 but characters) is planned for the next one. + +This class has all standard operations you can expect to find in a string class: +dynamic memory management (string extends to accomodate new characters), +construction from other strings, C strings and characters, assignment operators, +access to separate characters, string concatenation and comparison, substring +extraction, case conversion, trimming and padding (with spaces), searching and +replacing and both C-like \helpref{Printf()}{wxstringprintf} and stream-like +insertion functions as well as much else - see \helpref{wxString}{wxstring} +for the list of all functions. + +\subsection{Comparison of wxString to other string classes} + +The advantages of using a special string class instead of working directly with +C strings are so obvious (the most imoprtant being, of course, the need to always +remember to allocate/free memory for C strings unless the programmer prefers +working with fixed size buffers which almost certainly leads to the dreaded +buffer overflows) that there is a huge number of such classes available and now, +finally, C++ even has one (std::string) in standard. Why use wxString then? + +There are several advantages: + +\begin{enumerate}\itemsep=0pt +\item {\bf Efficiency} {This class was made to be as efficient as possible: both +in terms of size (each wxString objects takes exactly the same place as {\it +char *} pointer, \helpref{reference counting}{wxstringrefcount}) and speed. +It also provides performance \helpref{statistics gathering code}{wxstringtuning} +which may be enabled to fine tune the memory allocation strategy for your +particular application - and the gain might be quite big.} +\item {\bf Compatibility} {This class tries to combine almost full compatibility +with the old wxWindows 1.xx wxString class, some reminiscence to MFC CString +class and 90\% of functionality of std::string class.} +\item {\bf Rich set of functions} {Some of the functions present in wxString are +very useful but don't exist in most of other string classes: for example, +\helpref{AfterFirst}{wxstringafterfirst}, +\helpref{BeforLast}{wxstringbeforlast}, \helpref{operator<<}{wxstringoperator} +or \helpref{Printf}{wxstringprintf}. Of course, all the standard string +operations are supported as well.} +\item {\bf UNICODE} {In this release, wxString only supports construction from +an UNICODE string, but in the next one it will be capable of also storing its +internal data in either ASCII or UNICODE format.} +\item {\bf Used by wxWindows} {And, of course, this class is used everywhere +inside wxWindows so there is no performance loss which would result from +conversions of objects of any other string class (including std::string) to +wxString internally by wxWindows.} +\end{enumerate} + +However, there are several problems as well. The most important one is probably +that there are often several functions to do exactly the same thing: for +example, to get the length of the string either one of +\helpref{length()}{wxstringlength}, \helpref{Len()}{wxstringlen} or +\helpref{Length()}{wxstringLength} may be used. The first function, as almost +all the other functions in lowercase, is std::string compatible. The second one +is "native" wxString version and the last one is wxWindows 1.xx way. So the +question is: which one is better to use? And the answer is that: + +{\bf The usage of std::string compatible functions is strongly advised!} It will +both make your code more familiar to other C++ programmers (who are supposed to +have knowledge of std::string but not of wxString), let you reuse the same code +in both wxWindows and other programs (by just typedefing wxString as std::string +when used outside wxWindows) and by staying compatible with future versions of +wxWindows which will probably start using std::string sooner or later too. + +In the situations when there is no correspondinw std::string function, please +try to use the new wxString methods and not the old wxWindows 1.xx variants +which are deprecated and risk to disappear in future versions. + +\subsection{Some advices about using wxString}\label{wxstringadvices} + +Probably main trap with using this class is the implicit conversion operator to +{\it const char *}. It is advised that you use \helpref{c\_str()}{wxstringcstr} +instead of it to clearly indicate when the conversion is done. Specifically, the +danger of this implicit conversion may be seen in the following code fragment: + +\begin{verbatim} + +// this function converts the input string to uppercase, output it to the screen +// and returns the result +const char *SayHELLO(const wxString& input) +{ + wxString output = input.Upper(); + + printf("Hello, %s!\n", output); + + return output; +} + +\end{verbatim} + +There are two nasty bugs in these three lines. First of them is in the call to +{\it printf()} function. Although the implicit conversion to C strings is applied +automatically by the compiler in case of + +\begin{verbatim} + puts(output); +\end{verbatim} + +because the argument of {\it puts()} is known to be of the type {\it const char +*}, this is {\bf not} done for {\it printf()} which is a function with variable +number of arguments (and whose arguments are of unknown types). So this call may +do anything at all (including displaying the correct string on screen), although +the most likely result is a program crash. The solution is to use +\helpref{c\_str()}{wxstringcstr}: just replace this line with + +\begin{verbatim} + printf("Hello, %s!\n", output.c_str()); +\end{verbatim} + +The second bug is that returning {\it output} doesn't work. The implicit cast is +used again, so the code compiles, but as it returns a pointer to a buffer +belonging to a local variable which is deleted as soon as the function exits, +its contents is totally arbitrary. The solution to this problem is also easy: +just make the function return wxString instead of C string. + +This leads us to the following general advice: all functions taking string +arguments should take {\it const wxString\&} (this makes assignment to the +strings inside the function faster because of +\helpref{reference counting}{wxstringrefcount}) and all functions returning +strings should return {\it wxString} - this makes it safe to return local +variables. + +\subsection{Other string related functions and classes} + +As any program operates with character strings, the standard C library provides quite a +few of functions to work with them. Unfortunately, some of them have rather non +intuitive behaviour (like strncpy() which doesn't always terminate the resulting +string with a NUL) and are in general not very safe (passing NULL to them will +probably lead to program crash). Moreover, some of very useful functions are not +standard at all. This is why in addition to all wxString functions, there are +also a few of global string functions which try to correct these problems: +\helpref{IsEmpty()}{isempty} verifies whether the string is empty (returning +TRUE for NULL pointers), \helpref{Strlen()}{strlen} also handles NULLs correctly +and returns 0 for them and \helpref{Stricmp()}{stricmp} is just a +platform-independent version of case-insensitive string comparison function +known either as stricmp() or strcasecmp() on different platforms. + +There is another class which might be useful when working with wxString: +\helpref{wxStringTokenizer}{wxstringtokenizer}. It is helpful when a string must +be broken into tokens and replaces advatageously the standard C library {\it +strtok()} function. + +And the very last string related class is \helpref{wxArrayString}{wxarray}: it +is just a version of "template" dynamic array class which is specialized to work +with strings. Please note that this class is specially optimized (it uses its +knowledge of internal structure of wxString) for storing strigns and so it is +vastly better from performance point of view than wxObjectArray of wxString. + +\subsection{Reference counting and why you shouldn't care about it}\label{wxstringrefcount} + +wxString objects use a technique known as {\it copy on write} (COW). This means +that when a string is assigned to another, no copying really takes place: only +the reference count on the shared string data is increased and both strings +share the same data. + +But as soon as one of the two (or more) strings is modified, the data has to be +copied because the changes to one of the strings shouldn't be seen in the +otheres. As data copying only happens when the string is written to, this is +known as COW. + +What is important to understand is that all this happens absolutely +transparently to the class users and that whether a string is shared or not is +not seen from the outside of the class - in any case, the result of any +operation on it is the same. + +Probably the unique case when you might want to think about reference +counting is when a string character is taken from a string which is not a +constant (or a constant reference). In this case, due to C++ rules, the +"read-only" {\it operator[]} (which is the same as +\helpref{GetChar()}{wxstringgetchar}) cannot be chosen and the "read/write" +{\it operator[]} (the same as +\helpref{GetWritableChar()}{wxstringgetwritablechar}) is used instead. As the +call to this operator may modify the string, its data is unshared (COW is done) +and so if the string was really shared there is some performance loss (both in +terms of speed and memory consumption). In the rare cases when this may be +important, you might prefer using \helpref{GetChar()}{wxstringgetchar} instead +of array subscript operator for this reasons. Please note that +\helpref{at()}{wxstringat} method has the same problem as subscript operator in +this situation and so using it is not really better. Also note that if all +string arguments to your functions are passed as {\it const wxString\&} (see the +section \helpref{Some advices}{wxstringadvices}) this situation will almost +never arise because for constant references the correct operator is called automatically. + +\subsection{Tuning wxString for your application}\label{wxstringtuning} + +\normalbox{{\bf Note:} this section is strictly about performance issues and is +absolutely not necessary to read for using wxString class. Please skip it unless +you feel familiar with profilers and relative tools. If you do read it, please +also read the preceding section about +\helpref{reference counting}{wxstringrefcounting}.} + +For the performance reasons wxString doesn't allocate exactly the amount of +memory needed for each string. Instead, it adds a small amount of space to each +allocated block which allows it to not reallocate memory (this is a relatively +expensive operation) too often as when, for example, a string is constructed by +subsequently adding one character at a time to it, as for example in: + +\begin{verbatim} + +// delete all vowels from the string +wxString DeleteAllVowels(const wxString& original) +{ + wxString result; + + size_t len = original.length(); + for ( size_t n = 0; n < len; n++ ) + { + if ( strchr("aeuio", tolower(original[n])) == NULL ) + result += original[n]; + } + + return result; +} + +\end{verbatim} + +This is a quite common situation and not allocating extra memory at all would +lead to very bad performance in this case because there would be as many memory +(re)allocations as there are consonants in the original string. Allocating too +much extra memory would help to improve the speed in this situation, but due to +a great number of wxString objects typically used in a program would also +increase the memory consumption too much. + +The very best solution in precisely this case would be to use +\helpref{Alloc()}{wxstringalloc} function to preallocate, for example, len bytes +from the beginning - this will lead to exactly one memory allocation being +performed (because the result is at most as long as the original string). + +However, using Alloc() is tedious and so wxString tries to do its best. The +default algorithm assumes that memory allocation is done in granularity of at +least 16 bytes (which is the case on almost all of wide-spread platforms) and so +nothing is lost if the amount of memory to allocate is rounded up to the next +multiple of 16. Like this, no memory is lost and 15 iterations from 16 in the +example above won't allocate memory but use the already allocated pool. + +The default approach is quite conservative. Allocating more memory may bring +important performance benefits for programs using (relatively) few very long +strings. The amount of memory allocated is configured by the setting of {\it +EXTRA\_ALLOC} in the file string.cpp during compilation (be sure to understand +why its default value is what it is before modifying it!). You may try setting +it to greater amount (say twice nLen) or to 0 (to see performance degradation +which will follow) and analyse the impact of it on your program. If you do it, +you will probably find it helpful to also define WXSTRING\_STATISTICS symbol +which tells the wxString class to collect performance statistics and to show +them on stderr on program termination. This will show you the average length of +strings your program manipulates, their average initial length and also the +percent of times when memory wasn't reallocated when string concatenation was +done but the alread preallocated memory was used (this value should be about +98\% for the default allocation policy, if it is less than 90\% you should +really consider fine tuning wxString for your application). + +It goes without saying that a profiler should be used to measure the precise +difference the change to EXTRA\_ALLOC makes to your program. diff --git a/docs/latex/wx/tthreads.tex b/docs/latex/wx/tthreads.tex index 42234f0ad9..a034599c70 100644 --- a/docs/latex/wx/tthreads.tex +++ b/docs/latex/wx/tthreads.tex @@ -4,5 +4,39 @@ Classes: \helpref{wxThread}{wxthread}, \helpref{wxMutex}{wxmutex}, \helpref{wxCriticalSection}{wxcriticalsection}, \helpref{wxCondition}{wxcondition} -TODO +wxWindows provides a complete set of classes encapsulating objects necessary in +multithreaded (MT) programs: the \helpref{thread}{wxthread} class itself and different +synchronization objects: \helpref{mutexes}{wxmutex} and +\helpref{critical sections}{wxcriticalsection} with +\helpref{conditions}{wxcondition}. +These classes will hopefully make writing MT programs easier and they also +provide some extra error checking (compared to the native (be it Win32 or Posix) +thread API), however it is still an untrivial undertaking especially for large +projects. Before starting an MT application (or starting to add MT features to +an existing one) it is worth asking oneself if there is no easier and safer way +to implement the same functionality. Of course, in some situations threads +really make sense (classical example is a server application which launches a +new thread for each new client), but in others it might be a very poor choice +(example: launching a separate thread when doing a long computation to show a +progress dialog). Other implementation choices are available: for the progress +dialog example it is far better to do the calculations in the +\helpref{idle handler}{wxidleevent} or call \helpref{wxYield()}{wxyield} +periodically to update the screen. + +If you do decide to use threads in your application, it is strongly recommended +that no more than one thread calls GUI functions. The thread sample shows that +it {\it is} possible for many different threads to call GUI functions at once +(all the threads created in the sample access GUI), but it is a very poor design +choice for anything except an example. The design which uses one GUI thread and +several worker threads which communicate with the main one using events is much +more robust and will undoubtedly save you countless problems (example: under +Win32 a thread can only access GDI objects such as pens, brushes, \&c created by +itself and not by the other threads). + +Final note: in the current release of wxWindows, there are no specific +facilities for communicating between the threads. However, the usual +\helpref{ProcessEvent()}{wxevthandlerprocessevent} function may be used for +thread communication too - but you should provide your own synchronisation +mechanism if you use it (e.g. just use a critical section before sending a +message) because there is no built-in synchronisation. diff --git a/docs/latex/wx/wxstring.tex b/docs/latex/wx/wxstring.tex index 8491343e44..a70122b4ea 100644 --- a/docs/latex/wx/wxstring.tex +++ b/docs/latex/wx/wxstring.tex @@ -1,5 +1,13 @@ \section{\class{wxString}}\label{wxstring} +wxString is a class representing a character string. Please see wxString +\helpref{overview}{wxstringoverview} for more information about it. As explained +there, wxStrign implements about 90\% of methods of std::string class (iterators +are not supported and so all methods which use them are not supported neither), +but they are not documented here - please see any source of STL documentation. +The behaviour of all these functions is identical to the behaviour described +there. + \wxheading{Derived from} None @@ -12,7 +20,332 @@ None \overview{Overview}{wxstringoverview} -\latexignore{\rtfignore{\wxheading{Members}}} +\latexignore{\rtfignore{\wxheading{Function groups}}} + +\membersection{Constructors and assignment operators} + +A strign may be constructed either from a C string, (some number of copies of) +a single character or a wide (UNICODE) string. For all constructors (except the +default which creates an empty string) there is also a corresponding assignment +operator. + +\helpref{wxString}{wxstringconstruct}\\ +\helpref{operator $=$}{wxstringoperatorassign}\\ +\helpref{\destruct{wxString}}{wxstringdestruct} + +\membersection{String length} + +These functions return the string length and check whether the string is empty +or empty it. + +\helpref{Len}{wxstringlen}\\ +\helpref{IsEmpty}{wxstringisempty}\\ +\helpref{operator!}{wxstringoperatornot}\\ +\helpref{Empty}{wxstringempty}\\ +\helpref{Clear}{wxstringclear} + +\membersection{Character access} + +Many functions in this section take a character index in the string. As with C +strings and/or arrays, the indices start from $0$, so the first character of a +string is string[$0$]. Attempt to access a character beyond the end of the +string (which may be even $0$ if the string is empty) will provocate an assert +failure in \helpref{debug build}{debuggingoverview}, but no checks are done in +release builds. + +This section also contains both implicit and explicit conversions to C style +strings. Although implicit conversion is quite convenient, it is advised to use +explicit \helpref{c\_str()}{wxstringcstr} method for the sake of clarity. Also +see \helpref{overiview}{wxstringadvices} for the cases where it is necessary to +use it. + +\helpref{GetChar}{wxstringgetchar}\\ +\helpref{GetWritableChar}{wxstringgetwritablechar}\\ +\helpref{SetChar}{wxstringsetchar}\\ +\helpref{Last}{wxstringlast}\\ +\helpref{operator []}{wxstringoperatorbracket}\\ +\helpref{c\_str}{wxstringcstr}\\ +\helpref{operator const char*}{wxstringoperatorconstcharpt} + +\membersection{Concatenation} + +Anything may be concatenated (appended to) with a string. However, you can't +append something to a C string (including literal constants), so to do this it +should be converted to a wxString first. + +\helpref{operator \cinsert}{wxstringoperatorout}\\ +\helpref{operator $+=$}{wxstringplusequal}\\ +\helpref{operator $+$}{wxstringoperatorplus}\\ +\helpref{Append}{wxstringappend}\\ +\helpref{Prepend}{wxstringprepend} + +\membersection{Comparison} + +The default comparison function \helpref{Cmp}{wxstringcmp} is case-sensitive and +so is the default version of \helpref{IsSameAs}{wxstringissameas}. For case +insensitive comparisons you should use \helpref{CmpNoCase}{wxstringcmpnocase} or +give a second parameter to IsSameAs. This last function is may be more +convenient if only equality of the strings matters because it returns a boolean +true value if the strings are the same and not 0 (which is usually FALSE in C) +as Cmp does. + +\helpref{Matches}{wxstringmatches} is a poor man's regular expression matcher: +it only understands '*' and '?' metacharacters in the sense of DOS command line +interpreter. + +\helpref{Cmp}{wxstringcmp}\\ +\helpref{CmpNoCase}{wxstringcmpnocase}\\ +\helpref{IsSameAs}{wxstringissameas}\\ +\helpref{Matches}{wxstringmatches} + +\membersection{Substring extraction} + +These functions allow to extract substring from this string. All of them don't +modify the original string and return a new string containing the extracted +substring. + +\helpref{Mid}{wxstringmid}\\ +\helpref{operator()}{wxstringoperatorparenth}\\ +\helpref{Left}{wxstringleft}\\ +\helpref{Right}{wxstringright}\\ +\helpref{BeforeFirst}{wxstringbeforefirst}\\ +\helpref{BeforeLast}{wxstringbeforelast}\\ +\helpref{AfterFirst}{wxstringafterfirst}\\ +\helpref{AfterLast}{wxstringafterlast} + +\membersection{Case conversion} + +The MakeXXX() variants modify the string in place, while the other functions +return a new string which containts the original text converted to the upper or +lower case and leave the original string unchanged. + +\helpref{MakeUpper}{wxstringmakeupper}\\ +\helpref{Upper}{wxstringupper}\\ +\helpref{MakeLower}{wxstringmakelower}\\ +\helpref{Lower}{wxstringlower} + +\membersection{Searching and replacing} + +These functions replace the standard {\it strchr()} and {\it strstr()} +functions. + +\helpref{Find}{wxstringfind}\\ +\helpref{Replace}{wxstringreplace} + +\membersection{Writing values into the string} + +Both formatted versions (\helpref{Printf}{wxstringprintf}) and stream-like +insertion operators exist (for basic types only). + +\helpref{Printf}{wxstringprintf}\\ +\helpref{PrintfV}{wxstringprintfv}\\ +\helpref{operator \cinsert}{wxstringoperatorout) + +\membersection{Memory management} + +These are "advanced" functions and they will be needed quite rarily. +\helpref{Alloc}{wxstringalloc} and \helpref{Shrink}{wxstringshrink} are only +interesting for optimization purposes. +\helpref{GetWriteBuf}{wxstringgetwritebuf} may be very useful when working with +some external API which requires the caller to provide a writable buffer, but +extreme care should be taken when using it: before performing any other +operation on the string \helpref{UngetWriteBuf}{wxstringungetwritebuf} {\bf +must} be called! + +\helpref{Alloc}{wxstringalloc}\\ +\helpref{Shrink}{wxstringshrink}\\ +\helpref{GetWriteBuf}{wxstringgetwritebuf}\\ +\helpref{UngetWriteBuf}{wxstringungetwritebuf} + +\membersection{Miscellaneous} + +Other string functions. + +\helpref{Trim}{wxstringtrim}\\ +\helpref{Pad}{wxstringpad}\\ +\helpref{Truncate}{wxstringtruncate} + +\membersection{wxWindows 1.xx compatiblity functions} + +These functiosn are deprecated, please consider using new wxWindows 2.0 +functions instead of them (or, even better, std::string compatible variants). + +\helpref{SubString}{wxstringsubstring}\\ +\helpref{sprintf}{wxstringsprintf}\\ +\helpref{CompareTo}{wxstringcompareto}\\ +\helpref{Length}{wxstringlength}\\ +\helpref{Freq}{wxstringfreq}\\ +\helpref{LowerCase}{wxstringlowercase}\\ +\helpref{UpperCase}{wxstringuppercase}\\ +\helpref{Strip}{wxstringstrip}\\ +\helpref{Index}{wxstringindex}\\ +\helpref{Remove}{wxstringremove}\\ +\helpref{First}{wxstringfirst}\\ +\helpref{Last}{wxstringlast}\\ +\helpref{Contains}{wxstringcontains}\\ +\helpref{IsNull}{wxstringisnull}\\ +\helpref{IsAscii}{wxstringisascii}\\ +\helpref{IsNumber}{wxstringisnumber}\\ +\helpref{IsWord}{wxstringisword} + +\membersection{std::string compatibility functions} + +The supported functions are only listed here, please see any STL reference for +their documentation. + +\begin{verbatim} + // take nLen chars starting at nPos + wxString(const wxString& str, size_t nPos, size_t nLen); + // take all characters from pStart to pEnd (poor man's iterators) + wxString(const void *pStart, const void *pEnd); + + // lib.string.capacity + // return the length of the string + size_t size() const; + // return the length of the string + size_t length() const; + // return the maximum size of the string + size_t max_size() const; + // resize the string, filling the space with c if c != 0 + void resize(size_t nSize, char ch = '\0'); + // delete the contents of the string + void clear(); + // returns true if the string is empty + bool empty() const; + + // lib.string.access + // return the character at position n + char at(size_t n) const; + // returns the writable character at position n + char& at(size_t n); + + // lib.string.modifiers + // append a string + wxString& append(const wxString& str); + // append elements str[pos], ..., str[pos+n] + wxString& append(const wxString& str, size_t pos, size_t n); + // append first n (or all if n == npos) characters of sz + wxString& append(const char *sz, size_t n = npos); + + // append n copies of ch + wxString& append(size_t n, char ch); + + // same as `this_string = str' + wxString& assign(const wxString& str); + // same as ` = str[pos..pos + n] + wxString& assign(const wxString& str, size_t pos, size_t n); + // same as `= first n (or all if n == npos) characters of sz' + wxString& assign(const char *sz, size_t n = npos); + // same as `= n copies of ch' + wxString& assign(size_t n, char ch); + + // insert another string + wxString& insert(size_t nPos, const wxString& str); + // insert n chars of str starting at nStart (in str) + wxString& insert(size_t nPos, const wxString& str, size_t nStart, size_t n); + + // insert first n (or all if n == npos) characters of sz + wxString& insert(size_t nPos, const char *sz, size_t n = npos); + // insert n copies of ch + wxString& insert(size_t nPos, size_t n, char ch); + + // delete characters from nStart to nStart + nLen + wxString& erase(size_t nStart = 0, size_t nLen = npos); + + // replaces the substring of length nLen starting at nStart + wxString& replace(size_t nStart, size_t nLen, const char* sz); + // replaces the substring with nCount copies of ch + wxString& replace(size_t nStart, size_t nLen, size_t nCount, char ch); + // replaces a substring with another substring + wxString& replace(size_t nStart, size_t nLen, + const wxString& str, size_t nStart2, size_t nLen2); + // replaces the substring with first nCount chars of sz + wxString& replace(size_t nStart, size_t nLen, + const char* sz, size_t nCount); + + // swap two strings + void swap(wxString& str); + + // All find() functions take the nStart argument which specifies the + // position to start the search on, the default value is 0. All functions + // return npos if there were no match. + + // find a substring + size_t find(const wxString& str, size_t nStart = 0) const; + + // find first n characters of sz + size_t find(const char* sz, size_t nStart = 0, size_t n = npos) const; + + // find the first occurence of character ch after nStart + size_t find(char ch, size_t nStart = 0) const; + + // rfind() family is exactly like find() but works right to left + + // as find, but from the end + size_t rfind(const wxString& str, size_t nStart = npos) const; + + // as find, but from the end + size_t rfind(const char* sz, size_t nStart = npos, + size_t n = npos) const; + // as find, but from the end + size_t rfind(char ch, size_t nStart = npos) const; + + // find first/last occurence of any character in the set + + // + size_t find_first_of(const wxString& str, size_t nStart = 0) const; + // + size_t find_first_of(const char* sz, size_t nStart = 0) const; + // same as find(char, size_t) + size_t find_first_of(char 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* s, size_t nStart = npos) const; + // same as rfind(char, size_t) + size_t find_last_of (char c, size_t nStart = npos) const; + + // find first/last occurence of any character not in the set + + // + size_t find_first_not_of(const wxString& str, size_t nStart = 0) const; + // + size_t find_first_not_of(const char* s, size_t nStart = 0) const; + // + size_t find_first_not_of(char 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* s, size_t nStart = npos) const; + // + size_t find_last_not_of(char ch, size_t nStart = npos) const; + + // All compare functions return a negative, zero or positive value + // if the [sub]string is less, equal or greater than the compare() argument. + + // just like strcmp() + int compare(const wxString& str) const; + // comparison with a substring + int compare(size_t nStart, size_t nLen, const wxString& str) const; + // comparison of 2 substrings + int compare(size_t nStart, size_t nLen, + const wxString& str, size_t nStart2, size_t nLen2) const; + // just like strcmp() + int compare(const char* sz) const; + // substring comparison with first nCount characters of sz + int compare(size_t nStart, size_t nLen, + const char* sz, size_t nCount = npos) const; + + // substring extraction + wxString substr(size_t nStart = 0, size_t nLen = npos) const; +\end{verbatim} + +%%%%% MEMBERS HERE %%%%% +\helponly{\insertatlevel{2}{ + +\wxheading{Members} + +}} \membersection{wxString::wxString}\label{wxstringconstruct} @@ -28,15 +361,15 @@ Copy constructor. Constructs a string of {\it n} copies of character {\it ch}. -\func{}{wxString}{\param{const char*}{ psz}, \param{size\_t}{ nLength = STRING\_MAXLEN}} +\func{}{wxString}{\param{const char*}{ psz}, \param{size\_t}{ nLength = wxSTRING\_MAXLEN}} Takes first {\it nLength} characters from the C string {\it psz}. -The default value of STRING\_MAXLEN means take all the string. +The default value of wxSTRING\_MAXLEN means take all the string. -\func{}{wxString}{\param{const unsigned char*}{ psz}, \param{size\_t}{ nLength = STRING\_MAXLEN}} +\func{}{wxString}{\param{const unsigned char*}{ psz}, \param{size\_t}{ nLength = wxSTRING\_MAXLEN}} For compilers using unsigned char: takes first {\it nLength} characters from the C string {\it psz}. -The default value of STRING\_MAXLEN means take all the string. +The default value of wxSTRING\_MAXLEN means take all the string. \func{}{wxString}{\param{const wchar\_t*}{ psz}} @@ -48,13 +381,44 @@ Constructs a string from the wide (UNICODE) string. String destructor. Note that this is not virtual, so wxString must not be inherited from. -\membersection{wxString::Alloc}\label{wxstringAlloc} +\membersection{wxString::Alloc}\label{wxstringalloc} + +\func{void}{Alloc}{\param{size\_t}{ nLen}} + +Preallocate enough space for wxString to store {\it nLen} characters. This function +may be used to increase speed when the string is constructed by repeated +concatenation as in + +\begin{verbatim} -\func{void}{Alloc}{\param{uint}{ newsize}} +// delete all vowels from the string +wxString DeleteAllVowels(const wxString& original) +{ + wxString result; -Preallocate some space for wxString. Only works if the data of this string is not shared. + size_t len = original.length(); -\membersection{wxString::Append}\label{wxstringAppend} + result.Alloc(len); + + for ( size_t n = 0; n < len; n++ ) + { + if ( strchr("aeuio", tolower(original[n])) == NULL ) + result += original[n]; + } + + return result; +} + +\end{verbatim} + +because it will avoid the need of reallocating string memory many times (in case +of long strings). Note that it does not set the maximal length of a string - it +will still expand if more than {\it nLen} characters are stored in it. Also, it +does not truncate the existing string (use +\helpref{Truncate()}{wxstringtruncate} for this) even if its current length is +greater than {\it nLen} + +\membersection{wxString::Append}\label{wxstringappend} \func{wxString\&}{Append}{\param{const char*}{ psz}} @@ -65,19 +429,33 @@ Concatenates {\it psz} to this string, returning a reference to it. Concatenates character {\it ch} to this string, {\it count} times, returning a reference to it. -\membersection{wxString::After}\label{wxstringAfter} +\membersection{wxString::AfterFirst}\label{wxstringafterfirst} -\constfunc{wxString}{After}{\param{char}{ ch}} +\constfunc{wxString}{AfterFirst}{\param{char}{ ch}} Gets all the characters after the first occurence of {\it ch}. Returns the empty string if {\it ch} is not found. -\membersection{wxString::Before}\label{wxstringBefore} +\membersection{wxString::AfterLast}\label{wxstringafterlast} -\constfunc{wxString}{Before}{\param{char}{ ch}} +\constfunc{wxString}{AfterLast}{\param{char}{ ch}} + +Gets all the characters after the last occurence of {\it ch}. +Returns the whole string if {\it ch} is not found. + +\membersection{wxString::BeforeFirst}\label{wxstringbeforefirst} + +\constfunc{wxString}{BeforeFirst}{\param{char}{ ch}} + +Gets all characters before the first occurence of {\it ch}. +Returns the whole string if {\it ch} is not found. + +\membersection{wxString::BeforeLast}\label{wxstringbeforelast} + +\constfunc{wxString}{BeforeLast}{\param{char}{ ch}} Gets all characters before the last occurence of {\it ch}. -Returns empty string if {\it ch} is not found. +Returns the empty string if {\it ch} is not found. \membersection{wxString::Cmp}\label{wxstringcmp} @@ -85,9 +463,11 @@ Returns empty string if {\it ch} is not found. Case-sensitive comparison. -Returns 0 if equal, +1 if greater or -1 if less. +Returns a positive value if the string is greater than the argument, zero if +it si equal to it or negative value if it is less than argument (same semantics +as the standard {\it strcmp()} function). -See also CmpNoCase, IsSameAs. +See also \helpref{CmpNoCase}{wxstringcmpnocase}, \helpref{IsSameAs}{wxstringissameas}. \membersection{wxString::CmpNoCase}\label{wxstringcmpnocase} @@ -95,11 +475,13 @@ See also CmpNoCase, IsSameAs. Case-insensitive comparison. -Returns 0 if equal, +1 if greater or -1 if less. +Returns a positive value if the string is greater than the argument, zero if +it si equal to it or negative value if it is less than argument (same semantics +as the standard {\it strcmp()} function). -See also Cmp, IsSameAs. +See also \helpref{Cmp}{wxstringcmp}, \helpref{IsSameAs}{wxstringissameas}. -\membersection{wxString::CompareTo}\label{wxstringCompareTo} +\membersection{wxString::CompareTo}\label{wxstringcompareto} \begin{verbatim} #define NO_POS ((int)(-1)) // undefined position @@ -110,9 +492,9 @@ enum caseCompare {exact, ignoreCase}; Case-sensitive comparison. Returns 0 if equal, 1 if greater or -1 if less. -\membersection{wxString::Contains}\label{wxstringContains} +\membersection{wxString::Contains}\label{wxstringcontains} -\func{bool}{Contains}{\param{const wxString\&}{ str}} +\constfunc{bool}{Contains}{\param{const wxString\&}{ str}} Returns 1 if target appears anyhere in wxString; else 0. @@ -144,13 +526,19 @@ Searches for the given string. Returns the starting index, or -1 if not found. Returns the first occurrence of the item. +\membersection{wxString::Freq}\label{wxstringfreq} + +\constfunc{int}{Frec}{\param{char }{ch}} + +Returns the number of occurences of {it ch} in the string. + \membersection{wxString::GetChar}\label{wxstringgetchar} \constfunc{char}{GetChar}{\param{size\_t}{ n}} Returns the character at position {\it n} (read-only). -\membersection{wxString::GetData}\label{wxstringGetData} +\membersection{wxString::GetData}\label{wxstringgetdata} \constfunc{const char*}{GetData}{\void} @@ -164,14 +552,14 @@ Returns a reference to the character at position {\it n}. \membersection{wxString::GetWriteBuf}\label{wxstringgetwritebuf} -\func{char*}{GetWriteBuf}{\param{uint}{ len}} +\func{char*}{GetWriteBuf}{\param{size\_t}{ len}} Returns a writable buffer of at least {\it len} bytes. Call \helpref{wxString::UngetWriteBuf}{wxstringungetwritebuf} as soon as possible to put the string back into a reasonable state. -\membersection{wxString::Index}\label{wxstringIndex} +\membersection{wxString::Index}\label{wxstringindex} \constfunc{size\_t}{Index}{\param{char}{ ch}, \param{int}{ startpos = 0}} @@ -194,11 +582,11 @@ Returns the index of the first item matched, or NOT\_FOUND. % TODO %\membersection{wxString::insert}\label{wxstringinsert} % Wrong! -%\func{void}{insert}{\param{const wxString\&}{ str}, \param{uint}{ index}} +%\func{void}{insert}{\param{const wxString\&}{ str}, \param{size\_t}{ index}} % %Add new element at the given position. % -\membersection{wxString::IsAscii}\label{wxstringIsAscii} +\membersection{wxString::IsAscii}\label{wxstringisascii} \constfunc{bool}{IsAscii}{\void} @@ -210,13 +598,13 @@ Returns TRUE if the string is ASCII. Returns TRUE if the string is NULL. -\membersection{wxString::IsNull}\label{wxstringIsNull} +\membersection{wxString::IsNull}\label{wxstringisnull} \constfunc{bool}{IsNull}{\void} Returns TRUE if the string is NULL (same as IsEmpty). -\membersection{wxString::IsNumber}\label{wxstringIsNumber} +\membersection{wxString::IsNumber}\label{wxstringisnumber} \constfunc{bool}{IsNumber}{\void} @@ -232,15 +620,15 @@ caseSensitive is TRUE by default (case matters). Returns TRUE if strings are equal, FALSE otherwise. -See also Cmp, CmpNoCase. +See also \helpref{Cmp}{wxstringcmp}, \helpref{CmpNoCase}{wxstringcmpnocase}. -\membersection{wxString::IsWord}\label{wxstringIsWord} +\membersection{wxString::IsWord}\label{wxstringisword} \constfunc{bool}{IsWord}{\void} Returns TRUE if the string is a word. TODO: what's the definition of a word? -\membersection{wxString::Last}\label{wxstringLast} +\membersection{wxString::Last}\label{wxstringlast} \constfunc{char}{Last}{\void} @@ -273,7 +661,13 @@ Returns the length of the string. Returns the length of the string (same as Len). -\membersection{wxString::LowerCase}\label{wxstringLowerCase} +\membersection{wxString::Lower}\label{wxstringlower} + +\constfunc{wxString}{Lower}{\void} + +Returns this string converted to the lower case. + +\membersection{wxString::LowerCase}\label{wxstringlowercase} \func{void}{LowerCase}{\void} @@ -291,7 +685,7 @@ Converts all characters to lower case. Converts all characters to upper case. -\membersection{wxString::Matches}\label{wxstringMatches} +\membersection{wxString::Matches}\label{wxstringmatches} \constfunc{bool}{Matches}{\param{const char*}{ szMask}} @@ -299,7 +693,7 @@ Returns TRUE if the string contents matches a mask containing '*' and '?'. \membersection{wxString::Mid}\label{wxstringmid} -\constfunc{wxString}{Mid}{\param{size\_t}{ first}, \param{size\_t}{ count = STRING\_MAXLEN}} +\constfunc{wxString}{Mid}{\param{size\_t}{ first}, \param{size\_t}{ count = wxSTRING\_MAXLEN}} Returns a substring starting at {\it first}, with length {\it count}, or the rest of the string if {\it count} is the default value. @@ -312,7 +706,7 @@ Adds {\it count} copies of {\it pad} to the beginning, or to the end of the stri Removes spaces from the left or from the right (default). -\membersection{wxString::Prepend}\label{wxstringPrepend} +\membersection{wxString::Prepend}\label{wxstringprepend} \func{wxString\&}{Prepend}{\param{const wxString\&}{ str}} @@ -322,8 +716,13 @@ Prepends {\it str} to this string, returning a reference to this string. \func{int}{Printf}{\param{const char* }{pszFormat}, \param{}{...}} -Similar to sprintf. Returns the number of characters written, or an integer less than zero -on error. +Similar to the standard function {\it sprintf()}. Returns the number of +characters written, or an integer less than zero on error. + +{\bf NB:} This function will use a safe version of {\it vsprintf()} (usually called +{\it vsnprintf()}) whenever available to always allocate the buffer of correct +size. Unfortunately, this function is not available on all platforms and the +dangerous {\it vsprintf()} will be used then which may lead to buffer overflows. \membersection{wxString::PrintfV}\label{wxstringprintfv} @@ -332,7 +731,7 @@ on error. Similar to vprintf. Returns the number of characters written, or an integer less than zero on error. -\membersection{wxString::Remove}\label{wxstringRemove} +\membersection{wxString::Remove}\label{wxstringremove} \func{wxString\&}{Remove}{\param{size\_t}{ pos}} @@ -348,9 +747,9 @@ Removes the last {\it len} characters from the string, starting at {\it pos}. Removes the last character. -\membersection{wxString::Replace}\label{wxstringReplace} +\membersection{wxString::Replace}\label{wxstringreplace} -\func{uint}{Replace}{\param{const char*}{ szOld}, \param{const char*}{ szNew}, \param{bool}{ replaceAll}} +\func{size\_t}{Replace}{\param{const char*}{ szOld}, \param{const char*}{ szNew}, \param{bool}{ replaceAll = TRUE}} Replace first (or all) occurences of substring with another one. @@ -379,7 +778,8 @@ Sets the character at position {\it n}. \func{void}{Shrink}{\void} -Minimizes the string's memory. Only works if the data of this string is not shared. +Minimizes the string's memory. This can be useful after a call to +\helpref{Alloc()}{wxstringalloc} if too much memory were preallocated. \membersection{wxString::sprintf}\label{wxstringsprintf} @@ -387,7 +787,7 @@ Minimizes the string's memory. Only works if the data of this string is not shar The same as Printf. -\membersection{wxString::Strip}\label{wxstringStrip} +\membersection{wxString::Strip}\label{wxstringstrip} \begin{verbatim} enum stripType {leading = 0x1, trailing = 0x2, both = 0x3}; @@ -398,6 +798,12 @@ enum stripType {leading = 0x1, trailing = 0x2, both = 0x3}; Strip characters at the front and/or end. The same as Trim except that it doesn't change this string. +\membersection{wxString::SubString}\label{wxstringsubstring} + +\constfunc{wxString}{SubString}{\param{size\_t}{ to}, \param{size\_t}{ from}} + +Same as \helpref{Mid}{wxstringmid}. + \membersection{wxString::Trim}\label{wxstringtrim} \func{wxString\&}{Trim}{\param{bool}{ fromRight = TRUE}} @@ -417,12 +823,29 @@ Truncate the string to the given length. Puts the string back into a reasonable state, after \rtfsp\helpref{wxString::GetWriteBuf}{wxstringgetwritebuf} was called. -\membersection{wxString::UpperCase}\label{wxstringUpperCase} +\membersection{wxString::Upper}\label{wxstringupper} + +\constfunc{wxString}{Upper}{\void} + +Returns this string converted to upper case. + +\membersection{wxString::UpperCase}\label{wxstringuppercase} \func{void}{UpperCase}{\void} The same as MakeUpper. +\membersection{wxString::operator!}\label{wxstringoperatornot} + +\constfunc{bool}{operator!}{\void} + +Empty string is FALSE, so !string will only return TRUE if the string is empty. +This allows the tests for NULLness of a {\it const char *} pointer and emptyness +of the string to look the same in the code and makes it easier to port old code +to wxString. + +See also \helpref{IsEmpty()}{wxstringisempty}. + \membersection{wxString::operator $=$}\label{wxstringoperatorassign} \func{wxString\&}{operator $=$}{\param{const wxString\&}{ str}} @@ -435,11 +858,13 @@ The same as MakeUpper. \func{wxString\&}{operator $=$}{\param{const wchar\_t*}{ pwz}} -Assignment. +Assignment: the effect of each operation is the same as for the corresponding +constructor (see \helpref{wxString constructors}{wxstringconstruct}). \membersection{operator wxString::$+$}\label{wxstringoperatorplus} -Concatenation. +Concatenation: all these operators return a new strign equal to the sum of the +operands. \func{wxString}{operator $+$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}} @@ -449,7 +874,7 @@ Concatenation. \func{wxString}{operator $+$}{\param{const char*}{ x}, \param{const wxString\&}{ y}} -\membersection{wxString::operator $+=$}\label{wxstringPlusEqual} +\membersection{wxString::operator $+=$}\label{wxstringplusequal} \func{void}{operator $+=$}{\param{const wxString\&}{ str}} @@ -457,7 +882,7 @@ Concatenation. \func{void}{operator $+=$}{\param{char}{ c}} -Concatenation. +Concatenation in place: the argument is appended to the string. \membersection{wxString::operator []}\label{wxstringoperatorbracket} @@ -485,6 +910,16 @@ Same as Mid (substring extraction). Same as $+=$. +\func{wxString\&}{operator \cinsert}{\param{int}{ i}} + +\func{wxString\&}{operator \cinsert}{\param{float}{ f}} + +\func{wxString\&}{operator \cinsert}{\param{double}{ d}} + +These functions work as C++ stream insertion operators: they insert the given +value into the string. Precision or format cannot be set using them, you can use +\helpref{Printf}{wxstringprintf} for this. + \membersection{wxString::operator \cextract}\label{wxstringoperatorin} \func{friend istream\&}{operator \cextract}{\param{istream\&}{ is}, \param{wxString\&}{ str}} @@ -497,7 +932,7 @@ Extraction from a stream. Implicit conversion to a C string. -\membersection{Comparison operators}\label{wxstringComparison} +\membersection{Comparison operators}\label{wxstringcomparison} \func{bool}{operator $==$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}} -- 2.47.2