1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: wxString class
4 // Author: Vadim Zeitlin
8 // Copyright: (c) 1998 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
9 // Licence: wxWindows license
10 /////////////////////////////////////////////////////////////////////////////
12 #ifndef _WX_WXSTRINGH__
13 #define _WX_WXSTRINGH__
16 #pragma interface "string.h"
19 /* Dependencies (should be included before this header):
32 #include "wx/defs.h" // Robert Roebling
33 #ifdef WXSTRING_IS_WXOBJECT
34 #include "wx/object.h"
40 /** @name wxString library
41 @memo Efficient wxString class [more or less] compatible with MFC CString,
42 wxWindows wxString and std::string and some handy functions
43 missing from string.h.
47 // ---------------------------------------------------------------------------
49 // ---------------------------------------------------------------------------
52 @memo You can switch off wxString/std::string compatibility if desired
54 /// compile the std::string compatibility functions
55 #define STD_STRING_COMPATIBILITY
57 /// define to derive wxString from wxObject
58 #undef WXSTRING_IS_WXOBJECT
60 /// maximum possible length for a string means "take all string" everywhere
61 // (as sizeof(StringData) is unknown here we substract 100)
62 #define STRING_MAXLEN (UINT_MAX - 100)
65 #define WXSTRINGCAST (char *)(const char *)
67 // NB: works only inside wxString class
68 #define ASSERT_VALID_INDEX(i) wxASSERT( (unsigned)(i) < Len() )
70 // ---------------------------------------------------------------------------
71 /** @name Global functions complementing standard C string library
72 @memo replacements for strlen() and portable strcasecmp()
74 // ---------------------------------------------------------------------------
76 /// checks whether the passed in pointer is NULL and if the string is empty
77 inline bool WXDLLEXPORT
IsEmpty(const char *p
) { return !p
|| !*p
; }
79 /// safe version of strlen() (returns 0 if passed NULL pointer)
80 inline size_t WXDLLEXPORT
Strlen(const char *psz
)
81 { return psz
? strlen(psz
) : 0; }
83 /// portable strcasecmp/_stricmp
84 inline int WXDLLEXPORT
Stricmp(const char *psz1
, const char *psz2
)
87 return _stricmp(psz1
, psz2
);
88 #elif defined(__BORLANDC__)
89 return stricmp(psz1
, psz2
);
90 #elif defined(__UNIX__) || defined(__GNUWIN32__)
91 return strcasecmp(psz1
, psz2
);
93 // almost all compilers/libraries provide this function (unfortunately under
94 // different names), that's why we don't implement our own which will surely
95 // be more efficient than this code (uncomment to use):
99 c1 = tolower(*psz1++);
100 c2 = tolower(*psz2++);
101 } while ( c1 && (c1 == c2) );
106 #error "Please define string case-insensitive compare for your OS/compiler"
107 #endif // OS/compiler
110 // ----------------------------------------------------------------------------
112 // ----------------------------------------------------------------------------
114 // global pointer to empty string
115 WXDLLEXPORT_DATA(extern const char*) g_szNul
;
117 // return an empty wxString
118 class WXDLLEXPORT wxString
; // not yet defined
119 inline const wxString
& wxGetEmptyString() { return *(wxString
*)&g_szNul
; }
121 // ---------------------------------------------------------------------------
122 // string data prepended with some housekeeping info (used by wxString class),
123 // is never used directly (but had to be put here to allow inlining)
124 // ---------------------------------------------------------------------------
125 struct WXDLLEXPORT wxStringData
127 int nRefs
; // reference count
128 size_t nDataLength
, // actual string length
129 nAllocLength
; // allocated memory size
131 // mimics declaration 'char data[nAllocLength]'
132 char* data() const { return (char*)(this + 1); }
134 // empty string has a special ref count so it's never deleted
135 bool IsEmpty() const { return nRefs
== -1; }
136 bool IsShared() const { return nRefs
> 1; }
139 void Lock() { if ( !IsEmpty() ) nRefs
++; }
140 void Unlock() { if ( !IsEmpty() && --nRefs
== 0) free(this); }
142 // if we had taken control over string memory (GetWriteBuf), it's
143 // intentionally put in invalid state
144 void Validate(bool b
) { nRefs
= b
? 1 : 0; }
145 bool IsValid() const { return nRefs
!= 0; }
148 // ---------------------------------------------------------------------------
150 This is (yet another one) String class for C++ programmers. It doesn't use
151 any of "advanced" C++ features (i.e. templates, exceptions, namespaces...)
152 thus you should be able to compile it with practicaly any C++ compiler.
153 This class uses copy-on-write technique, i.e. identical strings share the
154 same memory as long as neither of them is changed.
156 This class aims to be as compatible as possible with the new standard
157 std::string class, but adds some additional functions and should be
158 at least as efficient than the standard implementation.
160 Performance note: it's more efficient to write functions which take
161 "const String&" arguments than "const char *" if you assign the argument
164 It was compiled and tested under Win32, Linux (libc 5 & 6), Solaris 5.5.
167 - ressource support (string tables in ressources)
168 - more wide character (UNICODE) support
169 - regular expressions support
171 @memo A non-template portable wxString class implementing copy-on-write.
175 // ---------------------------------------------------------------------------
176 #ifdef WXSTRING_IS_WXOBJECT
177 class WXDLLEXPORT wxString
: public wxObject
179 DECLARE_DYNAMIC_CLASS(wxString
)
180 #else //WXSTRING_IS_WXOBJECT
181 class WXDLLEXPORT wxString
183 #endif //WXSTRING_IS_WXOBJECT
185 friend class WXDLLEXPORT wxArrayString
;
187 // NB: special care was taken in arrangin the member functions in such order
188 // that all inline functions can be effectively inlined
190 // points to data preceded by wxStringData structure with ref count info
193 // accessor to string data
194 wxStringData
* GetStringData() const { return (wxStringData
*)m_pchData
- 1; }
196 // string (re)initialization functions
197 // initializes the string to the empty value (must be called only from
198 // ctors, use Reinit() otherwise)
199 void Init() { m_pchData
= (char *)g_szNul
; }
200 // initializaes the string with (a part of) C-string
201 void InitWith(const char *psz
, size_t nPos
= 0, size_t nLen
= STRING_MAXLEN
);
202 // as Init, but also frees old data
203 void Reinit() { GetStringData()->Unlock(); Init(); }
206 // allocates memory for string of lenght nLen
207 void AllocBuffer(size_t nLen
);
208 // copies data to another string
209 void AllocCopy(wxString
&, int, int) const;
210 // effectively copies data to string
211 void AssignCopy(size_t, const char *);
213 // append a (sub)string
214 void ConcatSelf(int nLen
, const char *src
);
216 // functions called before writing to the string: they copy it if there
217 // are other references to our data (should be the only owner when writing)
218 void CopyBeforeWrite();
219 void AllocBeforeWrite(size_t);
222 /** @name constructors & dtor */
224 /// ctor for an empty string
225 wxString() { Init(); }
227 wxString(const wxString
& stringSrc
)
229 wxASSERT( stringSrc
.GetStringData()->IsValid() );
231 if ( stringSrc
.IsEmpty() ) {
232 // nothing to do for an empty string
236 m_pchData
= stringSrc
.m_pchData
; // share same data
237 GetStringData()->Lock(); // => one more copy
240 /// string containing nRepeat copies of ch
241 wxString(char ch
, size_t nRepeat
= 1);
242 /// ctor takes first nLength characters from C string
243 // (default value of STRING_MAXLEN means take all the string)
244 wxString(const char *psz
, size_t nLength
= STRING_MAXLEN
)
245 { InitWith(psz
, 0, nLength
); }
246 /// from C string (for compilers using unsigned char)
247 wxString(const unsigned char* psz
, size_t nLength
= STRING_MAXLEN
);
248 /// from wide (UNICODE) string
249 wxString(const wchar_t *pwz
);
250 /// dtor is not virtual, this class must not be inherited from!
251 ~wxString() { GetStringData()->Unlock(); }
254 /** @name generic attributes & operations */
256 /// as standard strlen()
257 size_t Len() const { return GetStringData()->nDataLength
; }
258 /// string contains any characters?
259 bool IsEmpty() const { return Len() == 0; }
260 /// empty string contents
267 wxASSERT( GetStringData()->nDataLength
== 0 );
269 /// empty the string and free memory
272 if ( !GetStringData()->IsEmpty() )
275 wxASSERT( GetStringData()->nDataLength
== 0 ); // should be empty
276 wxASSERT( GetStringData()->nAllocLength
== 0 ); // and not own any memory
279 /// Is an ascii value
280 bool IsAscii() const;
282 bool IsNumber() const;
287 /** @name data access (all indexes are 0 based) */
290 char GetChar(size_t n
) const
291 { ASSERT_VALID_INDEX( n
); return m_pchData
[n
]; }
292 /// read/write access
293 char& GetWritableChar(size_t n
)
294 { ASSERT_VALID_INDEX( n
); CopyBeforeWrite(); return m_pchData
[n
]; }
296 void SetChar(size_t n
, char ch
)
297 { ASSERT_VALID_INDEX( n
); CopyBeforeWrite(); m_pchData
[n
] = ch
; }
299 /// get last character
301 { wxASSERT( !IsEmpty() ); return m_pchData
[Len() - 1]; }
302 /// get writable last character
304 { wxASSERT( !IsEmpty() ); CopyBeforeWrite(); return m_pchData
[Len()-1]; }
306 // Alternatively, we could uncomment one of them for 64bit platforms
307 // by using #if SIZEOF_INT > 32
309 /// operator version of GetChar
310 char operator[](size_t n
) const
311 { ASSERT_VALID_INDEX( n
); return m_pchData
[n
]; }
313 /// operator version of GetChar
314 char operator[](int n
) const
315 { ASSERT_VALID_INDEX( n
); return m_pchData
[n
]; }
316 /// operator version of GetWritableChar
317 char& operator[](size_t n
)
318 { ASSERT_VALID_INDEX( n
); CopyBeforeWrite(); return m_pchData
[n
]; }
320 /// implicit conversion to C string
321 operator const char*() const { return m_pchData
; }
322 /// explicit conversion to C string (use this with printf()!)
323 const char* c_str() const { return m_pchData
; }
325 const char* GetData() const { return m_pchData
; }
328 /** @name overloaded assignment */
331 wxString
& operator=(const wxString
& stringSrc
);
333 wxString
& operator=(char ch
);
335 wxString
& operator=(const char *psz
);
337 wxString
& operator=(const unsigned char* psz
);
339 wxString
& operator=(const wchar_t *pwz
);
342 /** @name string concatenation */
344 /** @name in place concatenation */
345 /** @name concatenate and return the result
346 left to right associativity of << allows to write
347 things like "str << str1 << str2 << ..." */
350 wxString
& operator<<(const wxString
& s
)
352 wxASSERT( s
.GetStringData()->IsValid() );
354 ConcatSelf(s
.Len(), s
);
358 wxString
& operator<<(const char *psz
)
359 { ConcatSelf(Strlen(psz
), psz
); return *this; }
361 wxString
& operator<<(char ch
) { ConcatSelf(1, &ch
); return *this; }
366 void operator+=(const wxString
& s
) { (void)operator<<(s
); }
367 /// string += C string
368 void operator+=(const char *psz
) { (void)operator<<(psz
); }
370 void operator+=(char ch
) { (void)operator<<(ch
); }
373 /** @name return resulting string */
376 friend wxString WXDLLEXPORT
operator+(const wxString
& string1
, const wxString
& string2
);
378 friend wxString WXDLLEXPORT
operator+(const wxString
& string
, char ch
);
380 friend wxString WXDLLEXPORT
operator+(char ch
, const wxString
& string
);
382 friend wxString WXDLLEXPORT
operator+(const wxString
& string
, const char *psz
);
384 friend wxString WXDLLEXPORT
operator+(const char *psz
, const wxString
& string
);
388 /** @name stream-like functions */
390 /// insert an int into string
391 wxString
& operator<<(int i
);
392 /// insert a float into string
393 wxString
& operator<<(float f
);
394 /// insert a double into string
395 wxString
& operator<<(double d
);
398 /** @name string comparison */
401 case-sensitive comparison
402 @return 0 if equal, +1 if greater or -1 if less
403 @see CmpNoCase, IsSameAs
405 int Cmp(const char *psz
) const { return strcmp(c_str(), psz
); }
407 case-insensitive comparison, return code as for wxString::Cmp()
410 int CmpNoCase(const char *psz
) const { return Stricmp(c_str(), psz
); }
412 test for string equality, case-sensitive (default) or not
413 @param bCase is TRUE by default (case matters)
414 @return TRUE if strings are equal, FALSE otherwise
417 bool IsSameAs(const char *psz
, bool bCase
= TRUE
) const
418 { return !(bCase
? Cmp(psz
) : CmpNoCase(psz
)); }
421 /** @name other standard string operations */
423 /** @name simple sub-string extraction
427 return substring starting at nFirst of length
428 nCount (or till the end if nCount = default value)
430 wxString
Mid(size_t nFirst
, size_t nCount
= STRING_MAXLEN
) const;
431 /// get first nCount characters
432 wxString
Left(size_t nCount
) const;
433 /// get all characters before the first occurence of ch
434 /// (returns the whole string if ch not found)
435 wxString
Left(char ch
) const;
436 /// get all characters before the last occurence of ch
437 /// (returns empty string if ch not found)
438 wxString
Before(char ch
) const;
439 /// get all characters after the first occurence of ch
440 /// (returns empty string if ch not found)
441 wxString
After(char ch
) const;
442 /// get last nCount characters
443 wxString
Right(size_t nCount
) const;
444 /// get all characters after the last occurence of ch
445 /// (returns the whole string if ch not found)
446 wxString
Right(char ch
) const;
449 /** @name case conversion */
452 wxString
& MakeUpper();
454 wxString
& MakeLower();
457 /** @name trimming/padding whitespace (either side) and truncating */
459 /// remove spaces from left or from right (default) side
460 wxString
& Trim(bool bFromRight
= TRUE
);
461 /// add nCount copies chPad in the beginning or at the end (default)
462 wxString
& Pad(size_t nCount
, char chPad
= ' ', bool bFromRight
= TRUE
);
463 /// truncate string to given length
464 wxString
& Truncate(size_t uiLen
);
467 /** @name searching and replacing */
469 /// searching (return starting index, or -1 if not found)
470 int Find(char ch
, bool bFromEnd
= FALSE
) const; // like strchr/strrchr
471 /// searching (return starting index, or -1 if not found)
472 int Find(const char *pszSub
) const; // like strstr
474 replace first (or all) occurences of substring with another one
475 @param bReplaceAll: global replace (default) or only the first occurence
476 @return the number of replacements made
478 size_t Replace(const char *szOld
, const char *szNew
, bool bReplaceAll
= TRUE
);
481 /// check if the string contents matches a mask containing '*' and '?'
482 bool Matches(const char *szMask
) const;
485 /** @name formated input/output */
487 /// as sprintf(), returns the number of characters written or < 0 on error
488 int Printf(const char *pszFormat
, ...);
489 /// as vprintf(), returns the number of characters written or < 0 on error
490 int PrintfV(const char* pszFormat
, va_list argptr
);
493 /** @name raw access to string memory */
495 /// ensure that string has space for at least nLen characters
496 // only works if the data of this string is not shared
497 void Alloc(size_t nLen
);
498 /// minimize the string's memory
499 // only works if the data of this string is not shared
502 get writable buffer of at least nLen bytes.
503 Unget() *must* be called a.s.a.p. to put string back in a reasonable
506 char *GetWriteBuf(size_t nLen
);
507 /// call this immediately after GetWriteBuf() has been used
508 void UngetWriteBuf();
511 /** @name wxWindows compatibility functions */
513 /// values for second parameter of CompareTo function
514 enum caseCompare
{exact
, ignoreCase
};
515 /// values for first parameter of Strip function
516 enum stripType
{leading
= 0x1, trailing
= 0x2, both
= 0x3};
518 inline int sprintf(const char *pszFormat
, ...)
521 va_start(argptr
, pszFormat
);
522 int iLen
= PrintfV(pszFormat
, argptr
);
528 inline int CompareTo(const char* psz
, caseCompare cmp
= exact
) const
529 { return cmp
== exact
? Cmp(psz
) : CmpNoCase(psz
); }
531 /// same as Mid (substring extraction)
532 inline wxString
operator()(size_t start
, size_t len
) const
533 { return Mid(start
, len
); }
536 inline wxString
& Append(const char* psz
) { return *this << psz
; }
537 inline wxString
& Append(char ch
, int count
= 1)
538 { wxString
str(ch
, count
); (*this) += str
; return *this; }
541 wxString
& Prepend(const wxString
& str
)
542 { *this = str
+ *this; return *this; }
544 size_t Length() const { return Len(); }
545 /// same as MakeLower
546 void LowerCase() { MakeLower(); }
547 /// same as MakeUpper
548 void UpperCase() { MakeUpper(); }
549 /// same as Trim except that it doesn't change this string
550 wxString
Strip(stripType w
= trailing
) const;
552 /// same as Find (more general variants not yet supported)
553 size_t Index(const char* psz
) const { return Find(psz
); }
554 size_t Index(char ch
) const { return Find(ch
); }
556 wxString
& Remove(size_t pos
) { return Truncate(pos
); }
557 wxString
& RemoveLast() { return Truncate(Len() - 1); }
559 wxString
& Remove(size_t nStart
, size_t nLen
) { return erase( nStart
, nLen
); }
561 int First( const char ch
) const { return Find(ch
); }
562 int First( const char* psz
) const { return Find(psz
); }
563 int First( const wxString
&str
) const { return Find(str
); }
565 int Last( const char ch
) const { return Find(ch
, TRUE
); }
568 bool IsNull() const { return IsEmpty(); }
571 #ifdef STD_STRING_COMPATIBILITY
572 /** @name std::string compatibility functions */
574 /// an 'invalid' value for string index
575 static const size_t npos
;
578 /** @name constructors */
580 /// take nLen chars starting at nPos
581 wxString(const wxString
& str
, size_t nPos
, size_t nLen
= npos
)
583 wxASSERT( str
.GetStringData()->IsValid() );
584 InitWith(str
.c_str(), nPos
, nLen
== npos
? 0 : nLen
);
586 /// take all characters from pStart to pEnd
587 wxString(const void *pStart
, const void *pEnd
);
589 /** @name lib.string.capacity */
591 /// return the length of the string
592 size_t size() const { return Len(); }
593 /// return the length of the string
594 size_t length() const { return Len(); }
595 /// return the maximum size of the string
596 size_t max_size() const { return STRING_MAXLEN
; }
597 /// resize the string, filling the space with c if c != 0
598 void resize(size_t nSize
, char ch
= '\0');
599 /// delete the contents of the string
600 void clear() { Empty(); }
601 /// returns true if the string is empty
602 bool empty() const { return IsEmpty(); }
604 /** @name lib.string.access */
606 /// return the character at position n
607 char at(size_t n
) const { return GetChar(n
); }
608 /// returns the writable character at position n
609 char& at(size_t n
) { return GetWritableChar(n
); }
611 /** @name lib.string.modifiers */
613 /** @name append something to the end of this one */
616 wxString
& append(const wxString
& str
)
617 { *this += str
; return *this; }
618 /// append elements str[pos], ..., str[pos+n]
619 wxString
& append(const wxString
& str
, size_t pos
, size_t n
)
620 { ConcatSelf(n
, str
.c_str() + pos
); return *this; }
621 /// append first n (or all if n == npos) characters of sz
622 wxString
& append(const char *sz
, size_t n
= npos
)
623 { ConcatSelf(n
== npos
? Strlen(sz
) : n
, sz
); return *this; }
625 /// append n copies of ch
626 wxString
& append(size_t n
, char ch
) { return Pad(n
, ch
); }
629 /** @name replaces the contents of this string with another one */
631 /// same as `this_string = str'
632 wxString
& assign(const wxString
& str
) { return (*this) = str
; }
633 /// same as ` = str[pos..pos + n]
634 wxString
& assign(const wxString
& str
, size_t pos
, size_t n
)
635 { return *this = wxString((const char *)str
+ pos
, n
); }
636 /// same as `= first n (or all if n == npos) characters of sz'
637 wxString
& assign(const char *sz
, size_t n
= npos
)
638 { return *this = wxString(sz
, n
); }
639 /// same as `= n copies of ch'
640 wxString
& assign(size_t n
, char ch
)
641 { return *this = wxString(ch
, n
); }
645 /** @name inserts something at position nPos into this one */
647 /// insert another string
648 wxString
& insert(size_t nPos
, const wxString
& str
);
649 /// insert n chars of str starting at nStart (in str)
650 wxString
& insert(size_t nPos
, const wxString
& str
, size_t nStart
, size_t n
)
651 { return insert(nPos
, wxString((const char *)str
+ nStart
, n
)); }
653 /// insert first n (or all if n == npos) characters of sz
654 wxString
& insert(size_t nPos
, const char *sz
, size_t n
= npos
)
655 { return insert(nPos
, wxString(sz
, n
)); }
656 /// insert n copies of ch
657 wxString
& insert(size_t nPos
, size_t n
, char ch
)
658 { return insert(nPos
, wxString(ch
, n
)); }
662 /** @name deletes a part of the string */
664 /// delete characters from nStart to nStart + nLen
665 wxString
& erase(size_t nStart
= 0, size_t nLen
= npos
);
668 /** @name replaces a substring of this string with another one */
670 /// replaces the substring of length nLen starting at nStart
671 wxString
& replace(size_t nStart
, size_t nLen
, const char* sz
);
672 /// replaces the substring with nCount copies of ch
673 wxString
& replace(size_t nStart
, size_t nLen
, size_t nCount
, char ch
);
674 /// replaces a substring with another substring
675 wxString
& replace(size_t nStart
, size_t nLen
,
676 const wxString
& str
, size_t nStart2
, size_t nLen2
);
677 /// replaces the substring with first nCount chars of sz
678 wxString
& replace(size_t nStart
, size_t nLen
,
679 const char* sz
, size_t nCount
);
684 void swap(wxString
& str
);
686 /** @name string operations */
688 /** All find() functions take the nStart argument which specifies
689 the position to start the search on, the default value is 0.
691 All functions return npos if there were no match.
697 @name find a match for the string/character in this string
701 size_t find(const wxString
& str
, size_t nStart
= 0) const;
703 // VC++ 1.5 can't cope with this syntax.
704 #if ! (defined(_MSC_VER) && !defined(__WIN32__))
705 /// find first n characters of sz
706 size_t find(const char* sz
, size_t nStart
= 0, size_t n
= npos
) const;
708 /// find the first occurence of character ch after nStart
709 size_t find(char ch
, size_t nStart
= 0) const;
711 // wxWin compatibility
712 inline bool Contains(const wxString
& str
) const { return Find(str
) != -1; }
717 @name rfind() family is exactly like find() but works right to left
720 /// as find, but from the end
721 size_t rfind(const wxString
& str
, size_t nStart
= npos
) const;
722 /// as find, but from the end
723 // VC++ 1.5 can't cope with this syntax.
724 #if ! (defined(_MSC_VER) && !defined(__WIN32__))
725 size_t rfind(const char* sz
, size_t nStart
= npos
,
726 size_t n
= npos
) const;
727 /// as find, but from the end
728 size_t rfind(char ch
, size_t nStart
= npos
) const;
733 @name find first/last occurence of any character in the set
737 size_t find_first_of(const wxString
& str
, size_t nStart
= 0) const;
739 size_t find_first_of(const char* sz
, size_t nStart
= 0) const;
740 /// same as find(char, size_t)
741 size_t find_first_of(char c
, size_t nStart
= 0) const;
744 size_t find_last_of (const wxString
& str
, size_t nStart
= npos
) const;
746 size_t find_last_of (const char* s
, size_t nStart
= npos
) const;
747 /// same as rfind(char, size_t)
748 size_t find_last_of (char c
, size_t nStart
= npos
) const;
752 @name find first/last occurence of any character not in the set
756 size_t find_first_not_of(const wxString
& str
, size_t nStart
= 0) const;
758 size_t find_first_not_of(const char* s
, size_t nStart
= 0) const;
760 size_t find_first_not_of(char ch
, size_t nStart
= 0) const;
763 size_t find_last_not_of(const wxString
& str
, size_t nStart
=npos
) const;
765 size_t find_last_not_of(const char* s
, size_t nStart
= npos
) const;
767 size_t find_last_not_of(char ch
, size_t nStart
= npos
) const;
772 All compare functions return -1, 0 or 1 if the [sub]string
773 is less, equal or greater than the compare() argument.
778 /// just like strcmp()
779 int compare(const wxString
& str
) const { return Cmp(str
); }
780 /// comparison with a substring
781 int compare(size_t nStart
, size_t nLen
, const wxString
& str
) const;
782 /// comparison of 2 substrings
783 int compare(size_t nStart
, size_t nLen
,
784 const wxString
& str
, size_t nStart2
, size_t nLen2
) const;
785 /// just like strcmp()
786 int compare(const char* sz
) const { return Cmp(sz
); }
787 /// substring comparison with first nCount characters of sz
788 int compare(size_t nStart
, size_t nLen
,
789 const char* sz
, size_t nCount
= npos
) const;
791 wxString
substr(size_t nStart
= 0, size_t nLen
= npos
) const;
796 // ----------------------------------------------------------------------------
797 /** The string array uses it's knowledge of internal structure of the String
798 class to optimize string storage. Normally, we would store pointers to
799 string, but as String is, in fact, itself a pointer (sizeof(String) is
800 sizeof(char *)) we store these pointers instead. The cast to "String *"
801 is really all we need to turn such pointer into a string!
803 Of course, it can be called a dirty hack, but we use twice less memory
804 and this approach is also more speed efficient, so it's probably worth it.
806 Usage notes: when a string is added/inserted, a new copy of it is created,
807 so the original string may be safely deleted. When a string is retrieved
808 from the array (operator[] or Item() method), a reference is returned.
811 @memo probably the most commonly used array type - array of strings
813 // ----------------------------------------------------------------------------
814 class WXDLLEXPORT wxArrayString
817 /** @name ctors and dtor */
822 wxArrayString(const wxArrayString
& array
);
823 /// assignment operator
824 wxArrayString
& operator=(const wxArrayString
& src
);
825 /// not virtual, this class can't be derived from
829 /** @name memory management */
831 /// empties the list, but doesn't release memory
833 /// empties the list and releases memory
835 /// preallocates memory for given number of items
836 void Alloc(size_t nCount
);
837 /// minimzes the memory usage (by freeing all extra memory)
841 /** @name simple accessors */
843 /// number of elements in the array
844 size_t Count() const { return m_nCount
; }
846 bool IsEmpty() const { return m_nCount
== 0; }
849 /** @name items access (range checking is done in debug version) */
851 /// get item at position uiIndex
852 wxString
& Item(size_t nIndex
) const
853 { wxASSERT( nIndex
< m_nCount
); return *(wxString
*)&(m_pItems
[nIndex
]); }
855 wxString
& operator[](size_t nIndex
) const { return Item(nIndex
); }
857 wxString
& Last() const { wxASSERT( !IsEmpty() ); return Item(Count() - 1); }
860 /** @name item management */
863 Search the element in the array, starting from the either side
864 @param if bFromEnd reverse search direction
865 @param if bCase, comparison is case sensitive (default)
866 @return index of the first item matched or NOT_FOUND
869 int Index (const char *sz
, bool bCase
= TRUE
, bool bFromEnd
= FALSE
) const;
870 /// add new element at the end
871 void Add (const wxString
& str
);
872 /// add new element at given position
873 void Insert(const wxString
& str
, size_t uiIndex
);
874 /// remove first item matching this value
875 void Remove(const char *sz
);
876 /// remove item by index
877 void Remove(size_t nIndex
);
880 /// sort array elements
881 void Sort(bool bCase
= TRUE
, bool bReverse
= FALSE
);
884 void Grow(); // makes array bigger if needed
885 void Free(); // free the string stored
887 size_t m_nSize
, // current size of the array
888 m_nCount
; // current number of elements
890 char **m_pItems
; // pointer to data
893 // ---------------------------------------------------------------------------
894 /** @name wxString comparison functions
895 @memo Comparisons are case sensitive
897 // ---------------------------------------------------------------------------
899 inline bool operator==(const wxString
& s1
, const wxString
& s2
) { return s1
.Cmp(s2
) == 0; }
901 inline bool operator==(const wxString
& s1
, const char * s2
) { return s1
.Cmp(s2
) == 0; }
903 inline bool operator==(const char * s1
, const wxString
& s2
) { return s2
.Cmp(s1
) == 0; }
905 inline bool operator!=(const wxString
& s1
, const wxString
& s2
) { return s1
.Cmp(s2
) != 0; }
907 inline bool operator!=(const wxString
& s1
, const char * s2
) { return s1
.Cmp(s2
) != 0; }
909 inline bool operator!=(const char * s1
, const wxString
& s2
) { return s2
.Cmp(s1
) != 0; }
911 inline bool operator< (const wxString
& s1
, const wxString
& s2
) { return s1
.Cmp(s2
) < 0; }
913 inline bool operator< (const wxString
& s1
, const char * s2
) { return s1
.Cmp(s2
) < 0; }
915 inline bool operator< (const char * s1
, const wxString
& s2
) { return s2
.Cmp(s1
) > 0; }
917 inline bool operator> (const wxString
& s1
, const wxString
& s2
) { return s1
.Cmp(s2
) > 0; }
919 inline bool operator> (const wxString
& s1
, const char * s2
) { return s1
.Cmp(s2
) > 0; }
921 inline bool operator> (const char * s1
, const wxString
& s2
) { return s2
.Cmp(s1
) < 0; }
923 inline bool operator<=(const wxString
& s1
, const wxString
& s2
) { return s1
.Cmp(s2
) <= 0; }
925 inline bool operator<=(const wxString
& s1
, const char * s2
) { return s1
.Cmp(s2
) <= 0; }
927 inline bool operator<=(const char * s1
, const wxString
& s2
) { return s2
.Cmp(s1
) >= 0; }
929 inline bool operator>=(const wxString
& s1
, const wxString
& s2
) { return s1
.Cmp(s2
) >= 0; }
931 inline bool operator>=(const wxString
& s1
, const char * s2
) { return s1
.Cmp(s2
) >= 0; }
933 inline bool operator>=(const char * s1
, const wxString
& s2
) { return s2
.Cmp(s1
) <= 0; }
935 wxString WXDLLEXPORT
operator+(const wxString
& string1
, const wxString
& string2
);
936 wxString WXDLLEXPORT
operator+(const wxString
& string
, char ch
);
937 wxString WXDLLEXPORT
operator+(char ch
, const wxString
& string
);
938 wxString WXDLLEXPORT
operator+(const wxString
& string
, const char *psz
);
939 wxString WXDLLEXPORT
operator+(const char *psz
, const wxString
& string
);
941 // ---------------------------------------------------------------------------
942 /** @name Global functions complementing standard C string library
943 @memo replacements for strlen() and portable strcasecmp()
945 // ---------------------------------------------------------------------------
947 #ifdef STD_STRING_COMPATIBILITY
950 // Known not to work with wxUSE_IOSTREAMH set to 0, so
951 // replacing with includes (on advice of ungod@pasdex.com.au)
952 // class WXDLLEXPORT istream;
954 // N.B. BC++ doesn't have istream.h, ostream.h
955 #include <iostream.h>
963 WXDLLEXPORT istream
& operator>>(istream
& is
, wxString
& str
);
965 #endif //std::string compatibility
967 #endif // _WX_WXSTRINGH__