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(__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 /// reinitialize string (and free data!)
263 if ( GetStringData()->nDataLength
!= 0 )
266 wxASSERT( GetStringData()->nDataLength
== 0 );
267 wxASSERT( GetStringData()->nAllocLength
== 0 );
270 /// Is an ascii value
271 bool IsAscii() const;
273 bool IsNumber() const;
278 /** @name data access (all indexes are 0 based) */
281 char GetChar(size_t n
) const
282 { ASSERT_VALID_INDEX( n
); return m_pchData
[n
]; }
283 /// read/write access
284 char& GetWritableChar(size_t n
)
285 { ASSERT_VALID_INDEX( n
); CopyBeforeWrite(); return m_pchData
[n
]; }
287 void SetChar(size_t n
, char ch
)
288 { ASSERT_VALID_INDEX( n
); CopyBeforeWrite(); m_pchData
[n
] = ch
; }
290 /// get last character
292 { wxASSERT( !IsEmpty() ); return m_pchData
[Len() - 1]; }
293 /// get writable last character
295 { wxASSERT( !IsEmpty() ); CopyBeforeWrite(); return m_pchData
[Len()-1]; }
297 /// operator version of GetChar
298 char operator[](size_t n
) const
299 { ASSERT_VALID_INDEX( n
); return m_pchData
[n
]; }
300 /// operator version of GetChar
301 char operator[](int n
) const
302 { ASSERT_VALID_INDEX( n
); return m_pchData
[n
]; }
303 /// operator version of GetWritableChar
304 char& operator[](size_t n
)
305 { ASSERT_VALID_INDEX( n
); CopyBeforeWrite(); return m_pchData
[n
]; }
307 /// implicit conversion to C string
308 operator const char*() const { return m_pchData
; }
309 /// explicit conversion to C string (use this with printf()!)
310 const char* c_str() const { return m_pchData
; }
312 const char* GetData() const { return m_pchData
; }
315 /** @name overloaded assignment */
318 wxString
& operator=(const wxString
& stringSrc
);
320 wxString
& operator=(char ch
);
322 wxString
& operator=(const char *psz
);
324 wxString
& operator=(const unsigned char* psz
);
326 wxString
& operator=(const wchar_t *pwz
);
329 /** @name string concatenation */
331 /** @name in place concatenation */
332 /** @name concatenate and return the result
333 left to right associativity of << allows to write
334 things like "str << str1 << str2 << ..." */
337 wxString
& operator<<(const wxString
& s
)
339 wxASSERT( s
.GetStringData()->IsValid() );
341 ConcatSelf(s
.Len(), s
);
345 wxString
& operator<<(const char *psz
)
346 { ConcatSelf(Strlen(psz
), psz
); return *this; }
348 wxString
& operator<<(char ch
) { ConcatSelf(1, &ch
); return *this; }
353 void operator+=(const wxString
& s
) { (void)operator<<(s
); }
354 /// string += C string
355 void operator+=(const char *psz
) { (void)operator<<(psz
); }
357 void operator+=(char ch
) { (void)operator<<(ch
); }
360 /** @name return resulting string */
363 friend wxString
operator+(const wxString
& string1
, const wxString
& string2
);
365 friend wxString
operator+(const wxString
& string
, char ch
);
367 friend wxString
operator+(char ch
, const wxString
& string
);
369 friend wxString
operator+(const wxString
& string
, const char *psz
);
371 friend wxString
operator+(const char *psz
, const wxString
& string
);
375 /** @name string comparison */
378 case-sensitive comparison
379 @return 0 if equal, +1 if greater or -1 if less
380 @see CmpNoCase, IsSameAs
382 int Cmp(const char *psz
) const { return strcmp(c_str(), psz
); }
384 case-insensitive comparison, return code as for wxString::Cmp()
387 int CmpNoCase(const char *psz
) const { return Stricmp(c_str(), psz
); }
389 test for string equality, case-sensitive (default) or not
390 @param bCase is TRUE by default (case matters)
391 @return TRUE if strings are equal, FALSE otherwise
394 bool IsSameAs(const char *psz
, bool bCase
= TRUE
) const
395 { return !(bCase
? Cmp(psz
) : CmpNoCase(psz
)); }
398 /** @name other standard string operations */
400 /** @name simple sub-string extraction
404 return substring starting at nFirst of length
405 nCount (or till the end if nCount = default value)
407 wxString
Mid(size_t nFirst
, size_t nCount
= STRING_MAXLEN
) const;
408 /// get first nCount characters
409 wxString
Left(size_t nCount
) const;
410 /// get all characters before the first occurence of ch
411 /// (returns the whole string if ch not found)
412 wxString
Left(char ch
) const;
413 /// get all characters before the last occurence of ch
414 /// (returns empty string if ch not found)
415 wxString
Before(char ch
) const;
416 /// get all characters after the first occurence of ch
417 /// (returns empty string if ch not found)
418 wxString
After(char ch
) const;
419 /// get last nCount characters
420 wxString
Right(size_t nCount
) const;
421 /// get all characters after the last occurence of ch
422 /// (returns the whole string if ch not found)
423 wxString
Right(char ch
) const;
426 /** @name case conversion */
429 wxString
& MakeUpper();
431 wxString
& MakeLower();
434 /** @name trimming/padding whitespace (either side) and truncating */
436 /// remove spaces from left or from right (default) side
437 wxString
& Trim(bool bFromRight
= TRUE
);
438 /// add nCount copies chPad in the beginning or at the end (default)
439 wxString
& Pad(size_t nCount
, char chPad
= ' ', bool bFromRight
= TRUE
);
440 /// truncate string to given length
441 wxString
& Truncate(size_t uiLen
);
444 /** @name searching and replacing */
446 /// searching (return starting index, or -1 if not found)
447 int Find(char ch
, bool bFromEnd
= FALSE
) const; // like strchr/strrchr
448 /// searching (return starting index, or -1 if not found)
449 int Find(const char *pszSub
) const; // like strstr
451 replace first (or all) occurences of substring with another one
452 @param bReplaceAll: global replace (default) or only the first occurence
453 @return the number of replacements made
455 size_t Replace(const char *szOld
, const char *szNew
, bool bReplaceAll
= TRUE
);
458 /// check if the string contents matches a mask containing '*' and '?'
459 bool Matches(const char *szMask
) const;
462 /** @name formated input/output */
464 /// as sprintf(), returns the number of characters written or < 0 on error
465 int Printf(const char *pszFormat
, ...);
466 /// as vprintf(), returns the number of characters written or < 0 on error
467 int PrintfV(const char* pszFormat
, va_list argptr
);
470 /** @name raw access to string memory */
472 /// ensure that string has space for at least nLen characters
473 // only works if the data of this string is not shared
474 void Alloc(size_t nLen
);
475 /// minimize the string's memory
476 // only works if the data of this string is not shared
479 get writable buffer of at least nLen bytes.
480 Unget() *must* be called a.s.a.p. to put string back in a reasonable
483 char *GetWriteBuf(size_t nLen
);
484 /// call this immediately after GetWriteBuf() has been used
485 void UngetWriteBuf();
488 /** @name wxWindows compatibility functions */
490 /// values for second parameter of CompareTo function
491 enum caseCompare
{exact
, ignoreCase
};
492 /// values for first parameter of Strip function
493 enum stripType
{leading
= 0x1, trailing
= 0x2, both
= 0x3};
495 inline int sprintf(const char *pszFormat
, ...)
498 va_start(argptr
, pszFormat
);
499 int iLen
= PrintfV(pszFormat
, argptr
);
505 inline int CompareTo(const char* psz
, caseCompare cmp
= exact
) const
506 { return cmp
== exact
? Cmp(psz
) : CmpNoCase(psz
); }
508 /// same as Mid (substring extraction)
509 inline wxString
operator()(size_t start
, size_t len
) const
510 { return Mid(start
, len
); }
513 inline wxString
& Append(const char* psz
) { return *this << psz
; }
514 inline wxString
& Append(char ch
, int count
= 1)
515 { wxString
str(ch
, count
); (*this) += str
; return *this; }
518 wxString
& Prepend(const wxString
& str
)
519 { *this = str
+ *this; return *this; }
521 size_t Length() const { return Len(); }
522 /// same as MakeLower
523 void LowerCase() { MakeLower(); }
524 /// same as MakeUpper
525 void UpperCase() { MakeUpper(); }
526 /// same as Trim except that it doesn't change this string
527 wxString
Strip(stripType w
= trailing
) const;
529 /// same as Find (more general variants not yet supported)
530 size_t Index(const char* psz
) const { return Find(psz
); }
531 size_t Index(char ch
) const { return Find(ch
); }
533 wxString
& Remove(size_t pos
) { return Truncate(pos
); }
534 wxString
& RemoveLast() { return Truncate(Len() - 1); }
536 wxString
& Remove(size_t nStart
, size_t nLen
) { return erase( nStart
, nLen
); }
538 int First( const char ch
) const { return Find(ch
); }
539 int First( const char* psz
) const { return Find(psz
); }
540 int First( const wxString
&str
) const { return Find(str
); }
542 int Last( const char ch
) const { return Find(ch
, TRUE
); }
545 bool IsNull() const { return IsEmpty(); }
548 #ifdef STD_STRING_COMPATIBILITY
549 /** @name std::string compatibility functions */
551 /// an 'invalid' value for string index
552 static const size_t npos
;
555 /** @name constructors */
557 /// take nLen chars starting at nPos
558 wxString(const wxString
& str
, size_t nPos
, size_t nLen
= npos
)
560 wxASSERT( str
.GetStringData()->IsValid() );
561 InitWith(str
.c_str(), nPos
, nLen
== npos
? 0 : nLen
);
563 /// take all characters from pStart to pEnd
564 wxString(const void *pStart
, const void *pEnd
);
566 /** @name lib.string.capacity */
568 /// return the length of the string
569 size_t size() const { return Len(); }
570 /// return the length of the string
571 size_t length() const { return Len(); }
572 /// return the maximum size of the string
573 size_t max_size() const { return STRING_MAXLEN
; }
574 /// resize the string, filling the space with c if c != 0
575 void resize(size_t nSize
, char ch
= '\0');
576 /// delete the contents of the string
577 void clear() { Empty(); }
578 /// returns true if the string is empty
579 bool empty() const { return IsEmpty(); }
581 /** @name lib.string.access */
583 /// return the character at position n
584 char at(size_t n
) const { return GetChar(n
); }
585 /// returns the writable character at position n
586 char& at(size_t n
) { return GetWritableChar(n
); }
588 /** @name lib.string.modifiers */
590 /** @name append something to the end of this one */
593 wxString
& append(const wxString
& str
)
594 { *this += str
; return *this; }
595 /// append elements str[pos], ..., str[pos+n]
596 wxString
& append(const wxString
& str
, size_t pos
, size_t n
)
597 { ConcatSelf(n
, str
.c_str() + pos
); return *this; }
598 /// append first n (or all if n == npos) characters of sz
599 wxString
& append(const char *sz
, size_t n
= npos
)
600 { ConcatSelf(n
== npos
? Strlen(sz
) : n
, sz
); return *this; }
602 /// append n copies of ch
603 wxString
& append(size_t n
, char ch
) { return Pad(n
, ch
); }
606 /** @name replaces the contents of this string with another one */
608 /// same as `this_string = str'
609 wxString
& assign(const wxString
& str
) { return (*this) = str
; }
610 /// same as ` = str[pos..pos + n]
611 wxString
& assign(const wxString
& str
, size_t pos
, size_t n
)
612 { return *this = wxString((const char *)str
+ pos
, n
); }
613 /// same as `= first n (or all if n == npos) characters of sz'
614 wxString
& assign(const char *sz
, size_t n
= npos
)
615 { return *this = wxString(sz
, n
); }
616 /// same as `= n copies of ch'
617 wxString
& assign(size_t n
, char ch
)
618 { return *this = wxString(ch
, n
); }
622 /** @name inserts something at position nPos into this one */
624 /// insert another string
625 wxString
& insert(size_t nPos
, const wxString
& str
);
626 /// insert n chars of str starting at nStart (in str)
627 wxString
& insert(size_t nPos
, const wxString
& str
, size_t nStart
, size_t n
)
628 { return insert(nPos
, wxString((const char *)str
+ nStart
, n
)); }
630 /// insert first n (or all if n == npos) characters of sz
631 wxString
& insert(size_t nPos
, const char *sz
, size_t n
= npos
)
632 { return insert(nPos
, wxString(sz
, n
)); }
633 /// insert n copies of ch
634 wxString
& insert(size_t nPos
, size_t n
, char ch
)
635 { return insert(nPos
, wxString(ch
, n
)); }
639 /** @name deletes a part of the string */
641 /// delete characters from nStart to nStart + nLen
642 wxString
& erase(size_t nStart
= 0, size_t nLen
= npos
);
645 /** @name replaces a substring of this string with another one */
647 /// replaces the substring of length nLen starting at nStart
648 wxString
& replace(size_t nStart
, size_t nLen
, const char* sz
);
649 /// replaces the substring with nCount copies of ch
650 wxString
& replace(size_t nStart
, size_t nLen
, size_t nCount
, char ch
);
651 /// replaces a substring with another substring
652 wxString
& replace(size_t nStart
, size_t nLen
,
653 const wxString
& str
, size_t nStart2
, size_t nLen2
);
654 /// replaces the substring with first nCount chars of sz
655 wxString
& replace(size_t nStart
, size_t nLen
,
656 const char* sz
, size_t nCount
);
661 void swap(wxString
& str
);
663 /** @name string operations */
665 /** All find() functions take the nStart argument which specifies
666 the position to start the search on, the default value is 0.
668 All functions return npos if there were no match.
674 @name find a match for the string/character in this string
678 size_t find(const wxString
& str
, size_t nStart
= 0) const;
680 // VC++ 1.5 can't cope with this syntax.
681 #if ! (defined(_MSC_VER) && !defined(__WIN32__))
682 /// find first n characters of sz
683 size_t find(const char* sz
, size_t nStart
= 0, size_t n
= npos
) const;
685 /// find the first occurence of character ch after nStart
686 size_t find(char ch
, size_t nStart
= 0) const;
688 // wxWin compatibility
689 inline bool Contains(const wxString
& str
) { return Find(str
) != -1; }
694 @name rfind() family is exactly like find() but works right to left
697 /// as find, but from the end
698 size_t rfind(const wxString
& str
, size_t nStart
= npos
) const;
699 /// as find, but from the end
700 // VC++ 1.5 can't cope with this syntax.
701 #if ! (defined(_MSC_VER) && !defined(__WIN32__))
702 size_t rfind(const char* sz
, size_t nStart
= npos
,
703 size_t n
= npos
) const;
704 /// as find, but from the end
705 size_t rfind(char ch
, size_t nStart
= npos
) const;
710 @name find first/last occurence of any character in the set
714 size_t find_first_of(const wxString
& str
, size_t nStart
= 0) const;
716 size_t find_first_of(const char* sz
, size_t nStart
= 0) const;
717 /// same as find(char, size_t)
718 size_t find_first_of(char c
, size_t nStart
= 0) const;
721 size_t find_last_of (const wxString
& str
, size_t nStart
= npos
) const;
723 size_t find_last_of (const char* s
, size_t nStart
= npos
) const;
724 /// same as rfind(char, size_t)
725 size_t find_last_of (char c
, size_t nStart
= npos
) const;
729 @name find first/last occurence of any character not in the set
733 size_t find_first_not_of(const wxString
& str
, size_t nStart
= 0) const;
735 size_t find_first_not_of(const char* s
, size_t nStart
= 0) const;
737 size_t find_first_not_of(char ch
, size_t nStart
= 0) const;
740 size_t find_last_not_of(const wxString
& str
, size_t nStart
=npos
) const;
742 size_t find_last_not_of(const char* s
, size_t nStart
= npos
) const;
744 size_t find_last_not_of(char ch
, size_t nStart
= npos
) const;
749 All compare functions return -1, 0 or 1 if the [sub]string
750 is less, equal or greater than the compare() argument.
755 /// just like strcmp()
756 int compare(const wxString
& str
) const { return Cmp(str
); }
757 /// comparison with a substring
758 int compare(size_t nStart
, size_t nLen
, const wxString
& str
) const;
759 /// comparison of 2 substrings
760 int compare(size_t nStart
, size_t nLen
,
761 const wxString
& str
, size_t nStart2
, size_t nLen2
) const;
762 /// just like strcmp()
763 int compare(const char* sz
) const { return Cmp(sz
); }
764 /// substring comparison with first nCount characters of sz
765 int compare(size_t nStart
, size_t nLen
,
766 const char* sz
, size_t nCount
= npos
) const;
768 wxString
substr(size_t nStart
= 0, size_t nLen
= npos
) const;
773 // ----------------------------------------------------------------------------
774 /** The string array uses it's knowledge of internal structure of the String
775 class to optimize string storage. Normally, we would store pointers to
776 string, but as String is, in fact, itself a pointer (sizeof(String) is
777 sizeof(char *)) we store these pointers instead. The cast to "String *"
778 is really all we need to turn such pointer into a string!
780 Of course, it can be called a dirty hack, but we use twice less memory
781 and this approach is also more speed efficient, so it's probably worth it.
783 Usage notes: when a string is added/inserted, a new copy of it is created,
784 so the original string may be safely deleted. When a string is retrieved
785 from the array (operator[] or Item() method), a reference is returned.
788 @memo probably the most commonly used array type - array of strings
790 // ----------------------------------------------------------------------------
791 class WXDLLEXPORT wxArrayString
794 /** @name ctors and dtor */
799 wxArrayString(const wxArrayString
& array
);
800 /// assignment operator
801 wxArrayString
& operator=(const wxArrayString
& src
);
802 /// not virtual, this class can't be derived from
806 /** @name memory management */
808 /// empties the list, but doesn't release memory
810 /// empties the list and releases memory
812 /// preallocates memory for given number of items
813 void Alloc(size_t nCount
);
814 /// minimzes the memory usage (by freeing all extra memory)
818 /** @name simple accessors */
820 /// number of elements in the array
821 size_t Count() const { return m_nCount
; }
823 bool IsEmpty() const { return m_nCount
== 0; }
826 /** @name items access (range checking is done in debug version) */
828 /// get item at position uiIndex
829 wxString
& Item(size_t nIndex
) const
830 { wxASSERT( nIndex
< m_nCount
); return *(wxString
*)&(m_pItems
[nIndex
]); }
832 wxString
& operator[](size_t nIndex
) const { return Item(nIndex
); }
834 wxString
& Last() const { wxASSERT( !IsEmpty() ); return Item(Count() - 1); }
837 /** @name item management */
840 Search the element in the array, starting from the either side
841 @param if bFromEnd reverse search direction
842 @param if bCase, comparison is case sensitive (default)
843 @return index of the first item matched or NOT_FOUND
846 int Index (const char *sz
, bool bCase
= TRUE
, bool bFromEnd
= FALSE
) const;
847 /// add new element at the end
848 void Add (const wxString
& str
);
849 /// add new element at given position
850 void Insert(const wxString
& str
, size_t uiIndex
);
851 /// remove first item matching this value
852 void Remove(const char *sz
);
853 /// remove item by index
854 void Remove(size_t nIndex
);
857 /// sort array elements
858 void Sort(bool bCase
= TRUE
, bool bReverse
= FALSE
);
861 void Grow(); // makes array bigger if needed
862 void Free(); // free the string stored
864 size_t m_nSize
, // current size of the array
865 m_nCount
; // current number of elements
867 char **m_pItems
; // pointer to data
870 // ---------------------------------------------------------------------------
871 /** @name wxString comparison functions
872 @memo Comparisons are case sensitive
874 // ---------------------------------------------------------------------------
876 inline bool operator==(const wxString
& s1
, const wxString
& s2
) { return s1
.Cmp(s2
) == 0; }
878 inline bool operator==(const wxString
& s1
, const char * s2
) { return s1
.Cmp(s2
) == 0; }
880 inline bool operator==(const char * s1
, const wxString
& s2
) { return s2
.Cmp(s1
) == 0; }
882 inline bool operator!=(const wxString
& s1
, const wxString
& s2
) { return s1
.Cmp(s2
) != 0; }
884 inline bool operator!=(const wxString
& s1
, const char * s2
) { return s1
.Cmp(s2
) != 0; }
886 inline bool operator!=(const char * s1
, const wxString
& s2
) { return s2
.Cmp(s1
) != 0; }
888 inline bool operator< (const wxString
& s1
, const wxString
& s2
) { return s1
.Cmp(s2
) < 0; }
890 inline bool operator< (const wxString
& s1
, const char * s2
) { return s1
.Cmp(s2
) < 0; }
892 inline bool operator< (const char * s1
, const wxString
& s2
) { return s2
.Cmp(s1
) > 0; }
894 inline bool operator> (const wxString
& s1
, const wxString
& s2
) { return s1
.Cmp(s2
) > 0; }
896 inline bool operator> (const wxString
& s1
, const char * s2
) { return s1
.Cmp(s2
) > 0; }
898 inline bool operator> (const char * s1
, const wxString
& s2
) { return s2
.Cmp(s1
) < 0; }
900 inline bool operator<=(const wxString
& s1
, const wxString
& s2
) { return s1
.Cmp(s2
) <= 0; }
902 inline bool operator<=(const wxString
& s1
, const char * s2
) { return s1
.Cmp(s2
) <= 0; }
904 inline bool operator<=(const char * s1
, const wxString
& s2
) { return s2
.Cmp(s1
) >= 0; }
906 inline bool operator>=(const wxString
& s1
, const wxString
& s2
) { return s1
.Cmp(s2
) >= 0; }
908 inline bool operator>=(const wxString
& s1
, const char * s2
) { return s1
.Cmp(s2
) >= 0; }
910 inline bool operator>=(const char * s1
, const wxString
& s2
) { return s2
.Cmp(s1
) <= 0; }
913 // ---------------------------------------------------------------------------
914 /** @name Global functions complementing standard C string library
915 @memo replacements for strlen() and portable strcasecmp()
917 // ---------------------------------------------------------------------------
919 #ifdef STD_STRING_COMPATIBILITY
922 class WXDLLEXPORT istream
;
924 istream
& WXDLLEXPORT
operator>>(istream
& is
, wxString
& str
);
926 #endif //std::string compatibility
928 #endif // _WX_WXSTRINGH__