1 /***********************************************************************
2 filename: CEGUIString.h
6 purpose: Defines string class used within the GUI system.
7 *************************************************************************/
8 /***************************************************************************
9 * Copyright (C) 2004 - 2006 Paul D Turner & The CEGUI Development Team
11 * Permission is hereby granted, free of charge, to any person obtaining
12 * a copy of this software and associated documentation files (the
13 * "Software"), to deal in the Software without restriction, including
14 * without limitation the rights to use, copy, modify, merge, publish,
15 * distribute, sublicense, and/or sell copies of the Software, and to
16 * permit persons to whom the Software is furnished to do so, subject to
17 * the following conditions:
19 * The above copyright notice and this permission notice shall be
20 * included in all copies or substantial portions of the Software.
22 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
23 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
24 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
25 * IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
26 * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
27 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
28 * OTHER DEALINGS IN THE SOFTWARE.
29 ***************************************************************************/
30 #ifndef _CEGUIString_h_
31 #define _CEGUIString_h_
33 #include "CEGUIBase.h"
38 // Start of CEGUI namespace section
41 #define STR_QUICKBUFF_SIZE 32
42 /*************************************************************************
44 *************************************************************************/
46 //typedef uint16 utf16; // removed typedef to prevent usage, as utf16 is not supported (yet)
51 String class used within the GUI system.
53 For the most part, this class can replace std::string in basic usage. However, currently String does not use the
54 current locale, and also comparisons do not take into account the Unicode data tables, so are not 'correct'
57 class CEGUIEXPORT String
60 /*************************************************************************
62 *************************************************************************/
63 typedef utf32 value_type
; //!< Basic 'code point' type used for String (utf32)
64 typedef size_t size_type
; //!< Unsigned type used for size values and indices
65 typedef std::ptrdiff_t difference_type
; //!< Signed type used for differences
66 typedef utf32
& reference
; //!< Type used for utf32 code point references
67 typedef const utf32
& const_reference
; //!< Type used for constant utf32 code point references
68 typedef utf32
* pointer
; //!< Type used for utf32 code point pointers
69 typedef const utf32
* const_pointer
; //!< Type used for constant utf32 code point pointers
71 static const size_type npos
; //!< Value used to represent 'not found' conditions and 'all code points' etc.
74 /*************************************************************************
76 *************************************************************************/
77 size_type d_cplength
; //!< holds length of string in code points (not including null termination)
78 size_type d_reserve
; //!< code point reserve size (currently allocated buffer size in code points).
80 mutable utf8
* d_encodedbuff
; //!< holds string data encoded as utf8 (generated only by calls to c_str() and data())
81 mutable size_type d_encodeddatlen
; //!< holds length of encoded data (in case it's smaller than buffer).
82 mutable size_type d_encodedbufflen
; //!< length of above buffer (since buffer can be bigger then the data it holds to save re-allocations).
84 utf32 d_quickbuff
[STR_QUICKBUFF_SIZE
]; //!< This is a integrated 'quick' buffer to save allocations for smallish strings
85 utf32
* d_buffer
; //!< Pointer the the main buffer memory. This is only valid when quick-buffer is not being used
88 /*************************************************************************
90 *************************************************************************/
93 Constant forward iterator class for String objects
95 #if defined(_MSC_VER) && (_MSC_VER <= 1200)
96 class const_iterator
: public std::iterator
<std::random_access_iterator_tag
, utf32
>
98 class const_iterator
: public std::iterator
<std::random_access_iterator_tag
, utf32
, std::ptrdiff_t, const utf32
*, const utf32
&>
103 //////////////////////////////////////////////////////////////////////////
105 //////////////////////////////////////////////////////////////////////////
109 //////////////////////////////////////////////////////////////////////////
111 //////////////////////////////////////////////////////////////////////////
116 const_iterator(const_pointer ptr
)
121 const_reference
operator*() const
126 #if defined(_MSC_VER) && (_MSC_VER <= 1200)
127 # pragma warning (push)
128 # pragma warning (disable : 4284)
130 const_pointer
operator->() const
135 #if defined(_MSC_VER) && (_MSC_VER <= 1200)
136 # pragma warning (pop)
139 const_iterator
& operator++()
145 const_iterator
operator++(int)
147 const_iterator temp
= *this;
152 const_iterator
& operator--()
158 const_iterator
operator--(int)
160 const_iterator temp
= *this;
165 const_iterator
& operator+=(difference_type offset
)
171 const_iterator
operator+(difference_type offset
) const
173 const_iterator temp
= *this;
174 return temp
+= offset
;
177 const_iterator
& operator-=(difference_type offset
)
179 return *this += -offset
;
182 const_iterator
operator-(difference_type offset
) const
184 const_iterator temp
= *this;
185 return temp
-= offset
;
188 difference_type
operator-(const const_iterator
& iter
) const
190 return d_ptr
- iter
.d_ptr
;
193 const_reference
operator[](difference_type offset
) const
195 return *(*this + offset
);
198 bool operator==(const const_iterator
& iter
) const
200 return d_ptr
== iter
.d_ptr
;
203 bool operator!=(const const_iterator
& iter
) const
205 return !(*this == iter
);
208 bool operator<(const const_iterator
& iter
) const
210 return d_ptr
< iter
.d_ptr
;
213 bool operator>(const const_iterator
& iter
) const
215 return (!(iter
< *this));
218 bool operator<=(const const_iterator
& iter
) const
220 return (!(iter
< *this));
223 bool operator>=(const const_iterator
& iter
) const
225 return (!(*this < iter
));
228 friend const_iterator
operator+(difference_type offset
, const const_iterator
& iter
)
230 return iter
+ offset
;
237 Forward iterator class for String objects
239 class iterator
: public const_iterator
243 iterator(pointer ptr
) : const_iterator(ptr
) {}
246 reference
operator*() const
248 return ((reference
)**(const_iterator
*)this);
251 #if defined(_MSC_VER) && (_MSC_VER <= 1200)
252 # pragma warning (push)
253 # pragma warning (disable : 4284)
256 pointer
operator->() const
261 #if defined(_MSC_VER) && (_MSC_VER <= 1200)
262 # pragma warning (pop)
265 iterator
& operator++()
271 iterator
operator++(int)
273 iterator temp
= *this;
278 iterator
& operator--()
284 iterator
operator--(int)
286 iterator temp
= *this;
291 iterator
& operator+=(difference_type offset
)
293 this->d_ptr
+= offset
;
297 iterator
operator+(difference_type offset
) const
299 iterator temp
= *this;
300 return temp
+ offset
;
303 iterator
& operator-=(difference_type offset
)
305 return *this += -offset
;
308 iterator
operator-(difference_type offset
) const
310 iterator temp
= *this;
311 return temp
-= offset
;
314 difference_type
operator-(const const_iterator
& iter
) const
316 return ((const_iterator
)*this - iter
);
319 reference
operator[](difference_type offset
) const
321 return *(*this + offset
);
324 friend iterator
operator+(difference_type offset
, const iterator
& iter
)
326 return iter
+ offset
;
333 Constant reverse iterator class for String objects
335 #if defined(_MSC_VER) && ((_MSC_VER <= 1200) || ((_MSC_VER <= 1300) && defined(_STLPORT_VERSION)))
336 typedef std::reverse_iterator
<const_iterator
, const_pointer
, const_reference
, difference_type
> const_reverse_iterator
;
338 typedef std::reverse_iterator
<const_iterator
> const_reverse_iterator
;
343 Reverse iterator class for String objects
345 #if defined(_MSC_VER) && ((_MSC_VER <= 1200) || ((_MSC_VER <= 1300) && defined(_STLPORT_VERSION)))
346 typedef std::reverse_iterator
<iterator
, pointer
, reference
, difference_type
> reverse_iterator
;
348 typedef std::reverse_iterator
<iterator
> reverse_iterator
;
354 Functor that can be used as comparator in a std::map with String keys.
355 It's faster than using the default, but the map will no longer be sorted alphabetically.
357 struct FastLessCompare
359 bool operator() (const String
& a
, const String
& b
) const
361 const size_t la
= a
.length();
362 const size_t lb
= b
.length();
364 return (memcmp(a
.ptr(), b
.ptr(), la
*sizeof(utf32
)) < 0);
370 //////////////////////////////////////////////////////////////////////////
371 // Default Construction and Destructor
372 //////////////////////////////////////////////////////////////////////////
375 Constructs an empty string
384 Destructor for String objects
388 //////////////////////////////////////////////////////////////////////////
389 // Construction via CEGUI::String
390 //////////////////////////////////////////////////////////////////////////
393 Copy constructor - Creates a new string with the same value as \a str
396 String object used to initialise the newly created string
401 String(const String
& str
)
410 Constructs a new string initialised with code points from another String object.
413 String object used to initialise the newly created string
416 Starting code-point of \a str to be used when initialising the new String
419 Maximum number of code points from \a str that are to be assigned to the new String
424 String(const String
& str
, size_type str_idx
, size_type str_num
= npos
)
427 assign(str
, str_idx
, str_num
);
430 //////////////////////////////////////////////////////////////////////////
431 // Construction via std::string
432 //////////////////////////////////////////////////////////////////////////
435 Constructs a new string and initialises it using the std::string std_str
438 The std::string object that is to be used to initialise the new String object.
441 The characters of \a std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF. No translation of
442 the provided data will occur.
447 \exception std::length_error Thrown if resulting String object would be too big.
449 String(const std::string
& std_str
)
457 Constructs a new string initialised with characters from the given std::string object.
460 std::string object used to initialise the newly created string
463 Starting character of \a std_str to be used when initialising the new String
466 The characters of \a std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF. No translation of
467 the provided data will occur.
470 Maximum number of characters from \a std_str that are to be assigned to the new String
475 \exception std::length_error Thrown if resulting String object would be too big.
477 String(const std::string
& std_str
, size_type str_idx
, size_type str_num
= npos
)
480 assign(std_str
, str_idx
, str_num
);
484 //////////////////////////////////////////////////////////////////////////
485 // Construction via UTF-8 stream (for straight ASCII use, only codes 0x00 - 0x7f are valid)
486 //////////////////////////////////////////////////////////////////////////
489 Constructs a new String object and initialise it using the provided utf8 encoded string buffer.
492 Pointer to a buffer containing a null-terminated Unicode string encoded as utf8 data.
495 A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
496 comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f)
497 would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
503 \exception std::length_error Thrown if resulting String object would be too big.
505 String(const utf8
* utf8_str
)
513 Constructs a new String object and initialise it using the provided utf8 encoded string buffer.
515 A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
516 comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f)
517 would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
521 Pointer to a buffer containing Unicode string data encoded as utf8.
524 A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
525 comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f)
526 would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
530 Length of the provided utf8 string in code units (not code-points).
535 \exception std::length_error Thrown if resulting String object would be too big.
537 String(const utf8
* utf8_str
, size_type chars_len
)
540 assign(utf8_str
, chars_len
);
543 //////////////////////////////////////////////////////////////////////////
544 // Construction via code-point (using a UTF-32 code unit)
545 //////////////////////////////////////////////////////////////////////////
548 Constructs a new String that is initialised with the specified code point
551 The number of times \a code_point is to be put into new String object
554 The Unicode code point to be used when initialising the String object
559 \exception std::length_error Thrown if resulting String object would be too big.
561 String(size_type num
, utf32 code_point
)
564 assign(num
, code_point
);
567 //////////////////////////////////////////////////////////////////////////
568 // Construction via iterator
569 //////////////////////////////////////////////////////////////////////////
570 // Create string with characters in the range [beg, end)
573 Construct a new string object and initialise it with code-points from the range [beg, end).
576 Iterator describing the start of the data to be used when initialising the String object
579 Iterator describing the (exclusive) end of the data to be used when initialising the String object
584 String(const_iterator iter_beg
, const_iterator iter_end
)
587 append(iter_beg
, iter_end
);
591 //////////////////////////////////////////////////////////////////////////
592 // Construction via c-string
593 //////////////////////////////////////////////////////////////////////////
596 Constructs a new String object and initialise it using the provided c-string.
599 Pointer to a c-string.
604 \exception std::length_error Thrown if resulting String object would be too big.
606 String(const char* cstr
)
614 Constructs a new String object and initialise it using characters from the provided char array.
620 Number of chars from the array to be used.
625 \exception std::length_error Thrown if resulting String object would be too big.
627 String(const char* chars
, size_type chars_len
)
630 assign(chars
, chars_len
);
634 //////////////////////////////////////////////////////////////////////////
636 //////////////////////////////////////////////////////////////////////////
639 Returns the size of the String in code points
642 Number of code points currently in the String
644 size_type
size(void) const
651 Returns the size of the String in code points
654 Number of code points currently in the String
656 size_type
length(void) const
663 Returns true if the String is empty
666 true if the String is empty, else false.
668 bool empty(void) const
670 return (d_cplength
== 0);
675 Returns the maximum size of a String.
677 Any operation that would result in a String that is larger than this value will throw the std::length_error exception.
680 The maximum number of code points that a string can contain
682 static size_type
max_size(void)
684 return (((size_type
)-1) / sizeof(utf32
));
687 //////////////////////////////////////////////////////////////////////////
688 // Capacity Operations
689 //////////////////////////////////////////////////////////////////////////
690 // return the number of code points the string could hold without re-allocation
691 // (due to internal encoding this will always report the figure for worst-case encoding, and could even be < size()!)
694 Return the number of code points that the String could hold before a re-allocation would be required.
697 Size of the current reserve buffer. This is the maximum number of code points the String could hold before a buffer
698 re-allocation would be required
700 size_type
capacity(void) const
702 return d_reserve
- 1;
705 // reserve internal memory for at-least 'num' code-points (characters). if num is 0, request is shrink-to-fit.
708 Specifies the amount of reserve capacity to allocate.
711 The number of code points to allocate space for. If \a num is larger that the current reserve, then a re-allocation will occur. If
712 \a num is smaller than the current reserve (but not 0) the buffer may be shrunk to the larger of the specified number, or the current
713 String size (operation is currently not implemented). If \a num is 0, then the buffer is re-allocated to fit the current String size.
718 \exception std::length_error Thrown if resulting String object would be too big.
720 void reserve(size_type num
= 0)
728 //////////////////////////////////////////////////////////////////////////
730 //////////////////////////////////////////////////////////////////////////
733 Compares this String with the String 'str'.
736 This does currently not properly consider Unicode and / or the system locale.
739 The String object that is to compared with this String.
742 - 0 if the String objects are equal
743 - <0 if this String is lexicographically smaller than \a str
744 - >0 if this String is lexicographically greater than \a str
746 int compare(const String
& str
) const
748 return compare(0, d_cplength
, str
);
753 Compares code points from this String with code points from the String 'str'.
756 This does currently not properly consider Unicode and / or the system locale.
759 Index of the first code point from this String to consider.
762 Maximum number of code points from this String to consider.
765 The String object that is to compared with this String.
768 Index of the first code point from String \a str to consider.
771 Maximum number of code points from String \a str to consider
774 - 0 if the specified sub-strings are equal
775 - <0 if specified sub-strings are lexicographically smaller than \a str
776 - >0 if specified sub-strings are lexicographically greater than \a str
778 \exception std::out_of_range Thrown if either \a idx or \a str_idx are invalid.
780 int compare(size_type idx
, size_type len
, const String
& str
, size_type str_idx
= 0, size_type str_len
= npos
) const
782 if ((d_cplength
< idx
) || (str
.d_cplength
< str_idx
))
783 throw std::out_of_range("Index is out of range for CEGUI::String");
785 if ((len
== npos
) || (idx
+ len
> d_cplength
))
786 len
= d_cplength
- idx
;
788 if ((str_len
== npos
) || (str_idx
+ str_len
> str
.d_cplength
))
789 str_len
= str
.d_cplength
- str_idx
;
791 int val
= (len
== 0) ? 0 : utf32_comp_utf32(&ptr()[idx
], &str
.ptr()[str_idx
], (len
< str_len
) ? len
: str_len
);
793 return (val
!= 0) ? ((val
< 0) ? -1 : 1) : (len
< str_len
) ? -1 : (len
== str_len
) ? 0 : 1;
799 Compares this String with the std::string 'std_str'.
802 This does currently not properly consider Unicode and / or the system locale.
805 The std::string object that is to compared with this String.
808 Characters from \a std_str are considered to represent Unicode code points in the range 0x00..0xFF. No translation of
809 the encountered data is performed.
812 - 0 if the string objects are equal
813 - <0 if this string is lexicographically smaller than \a std_str
814 - >0 if this string is lexicographically greater than \a std_str
816 int compare(const std::string
& std_str
) const
818 return compare(0, d_cplength
, std_str
);
824 Compares code points from this String with code points from the std::string 'std_str'.
827 This does currently not properly consider Unicode and / or the system locale.
830 Index of the first code point from this String to consider.
833 Maximum number of code points from this String to consider.
836 The std::string object that is to compared with this String.
839 Characters from \a std_str are considered to represent Unicode code points in the range 0x00..0xFF. No translation of
840 the encountered data is performed.
843 Index of the first character from std::string \a std_str to consider.
846 Maximum number of characters from std::string \a std_str to consider
849 - 0 if the specified sub-strings are equal
850 - <0 if specified sub-strings are lexicographically smaller than \a std_str
851 - >0 if specified sub-strings are lexicographically greater than \a std_str
853 \exception std::out_of_range Thrown if either \a idx or \a str_idx are invalid.
855 int compare(size_type idx
, size_type len
, const std::string
& std_str
, size_type str_idx
= 0, size_type str_len
= npos
) const
857 if (d_cplength
< idx
)
858 throw std::out_of_range("Index is out of range for CEGUI::String");
860 if (std_str
.size() < str_idx
)
861 throw std::out_of_range("Index is out of range for std::string");
863 if ((len
== npos
) || (idx
+ len
> d_cplength
))
864 len
= d_cplength
- idx
;
866 if ((str_len
== npos
) || (str_idx
+ str_len
> std_str
.size()))
867 str_len
= (size_type
)std_str
.size() - str_idx
;
869 int val
= (len
== 0) ? 0 : utf32_comp_char(&ptr()[idx
], &std_str
.c_str()[str_idx
], (len
< str_len
) ? len
: str_len
);
871 return (val
!= 0) ? ((val
< 0) ? -1 : 1) : (len
< str_len
) ? -1 : (len
== str_len
) ? 0 : 1;
877 Compares this String with the null-terminated utf8 encoded 'utf8_str'.
880 This does currently not properly consider Unicode and / or the system locale.
883 The buffer containing valid Unicode data encoded as utf8 that is to compared with this String.
886 A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
887 comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f)
888 would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
892 - 0 if the strings are equal
893 - <0 if this string is lexicographically smaller than \a utf8_str
894 - >0 if this string is lexicographically greater than \a utf8_str
896 int compare(const utf8
* utf8_str
) const
898 return compare(0, d_cplength
, utf8_str
, encoded_size(utf8_str
));
904 Compares code points from this String with the null-terminated utf8 encoded 'utf8_str'.
907 This does currently not properly consider Unicode and / or the system locale.
910 Index of the first code point from this String to consider.
913 Maximum number of code points from this String to consider.
916 The buffer containing valid Unicode data encoded as utf8 that is to compared with this String.
919 A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
920 comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f)
921 would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
925 - 0 if the specified sub-strings are equal
926 - <0 if specified sub-strings are lexicographically smaller than \a utf8_str
927 - >0 if specified sub-strings are lexicographically greater than \a utf8_str
929 \exception std::out_of_range Thrown if \a idx is invalid.
931 int compare(size_type idx
, size_type len
, const utf8
* utf8_str
) const
933 return compare(idx
, len
, utf8_str
, encoded_size(utf8_str
));
938 Compares code points from this String with the utf8 encoded data in buffer 'utf8_str'.
941 This does currently not properly consider Unicode and / or the system locale.
944 Index of the first code point from this String to consider.
947 Maximum number of code points from this String to consider.
950 The buffer containing valid Unicode data encoded as utf8 that is to compared with this String.
953 A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
954 comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f)
955 would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
959 The number of encoded code points in the buffer \a utf8_str (this is not the same as the number of code units).
962 - 0 if the specified sub-strings are equal
963 - <0 if specified sub-strings are lexicographically smaller than \a utf8_str
964 - >0 if specified sub-strings are lexicographically greater than \a utf8_str
966 \exception std::out_of_range Thrown if \a idx is invalid.
967 \exception std::length_error Thrown if \a str_cplen is set to npos.
969 int compare(size_type idx
, size_type len
, const utf8
* utf8_str
, size_type str_cplen
) const
971 if (d_cplength
< idx
)
972 throw std::out_of_range("Index is out of range for CEGUI::String");
974 if (str_cplen
== npos
)
975 throw std::length_error("Length for utf8 encoded string can not be 'npos'");
977 if ((len
== npos
) || (idx
+ len
> d_cplength
))
978 len
= d_cplength
- idx
;
980 int val
= (len
== 0) ? 0 : utf32_comp_utf8(&ptr()[idx
], utf8_str
, (len
< str_cplen
) ? len
: str_cplen
);
982 return (val
!= 0) ? ((val
< 0) ? -1 : 1) : (len
< str_cplen
) ? -1 : (len
== str_cplen
) ? 0 : 1;
988 Compares this String with the given c-string.
991 This does currently not properly consider Unicode and / or the system locale.
994 The c-string that is to compared with this String.
997 - 0 if the strings are equal
998 - <0 if this string is lexicographically smaller than \a c_str
999 - >0 if this string is lexicographically greater than \a c_str
1001 int compare(const char* cstr
) const
1003 return compare(0, d_cplength
, cstr
, strlen(cstr
));
1009 Compares code points from this String with the given c-string.
1012 This does currently not properly consider Unicode and / or the system locale.
1015 Index of the first code point from this String to consider.
1018 Maximum number of code points from this String to consider.
1021 The c-string that is to compared with this String.
1024 - 0 if the specified sub-strings are equal
1025 - <0 if specified sub-strings are lexicographically smaller than \a c_str
1026 - >0 if specified sub-strings are lexicographically greater than \a c_str
1028 \exception std::out_of_range Thrown if \a idx is invalid.
1030 int compare(size_type idx
, size_type len
, const char* cstr
) const
1032 return compare(idx
, len
, cstr
, strlen(cstr
));
1038 Compares code points from this String with chars in the given char array.
1041 This does currently not properly consider Unicode and / or the system locale.
1044 Index of the first code point from this String to consider.
1047 Maximum number of code points from this String to consider.
1050 The array containing the chars that are to compared with this String.
1053 The number of chars in the array.
1056 - 0 if the specified sub-strings are equal
1057 - <0 if specified sub-strings are lexicographically smaller than \a chars
1058 - >0 if specified sub-strings are lexicographically greater than \a chars
1060 \exception std::out_of_range Thrown if \a idx is invalid.
1061 \exception std::length_error Thrown if \a chars_len is set to npos.
1063 int compare(size_type idx
, size_type len
, const char* chars
, size_type chars_len
) const
1065 if (d_cplength
< idx
)
1066 throw std::out_of_range("Index is out of range for CEGUI::String");
1068 if (chars_len
== npos
)
1069 throw std::length_error("Length for char array can not be 'npos'");
1071 if ((len
== npos
) || (idx
+ len
> d_cplength
))
1072 len
= d_cplength
- idx
;
1074 int val
= (len
== 0) ? 0 : utf32_comp_char(&ptr()[idx
], chars
, (len
< chars_len
) ? len
: chars_len
);
1076 return (val
!= 0) ? ((val
< 0) ? -1 : 1) : (len
< chars_len
) ? -1 : (len
== chars_len
) ? 0 : 1;
1080 //////////////////////////////////////////////////////////////////////////
1082 //////////////////////////////////////////////////////////////////////////
1085 Returns the code point at the given index.
1088 Zero based index of the code point to be returned.
1091 - For constant strings length()/size() provide a valid index and will access the default utf32 value.
1092 - For non-constant strings length()/size() is an invalid index, and acceesing (especially writing) this index could cause string corruption.
1095 The utf32 code point at the given index within the String.
1097 reference
operator[](size_type idx
)
1099 return (ptr()[idx
]);
1104 Returns the code point at the given index.
1107 Zero based index of the code point to be returned.
1110 - For constant strings length()/size() provide a valid index and will access the default utf32 value.
1111 - For non-constant strings length()/size() is an invalid index, and acceesing (especially writing) this index could cause string corruption.
1114 The utf32 code point at the given index within the String.
1116 value_type
operator[](size_type idx
) const
1123 Returns the code point at the given index.
1126 Zero based index of the code point to be returned.
1129 The utf32 code point at the given index within the String.
1131 \exception std::out_of_range Thrown if \a idx is >= length().
1133 reference
at(size_type idx
)
1135 if (d_cplength
<= idx
)
1136 throw std::out_of_range("Index is out of range for CEGUI::String");
1143 Returns the code point at the given index.
1146 Zero based index of the code point to be returned.
1149 The utf32 code point at the given index within the String.
1151 \exception std::out_of_range Thrown if \a idx is >= length().
1153 const_reference
at(size_type idx
) const
1155 if (d_cplength
<= idx
)
1156 throw std::out_of_range("Index is out of range for CEGUI::String");
1162 //////////////////////////////////////////////////////////////////////////
1163 // C-Strings and arrays
1164 //////////////////////////////////////////////////////////////////////////
1167 Returns contents of the String as a null terminated string of utf8 encoded data.
1170 Pointer to a char buffer containing the contents of the String encoded as null-terminated utf8 data.
1173 The buffer returned from this function is owned by the String object.
1176 Any function that modifies the String data will invalidate the buffer returned by this call.
1178 const char* c_str(void) const
1180 return (const char*)build_utf8_buff();
1185 Returns contents of the String as utf8 encoded data.
1188 Pointer to a buffer containing the contents of the String encoded utf8 data.
1191 The buffer returned from this function is owned by the String object.
1194 Any function that modifies the String data will invalidate the buffer returned by this call.
1196 const utf8
* data(void) const
1198 return build_utf8_buff();
1203 Returns a pointer to the buffer in use.
1207 return (d_reserve
> STR_QUICKBUFF_SIZE
) ? d_buffer
: d_quickbuff
;
1212 Returns a pointer to the buffer in use. (const version)
1214 const utf32
* ptr(void) const
1216 return (d_reserve
> STR_QUICKBUFF_SIZE
) ? d_buffer
: d_quickbuff
;
1219 // copy, at most, 'len' code-points of the string, begining with code-point 'idx', into the array 'buf' as valid utf8 encoded data
1220 // return number of utf8 code units placed into the buffer
1223 Copies an area of the String into the provided buffer as encoded utf8 data.
1226 Pointer to a buffer that is to receive the encoded data (this must be big enough to hold the encoded data)
1229 Maximum number of code points from the String that should be encoded into the buffer
1232 Index of the first code point to be encoded into the buffer
1235 The number of utf8 encoded code units transferred to the buffer.
1237 \note A code unit does not equal a code point. A utf32 code point, when encoded as utf8, can occupy between 1 and 4 code units.
1239 \exception std::out_of_range Thrown if \a idx was invalid for this String.
1241 size_type
copy(utf8
* buf
, size_type len
= npos
, size_type idx
= 0) const
1243 if (d_cplength
< idx
)
1244 throw std::out_of_range("Index is out of range for CEGUI::String");
1249 return encode(&ptr()[idx
], buf
, npos
, len
);
1252 //////////////////////////////////////////////////////////////////////////
1253 // UTF8 Encoding length information
1254 //////////////////////////////////////////////////////////////////////////
1255 // return the number of bytes required to hold 'num' code-points, starting at code-point 'idx', of the the string when encoded as utf8 data.
1258 Return the number of utf8 code units required to hold an area of the String when encoded as utf8 data
1261 Maximum number of code points to consider when calculating utf8 encoded size.
1264 Index of the first code point to consider when calculating the utf8 encoded size
1267 The number of utf8 code units (bytes) required to hold the specified sub-string when encoded as utf8 data.
1269 \exception std::out_of_range Thrown if \a idx was invalid for this String.
1271 size_type
utf8_stream_len(size_type num
= npos
, size_type idx
= 0) const
1273 using namespace std
;
1275 if (d_cplength
< idx
)
1276 throw out_of_range("Index was out of range for CEGUI::String object");
1278 size_type maxlen
= d_cplength
- idx
;
1280 return encoded_size(&ptr()[idx
], ceguimin(num
, maxlen
));
1283 //////////////////////////////////////////////////////////////////////////
1284 // Assignment Functions
1285 //////////////////////////////////////////////////////////////////////////
1288 Assign the value of String \a str to this String
1291 String object containing the string value to be assigned.
1294 This String after the assignment has happened
1296 String
& operator=(const String
& str
)
1303 Assign a sub-string of String \a str to this String
1306 String object containing the string data to be assigned.
1309 Index of the first code point in \a str that is to be assigned
1312 Maximum number of code points from \a str that are be be assigned
1315 This String after the assignment has happened
1317 \exception std::out_of_range Thrown if str_idx is invalid for \a str
1319 String
& assign(const String
& str
, size_type str_idx
= 0, size_type str_num
= npos
)
1321 if (str
.d_cplength
< str_idx
)
1322 throw std::out_of_range("Index was out of range for CEGUI::String object");
1324 if (str_num
== npos
)
1325 str_num
= str
.d_cplength
- str_idx
;
1329 memcpy(ptr(), &str
.ptr()[str_idx
], str_num
* sizeof(utf32
));
1336 Assign the value of std::string \a std_str to this String
1339 The characters of \a std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF. No translation of
1340 the provided data will occur.
1343 std::string object containing the string value to be assigned.
1346 This String after the assignment has happened
1348 \exception std::length_error Thrown if the resulting String would have been too large.
1350 String
& operator=(const std::string
& std_str
)
1352 return assign(std_str
);
1357 Assign a sub-string of std::string \a std_str to this String
1360 The characters of \a std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF. No translation of
1361 the provided data will occur.
1364 std::string object containing the string value to be assigned.
1367 Index of the first character of \a std_str to be assigned
1370 Maximum number of characters from \a std_str to be assigned
1373 This String after the assignment has happened
1375 \exception std::out_of_range Thrown if \a str_idx is invalid for \a std_str
1376 \exception std::length_error Thrown if the resulting String would have been too large.
1378 String
& assign(const std::string
& std_str
, size_type str_idx
= 0, size_type str_num
= npos
)
1380 if (std_str
.size() < str_idx
)
1381 throw std::out_of_range("Index was out of range for std::string object");
1383 if (str_num
== npos
)
1384 str_num
= (size_type
)std_str
.size() - str_idx
;
1391 ((*this)[str_num
]) = static_cast<utf32
>(static_cast<unsigned char>(std_str
[str_num
+ str_idx
]));
1399 Assign to this String the string value represented by the given null-terminated utf8 encoded data
1402 A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
1403 comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f)
1404 would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
1408 Buffer containing valid null-terminated utf8 encoded data
1411 This String after the assignment has happened
1413 \exception std::length_error Thrown if the resulting String would have been too large.
1415 String
& operator=(const utf8
* utf8_str
)
1417 return assign(utf8_str
, utf_length(utf8_str
));
1422 Assign to this String the string value represented by the given null-terminated utf8 encoded data
1425 A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
1426 comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f)
1427 would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
1431 Buffer containing valid null-terminated utf8 encoded data
1434 This String after the assignment has happened
1436 \exception std::length_error Thrown if the resulting String would have been too large.
1438 String
& assign(const utf8
* utf8_str
)
1440 return assign(utf8_str
, utf_length(utf8_str
));
1445 Assign to this String the string value represented by the given utf8 encoded data
1448 A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
1449 comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f)
1450 would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
1454 Buffer containing valid utf8 encoded data
1457 Number of code units (not code points) in the buffer pointed to by \a utf8_str
1460 This String after the assignment has happened
1462 \exception std::length_error Thrown if the resulting String would have been too large, or if str_num is 'npos'.
1464 String
& assign(const utf8
* utf8_str
, size_type str_num
)
1466 if (str_num
== npos
)
1467 throw std::length_error("Length for utf8 encoded string can not be 'npos'");
1469 size_type enc_sze
= encoded_size(utf8_str
, str_num
);
1472 encode(utf8_str
, ptr(), d_reserve
, str_num
);
1479 Assigns the specified utf32 code point to this String. Result is always a String 1 code point in length.
1482 Valid utf32 Unicode code point to be assigned to the string
1485 This String after assignment
1487 String
& operator=(utf32 code_point
)
1489 return assign(1, code_point
);
1494 Assigns the specified code point repeatedly to the String
1497 The number of times to assign the code point
1500 Valid utf32 Unicode code point to be assigned to the string
1503 This String after assignment.
1505 \exception std::length_error Thrown if \a num was 'npos'
1507 String
& assign(size_type num
, utf32 code_point
)
1510 throw std::length_error("Code point count can not be 'npos'");
1525 Assign to this String the given C-string.
1528 Pointer to a valid C style string.
1531 This String after the assignment has happened
1533 \exception std::length_error Thrown if the resulting String would have been too large.
1535 String
& operator=(const char* cstr
)
1537 return assign(cstr
, strlen(cstr
));
1543 Assign to this String the given C-string.
1546 Pointer to a valid C style string.
1549 This String after the assignment has happened
1551 \exception std::length_error Thrown if the resulting String would have been too large.
1553 String
& assign(const char* cstr
)
1555 return assign(cstr
, strlen(cstr
));
1561 Assign to this String a number of chars from a char array.
1567 Number of chars to be assigned.
1570 This String after the assignment has happened
1572 \exception std::length_error Thrown if the resulting String would have been too large.
1574 String
& assign(const char* chars
, size_type chars_len
)
1579 for (size_type i
= 0; i
< chars_len
; ++i
)
1581 *pt
++ = static_cast<utf32
>(static_cast<unsigned char>(*chars
++));
1591 Swaps the value of this String with the given String \a str
1594 String object whos value is to be swapped with this String.
1599 void swap(String
& str
)
1601 size_type temp_len
= d_cplength
;
1602 d_cplength
= str
.d_cplength
;
1603 str
.d_cplength
= temp_len
;
1605 size_type temp_res
= d_reserve
;
1606 d_reserve
= str
.d_reserve
;
1607 str
.d_reserve
= temp_res
;
1609 utf32
* temp_buf
= d_buffer
;
1610 d_buffer
= str
.d_buffer
;
1611 str
.d_buffer
= temp_buf
;
1613 // see if we need to swap 'quick buffer' data
1614 if (temp_res
<= STR_QUICKBUFF_SIZE
)
1616 utf32 temp_qbf
[STR_QUICKBUFF_SIZE
];
1618 memcpy(temp_qbf
, d_quickbuff
, STR_QUICKBUFF_SIZE
* sizeof(utf32
));
1619 memcpy(d_quickbuff
, str
.d_quickbuff
, STR_QUICKBUFF_SIZE
* sizeof(utf32
));
1620 memcpy(str
.d_quickbuff
, temp_qbf
, STR_QUICKBUFF_SIZE
* sizeof(utf32
));
1625 //////////////////////////////////////////////////////////////////////////
1626 // Appending Functions
1627 //////////////////////////////////////////////////////////////////////////
1630 Appends the String \a str
1633 String object that is to be appended
1636 This String after the append operation
1638 \exception std::length_error Thrown if resulting String would be too large.
1640 String
& operator+=(const String
& str
)
1647 Appends a sub-string of the String \a str
1650 String object containing data to be appended
1653 Index of the first code point to be appended
1656 Maximum number of code points to be appended
1659 This String after the append operation
1661 \exception std::out_of_range Thrown if \a str_idx is invalid for \a str.
1662 \exception std::length_error Thrown if resulting String would be too large.
1664 String
& append(const String
& str
, size_type str_idx
= 0, size_type str_num
= npos
)
1666 if (str
.d_cplength
< str_idx
)
1667 throw std::out_of_range("Index is out of range for CEGUI::String");
1669 if (str_num
== npos
)
1670 str_num
= str
.d_cplength
- str_idx
;
1672 grow(d_cplength
+ str_num
);
1673 memcpy(&ptr()[d_cplength
], &str
.ptr()[str_idx
], str_num
* sizeof(utf32
));
1674 setlen(d_cplength
+ str_num
);
1681 Appends the std::string \a std_str
1684 std::string object that is to be appended
1687 The characters of \a std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF. No translation of
1688 the provided data will occur.
1691 This String after the append operation
1693 \exception std::length_error Thrown if resulting String would be too large.
1695 String
& operator+=(const std::string
& std_str
)
1697 return append(std_str
);
1702 Appends a sub-string of the std::string \a std_str
1705 std::string object containing data to be appended
1708 The characters of \a std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF. No translation of
1709 the provided data will occur.
1712 Index of the first character to be appended
1715 Maximum number of characters to be appended
1718 This String after the append operation
1720 \exception std::out_of_range Thrown if \a str_idx is invalid for \a std_str.
1721 \exception std::length_error Thrown if resulting String would be too large.
1723 String
& append(const std::string
& std_str
, size_type str_idx
= 0, size_type str_num
= npos
)
1725 if (std_str
.size() < str_idx
)
1726 throw std::out_of_range("Index is out of range for std::string");
1728 if (str_num
== npos
)
1729 str_num
= (size_type
)std_str
.size() - str_idx
;
1731 size_type newsze
= d_cplength
+ str_num
;
1734 utf32
* pt
= &ptr()[newsze
-1];
1737 *pt
-- = static_cast<utf32
>(static_cast<unsigned char>(std_str
[str_num
]));
1746 Appends to the String the null-terminated utf8 encoded data in the buffer utf8_str.
1749 buffer holding the null-terminated utf8 encoded data that is to be appended
1752 A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
1753 comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f)
1754 would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
1758 This String after the append operation
1760 \exception std::length_error Thrown if resulting String would be too large.
1762 String
& operator+=(const utf8
* utf8_str
)
1764 return append(utf8_str
, utf_length(utf8_str
));
1769 Appends to the String the null-terminated utf8 encoded data in the buffer utf8_str.
1772 Buffer holding the null-terminated utf8 encoded data that is to be appended
1775 A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
1776 comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f)
1777 would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
1781 This String after the append operation
1783 \exception std::length_error Thrown if resulting String would be too large.
1785 String
& append(const utf8
* utf8_str
)
1787 return append(utf8_str
, utf_length(utf8_str
));
1793 Appends to the String the utf8 encoded data in the buffer utf8_str.
1796 Buffer holding the utf8 encoded data that is to be appended
1799 A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
1800 comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f)
1801 would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
1805 Number of code units (not code points) in the buffer to be appended
1808 This String after the append operation
1810 \exception std::length_error Thrown if resulting String would be too large, or if \a len was 'npos'
1812 String
& append(const utf8
* utf8_str
, size_type len
)
1815 throw std::length_error("Length for utf8 encoded string can not be 'npos'");
1817 size_type encsz
= encoded_size(utf8_str
, len
);
1818 size_type newsz
= d_cplength
+ encsz
;
1821 encode(utf8_str
, &ptr()[d_cplength
], encsz
, len
);
1830 Appends a single code point to the string
1833 utf32 Unicode code point that is to be appended
1836 This String after the append operation
1838 \exception std::length_error Thrown if resulting String would be too long.
1840 String
& operator+=(utf32 code_point
)
1842 return append(1, code_point
);
1847 Appends a single code point multiple times to the string
1850 Number of copies of the code point to be appended
1853 utf32 Unicode code point that is to be appended
1856 This String after the append operation
1858 \exception std::length_error Thrown if resulting String would be too long, or if \a num was 'npos'.
1860 String
& append(size_type num
, utf32 code_point
)
1863 throw std::length_error("Code point count can not be 'npos'");
1865 size_type newsz
= d_cplength
+ num
;
1868 utf32
* p
= &ptr()[d_cplength
];
1880 Appends a single code point to the string
1883 utf32 Unicode code point that is to be appended
1888 \exception std::length_error Thrown if resulting String would be too long.
1890 void push_back(utf32 code_point
)
1892 append(1, code_point
);
1897 Appends the code points in the reange [beg, end)
1900 Iterator describing the start of the range to be appended
1903 Iterator describing the (exclusive) end of the range to be appended.
1906 This String after the append operation
1908 \exception std::length_error Thrown if the resulting string would be too large.
1910 String
& append(const_iterator iter_beg
, const_iterator iter_end
)
1912 return replace(end(), end(), iter_beg
, iter_end
);
1918 Appends to the String the given c-string.
1921 c-string that is to be appended.
1924 This String after the append operation
1926 \exception std::length_error Thrown if resulting String would be too large.
1928 String
& operator+=(const char* cstr
)
1930 return append(cstr
, strlen(cstr
));
1936 Appends to the String the given c-string.
1939 c-string that is to be appended.
1942 This String after the append operation
1944 \exception std::length_error Thrown if resulting String would be too large.
1946 String
& append(const char* cstr
)
1948 return append(cstr
, strlen(cstr
));
1954 Appends to the String chars from the given char array.
1957 char array holding the chars that are to be appended
1960 Number of chars to be appended
1963 This String after the append operation
1965 \exception std::length_error Thrown if resulting String would be too large, or if \a chars_len was 'npos'
1967 String
& append(const char* chars
, size_type chars_len
)
1969 if (chars_len
== npos
)
1970 throw std::length_error("Length for char array can not be 'npos'");
1972 size_type newsz
= d_cplength
+ chars_len
;
1976 utf32
* pt
= &ptr()[newsz
-1];
1979 *pt
-- = static_cast<utf32
>(static_cast<unsigned char>(chars
[chars_len
]));
1987 //////////////////////////////////////////////////////////////////////////
1988 // Insertion Functions
1989 //////////////////////////////////////////////////////////////////////////
1992 Inserts the given String object at the specified position.
1995 Index where the string is to be inserted.
1998 String object that is to be inserted.
2001 This String after the insert.
2003 \exception std::out_of_range Thrown if \a idx is invalid for this String.
2004 \exception std::length_error Thrown if resulting String would be too large.
2006 String
& insert(size_type idx
, const String
& str
)
2008 return insert(idx
, str
, 0, npos
);
2013 Inserts a sub-string of the given String object at the specified position.
2016 Index where the string is to be inserted.
2019 String object containing data to be inserted.
2022 Index of the first code point from \a str to be inserted.
2025 Maximum number of code points from \a str to be inserted.
2028 This String after the insert.
2030 \exception std::out_of_range Thrown if \a idx or \a str_idx are out of range.
2031 \exception std::length_error Thrown if resulting String would be too large.
2033 String
& insert(size_type idx
, const String
& str
, size_type str_idx
, size_type str_num
)
2035 if ((d_cplength
< idx
) || (str
.d_cplength
< str_idx
))
2036 throw std::out_of_range("Index is out of range for CEGUI::String");
2038 if (str_num
== npos
)
2039 str_num
= str
.d_cplength
- str_idx
;
2041 size_type newsz
= d_cplength
+ str_num
;
2043 memmove(&ptr()[idx
+ str_num
], &ptr()[idx
], (d_cplength
- idx
) * sizeof(utf32
));
2044 memcpy(&ptr()[idx
], &str
.ptr()[str_idx
], str_num
* sizeof(utf32
));
2052 Inserts the given std::string object at the specified position.
2055 Index where the std::string is to be inserted.
2058 std::string object that is to be inserted.
2061 The characters of \a std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF. No translation of
2062 the provided data will occur.
2065 This String after the insert.
2067 \exception std::out_of_range Thrown if \a idx is invalid for this String.
2068 \exception std::length_error Thrown if resulting String would be too large.
2070 String
& insert(size_type idx
, const std::string
& std_str
)
2072 return insert(idx
, std_str
, 0, npos
);
2077 Inserts a sub-string of the given std::string object at the specified position.
2080 Index where the string is to be inserted.
2083 std::string object containing data to be inserted.
2086 The characters of \a std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF. No translation of
2087 the provided data will occur.
2090 Index of the first character from \a std_str to be inserted.
2093 Maximum number of characters from \a str to be inserted.
2096 This String after the insert.
2098 \exception std::out_of_range Thrown if \a idx or \a str_idx are out of range.
2099 \exception std::length_error Thrown if resulting String would be too large.
2101 String
& insert(size_type idx
, const std::string
& std_str
, size_type str_idx
, size_type str_num
)
2103 if (d_cplength
< idx
)
2104 throw std::out_of_range("Index is out of range for CEGUI::String");
2106 if (std_str
.size() < str_idx
)
2107 throw std::out_of_range("Index is out of range for std::string");
2109 if (str_num
== npos
)
2110 str_num
= (size_type
)std_str
.size() - str_idx
;
2112 size_type newsz
= d_cplength
+ str_num
;
2115 memmove(&ptr()[idx
+ str_num
], &ptr()[idx
], (d_cplength
- idx
) * sizeof(utf32
));
2117 utf32
* pt
= &ptr()[idx
+ str_num
- 1];
2120 *pt
-- = static_cast<utf32
>(static_cast<unsigned char>(std_str
[str_idx
+ str_num
]));
2129 Inserts the given null-terminated utf8 encoded data at the specified position.
2132 Index where the data is to be inserted.
2135 Buffer containing the null-terminated utf8 encoded data that is to be inserted.
2138 A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
2139 comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f)
2140 would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
2144 This String after the insert.
2146 \exception std::out_of_range Thrown if \a idx is invalid for this String.
2147 \exception std::length_error Thrown if resulting String would be too large.
2149 String
& insert(size_type idx
, const utf8
* utf8_str
)
2151 return insert(idx
, utf8_str
, utf_length(utf8_str
));
2156 Inserts the given utf8 encoded data at the specified position.
2159 Index where the data is to be inserted.
2162 Buffer containing the utf8 encoded data that is to be inserted.
2165 A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
2166 comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f)
2167 would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
2171 Length of the data to be inserted in uf8 code units (not code points)
2174 This String after the insert.
2176 \exception std::out_of_range Thrown if \a idx is invalid for this String.
2177 \exception std::length_error Thrown if resulting String would be too large, or if \a len is 'npos'
2179 String
& insert(size_type idx
, const utf8
* utf8_str
, size_type len
)
2181 if (d_cplength
< idx
)
2182 throw std::out_of_range("Index is out of range for CEGUI::String");
2185 throw std::length_error("Length of utf8 encoded string can not be 'npos'");
2187 size_type encsz
= encoded_size(utf8_str
, len
);
2188 size_type newsz
= d_cplength
+ encsz
;
2191 memmove(&ptr()[idx
+ encsz
], &ptr()[idx
], (d_cplength
- idx
) * sizeof(utf32
));
2192 encode(utf8_str
, &ptr()[idx
], encsz
, len
);
2200 Inserts a code point multiple times into the String
2203 Index where the code point(s) are to be inserted
2206 The number of times to insert the code point
2209 The utf32 code point that is to be inserted
2212 This String after the insertion.
2214 \exception std::out_of_range Thrown if \a idx is invalid for this String.
2215 \exception std::length_error Thrown if resulting String would be too large, or if \a num is 'npos'
2217 String
& insert(size_type idx
, size_type num
, utf32 code_point
)
2219 if (d_cplength
< idx
)
2220 throw std::out_of_range("Index is out of range for CEGUI::String");
2223 throw std::length_error("Code point count can not be 'npos'");
2225 size_type newsz
= d_cplength
+ num
;
2228 memmove(&ptr()[idx
+ num
], &ptr()[idx
], (d_cplength
- idx
) * sizeof(utf32
));
2230 utf32
* pt
= &ptr()[idx
+ num
- 1];
2242 Inserts a code point multiple times into the String
2245 Iterator describing the position where the code point(s) are to be inserted
2248 The number of times to insert the code point
2251 The utf32 code point that is to be inserted
2254 This String after the insertion.
2256 \exception std::length_error Thrown if resulting String would be too large, or if \a num is 'npos'
2258 void insert(iterator pos
, size_type num
, utf32 code_point
)
2260 insert(safe_iter_dif(pos
, begin()), num
, code_point
);
2265 Inserts a single code point into the String
2268 Iterator describing the position where the code point is to be inserted
2271 The utf32 code point that is to be inserted
2274 This String after the insertion.
2276 \exception std::length_error Thrown if resulting String would be too large.
2278 iterator
insert(iterator pos
, utf32 code_point
)
2280 insert(pos
, 1, code_point
);
2286 Inserts code points specified by the range [beg, end).
2289 Iterator describing the position where the data is to be inserted
2292 Iterator describing the begining of the range to be inserted
2295 Iterator describing the (exclusive) end of the range to be inserted.
2300 \exception std::length_error Thrown if resulting String would be too large.
2302 void insert(iterator iter_pos
, const_iterator iter_beg
, const_iterator iter_end
)
2304 replace(iter_pos
, iter_pos
, iter_beg
, iter_end
);
2310 Inserts the given c-string at the specified position.
2313 Index where the c-string is to be inserted.
2316 c-string that is to be inserted.
2319 This String after the insert.
2321 \exception std::out_of_range Thrown if \a idx is invalid for this String.
2322 \exception std::length_error Thrown if resulting String would be too large.
2324 String
& insert(size_type idx
, const char* cstr
)
2326 return insert(idx
, cstr
, strlen(cstr
));
2332 Inserts chars from the given char array at the specified position.
2335 Index where the data is to be inserted.
2338 char array containing the chars that are to be inserted.
2341 Length of the char array to be inserted.
2344 This String after the insert.
2346 \exception std::out_of_range Thrown if \a idx is invalid for this String.
2347 \exception std::length_error Thrown if resulting String would be too large, or if \a chars_len is 'npos'
2349 String
& insert(size_type idx
, const char* chars
, size_type chars_len
)
2351 if (d_cplength
< idx
)
2352 throw std::out_of_range("Index is out of range for CEGUI::String");
2354 if (chars_len
== npos
)
2355 throw std::length_error("Length of char array can not be 'npos'");
2357 size_type newsz
= d_cplength
+ chars_len
;
2360 memmove(&ptr()[idx
+ chars_len
], &ptr()[idx
], (d_cplength
- idx
) * sizeof(utf32
));
2362 utf32
* pt
= &ptr()[idx
+ chars_len
- 1];
2365 *pt
-- = static_cast<utf32
>(static_cast<unsigned char>(chars
[chars_len
]));
2373 //////////////////////////////////////////////////////////////////////////
2374 // Erasing characters
2375 //////////////////////////////////////////////////////////////////////////
2378 Removes all data from the String
2391 Removes all data from the String
2394 The empty String (*this)
2404 Erase a single code point from the string
2407 The index of the code point to be removed.
2410 This String after the erase operation
2412 \exception std::out_of_range Thrown if \a idx is invalid for this String.
2414 String
& erase(size_type idx
)
2416 return erase(idx
, 1);
2421 Erase a range of code points
2424 Index of the first code point to be removed.
2427 Maximum number of code points to be removed.
2430 This String after the erase operation.
2432 \exception std::out_of_range Thrown if \a idx is invalid for this String.
2434 String
& erase(size_type idx
, size_type len
= npos
)
2436 if (d_cplength
< idx
)
2437 throw std::out_of_range("Index is out of range foe CEGUI::String");
2440 len
= d_cplength
- idx
;
2442 size_type newsz
= d_cplength
- len
;
2444 memmove(&ptr()[idx
], &ptr()[idx
+ len
], (d_cplength
- idx
- len
) * sizeof(utf32
));
2451 Erase the code point described by the given iterator
2454 Iterator describing the code point to be erased
2457 This String after the erase operation.
2459 String
& erase(iterator pos
)
2461 return erase(safe_iter_dif(pos
, begin()), 1);
2466 Erase a range of code points described by the iterators [beg, end).
2469 Iterator describing the postion of the beginning of the range to erase
2472 Iterator describing the postion of the (exclusive) end of the range to erase
2475 This String after the erase operation.
2477 String
& erase(iterator iter_beg
, iterator iter_end
)
2479 return erase(safe_iter_dif(iter_beg
, begin()), safe_iter_dif(iter_end
, iter_beg
));
2482 //////////////////////////////////////////////////////////////////////////
2484 //////////////////////////////////////////////////////////////////////////
2487 Resizes the String either by inserting default utf32 code points to make it larger, or by truncating to make it smaller
2490 The length, in code points, that the String is to be made.
2495 \exception std::length_error Thrown if the String would be too large.
2497 void resize(size_type num
)
2499 resize(num
, utf32());
2504 Resizes the String either by inserting the given utf32 code point to make it larger, or by truncating to make it smaller
2507 The length, in code points, that the String is to be made.
2510 The utf32 code point that should be used when majing the String larger
2515 \exception std::length_error Thrown if the String would be too large.
2517 void resize(size_type num
, utf32 code_point
)
2519 if (num
< d_cplength
)
2525 append(num
- d_cplength
, code_point
);
2530 //////////////////////////////////////////////////////////////////////////
2531 // Replacing Characters
2532 //////////////////////////////////////////////////////////////////////////
2535 Replace code points in the String with the specified String object
2538 Index of the first code point to be replaced
2541 Maximum number of code points to be replaced (if this is 0, operation is an insert at position \a idx)
2544 The String object that is to replace the specified code points
2547 This String after the replace operation
2549 \exception std::out_of_range Thrown if \a idx is invalid for this String
2550 \exception std::length_error Thrown if the resulting String would be too large.
2552 String
& replace(size_type idx
, size_type len
, const String
& str
)
2554 return replace(idx
, len
, str
, 0, npos
);
2559 Replace the code points in the range [beg, end) with the specified String object
2562 If \a beg == \a end, the operation is a insert at iterator position \a beg
2565 Iterator describing the start of the range to be replaced
2568 Iterator describing the (exclusive) end of the range to be replaced.
2571 The String object that is to replace the specified range of code points
2574 This String after the replace operation
2576 \exception std::length_error Thrown if the resulting String would be too large.
2578 String
& replace(iterator iter_beg
, iterator iter_end
, const String
& str
)
2580 return replace(safe_iter_dif(iter_beg
, begin()), safe_iter_dif(iter_end
, iter_beg
), str
, 0, npos
);
2585 Replace code points in the String with a specified sub-string of a given String object.
2588 Index of the first code point to be replaced
2591 Maximum number of code points to be replaced. If this is 0, the operation is an insert at position \a idx.
2594 String object containing the data that will replace the specified range of code points
2597 Index of the first code point of \a str that is to replace the specified code point range
2600 Maximum number of code points of \a str that are to replace the specified code point range
2603 This String after the replace operation
2605 \exception std::out_of_range Thrown if either \a idx, or \a str_idx are invalid
2606 \exception std::length_error Thrown if the resulting String would have been too large.
2608 String
& replace(size_type idx
, size_type len
, const String
& str
, size_type str_idx
, size_type str_num
)
2610 if ((d_cplength
< idx
) || (str
.d_cplength
< str_idx
))
2611 throw std::out_of_range("Index is out of range for CEGUI::String");
2613 if (((str_idx
+ str_num
) > str
.d_cplength
) || (str_num
== npos
))
2614 str_num
= str
.d_cplength
- str_idx
;
2616 if (((len
+ idx
) > d_cplength
) || (len
== npos
))
2617 len
= d_cplength
- idx
;
2619 size_type newsz
= d_cplength
+ str_num
- len
;
2623 if ((idx
+ len
) < d_cplength
)
2624 memmove(&ptr()[idx
+ str_num
], &ptr()[len
+ idx
], (d_cplength
- idx
- len
) * sizeof(utf32
));
2626 memcpy(&ptr()[idx
], &str
.ptr()[str_idx
], str_num
* sizeof(utf32
));
2635 Replace code points in the String with the specified std::string object
2638 Index of the first code point to be replaced
2641 Maximum number of code points to be replaced (if this is 0, operation is an insert at position \a idx)
2644 The std::string object that is to replace the specified code points
2647 Characters from \a std_str are considered to represent Unicode code points in the range 0x00..0xFF. No translation of
2648 the encountered data is performed.
2651 This String after the replace operation
2653 \exception std::out_of_range Thrown if \a idx is invalid for this String
2654 \exception std::length_error Thrown if the resulting String would be too large.
2656 String
& replace(size_type idx
, size_type len
, const std::string
& std_str
)
2658 return replace(idx
, len
, std_str
, 0, npos
);
2663 Replace the code points in the range [beg, end) with the specified std::string object
2666 If \a beg == \a end, the operation is a insert at iterator position \a beg
2669 Iterator describing the start of the range to be replaced
2672 Iterator describing the (exclusive) end of the range to be replaced.
2675 The std::string object that is to replace the specified range of code points
2678 Characters from \a std_str are considered to represent Unicode code points in the range 0x00..0xFF. No translation of
2679 the encountered data is performed.
2682 This String after the replace operation
2684 \exception std::length_error Thrown if the resulting String would be too large.
2686 String
& replace(iterator iter_beg
, iterator iter_end
, const std::string
& std_str
)
2688 return replace(safe_iter_dif(iter_beg
, begin()), safe_iter_dif(iter_end
, iter_beg
), std_str
, 0, npos
);
2693 Replace code points in the String with a specified sub-string of a given std::string object.
2696 Index of the first code point to be replaced
2699 Maximum number of code points to be replaced. If this is 0, the operation is an insert at position \a idx.
2702 std::string object containing the data that will replace the specified range of code points
2705 Characters from \a std_str are considered to represent Unicode code points in the range 0x00..0xFF. No translation of
2706 the encountered data is performed.
2709 Index of the first code point of \a std_str that is to replace the specified code point range
2712 Maximum number of code points of \a std_str that are to replace the specified code point range
2715 This String after the replace operation
2717 \exception std::out_of_range Thrown if either \a idx, or \a str_idx are invalid
2718 \exception std::length_error Thrown if the resulting String would have been too large.
2720 String
& replace(size_type idx
, size_type len
, const std::string
& std_str
, size_type str_idx
, size_type str_num
)
2722 if (d_cplength
< idx
)
2723 throw std::out_of_range("Index is out of range for CEGUI::String");
2725 if (std_str
.size() < str_idx
)
2726 throw std::out_of_range("Index is out of range for std::string");
2728 if (((str_idx
+ str_num
) > std_str
.size()) || (str_num
== npos
))
2729 str_num
= (size_type
)std_str
.size() - str_idx
;
2731 if (((len
+ idx
) > d_cplength
) || (len
== npos
))
2732 len
= d_cplength
- idx
;
2734 size_type newsz
= d_cplength
+ str_num
- len
;
2738 if ((idx
+ len
) < d_cplength
)
2739 memmove(&ptr()[idx
+ str_num
], &ptr()[len
+ idx
], (d_cplength
- idx
- len
) * sizeof(utf32
));
2741 utf32
* pt
= &ptr()[idx
+ str_num
- 1];
2744 *pt
-- = static_cast<utf32
>(static_cast<unsigned char>(std_str
[str_idx
+ str_num
]));
2754 Replace code points in the String with the specified null-terminated utf8 encoded data.
2757 Index of the first code point to be replaced
2760 Maximum number of code points to be replaced (if this is 0, operation is an insert at position \a idx)
2763 Buffer containing the null-terminated utf8 encoded data that is to replace the specified code points
2766 A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
2767 comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f)
2768 would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
2772 This String after the replace operation
2774 \exception std::out_of_range Thrown if \a idx is invalid for this String
2775 \exception std::length_error Thrown if the resulting String would be too large.
2777 String
& replace(size_type idx
, size_type len
, const utf8
* utf8_str
)
2779 return replace(idx
, len
, utf8_str
, utf_length(utf8_str
));
2784 Replace the code points in the range [beg, end) with the specified null-terminated utf8 encoded data.
2787 If \a beg == \a end, the operation is a insert at iterator position \a beg
2790 Iterator describing the start of the range to be replaced
2793 Iterator describing the (exclusive) end of the range to be replaced.
2796 Buffer containing the null-terminated utf8 encoded data that is to replace the specified range of code points
2799 A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
2800 comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f)
2801 would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
2805 This String after the replace operation
2807 \exception std::length_error Thrown if the resulting String would be too large.
2809 String
& replace(iterator iter_beg
, iterator iter_end
, const utf8
* utf8_str
)
2811 return replace(iter_beg
, iter_end
, utf8_str
, utf_length(utf8_str
));
2816 Replace code points in the String with the specified utf8 encoded data.
2819 Index of the first code point to be replaced
2822 Maximum number of code points to be replaced (if this is 0, operation is an insert at position \a idx)
2825 Buffer containing the null-terminated utf8 encoded data that is to replace the specified code points
2828 A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
2829 comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f)
2830 would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
2834 Length of the utf8 encoded data in utf8 code units (not code points).
2837 This String after the replace operation
2839 \exception std::out_of_range Thrown if \a idx is invalid for this String
2840 \exception std::length_error Thrown if the resulting String would be too large, or if \a str_len was 'npos'.
2842 String
& replace(size_type idx
, size_type len
, const utf8
* utf8_str
, size_type str_len
)
2844 if (d_cplength
< idx
)
2845 throw std::out_of_range("Index is out of range for CEGUI::String");
2847 if (str_len
== npos
)
2848 throw std::length_error("Length for utf8 encoded string can not be 'npos'");
2850 if (((len
+ idx
) > d_cplength
) || (len
== npos
))
2851 len
= d_cplength
- idx
;
2853 size_type encsz
= encoded_size(utf8_str
, str_len
);
2854 size_type newsz
= d_cplength
+ encsz
- len
;
2858 if ((idx
+ len
) < d_cplength
)
2859 memmove(&ptr()[idx
+ encsz
], &ptr()[len
+ idx
], (d_cplength
- idx
- len
) * sizeof(utf32
));
2861 encode(utf8_str
, &ptr()[idx
], encsz
, str_len
);
2869 Replace the code points in the range [beg, end) with the specified null-terminated utf8 encoded data.
2872 If \a beg == \a end, the operation is a insert at iterator position \a beg
2875 Iterator describing the start of the range to be replaced
2878 Iterator describing the (exclusive) end of the range to be replaced.
2881 Buffer containing the null-terminated utf8 encoded data that is to replace the specified range of code points
2884 A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
2885 comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f)
2886 would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
2890 Length of the utf8 encoded data in utf8 code units (not code points).
2893 This String after the replace operation
2895 \exception std::length_error Thrown if the resulting String would be too large, or if \a str_len was 'npos'.
2897 String
& replace(iterator iter_beg
, iterator iter_end
, const utf8
* utf8_str
, size_type str_len
)
2899 return replace(safe_iter_dif(iter_beg
, begin()), safe_iter_dif(iter_end
, iter_beg
), utf8_str
, str_len
);
2904 Replaces a specified range of code points with occurrences of a given code point
2907 Index of the first code point to be replaced
2910 Maximum number of code points to replace. If this is 0 the operation is an insert
2913 Number of occurrences of \a code_point that are to replace the specified range of code points
2916 Code point that is to be used when replacing the specified range of code points
2919 This String after the replace operation.
2921 \exception std::out_of_range Thrown if \a idx is invalid for this String
2922 \exception std::length_error Thrown if resulting String would have been too long, or if \a num was 'npos'.
2924 String
& replace(size_type idx
, size_type len
, size_type num
, utf32 code_point
)
2926 if (d_cplength
< idx
)
2927 throw std::out_of_range("Index is out of range for CEGUI::String");
2930 throw std::length_error("Code point count can not be 'npos'");
2932 if (((len
+ idx
) > d_cplength
) || (len
== npos
))
2933 len
= d_cplength
- idx
;
2935 size_type newsz
= d_cplength
+ num
- len
;
2939 if ((idx
+ len
) < d_cplength
)
2940 memmove(&ptr()[idx
+ num
], &ptr()[len
+ idx
], (d_cplength
- idx
- len
) * sizeof(utf32
));
2942 utf32
* pt
= &ptr()[idx
+ num
- 1];
2954 Replace the code points in the range [beg, end) with occurrences of a given code point
2957 If \a beg == \a end, the operation is an insert at iterator position \a beg
2960 Iterator describing the start of the range to be replaced
2963 Iterator describing the (exclusive) end of the range to be replaced.
2966 Number of occurrences of \a code_point that are to replace the specified range of code points
2969 Code point that is to be used when replacing the specified range of code points
2972 This String after the replace operation
2974 \exception std::length_error Thrown if resulting String would have been too long, or if \a num was 'npos'.
2976 String
& replace(iterator iter_beg
, iterator iter_end
, size_type num
, utf32 code_point
)
2978 return replace(safe_iter_dif(iter_beg
, begin()), safe_iter_dif(iter_end
, iter_beg
), num
, code_point
);
2984 Replace the code points in the range [beg, end) with code points from the range [newBeg, newEnd).
2987 If \a beg == \a end, the operation is an insert at iterator position \a beg
2990 Iterator describing the start of the range to be replaced
2993 Iterator describing the (exclusive) end of the range to be replaced.
2996 Iterator describing the beginning of the range to insert.
2999 Iterator describing the (exclusive) end of the range to insert.
3002 This String after the insert operation.
3004 \exception std::length_error Thrown if the resulting string would be too long.
3006 String
& replace(iterator iter_beg
, iterator iter_end
, const_iterator iter_newBeg
, const_iterator iter_newEnd
)
3008 if (iter_beg
== iter_end
)
3010 erase(safe_iter_dif(iter_beg
, begin()), safe_iter_dif(iter_end
, iter_beg
));
3014 size_type str_len
= safe_iter_dif(iter_newEnd
, iter_newBeg
);
3015 size_type idx
= safe_iter_dif(iter_beg
, begin());
3016 size_type len
= safe_iter_dif(iter_end
, iter_beg
);
3018 if ((len
+ idx
) > d_cplength
)
3019 len
= d_cplength
- idx
;
3021 size_type newsz
= d_cplength
+ str_len
- len
;
3025 if ((idx
+ len
) < d_cplength
)
3026 memmove(&ptr()[idx
+ str_len
], &ptr()[len
+ idx
], (d_cplength
- idx
- len
) * sizeof(utf32
));
3028 memcpy(&ptr()[idx
], iter_newBeg
.d_ptr
, str_len
* sizeof(utf32
));
3038 Replace code points in the String with the specified c-string.
3041 Index of the first code point to be replaced
3044 Maximum number of code points to be replaced (if this is 0, operation is an insert at position \a idx)
3047 c-string that is to replace the specified code points
3050 This String after the replace operation
3052 \exception std::out_of_range Thrown if \a idx is invalid for this String
3053 \exception std::length_error Thrown if the resulting String would be too large.
3055 String
& replace(size_type idx
, size_type len
, const char* cstr
)
3057 return replace(idx
, len
, cstr
, strlen(cstr
));
3063 Replace the code points in the range [beg, end) with the specified c-string.
3066 If \a beg == \a end, the operation is a insert at iterator position \a beg
3069 Iterator describing the start of the range to be replaced
3072 Iterator describing the (exclusive) end of the range to be replaced.
3075 c-string that is to replace the specified range of code points
3078 This String after the replace operation
3080 \exception std::length_error Thrown if the resulting String would be too large.
3082 String
& replace(iterator iter_beg
, iterator iter_end
, const char* cstr
)
3084 return replace(iter_beg
, iter_end
, cstr
, strlen(cstr
));
3090 Replace code points in the String with chars from the given char array.
3093 Index of the first code point to be replaced
3096 Maximum number of code points to be replaced (if this is 0, operation is an insert at position \a idx)
3099 char array containing the cars that are to replace the specified code points
3102 Number of chars in the char array.
3105 This String after the replace operation
3107 \exception std::out_of_range Thrown if \a idx is invalid for this String
3108 \exception std::length_error Thrown if the resulting String would be too large, or if \a chars_len was 'npos'.
3110 String
& replace(size_type idx
, size_type len
, const char* chars
, size_type chars_len
)
3112 if (d_cplength
< idx
)
3113 throw std::out_of_range("Index is out of range for CEGUI::String");
3115 if (chars_len
== npos
)
3116 throw std::length_error("Length for the char array can not be 'npos'");
3118 if (((len
+ idx
) > d_cplength
) || (len
== npos
))
3119 len
= d_cplength
- idx
;
3121 size_type newsz
= d_cplength
+ chars_len
- len
;
3125 if ((idx
+ len
) < d_cplength
)
3126 memmove(&ptr()[idx
+ chars_len
], &ptr()[len
+ idx
], (d_cplength
- idx
- len
) * sizeof(utf32
));
3128 utf32
* pt
= &ptr()[idx
+ chars_len
- 1];
3131 *pt
-- = static_cast<utf32
>(static_cast<unsigned char>(chars
[chars_len
]));
3140 Replace the code points in the range [beg, end) with chars from the given char array.
3143 If \a beg == \a end, the operation is a insert at iterator position \a beg
3146 Iterator describing the start of the range to be replaced
3149 Iterator describing the (exclusive) end of the range to be replaced.
3152 char array containing the chars that are to replace the specified range of code points
3155 Number of chars in the char array.
3158 This String after the replace operation
3160 \exception std::length_error Thrown if the resulting String would be too large, or if \a chars_len was 'npos'.
3162 String
& replace(iterator iter_beg
, iterator iter_end
, const char* chars
, size_type chars_len
)
3164 return replace(safe_iter_dif(iter_beg
, begin()), safe_iter_dif(iter_end
, iter_beg
), chars
, chars_len
);
3168 //////////////////////////////////////////////////////////////////////////
3169 // Find a code point
3170 //////////////////////////////////////////////////////////////////////////
3173 Search forwards for a given code point
3176 The utf32 code point to search for
3179 Index of the code point where the search is to start.
3182 - Index of the first occurrence of \a code_point travelling forwards from \a idx.
3183 - npos if the code point could not be found
3185 size_type
find(utf32 code_point
, size_type idx
= 0) const
3187 if (idx
< d_cplength
)
3189 const utf32
* pt
= &ptr()[idx
];
3191 while (idx
< d_cplength
)
3193 if (*pt
++ == code_point
)
3206 Search backwards for a given code point
3209 The utf32 code point to search for
3212 Index of the code point where the search is to start.
3215 - Index of the first occurrence of \a code_point travelling backwards from \a idx.
3216 - npos if the code point could not be found
3218 size_type
rfind(utf32 code_point
, size_type idx
= npos
) const
3220 if (idx
>= d_cplength
)
3221 idx
= d_cplength
- 1;
3225 const utf32
* pt
= &ptr()[idx
];
3229 if (*pt
-- == code_point
)
3232 } while (idx
-- != 0);
3239 //////////////////////////////////////////////////////////////////////////
3241 //////////////////////////////////////////////////////////////////////////
3244 Search forwards for a sub-string
3247 String object describing the sub-string to search for
3250 Index of the code point where the search is to start
3253 - Index of the first occurrence of sub-string \a str travelling forwards from \a idx.
3254 - npos if the sub-string could not be found
3256 size_type
find(const String
& str
, size_type idx
= 0) const
3258 if ((str
.d_cplength
== 0) && (idx
< d_cplength
))
3261 if (idx
< d_cplength
)
3263 // loop while search string could fit in to search area
3264 while (d_cplength
- idx
>= str
.d_cplength
)
3266 if (0 == compare(idx
, str
.d_cplength
, str
))
3279 Search backwards for a sub-string
3282 String object describing the sub-string to search for
3285 Index of the code point where the search is to start
3288 - Index of the first occurrence of sub-string \a str travelling backwards from \a idx.
3289 - npos if the sub-string could not be found
3291 size_type
rfind(const String
& str
, size_type idx
= npos
) const
3293 if (str
.d_cplength
== 0)
3294 return (idx
< d_cplength
) ? idx
: d_cplength
;
3296 if (str
.d_cplength
<= d_cplength
)
3298 if (idx
> (d_cplength
- str
.d_cplength
))
3299 idx
= d_cplength
- str
.d_cplength
;
3303 if (0 == compare(idx
, str
.d_cplength
, str
))
3306 } while (idx
-- != 0);
3315 Search forwards for a sub-string
3318 std::string object describing the sub-string to search for
3321 Characters from \a std_str are considered to represent Unicode code points in the range 0x00..0xFF. No translation of
3322 the encountered data is performed.
3325 Index of the code point where the search is to start
3328 - Index of the first occurrence of sub-string \a std_str travelling forwards from \a idx.
3329 - npos if the sub-string could not be found
3331 size_type
find(const std::string
& std_str
, size_type idx
= 0) const
3333 std::string::size_type sze
= std_str
.size();
3335 if ((sze
== 0) && (idx
< d_cplength
))
3338 if (idx
< d_cplength
)
3340 // loop while search string could fit in to search area
3341 while (d_cplength
- idx
>= sze
)
3343 if (0 == compare(idx
, (size_type
)sze
, std_str
))
3356 Search backwards for a sub-string
3359 std::string object describing the sub-string to search for
3362 Characters from \a std_str are considered to represent Unicode code points in the range 0x00..0xFF. No translation of
3363 the encountered data is performed.
3366 Index of the code point where the search is to start
3369 - Index of the first occurrence of sub-string \a std_str travelling backwards from \a idx.
3370 - npos if the sub-string could not be found
3372 size_type
rfind(const std::string
& std_str
, size_type idx
= npos
) const
3374 std::string::size_type sze
= std_str
.size();
3377 return (idx
< d_cplength
) ? idx
: d_cplength
;
3379 if (sze
<= d_cplength
)
3381 if (idx
> (d_cplength
- sze
))
3382 idx
= d_cplength
- sze
;
3386 if (0 == compare(idx
, (size_type
)sze
, std_str
))
3389 } while (idx
-- != 0);
3398 Search forwards for a sub-string
3401 Buffer containing null-terminated utf8 encoded data describing the sub-string to search for
3404 A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
3405 comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f)
3406 would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
3410 Index of the code point where the search is to start
3413 - Index of the first occurrence of sub-string \a utf8_str travelling forwards from \a idx.
3414 - npos if the sub-string could not be found
3416 \exception std::out_of_range Thrown if \a idx is invalid for this String.
3418 size_type
find(const utf8
* utf8_str
, size_type idx
= 0) const
3420 return find(utf8_str
, idx
, utf_length(utf8_str
));
3425 Search backwards for a sub-string
3428 Buffer containing null-terminated utf8 encoded data describing the sub-string to search for
3431 A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
3432 comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f)
3433 would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
3437 Index of the code point where the search is to start
3440 - Index of the first occurrence of sub-string \a utf8_str travelling backwards from \a idx.
3441 - npos if the sub-string could not be found
3443 \exception std::out_of_range Thrown if \a idx is invalid for this String.
3445 size_type
rfind(const utf8
* utf8_str
, size_type idx
= npos
) const
3447 return rfind(utf8_str
, idx
, utf_length(utf8_str
));
3452 Search forwards for a sub-string
3455 Buffer containing utf8 encoded data describing the sub-string to search for
3458 A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
3459 comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f)
3460 would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
3464 Index of the code point where the search is to start
3467 Length of the utf8 encoded sub-string in utf8 code units (not code points)
3470 - Index of the first occurrence of sub-string \a utf8_str travelling forwards from \a idx.
3471 - npos if the sub-string could not be found
3473 \exception std::length_error Thrown if \a str_len is 'npos'
3475 size_type
find(const utf8
* utf8_str
, size_type idx
, size_type str_len
) const
3477 if (str_len
== npos
)
3478 throw std::length_error("Length for utf8 encoded string can not be 'npos'");
3480 size_type sze
= encoded_size(utf8_str
, str_len
);
3482 if ((sze
== 0) && (idx
< d_cplength
))
3485 if (idx
< d_cplength
)
3487 // loop while search string could fit in to search area
3488 while (d_cplength
- idx
>= sze
)
3490 if (0 == compare(idx
, sze
, utf8_str
, sze
))
3503 Search backwards for a sub-string
3506 Buffer containing utf8 encoded data describing the sub-string to search for
3509 A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
3510 comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f)
3511 would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
3515 Index of the code point where the search is to start
3518 Length of the utf8 encoded sub-string in utf8 code units (not code points)
3521 - Index of the first occurrence of sub-string \a utf8_str travelling backwards from \a idx.
3522 - npos if the sub-string could not be found
3524 \exception std::length_error Thrown if \a str_len is 'npos'
3526 size_type
rfind(const utf8
* utf8_str
, size_type idx
, size_type str_len
) const
3528 if (str_len
== npos
)
3529 throw std::length_error("Length for utf8 encoded string can not be 'npos'");
3531 size_type sze
= encoded_size(utf8_str
, str_len
);
3534 return (idx
< d_cplength
) ? idx
: d_cplength
;
3536 if (sze
<= d_cplength
)
3538 if (idx
> (d_cplength
- sze
))
3539 idx
= d_cplength
- sze
;
3543 if (0 == compare(idx
, sze
, utf8_str
, sze
))
3546 } while (idx
-- != 0);
3556 Search forwards for a sub-string
3559 c-string describing the sub-string to search for
3562 Index of the code point where the search is to start
3565 - Index of the first occurrence of sub-string \a c_str travelling forwards from \a idx.
3566 - npos if the sub-string could not be found
3568 \exception std::out_of_range Thrown if \a idx is invalid for this String.
3570 size_type
find(const char* cstr
, size_type idx
= 0) const
3572 return find(cstr
, idx
, strlen(cstr
));
3578 Search backwards for a sub-string
3581 c-string describing the sub-string to search for
3584 Index of the code point where the search is to start
3587 - Index of the first occurrence of sub-string \a c_str travelling backwards from \a idx.
3588 - npos if the sub-string could not be found
3590 \exception std::out_of_range Thrown if \a idx is invalid for this String.
3592 size_type
rfind(const char* cstr
, size_type idx
= npos
) const
3594 return rfind(cstr
, idx
, strlen(cstr
));
3600 Search forwards for a sub-string
3603 char array describing the sub-string to search for
3606 Index of the code point where the search is to start
3609 Number of chars in the char array.
3612 - Index of the first occurrence of sub-string \a chars travelling forwards from \a idx.
3613 - npos if the sub-string could not be found
3615 \exception std::length_error Thrown if \a chars_len is 'npos'
3617 size_type
find(const char* chars
, size_type idx
, size_type chars_len
) const
3619 if (chars_len
== npos
)
3620 throw std::length_error("Length for char array can not be 'npos'");
3622 if ((chars_len
== 0) && (idx
< d_cplength
))
3625 if (idx
< d_cplength
)
3627 // loop while search string could fit in to search area
3628 while (d_cplength
- idx
>= chars_len
)
3630 if (0 == compare(idx
, chars_len
, chars
, chars_len
))
3644 Search backwards for a sub-string
3647 char array describing the sub-string to search for
3650 Index of the code point where the search is to start
3653 Number of chars in the char array.
3656 - Index of the first occurrence of sub-string \a chars travelling backwards from \a idx.
3657 - npos if the sub-string could not be found
3659 \exception std::length_error Thrown if \a chars_len is 'npos'
3661 size_type
rfind(const char* chars
, size_type idx
, size_type chars_len
) const
3663 if (chars_len
== npos
)
3664 throw std::length_error("Length for char array can not be 'npos'");
3667 return (idx
< d_cplength
) ? idx
: d_cplength
;
3669 if (chars_len
<= d_cplength
)
3671 if (idx
> (d_cplength
- chars_len
))
3672 idx
= d_cplength
- chars_len
;
3676 if (0 == compare(idx
, chars_len
, chars
, chars_len
))
3679 } while (idx
-- != 0);
3687 //////////////////////////////////////////////////////////////////////////
3688 // Find first of different code-points
3689 //////////////////////////////////////////////////////////////////////////
3692 Find the first occurrence of one of a set of code points.
3695 String object describing the set of code points.
3698 Index of the start point for the search
3701 - Index of the first occurrence of any one of the code points in \a str starting from from \a idx.
3702 - npos if none of the code points in \a str were found.
3704 size_type
find_first_of(const String
& str
, size_type idx
= 0) const
3706 if (idx
< d_cplength
)
3708 const utf32
* pt
= &ptr()[idx
];
3712 if (npos
!= str
.find(*pt
++))
3715 } while (++idx
!= d_cplength
);
3724 Find the first code point that is not one of a set of code points.
3727 String object describing the set of code points.
3730 Index of the start point for the search
3733 - Index of the first code point that does not match any one of the code points in \a str starting from from \a idx.
3734 - npos if all code points matched one of the code points in \a str.
3736 size_type
find_first_not_of(const String
& str
, size_type idx
= 0) const
3738 if (idx
< d_cplength
)
3740 const utf32
* pt
= &ptr()[idx
];
3744 if (npos
== str
.find(*pt
++))
3747 } while (++idx
!= d_cplength
);
3757 Find the first occurrence of one of a set of code points.
3760 std::string object describing the set of code points.
3763 The characters of \a std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF. No translation of
3764 the provided data will occur.
3767 Index of the start point for the search
3770 - Index of the first occurrence of any one of the code points in \a std_str starting from from \a idx.
3771 - npos if none of the code points in \a std_str were found.
3773 size_type
find_first_of(const std::string
& std_str
, size_type idx
= 0) const
3775 if (idx
< d_cplength
)
3777 const utf32
* pt
= &ptr()[idx
];
3781 if (npos
!= find_codepoint(std_str
, *pt
++))
3784 } while (++idx
!= d_cplength
);
3793 Find the first code point that is not one of a set of code points.
3796 std::string object describing the set of code points.
3799 The characters of \a std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF. No translation of
3800 the provided data will occur.
3803 Index of the start point for the search
3806 - Index of the first code point that does not match any one of the code points in \a std_str starting from from \a idx.
3807 - npos if all code points matched one of the code points in \a std_str.
3809 size_type
find_first_not_of(const std::string
& std_str
, size_type idx
= 0) const
3811 if (idx
< d_cplength
)
3813 const utf32
* pt
= &ptr()[idx
];
3817 if (npos
== find_codepoint(std_str
, *pt
++))
3820 } while (++idx
!= d_cplength
);
3830 Find the first occurrence of one of a set of code points.
3833 Buffer containing null-terminated utf8 encoded data describing the set of code points.
3836 A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
3837 comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f)
3838 would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
3842 Index of the start point for the search
3845 - Index of the first occurrence of any one of the code points in \a utf8_str starting from from \a idx.
3846 - npos if none of the code points in \a utf8_str were found.
3848 \exception std::out_of_range Thrown if \a idx is invalid for this String.
3850 size_type
find_first_of(const utf8
* utf8_str
, size_type idx
= 0) const
3852 return find_first_of(utf8_str
, idx
, utf_length(utf8_str
));
3857 Find the first code point that is not one of a set of code points.
3860 Buffer containing null-terminated utf8 encoded data describing the set of code points.
3863 A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
3864 comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f)
3865 would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
3869 Index of the start point for the search
3872 - Index of the first code point that does not match any one of the code points in \a utf8_str starting from from \a idx.
3873 - npos if all code points matched one of the code points in \a utf8_str.
3875 \exception std::out_of_range Thrown if \a idx is invalid for this String.
3877 size_type
find_first_not_of(const utf8
* utf8_str
, size_type idx
= 0) const
3879 return find_first_not_of(utf8_str
, idx
, utf_length(utf8_str
));
3884 Find the first occurrence of one of a set of code points.
3887 Buffer containing utf8 encoded data describing the set of code points.
3890 A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
3891 comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f)
3892 would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
3896 Index of the start point for the search
3899 Length of the utf8 encoded data in utf8 code units (not code points).
3902 - Index of the first occurrence of any one of the code points in \a utf8_str starting from from \a idx.
3903 - npos if none of the code points in \a utf8_str were found.
3905 \exception std::length_error Thrown if \a str_len was 'npos'.
3907 size_type
find_first_of(const utf8
* utf8_str
, size_type idx
, size_type str_len
) const
3909 if (str_len
== npos
)
3910 throw std::length_error("Length for utf8 encoded string can not be 'npos'");
3912 if (idx
< d_cplength
)
3914 size_type encsze
= encoded_size(utf8_str
, str_len
);
3916 const utf32
* pt
= &ptr()[idx
];
3920 if (npos
!= find_codepoint(utf8_str
, encsze
, *pt
++))
3923 } while (++idx
!= d_cplength
);
3932 Find the first code point that is not one of a set of code points.
3935 Buffer containing utf8 encoded data describing the set of code points.
3938 A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
3939 comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f)
3940 would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
3944 Index of the start point for the search
3947 Length of the utf8 encoded data in utf8 code units (not code points).
3950 - Index of the first code point that does not match any one of the code points in \a utf8_str starting from from \a idx.
3951 - npos if all code points matched one of the code points in \a utf8_str.
3953 \exception std::length_error Thrown if \a str_len was 'npos'.
3955 size_type
find_first_not_of(const utf8
* utf8_str
, size_type idx
, size_type str_len
) const
3957 if (str_len
== npos
)
3958 throw std::length_error("Length for utf8 encoded string can not be 'npos'");
3960 if (idx
< d_cplength
)
3962 size_type encsze
= encoded_size(utf8_str
, str_len
);
3964 const utf32
* pt
= &ptr()[idx
];
3968 if (npos
== find_codepoint(utf8_str
, encsze
, *pt
++))
3971 } while (++idx
!= d_cplength
);
3981 Search forwards for a given code point
3984 The utf32 code point to search for
3987 Index of the code point where the search is to start.
3990 - Index of the first occurrence of \a code_point starting from from \a idx.
3991 - npos if the code point could not be found
3993 size_type
find_first_of(utf32 code_point
, size_type idx
= 0) const
3995 return find(code_point
, idx
);
4000 Search forwards for the first code point that does not match a given code point
4003 The utf32 code point to search for
4006 Index of the code point where the search is to start.
4009 - Index of the first code point that does not match \a code_point starting from from \a idx.
4010 - npos if all code points matched \a code_point
4012 \exception std::out_of_range Thrown if \a idx is invalid for this String.
4014 size_type
find_first_not_of(utf32 code_point
, size_type idx
= 0) const
4016 if (idx
< d_cplength
)
4020 if ((*this)[idx
] != code_point
)
4023 } while(idx
++ < d_cplength
);
4033 Find the first occurrence of one of a set of chars.
4036 c-string describing the set of chars.
4039 Index of the start point for the search
4042 - Index of the first occurrence of any one of the chars in \a c_str starting from from \a idx.
4043 - npos if none of the chars in \a c_str were found.
4045 \exception std::out_of_range Thrown if \a idx is invalid for this String.
4047 size_type
find_first_of(const char* cstr
, size_type idx
= 0) const
4049 return find_first_of(cstr
, idx
, strlen(cstr
));
4055 Find the first code point that is not one of a set of chars.
4058 c-string describing the set of chars.
4061 Index of the start point for the search
4064 - Index of the first code point that does not match any one of the chars in \a c_str starting from from \a idx.
4065 - npos if all code points matched any of the chars in \a c_str.
4067 \exception std::out_of_range Thrown if \a idx is invalid for this String.
4069 size_type
find_first_not_of(const char* cstr
, size_type idx
= 0) const
4071 return find_first_not_of(cstr
, idx
, strlen(cstr
));
4077 Find the first occurrence of one of a set of chars.
4080 char array containing the set of chars.
4083 Index of the start point for the search
4086 Number of chars in the char array.
4089 - Index of the first occurrence of any one of the chars in \a chars starting from from \a idx.
4090 - npos if none of the chars in \a chars were found.
4092 \exception std::length_error Thrown if \a chars_len was 'npos'.
4094 size_type
find_first_of(const char* chars
, size_type idx
, size_type chars_len
) const
4096 if (chars_len
== npos
)
4097 throw std::length_error("Length for char array can not be 'npos'");
4099 if (idx
< d_cplength
)
4101 const utf32
* pt
= &ptr()[idx
];
4105 if (npos
!= find_codepoint(chars
, chars_len
, *pt
++))
4108 } while (++idx
!= d_cplength
);
4118 Find the first code point that is not one of a set of chars.
4121 char array containing the set of chars.
4124 Index of the start point for the search
4127 Number of chars in the car array.
4130 - Index of the first code point that does not match any one of the chars in \a chars starting from from \a idx.
4131 - npos if all code points matched any of the chars in \a chars.
4133 \exception std::length_error Thrown if \a chars_len was 'npos'.
4135 size_type
find_first_not_of(const char* chars
, size_type idx
, size_type chars_len
) const
4137 if (chars_len
== npos
)
4138 throw std::length_error("Length for char array can not be 'npos'");
4140 if (idx
< d_cplength
)
4142 const utf32
* pt
= &ptr()[idx
];
4146 if (npos
== find_codepoint(chars
, chars_len
, *pt
++))
4149 } while (++idx
!= d_cplength
);
4157 //////////////////////////////////////////////////////////////////////////
4158 // Find last of different code-points
4159 //////////////////////////////////////////////////////////////////////////
4162 Find the last occurrence of one of a set of code points.
4165 String object describing the set of code points.
4168 Index of the start point for the search
4171 - Index of the last occurrence of any one of the code points in \a str starting from \a idx.
4172 - npos if none of the code points in \a str were found.
4174 size_type
find_last_of(const String
& str
, size_type idx
= npos
) const
4178 if (idx
>= d_cplength
)
4179 idx
= d_cplength
- 1;
4181 const utf32
* pt
= &ptr()[idx
];
4185 if (npos
!= str
.find(*pt
--))
4188 } while (idx
-- != 0);
4197 Find the last code point that is not one of a set of code points.
4200 String object describing the set of code points.
4203 Index of the start point for the search
4206 - Index of the last code point that does not match any one of the code points in \a str starting from \a idx.
4207 - npos if all code points matched one of the code points in \a str.
4209 size_type
find_last_not_of(const String
& str
, size_type idx
= npos
) const
4213 if (idx
>= d_cplength
)
4214 idx
= d_cplength
- 1;
4216 const utf32
* pt
= &ptr()[idx
];
4220 if (npos
== str
.find(*pt
--))
4223 } while (idx
-- != 0);
4233 Find the last occurrence of one of a set of code points.
4236 std::string object describing the set of code points.
4239 The characters of \a std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF. No translation of
4240 the provided data will occur.
4243 Index of the start point for the search
4246 - Index of the last occurrence of any one of the code points in \a std_str starting from \a idx.
4247 - npos if none of the code points in \a std_str were found.
4249 size_type
find_last_of(const std::string
& std_str
, size_type idx
= npos
) const
4253 if (idx
>= d_cplength
)
4254 idx
= d_cplength
- 1;
4256 const utf32
* pt
= &ptr()[idx
];
4260 if (npos
!= find_codepoint(std_str
, *pt
--))
4263 } while (idx
-- != 0);
4272 Find the last code point that is not one of a set of code points.
4275 std::string object describing the set of code points.
4278 The characters of \a std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF. No translation of
4279 the provided data will occur.
4282 Index of the start point for the search
4285 - Index of the last code point that does not match any one of the code points in \a std_str starting from \a idx.
4286 - npos if all code points matched one of the code points in \a std_str.
4288 size_type
find_last_not_of(const std::string
& std_str
, size_type idx
= npos
) const
4292 if (idx
>= d_cplength
)
4293 idx
= d_cplength
- 1;
4295 const utf32
* pt
= &ptr()[idx
];
4299 if (npos
== find_codepoint(std_str
, *pt
--))
4302 } while (idx
-- != 0);
4312 Find the last occurrence of one of a set of code points.
4315 Buffer containing null-terminated utf8 encoded data describing the set of code points.
4318 A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
4319 comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f)
4320 would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
4324 Index of the start point for the search
4327 - Index of the last occurrence of any one of the code points in \a utf8_str starting from \a idx.
4328 - npos if none of the code points in \a utf8_str were found.
4330 \exception std::out_of_range Thrown if \a idx is invalid for this String.
4332 size_type
find_last_of(const utf8
* utf8_str
, size_type idx
= npos
) const
4334 return find_last_of(utf8_str
, idx
, utf_length(utf8_str
));
4339 Find the last code point that is not one of a set of code points.
4342 Buffer containing null-terminated utf8 encoded data describing the set of code points.
4345 A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
4346 comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f)
4347 would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
4351 Index of the start point for the search
4354 - Index of the last code point that does not match any one of the code points in \a utf8_str starting from \a idx.
4355 - npos if all code points matched one of the code points in \a utf8_str.
4357 \exception std::out_of_range Thrown if \a idx is invalid for this String.
4359 size_type
find_last_not_of(const utf8
* utf8_str
, size_type idx
= npos
) const
4361 return find_last_not_of(utf8_str
, idx
, utf_length(utf8_str
));
4366 Find the last occurrence of one of a set of code points.
4369 Buffer containing utf8 encoded data describing the set of code points.
4372 A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
4373 comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f)
4374 would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
4378 Index of the start point for the search
4381 Length of the utf8 encoded data in utf8 code units (not code points).
4384 - Index of the last occurrence of any one of the code points in \a utf8_str starting from from \a idx.
4385 - npos if none of the code points in \a utf8_str were found.
4387 \exception std::length_error Thrown if \a str_len was 'npos'.
4389 size_type
find_last_of(const utf8
* utf8_str
, size_type idx
, size_type str_len
) const
4391 if (str_len
== npos
)
4392 throw std::length_error("Length for utf8 encoded string can not be 'npos'");
4396 if (idx
>= d_cplength
)
4397 idx
= d_cplength
- 1;
4399 size_type encsze
= encoded_size(utf8_str
, str_len
);
4401 const utf32
* pt
= &ptr()[idx
];
4405 if (npos
!= find_codepoint(utf8_str
, encsze
, *pt
--))
4408 } while (idx
-- != 0);
4417 Find the last code point that is not one of a set of code points.
4420 Buffer containing utf8 encoded data describing the set of code points.
4423 A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
4424 comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f)
4425 would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
4429 Index of the start point for the search
4432 Length of the utf8 encoded data in utf8 code units (not code points).
4435 - Index of the last code point that does not match any one of the code points in \a utf8_str starting from from \a idx.
4436 - npos if all code points matched one of the code points in \a utf8_str.
4438 \exception std::length_error Thrown if \a str_len was 'npos'.
4440 size_type
find_last_not_of(const utf8
* utf8_str
, size_type idx
, size_type str_len
) const
4442 if (str_len
== npos
)
4443 throw std::length_error("Length for utf8 encoded string can not be 'npos'");
4447 if (idx
>= d_cplength
)
4448 idx
= d_cplength
- 1;
4450 size_type encsze
= encoded_size(utf8_str
, str_len
);
4452 const utf32
* pt
= &ptr()[idx
];
4456 if (npos
== find_codepoint(utf8_str
, encsze
, *pt
--))
4459 } while (idx
-- != 0);
4469 Search for last occurrence of a given code point
4472 The utf32 code point to search for
4475 Index of the code point where the search is to start.
4478 - Index of the last occurrence of \a code_point starting from \a idx.
4479 - npos if the code point could not be found
4481 size_type
find_last_of(utf32 code_point
, size_type idx
= npos
) const
4483 return rfind(code_point
, idx
);
4488 Search for the last code point that does not match a given code point
4491 The utf32 code point to search for
4494 Index of the code point where the search is to start.
4497 - Index of the last code point that does not match \a code_point starting from from \a idx.
4498 - npos if all code points matched \a code_point
4500 size_type
find_last_not_of(utf32 code_point
, size_type idx
= npos
) const
4504 if (idx
>= d_cplength
)
4505 idx
= d_cplength
- 1;
4509 if ((*this)[idx
] != code_point
)
4512 } while(idx
-- != 0);
4522 Find the last occurrence of one of a set of chars.
4525 c-string describing the set of chars.
4528 Index of the start point for the search
4531 - Index of the last occurrence of any one of the chars in \a c_str starting from \a idx.
4532 - npos if none of the chars in \a c_str were found.
4534 \exception std::out_of_range Thrown if \a idx is invalid for this String.
4536 size_type
find_last_of(const char* cstr
, size_type idx
= npos
) const
4538 return find_last_of(cstr
, idx
, strlen(cstr
));
4544 Find the last code point that is not one of a set of chars.
4547 c-string describing the set of chars.
4550 Index of the start point for the search
4553 - Index of the last code point that does not match any one of the chars in \a c_str starting from \a idx.
4554 - npos if all code points matched any of the chars in \a c_str.
4556 \exception std::out_of_range Thrown if \a idx is invalid for this String.
4558 size_type
find_last_not_of(const char* cstr
, size_type idx
= npos
) const
4560 return find_last_not_of(cstr
, idx
, strlen(cstr
));
4566 Find the last occurrence of one of a set of chars.
4569 char array containing the set of chars.
4572 Index of the start point for the search
4575 Number of chars in the char array.
4578 - Index of the last occurrence of any one of the chars in \a chars, starting from from \a idx.
4579 - npos if none of the chars in \a chars were found.
4581 \exception std::length_error Thrown if \a chars_len was 'npos'.
4583 size_type
find_last_of(const char* chars
, size_type idx
, size_type chars_len
) const
4585 if (chars_len
== npos
)
4586 throw std::length_error("Length for char array can not be 'npos'");
4590 if (idx
>= d_cplength
)
4591 idx
= d_cplength
- 1;
4593 const utf32
* pt
= &ptr()[idx
];
4597 if (npos
!= find_codepoint(chars
, chars_len
, *pt
--))
4600 } while (idx
-- != 0);
4610 Find the last code point that is not one of a set of chars.
4613 char array containing the set of chars.
4616 Index of the start point for the search
4619 Number of chars in the char array.
4622 - Index of the last code point that does not match any one of the chars in \a chars, starting from from \a idx.
4623 - npos if all code points matched any of the chars in \a chars.
4625 \exception std::length_error Thrown if \a chars_len was 'npos'.
4627 size_type
find_last_not_of(const char* chars
, size_type idx
, size_type chars_len
) const
4629 if (chars_len
== npos
)
4630 throw std::length_error("Length for char array can not be 'npos'");
4634 if (idx
>= d_cplength
)
4635 idx
= d_cplength
- 1;
4637 const utf32
* pt
= &ptr()[idx
];
4641 if (npos
== find_codepoint(chars
, chars_len
, *pt
--))
4644 } while (idx
-- != 0);
4652 //////////////////////////////////////////////////////////////////////////
4654 //////////////////////////////////////////////////////////////////////////
4657 Returns a substring of this String.
4660 Index of the first code point to use for the sub-string.
4663 Maximum number of code points to use for the sub-string
4666 A String object containing the specified sub-string.
4668 \exception std::out_of_range Thrown if \a idx is invalid for this String.
4670 String
substr(size_type idx
= 0, size_type len
= npos
) const
4672 if (d_cplength
< idx
)
4673 throw std::out_of_range("Index is out of range for this CEGUI::String");
4675 return String(*this, idx
, len
);
4678 //////////////////////////////////////////////////////////////////////////
4679 // Iterator creation
4680 //////////////////////////////////////////////////////////////////////////
4683 Return a forwards iterator that describes the beginning of the String
4686 iterator object that describes the beginning of the String.
4688 iterator
begin(void)
4690 return iterator(ptr());
4695 Return a constant forwards iterator that describes the beginning of the String
4698 const_iterator object that describes the beginning of the String.
4700 const_iterator
begin(void) const
4702 return const_iterator(ptr());
4707 Return a forwards iterator that describes the end of the String
4710 iterator object that describes the end of the String.
4714 return iterator(&ptr()[d_cplength
]);
4719 Return a constant forwards iterator that describes the end of the String
4722 const_iterator object that describes the end of the String.
4724 const_iterator
end(void) const
4726 return const_iterator(&ptr()[d_cplength
]);
4731 Return a reverse iterator that describes the beginning of the String
4734 reverse_iterator object that describes the beginning of the String (so is actually at the end)
4736 reverse_iterator
rbegin(void)
4738 return reverse_iterator(end());
4743 Return a constant reverse iterator that describes the beginning of the String
4746 const_reverse_iterator object that describes the beginning of the String (so is actually at the end)
4748 const_reverse_iterator
rbegin(void) const
4750 return const_reverse_iterator(end());
4755 Return a reverse iterator that describes the end of the String
4758 reverse_iterator object that describes the end of the String (so is actually at the beginning)
4760 reverse_iterator
rend(void)
4762 return reverse_iterator(begin());
4767 Return a constant reverse iterator that describes the end of the String
4770 const_reverse_iterator object that describes the end of the String (so is actually at the beginning)
4772 const_reverse_iterator
rend(void) const
4774 return const_reverse_iterator(begin());
4778 /*************************************************************************
4779 Implementation Functions
4780 *************************************************************************/
4781 // string management
4783 // change size of allocated buffer so it is at least 'new_size'.
4784 // May or may not cause re-allocation and copy of buffer if size is larger
4785 // will never re-allocate to make size smaller. (see trim())
4786 bool grow(size_type new_size
);
4788 // perform re-allocation to remove wasted space.
4791 // set the length of the string, and terminate it, according to the given value (will not re-allocate, use grow() first).
4792 void setlen(size_type len
)
4795 ptr()[len
] = (utf32
)(0);
4798 // initialise string object
4801 d_reserve
= STR_QUICKBUFF_SIZE
;
4803 d_encodedbufflen
= 0;
4804 d_encodeddatlen
= 0;
4808 // return true if the given pointer is inside the string data
4809 bool inside(utf32
* inptr
)
4811 if (inptr
< ptr() || ptr() + d_cplength
<= inptr
)
4817 // compute distance between two iterators, returning a 'safe' value
4818 size_type
safe_iter_dif(const const_iterator
& iter1
, const const_iterator
& iter2
) const
4820 return (iter1
.d_ptr
== 0) ? 0 : (iter1
- iter2
);
4823 // encoding functions
4825 // src_len is in code units, or 0 for null terminated string.
4826 // dest_len is in code units.
4827 // returns number of code units put into dest buffer.
4828 size_type
encode(const utf32
* src
, utf8
* dest
, size_type dest_len
, size_type src_len
= 0) const
4830 // count length for null terminated source...
4833 src_len
= utf_length(src
);
4836 size_type destCapacity
= dest_len
;
4838 // while there is data in the source buffer,
4839 for (uint idx
= 0; idx
< src_len
; ++idx
)
4841 utf32 cp
= src
[idx
];
4843 // check there is enough destination buffer to receive this encoded unit (exit loop & return if not)
4844 if (destCapacity
< encoded_size(cp
))
4854 else if (cp
< 0x0800)
4856 *dest
++ = (utf8
)((cp
>> 6) | 0xC0);
4857 *dest
++ = (utf8
)((cp
& 0x3F) | 0x80);
4860 else if (cp
< 0x10000)
4862 *dest
++ = (utf8
)((cp
>> 12) | 0xE0);
4863 *dest
++ = (utf8
)(((cp
>> 6) & 0x3F) | 0x80);
4864 *dest
++ = (utf8
)((cp
& 0x3F) | 0x80);
4869 *dest
++ = (utf8
)((cp
>> 18) | 0xF0);
4870 *dest
++ = (utf8
)(((cp
>> 12) & 0x3F) | 0x80);
4871 *dest
++ = (utf8
)(((cp
>> 6) & 0x3F) | 0x80);
4872 *dest
++ = (utf8
)((cp
& 0x3F) | 0x80);
4878 return dest_len
- destCapacity
;
4881 size_type
encode(const utf8
* src
, utf32
* dest
, size_type dest_len
, size_type src_len
= 0) const
4883 // count length for null terminated source...
4886 src_len
= utf_length(src
);
4889 size_type destCapacity
= dest_len
;
4891 // while there is data in the source buffer, and space in the dest buffer
4892 for (uint idx
= 0; ((idx
< src_len
) && (destCapacity
> 0));)
4895 utf8 cu
= src
[idx
++];
4903 cp
= ((cu
& 0x1F) << 6);
4904 cp
|= (src
[idx
++] & 0x3F);
4908 cp
= ((cu
& 0x0F) << 12);
4909 cp
|= ((src
[idx
++] & 0x3F) << 6);
4910 cp
|= (src
[idx
++] & 0x3F);
4914 cp
= ((cu
& 0x07) << 18);
4915 cp
|= ((src
[idx
++] & 0x3F) << 12);
4916 cp
|= ((src
[idx
++] & 0x3F) << 6);
4917 cp
|= (src
[idx
++] & 0x3F);
4924 return dest_len
- destCapacity
;
4927 // return the number of utf8 code units required to encode the given utf32 code point
4928 size_type
encoded_size(utf32 code_point
) const
4930 if (code_point
< 0x80)
4932 else if (code_point
< 0x0800)
4934 else if (code_point
< 0x10000)
4940 // return number of code units required to re-encode given null-terminated utf32 data as utf8. return does not include terminating null.
4941 size_type
encoded_size(const utf32
* buf
) const
4943 return encoded_size(buf
, utf_length(buf
));
4946 // return number of code units required to re-encode given utf32 data as utf8. len is number of code units in 'buf'.
4947 size_type
encoded_size(const utf32
* buf
, size_type len
) const
4949 size_type count
= 0;
4953 count
+= encoded_size(*buf
++);
4959 // return number of utf32 code units required to re-encode given utf8 data as utf32. return does not include terminating null.
4960 size_type
encoded_size(const utf8
* buf
) const
4962 return encoded_size(buf
, utf_length(buf
));
4965 // return number of utf32 code units required to re-encode given utf8 data as utf32. len is number of code units in 'buf'.
4966 size_type
encoded_size(const utf8
* buf
, size_type len
) const
4969 size_type count
= 0;
4979 else if (tcp
< 0xE0)
4984 else if (tcp
< 0xF0)
5000 // return number of code units in a null terminated string
5001 size_type
utf_length(const utf8
* utf8_str
) const
5010 // return number of code units in a null terminated string
5011 size_type
utf_length(const utf32
* utf32_str
) const
5014 while (*utf32_str
++)
5020 // build an internal buffer with the string encoded as utf8 (remains valid until string is modified).
5021 utf8
* build_utf8_buff(void) const;
5023 // compare two utf32 buffers
5024 int utf32_comp_utf32(const utf32
* buf1
, const utf32
* buf2
, size_type cp_count
) const
5029 while ((--cp_count
) && (*buf1
== *buf2
))
5032 return *buf1
- *buf2
;
5035 // compare utf32 buffer with char buffer (chars are taken to be code-points in the range 0x00-0xFF)
5036 int utf32_comp_char(const utf32
* buf1
, const char* buf2
, size_type cp_count
) const
5041 while ((--cp_count
) && (*buf1
== static_cast<utf32
>(static_cast<unsigned char>(*buf2
))))
5044 return *buf1
- static_cast<utf32
>(static_cast<unsigned char>(*buf2
));
5047 // compare utf32 buffer with encoded utf8 data
5048 int utf32_comp_utf8(const utf32
* buf1
, const utf8
* buf2
, size_type cp_count
) const
5066 cp
= ((cu
& 0x1F) << 6);
5067 cp
|= (*buf2
++ & 0x3F);
5071 cp
= ((cu
& 0x0F) << 12);
5072 cp
|= ((*buf2
++ & 0x3F) << 6);
5073 cp
|= (*buf2
++ & 0x3F);
5077 cp
= ((cu
& 0x07) << 18);
5078 cp
|= ((*buf2
++ & 0x3F) << 12);
5079 cp
|= ((*buf2
++ & 0x3F) << 6);
5080 cp
|= (*buf2
++ & 0x3F);
5083 } while ((*buf1
++ == cp
) && (--cp_count
));
5085 return (*--buf1
) - cp
;
5088 // return index of first occurrence of 'code_point' in std::string 'str', or npos if none
5089 size_type
find_codepoint(const std::string
& str
, utf32 code_point
) const
5091 size_type idx
= 0, sze
= (size_type
)str
.size();
5095 if (code_point
== static_cast<utf32
>(static_cast<unsigned char>(str
[idx
])))
5104 // return index of first occurrence of 'code_point' in utf8 encoded string 'str', or npos if none. len is in code points.
5105 size_type
find_codepoint(const utf8
* str
, size_type len
, utf32 code_point
) const
5112 while (idx
!= len
) {
5121 cp
= ((cu
& 0x1F) << 6);
5122 cp
|= (*str
++ & 0x3F);
5126 cp
= ((cu
& 0x0F) << 12);
5127 cp
|= ((*str
++ & 0x3F) << 6);
5128 cp
|= (*str
++ & 0x3F);
5132 cp
= ((cu
& 0x07) << 18);
5133 cp
|= ((*str
++ & 0x3F) << 12);
5134 cp
|= ((*str
++ & 0x3F) << 6);
5135 cp
|= (*str
++ & 0x3F);
5138 if (code_point
== cp
)
5148 // return index of first occurrence of 'code_point' in char array 'chars', or npos if none
5149 size_type
find_codepoint(const char* chars
, size_type chars_len
, utf32 code_point
) const
5151 for (size_type idx
= 0; idx
!= chars_len
; ++idx
)
5153 if (code_point
== static_cast<utf32
>(static_cast<unsigned char>(chars
[idx
])))
5163 //////////////////////////////////////////////////////////////////////////
5164 // Comparison operators
5165 //////////////////////////////////////////////////////////////////////////
5168 Return true if String \a str1 is equal to String \a str2
5170 bool CEGUIEXPORT
operator==(const String
& str1
, const String
& str2
);
5174 Return true if String \a str is equal to std::string \a std_str
5176 bool CEGUIEXPORT
operator==(const String
& str
, const std::string
& std_str
);
5180 Return true if String \a str is equal to std::string \a std_str
5182 bool CEGUIEXPORT
operator==(const std::string
& std_str
, const String
& str
);
5186 Return true if String \a str is equal to null-terminated utf8 data \a utf8_str
5188 bool CEGUIEXPORT
operator==(const String
& str
, const utf8
* utf8_str
);
5192 Return true if String \a str is equal to null-terminated utf8 data \a utf8_str
5194 bool CEGUIEXPORT
operator==(const utf8
* utf8_str
, const String
& str
);
5198 Return true if String \a str1 is not equal to String \a str2
5200 bool CEGUIEXPORT
operator!=(const String
& str1
, const String
& str2
);
5204 Return true if String \a str is not equal to std::string \a std_str
5206 bool CEGUIEXPORT
operator!=(const String
& str
, const std::string
& std_str
);
5210 Return true if String \a str is not equal to std::string \a std_str
5212 bool CEGUIEXPORT
operator!=(const std::string
& std_str
, const String
& str
);
5216 Return true if String \a str is not equal to null-terminated utf8 data \a utf8_str
5218 bool CEGUIEXPORT
operator!=(const String
& str
, const utf8
* utf8_str
);
5222 Return true if String \a str is not equal to null-terminated utf8 data \a utf8_str
5224 bool CEGUIEXPORT
operator!=(const utf8
* utf8_str
, const String
& str
);
5228 Return true if String \a str1 is lexicographically less than String \a str2
5230 bool CEGUIEXPORT
operator<(const String
& str1
, const String
& str2
);
5234 Return true if String \a str is lexicographically less than std::string \a std_str
5236 bool CEGUIEXPORT
operator<(const String
& str
, const std::string
& std_str
);
5240 Return true if String \a str is lexicographically less than std::string \a std_str
5242 bool CEGUIEXPORT
operator<(const std::string
& std_str
, const String
& str
);
5246 Return true if String \a str is lexicographically less than null-terminated utf8 data \a utf8_str
5248 bool CEGUIEXPORT
operator<(const String
& str
, const utf8
* utf8_str
);
5252 Return true if String \a str is lexicographically less than null-terminated utf8 data \a utf8_str
5254 bool CEGUIEXPORT
operator<(const utf8
* utf8_str
, const String
& str
);
5258 Return true if String \a str1 is lexicographically greater than String \a str2
5260 bool CEGUIEXPORT
operator>(const String
& str1
, const String
& str2
);
5264 Return true if String \a str is lexicographically greater than std::string \a std_str
5266 bool CEGUIEXPORT
operator>(const String
& str
, const std::string
& std_str
);
5270 Return true if String \a str is lexicographically greater than std::string \a std_str
5272 bool CEGUIEXPORT
operator>(const std::string
& std_str
, const String
& str
);
5276 Return true if String \a str is lexicographically greater than null-terminated utf8 data \a utf8_str
5278 bool CEGUIEXPORT
operator>(const String
& str
, const utf8
* utf8_str
);
5282 Return true if String \a str is lexicographically greater than null-terminated utf8 data \a utf8_str
5284 bool CEGUIEXPORT
operator>(const utf8
* utf8_str
, const String
& str
);
5288 Return true if String \a str1 is lexicographically less than or equal to String \a str2
5290 bool CEGUIEXPORT
operator<=(const String
& str1
, const String
& str2
);
5294 Return true if String \a str is lexicographically less than or equal to std::string \a std_str
5296 bool CEGUIEXPORT
operator<=(const String
& str
, const std::string
& std_str
);
5300 Return true if String \a str is lexicographically less than or equal to std::string \a std_str
5302 bool CEGUIEXPORT
operator<=(const std::string
& std_str
, const String
& str
);
5306 Return true if String \a str is lexicographically less than or equal to null-terminated utf8 data \a utf8_str
5308 bool CEGUIEXPORT
operator<=(const String
& str
, const utf8
* utf8_str
);
5312 Return true if String \a str is lexicographically less than or equal to null-terminated utf8 data \a utf8_str
5314 bool CEGUIEXPORT
operator<=(const utf8
* utf8_str
, const String
& str
);
5318 Return true if String \a str1 is lexicographically greater than or equal to String \a str2
5320 bool CEGUIEXPORT
operator>=(const String
& str1
, const String
& str2
);
5324 Return true if String \a str is lexicographically greater than or equal to std::string \a std_str
5326 bool CEGUIEXPORT
operator>=(const String
& str
, const std::string
& std_str
);
5330 Return true if String \a str is lexicographically greater than or equal to std::string \a std_str
5332 bool CEGUIEXPORT
operator>=(const std::string
& std_str
, const String
& str
);
5336 Return true if String \a str is lexicographically greater than or equal to null-terminated utf8 data \a utf8_str
5338 bool CEGUIEXPORT
operator>=(const String
& str
, const utf8
* utf8_str
);
5342 Return true if String \a str is lexicographically greater than or equal to null-terminated utf8 data \a utf8_str
5344 bool CEGUIEXPORT
operator>=(const utf8
* utf8_str
, const String
& str
);
5348 Return true if String \a str is equal to c-string \a c_str
5350 bool CEGUIEXPORT
operator==(const String
& str
, const char* c_str
);
5354 Return true if c-string \a c_str is equal to String \a str
5356 bool CEGUIEXPORT
operator==(const char* c_str
, const String
& str
);
5360 Return true if String \a str is not equal to c-string \a c_str
5362 bool CEGUIEXPORT
operator!=(const String
& str
, const char* c_str
);
5366 Return true if c-string \a c_str is not equal to String \a str
5368 bool CEGUIEXPORT
operator!=(const char* c_str
, const String
& str
);
5372 Return true if String \a str is lexicographically less than c-string \a c_str
5374 bool CEGUIEXPORT
operator<(const String
& str
, const char* c_str
);
5378 Return true if c-string \a c_str is lexicographically less than String \a str
5380 bool CEGUIEXPORT
operator<(const char* c_str
, const String
& str
);
5384 Return true if String \a str is lexicographically greater than c-string \a c_str
5386 bool CEGUIEXPORT
operator>(const String
& str
, const char* c_str
);
5390 Return true if c-string \a c_str is lexicographically greater than String \a str
5392 bool CEGUIEXPORT
operator>(const char* c_str
, const String
& str
);
5396 Return true if String \a str is lexicographically less than or equal to c-string \a c_str
5398 bool CEGUIEXPORT
operator<=(const String
& str
, const char* c_str
);
5402 Return true if c-string \a c_str is lexicographically less than or equal to String \a str
5404 bool CEGUIEXPORT
operator<=(const char* c_str
, const String
& str
);
5408 Return true if String \a str is lexicographically greater than or equal to c-string \a c_str
5410 bool CEGUIEXPORT
operator>=(const String
& str
, const char* c_str
);
5414 Return true if c-string \a c_str is lexicographically greater than or equal to String \a str
5416 bool CEGUIEXPORT
operator>=(const char* c_str
, const String
& str
);
5418 //////////////////////////////////////////////////////////////////////////
5419 // Concatenation operator functions
5420 //////////////////////////////////////////////////////////////////////////
5423 Return String object that is the concatenation of the given inputs
5426 String object describing first part of the new string
5429 String object describing the second part of the new string
5432 A String object that is the concatenation of \a str1 and \a str2
5434 \exception std::length_error Thrown if the resulting String would be too large.
5436 String CEGUIEXPORT
operator+(const String
& str1
, const String
& str2
);
5440 Return String object that is the concatenation of the given inputs
5443 String object describing first part of the new string
5446 std::string object describing the second part of the new string
5449 A String object that is the concatenation of \a str and \a std_str
5451 \exception std::length_error Thrown if the resulting String would be too large.
5453 String CEGUIEXPORT
operator+(const String
& str
, const std::string
& std_str
);
5457 Return String object that is the concatenation of the given inputs
5460 std::string object describing the first part of the new string
5463 String object describing the second part of the new string
5466 A String object that is the concatenation of \a std_str and \a str
5468 \exception std::length_error Thrown if the resulting String would be too large.
5470 String CEGUIEXPORT
operator+(const std::string
& std_str
, const String
& str
);
5474 Return String object that is the concatenation of the given inputs
5477 String object describing first part of the new string
5480 Buffer containing null-terminated utf8 encoded data describing the second part of the new string
5483 A String object that is the concatenation of \a str and \a utf8_str
5485 \exception std::length_error Thrown if the resulting String would be too large.
5487 String CEGUIEXPORT
operator+(const String
& str
, const utf8
* utf8_str
);
5491 Return String object that is the concatenation of the given inputs
5494 Buffer containing null-terminated utf8 encoded data describing the first part of the new string
5497 String object describing the second part of the new string
5500 A String object that is the concatenation of \a str and \a utf8_str
5502 \exception std::length_error Thrown if the resulting String would be too large.
5504 String CEGUIEXPORT
operator+(const utf8
* utf8_str
, const String
& str
);
5508 Return String object that is the concatenation of the given inputs
5511 String object describing the first part of the new string
5514 utf32 code point describing the second part of the new string
5517 A String object that is the concatenation of \a str and \a code_point
5519 \exception std::length_error Thrown if the resulting String would be too large.
5521 String CEGUIEXPORT
operator+(const String
& str
, utf32 code_point
);
5525 Return String object that is the concatenation of the given inputs
5528 utf32 code point describing the first part of the new string
5531 String object describing the second part of the new string
5534 A String object that is the concatenation of \a code_point and \a str
5536 \exception std::length_error Thrown if the resulting String would be too large.
5538 String CEGUIEXPORT
operator+(utf32 code_point
, const String
& str
);
5542 Return String object that is the concatenation of the given inputs
5545 String object describing first part of the new string
5548 c-string describing the second part of the new string
5551 A String object that is the concatenation of \a str and \a c_str
5553 \exception std::length_error Thrown if the resulting String would be too large.
5555 String CEGUIEXPORT
operator+(const String
& str
, const char* c_str
);
5559 Return String object that is the concatenation of the given inputs
5562 c-string describing the first part of the new string
5565 String object describing the second part of the new string
5568 A String object that is the concatenation of \a c_str and \a str
5570 \exception std::length_error Thrown if the resulting String would be too large.
5572 String CEGUIEXPORT
operator+(const char* c_str
, const String
& str
);
5575 //////////////////////////////////////////////////////////////////////////
5576 // Output (stream) functions
5577 //////////////////////////////////////////////////////////////////////////
5578 CEGUIEXPORT
std::ostream
& operator<<(std::ostream
& s
, const String
& str
);
5581 //////////////////////////////////////////////////////////////////////////
5582 // Modifying operations
5583 //////////////////////////////////////////////////////////////////////////
5586 Swap the contents for two String objects
5589 String object who's contents are to be swapped with \a str2
5592 String object who's contents are to be swapped with \a str1
5597 void CEGUIEXPORT
swap(String
& str1
, String
& str2
);
5600 } // End of CEGUI namespace section
5603 #endif // end of guard _CEGUIString_h_