zorba_string.h
Go to the documentation of this file.
1 /*
2  * Copyright 2006-2008 The FLWOR Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #ifndef ZORBA_STRING_API_H
18 #define ZORBA_STRING_API_H
19 
20 #include <iterator>
21 #include <memory>
22 #include <string>
23 
24 #include <zorba/config.h>
25 
26 namespace zorba {
27 
28 /**
29  * The Zorba string class.
30  *
31  * Its API is mostly compatible with that of std::string.
32  */
33 class ZORBA_DLL_PUBLIC String {
34 public:
35  typedef char value_type;
36  typedef std::char_traits<value_type> traits_type;
37  typedef std::allocator<value_type> allocator_type;
38  typedef allocator_type::difference_type difference_type;
39  typedef allocator_type::size_type size_type;
40 
41  typedef value_type* pointer;
42  typedef value_type const* const_pointer;
44  typedef value_type const& const_reference;
45 
46  typedef pointer iterator;
48  typedef std::reverse_iterator<iterator> reverse_iterator;
49  typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
50 
51  /**
52  * The special value used to denote either (a) the maximum possible number as
53  * input or (b) "not found" as a result.
54  */
55  static size_type const npos = static_cast<size_type>( -1 );
56 
57  ////////// constructors & destructor ////////////////////////////////////////
58 
59  /**
60  * Constructs an empty string.
61  */
62  String();
63 
64  /**
65  * Copy constructs a new string from an existing string.
66  *
67  * @param s The string to copy from.
68  */
69  String( String const &s );
70 
71  /**
72  * Constructs a new string from an existing std::string.
73  *
74  * @param s The string to copy from.
75  */
76  String( std::string const &s );
77 
78  /**
79  * Constructs a string from the given C string.
80  *
81  * @param s The null-terminated C string.
82  */
83  String( const_pointer s );
84 
85  /**
86  * Copy constructs a new string from a substring of an existing string.
87  *
88  * @param s The string to copy from.
89  * @param pos The position of the first character to copy.
90  * @param n The number of characters to copy.
91  */
92  String( String const &s, size_type pos, size_type n = npos );
93 
94  /**
95  * Constructs a new string from a substring of an existing std::string.
96  *
97  * @param s The string to copy from.
98  * @param pos The starting position of the substring.
99  * @param n The number of characters of the substring.
100  */
101  String( std::string const &s, size_type pos, size_type n = npos );
102 
103  /**
104  * Constructs a string from the given C string.
105  *
106  * @param s The C string.
107  * @param n The number of characters to copy.
108  */
110 
111  /**
112  * Constructs a new string as \a n copies of \a c.
113  *
114  * @param n The number of times to repeat the character.
115  * @param c The character to repeat.
116  */
117  String( size_type n, value_type c );
118 
119  /**
120  * Constructs a string from a range of characters [i,j).
121  *
122  * @param i The iterator marking the first character of the range.
123  * @param j The iterator marking one past the last character of the range.
124  */
126 
127  /**
128  * Destructs this string.
129  */
130  ~String();
131 
132  ////////// assignment ///////////////////////////////////////////////////////
133 
134  /**
135  * Assigns another string to this string.
136  *
137  * @param s The string to assign from.
138  * @return this string.
139  */
140  String& operator=( String const &s );
141 
142  /**
143  * Assigns a std::string to this string.
144  *
145  * @param s The string to assign from.
146  * @return this string.
147  */
148  String& operator=( std::string const &s );
149 
150  /**
151  * Assigns a C string to this string.
152  *
153  * @param s The null-terminated C string to assign from.
154  * @return this string.
155  */
156  String& operator=( const_pointer s );
157 
158  /**
159  * Assigns a character to this string.
160  *
161  * @param c The character to assign.
162  * @return this string.
163  */
164  String& operator=( value_type c );
165 
166  ////////// properties ///////////////////////////////////////////////////////
167 
168  /**
169  * Gets the capacity of this string.
170  *
171  * @return said capacity.
172  */
173  size_type capacity() const;
174 
175  /**
176  * Checks whether the string is empty.
177  *
178  * @return True only if it is.
179  */
180  bool empty() const {
181  return length() == 0;
182  }
183 
184  /**
185  * Gets the number of characters in this string.
186  *
187  * @return The number of UTF-8 characters.
188  */
189  size_type length() const;
190 
191  /**
192  * Gets the number of characters in this string.
193  * (This is a synonym for length().)
194  *
195  * @return The number of UTF-8 characters.
196  */
197  size_type size() const {
198  return length();
199  }
200 
201  ////////// character access /////////////////////////////////////////////////
202 
203  /**
204  * References a particular character within the string.
205  *
206  * @param pos The index of the character. The index is bounds-checked.
207  * @return said character as an l-value.
208  * @throw std::out_of_range if \a pos >= \c size().
209  */
210  reference at( size_type pos );
211 
212  /**
213  * References a particular character within the string.
214  *
215  * @param pos The index of the character. The index is bounds-checked.
216  * @return said character as an r-value.
217  */
218  value_type at( size_type pos ) const;
219 
220  /**
221  * References a particular character within the string.
222  *
223  * @param pos The index of the character. The index is not bounds-checked.
224  * @return said character as an r-value.
225  */
226  const_reference operator[]( size_type pos ) const;
227 
228  ////////// append ///////////////////////////////////////////////////////////
229 
230  /**
231  * Appends the given string to this string.
232  *
233  * @param s The string to append.
234  * @return this string.
235  */
236  String& append( String const &s );
237 
238  /**
239  * Appends a substring of the given string to this string.
240  *
241  * @param s The string to append.
242  * @param s_pos The starting position is \a s.
243  * @param s_n The number of characters of \a s to append.
244  * @return this string.
245  */
246  String& append( String const &s, size_type s_pos, size_type s_n );
247 
248  /**
249  * Appends the given string to this string.
250  *
251  * @param s The string to append.
252  * @return this string.
253  */
254  String& append( std::string const &s );
255 
256  /**
257  * Appends a substring of the given string to this string.
258  *
259  * @param s The string to append.
260  * @param s_pos The starting position is \a s.
261  * @param s_n The number of characters of \a s to append.
262  * @return this string.
263  */
264  String& append( std::string const &s, size_type s_pos, size_type s_n );
265 
266  /**
267  * Appends the given C string to this string.
268  *
269  * @param s The null-terminated C string to append.
270  * @return this string.
271  */
272  String& append( const_pointer s );
273 
274  /**
275  * Appends the given C string to this string.
276  *
277  * @param s The C string to append.
278  * @param s_n The number of characters of \a s to append.
279  * @return this string.
280  */
281  String& append( const_pointer s, size_type s_n );
282 
283  /**
284  * Appends \a n copies of \a c to this string.
285  *
286  * @param n The numer of copies of \a c to append.
287  * @param c The character to append.
288  * @return this string.
289  */
290  String& append( size_type n, value_type c );
291 
292  /**
293  * Appends the given character to this string.
294  *
295  * @param c The character to append.
296  */
297  void push_back( value_type c );
298 
299  /**
300  * Appends the given string to this string.
301  *
302  * @param s The string to append.
303  * @return this string.
304  */
305  String& operator+=( String const &s ) {
306  return append( s );
307  }
308 
309  /**
310  * Appends the given std::string to this string.
311  *
312  * @param s The string to append.
313  * @return this string.
314  */
315  String& operator+=( std::string const &s ) {
316  return append( s.data(), s.size() );
317  }
318 
319  /**
320  * Appends the given C string to this string.
321  *
322  * @param s The null-terminated C string to append.
323  * @return this string.
324  */
326  return append( s );
327  }
328 
329  /**
330  * Appends the given character to this string.
331  *
332  * @param c The character to append.
333  * @return this string.
334  */
336  return append( 1, c );
337  }
338 
339  ////////// assign ///////////////////////////////////////////////////////////
340 
341  /**
342  * Assigns another string to this string.
343  *
344  * @param s The string to assign from.
345  * @return this string.
346  */
347  String& assign( String const &s );
348 
349  /**
350  * Assigns a std::string to this string.
351  *
352  * @param s The string to assign from.
353  * @return this string.
354  */
355  String& assign( std::string const &s );
356 
357  /**
358  * Assigns a substring of a string to this string.
359  *
360  * @param s The string to assign from.
361  * @param pos The starting position withing \a s.
362  * @param n The number of characters to assign.
363  * @return this string.
364  */
365  String& assign( String const &s, size_type pos, size_type n );
366 
367  /**
368  * Assigns a substring of a std::string to this string.
369  *
370  * @param s The string to assign from.
371  * @param pos The starting position withing \a s.
372  * @param n The number of characters to assign.
373  * @return this string.
374  */
375  String& assign( std::string const &s, size_type pos, size_type n );
376 
377  /**
378  * Assigns a C to this string.
379  *
380  * @param s The null-terminated C string to assign from.
381  * @return this string.
382  */
383  String& assign( const_pointer s );
384 
385  /**
386  * Assigns a substring of a C to this string.
387  *
388  * @param s The C string to assign from.
389  * @param n The number of characters to assign.
390  * @return this string.
391  */
392  String& assign( const_pointer s, size_type n );
393 
394  /**
395  * Assigned \a n copies of a character to this string.
396  *
397  * @param n The number of copies of the character.
398  * @param c The character.
399  * @return this string.
400  */
401  String& assign( size_type n, value_type c );
402 
403  /**
404  * Assigns characters from a range of characters [i,j).
405  *
406  * @param i The iterator marking the first character of the range.
407  * @param j The iterator marking one past the last character of the range.
408  */
409  String& assign( const_iterator i, const_iterator j );
410 
411  ////////// compare //////////////////////////////////////////////////////////
412 
413  /**
414  * Compares this string against another.
415  *
416  * @param s The string to compare to.
417  * @return -1 only if this string < \a s,
418  * 0 only if this string == \a s,
419  * or +1 only if this string > \a s.
420  */
421  int compare( String const &s ) const;
422 
423  /**
424  * Compares this string against another.
425  *
426  * @param s The string to compare to.
427  * @return -1 only if this string < \a s,
428  * 0 only if this string == \a s,
429  * or +1 only if this string > \a s.
430  */
431  int compare( std::string const &s ) const;
432 
433  /**
434  * Compares this string against a C string.
435  *
436  * @param s The null-terminated C string to compare to.
437  * @return -1 only if this string < \a s,
438  * 0 only if this string == \a s,
439  * or +1 only if this string > \a s.
440  */
441  int compare( const_pointer s ) const;
442 
443  /**
444  * Compares a substring of this string against another.
445  *
446  * @param pos The starting position within this string.
447  * @param n The number of characters to compare.
448  * @param s The string to compare to.
449  * @return -1 only if this string < \a s,
450  * 0 only if this string == \a s,
451  * or +1 only if this string > \a s.
452  */
453  int compare( size_type pos, size_type n, String const &s ) const;
454 
455  /**
456  * Compares a substring of this string against another.
457  *
458  * @param pos The starting position within this string.
459  * @param n The number of characters to compare.
460  * @param s The string to compare to.
461  * @return -1 only if this string < \a s,
462  * 0 only if this string == \a s,
463  * or +1 only if this string > \a s.
464  */
465  int compare( size_type pos, size_type n, std::string const &s ) const;
466 
467  /**
468  * Compares a substring of this string against a C string.
469  *
470  * @param pos The starting position within this string.
471  * @param n The number of characters to compare.
472  * @param s The null-terminated C string to compare to.
473  * @return -1 only if this string < \a s,
474  * 0 only if this string == \a s,
475  * or +1 only if this string > \a s.
476  */
477  int compare( size_type pos, size_type n, const_pointer s ) const;
478 
479  /**
480  * Compares a substring of this string against a substring of another.
481  *
482  * @param pos The starting position within this string.
483  * @param n The number of characters to compare.
484  * @param s The string to compare to.
485  * @param s_pos The starting position within \a s.
486  * @param s_n The number of characters of \a s to compare.
487  * @return -1 only if this string < \a s,
488  * 0 only if this string == \a s,
489  * or +1 only if this string > \a s.
490  */
491  int compare( size_type pos, size_type n, String const &s, size_type s_pos,
492  size_type s_n ) const;
493 
494  /**
495  * Compares a substring of this string against a substring of another.
496  *
497  * @param pos The starting position within this string.
498  * @param n The number of characters to compare.
499  * @param s The string to compare to.
500  * @param s_pos The starting position within \a s.
501  * @param s_n The number of characters of \a s to compare.
502  * @return -1 only if this string < \a s,
503  * 0 only if this string == \a s,
504  * or +1 only if this string > \a s.
505  */
506  int compare( size_type pos, size_type n, std::string const &s,
507  size_type s_pos, size_type s_n ) const;
508 
509  /**
510  * Compares a substring of this string against a C string.
511  *
512  * @param pos The starting position within this string.
513  * @param n The number of characters to compare.
514  * @param s The C string to compare to.
515  * @param s_n The number of characters of \a s to compare.
516  * @return -1 only if this string < \a s,
517  * 0 only if this string == \a s,
518  * or +1 only if this string > \a s.
519  */
520  int compare( size_type pos, size_type n, const_pointer s,
521  size_type s_n ) const;
522 
523  ////////// clear/erase //////////////////////////////////////////////////////
524 
525  /**
526  * Erases the string making it empty.
527  */
528  void clear();
529 
530  /**
531  * Erases the given number of characters starting at the given position.
532  *
533  * @param pos The position of the first character to erase.
534  * @param n The number of characters to erase.
535  * @return a reference to this string.
536  * @throw std::out_of_range if \a pos is beyond the end of the string.
537  */
538  String& erase( size_type pos = 0, size_type n = npos );
539 
540  /**
541  * Erases the character at the given iterator's position.
542  *
543  * @param i The iterator marking the position of the character to erase.
544  * @return a new iterator marking the same position (i.e., what becomes the
545  * next character).
546  */
547  iterator erase( iterator i );
548 
549  /**
550  * Erases a range of characters [i,j).
551  *
552  * @param i The iterator marking the first character of the range.
553  * @param j The iterator marking one past the last character of the range.
554  * @return a new iterator marking the same position as \a i.
555  */
556  iterator erase( iterator i, iterator j );
557 
558  ////////// find /////////////////////////////////////////////////////////////
559 
560  /**
561  * Searches this string for the given string starting at the given position.
562  *
563  * @param s The string to search for.
564  * @param pos The starting position within this string.
565  * @return the offset of \a s or \c npos if not found.
566  */
567  size_type find( String const &s, size_type pos = 0 ) const;
568 
569  /**
570  * Searches this string for the given string starting at the given position.
571  *
572  * @param s The string to search for.
573  * @param pos The starting position within this string.
574  * @return the offset of \a s or \c npos if not found.
575  */
576  size_type find( std::string const &s, size_type pos = 0 ) const;
577 
578  /**
579  * Searches this string for the given string starting at the given position.
580  *
581  * @param s The null-terminated C string to search for.
582  * @param pos The starting position within this string.
583  * @return the offset of \a s or \c npos if not found.
584  */
585  size_type find( const_pointer s, size_type pos = 0 ) const;
586 
587  /**
588  * Searches this string for the given string starting at the given position.
589  *
590  * @param s The C string to search for.
591  * @param pos The starting position within this string.
592  * @param s_n The number of characters to compare.
593  * @return the offset of \a s or \c npos if not found.
594  */
595  size_type find( const_pointer s, size_type pos, size_type s_n ) const;
596 
597  /**
598  * Searches this string for the given character staring at the given
599  * position.
600  *
601  * @param c The character to search for.
602  * @param pos The starting position within this string.
603  * @return the offset of \a c or \c npos if not found.
604  */
605  size_type find( value_type c, size_type pos = 0 ) const;
606 
607  /**
608  * Searches this string for any one of the characters in \a s starting at the
609  * given position.
610  *
611  * @param s The set of characters to search for.
612  * @param pos The starting position within this string.
613  * @return the offset of a matching character or \c npos if not found.
614  */
615  size_type find_first_of( String const &s, size_type pos = 0 ) const;
616 
617  /**
618  * Searches this string for any one of the characters in \a s starting at the
619  * given position.
620  *
621  * @param s The set of characters to search for.
622  * @param pos The starting position within this string.
623  * @return the offset of a matching character or \c npos if not found.
624  */
625  size_type find_first_of( std::string const &s, size_type pos = 0 ) const;
626 
627  /**
628  * Searches this string for any one of the characters in \a s starting at the
629  * given position.
630  *
631  * @param s The set of characters to search for.
632  * @param pos The starting position within this string.
633  * @return the offset of a matching character or \c npos if not found.
634  */
635  size_type find_first_of( const_pointer s, size_type pos = 0 ) const;
636 
637  /**
638  * Searches this string for any one of the first \a s_n characters in \a s
639  * starting at the given position.
640  *
641  * @param s The set of characters to search for.
642  * @param pos The starting position within this string.
643  * @param s_n The number of characters of \a s to consider.
644  * @return the offset of a matching character or \c npos if not found.
645  */
646  size_type find_first_of( const_pointer s, size_type pos,
647  size_type s_n ) const;
648 
649  /**
650  * Searches this string for the given character starting at the given
651  * position.
652  *
653  * @param c The character to search for.
654  * @param pos The starting position within this string.
655  * @return the offset of \a c or \c npos if not found.
656  */
657  size_type find_first_of( value_type c, size_type pos = 0 ) const;
658 
659  /**
660  * Searches this string for any one of the characters not in \a s starting at
661  * the given position.
662  *
663  * @param s The set of characters not to search for.
664  * @param pos The starting position within this string.
665  * @return the offset of a non-matching character or \c npos if not found.
666  */
667  size_type find_first_not_of( String const &s, size_type pos = 0 ) const;
668 
669  /**
670  * Searches this string for any one of the characters not in \a s starting at
671  * the given position.
672  *
673  * @param s The set of characters not to search for.
674  * @param pos The starting position within this string.
675  * @return the offset of a non-matching character or \c npos if not found.
676  */
677  size_type find_first_not_of( std::string const &s, size_type pos = 0 ) const;
678 
679  /**
680  * Searches this string for any one of the characters not in \a s starting at
681  * the given position.
682  *
683  * @param s The set of characters not to search for.
684  * @param pos The starting position within this string.
685  * @return the offset of a non-matching character or \c npos if not found.
686  */
687  size_type find_first_not_of( const_pointer s, size_type pos = 0 ) const;
688 
689  /**
690  * Searches this string for any one of the first \a s_n characters not in \a
691  * s starting at the given position.
692  *
693  * @param s The set of characters not to search for.
694  * @param pos The starting position within this string.
695  * @param s_n The number of characters of \a s to consider.
696  * @return the offset of a non-matching character or \c npos if not found.
697  */
698  size_type find_first_not_of( const_pointer s, size_type pos,
699  size_type s_n ) const;
700 
701  /**
702  * Searches this string for any character except the given character starting
703  * at the given position.
704  *
705  * @param c The character not to search for.
706  * @param pos The starting position within this string.
707  * @return the offset of any character except \a c or \c npos if not found.
708  */
709  size_type find_first_not_of( value_type c, size_type pos = 0 ) const;
710 
711  /**
712  * Searches this string backwards for any one of the characters in \a s
713  * starting at the given position.
714  *
715  * @param s The set of characters to search for.
716  * @param pos The starting position within this string.
717  * @return the offset of a matching character or \c npos if not found.
718  */
719  size_type find_last_of( String const &s, size_type pos = npos ) const;
720 
721  /**
722  * Searches this string backwards for any one of the characters in \a s
723  * starting at the given position.
724  *
725  * @param s The set of characters to search for.
726  * @param pos The starting position within this string.
727  * @return the offset of a matching character or \c npos if not found.
728  */
729  size_type find_last_of( std::string const &s, size_type pos = npos ) const;
730 
731  /**
732  * Searches this string backwards for any one of the characters in \a s
733  * starting at the given position.
734  *
735  * @param s The set of characters to search for.
736  * @param pos The starting position within this string.
737  * @return the offset of a matching character or \c npos if not found.
738  */
739  size_type find_last_of( const_pointer s, size_type pos = npos ) const;
740 
741  /**
742  * Searches this string backwards for any one of the first \a s_n characters
743  * in \a s starting at the given position.
744  *
745  * @param s The set of characters to search for.
746  * @param pos The starting position within this string.
747  * @param s_n The number of characters of \a s to consider.
748  * @return the offset of a matching character or \c npos if not found.
749  */
750  size_type find_last_of( const_pointer s, size_type pos, size_type s_n ) const;
751 
752  /**
753  * Searches this string backwards for the given character starting at the
754  * given position.
755  *
756  * @param c The character to search for.
757  * @param pos The starting position within this string.
758  * @return the offset of \a c or \c npos if not found.
759  */
760  size_type find_last_of( value_type c, size_type pos = npos ) const;
761 
762  /**
763  * Searches this string backwards for any one of the characters not in \a s
764  * starting at the given position.
765  *
766  * @param s The set of characters to not search for.
767  * @param pos The starting position within this string.
768  * @return the offset of a matching character or \c npos if not found.
769  */
770  size_type find_last_not_of( String const &s, size_type pos = npos ) const;
771 
772  /**
773  * Searches this string backwards for any one of the characters not in \a s
774  * starting at the given position.
775  *
776  * @param s The set of characters to not search for.
777  * @param pos The starting position within this string.
778  * @return the offset of a matching character or \c npos if not found.
779  */
780  size_type find_last_not_of( std::string const &s, size_type pos = npos ) const;
781 
782  /**
783  * Searches this string backwards for any one of the characters not in \a s
784  * starting at the given position.
785  *
786  * @param s The set of characters to not search for.
787  * @param pos The starting position within this string.
788  * @return the offset of a matching character or \c npos if not found.
789  */
790  size_type find_last_not_of( const_pointer s, size_type pos = npos ) const;
791 
792  /**
793  * Searches this string backwards for any one of the first \a s_n characters
794  * not in \a s starting at the given position.
795  *
796  * @param s The set of characters to not search for.
797  * @param pos The starting position within this string.
798  * @param s_n The number of characters of \a s to consider.
799  * @return the offset of a matching character or \c npos if not found.
800  */
801  size_type find_last_not_of( const_pointer s, size_type pos,
802  size_type s_n ) const;
803 
804  /**
805  * Searches this string backwards for any character except the given
806  * character starting at the given position.
807  *
808  * @param c The character to search for.
809  * @param pos The starting position within this string.
810  * @return the offset of any character except \a c or \c npos if not found.
811  */
812  size_type find_last_not_of( value_type c, size_type pos = npos ) const;
813 
814  /**
815  * Searches this backwards string for the given string starting at the given
816  * position.
817  *
818  * @param s The string to search for.
819  * @param pos The starting position within this string.
820  * @return the offset of \a s or \c npos if not found.
821  */
822  size_type rfind( String const &s, size_type pos = npos ) const;
823 
824  /**
825  * Searches this backwards string for the given string starting at the given
826  * position.
827  *
828  * @param s The string to search for.
829  * @param pos The starting position within this string.
830  * @return the offset of \a s or \c npos if not found.
831  */
832  size_type rfind( std::string const &s, size_type pos = npos ) const;
833 
834  /**
835  * Searches this backwards string for the given string starting at the given
836  * position.
837  *
838  * @param s The string to search for.
839  * @param pos The starting position within this string.
840  * @return the offset of \a s or \c npos if not found.
841  */
842  size_type rfind( const_pointer s, size_type pos = npos ) const;
843 
844  /**
845  * Searches this string backwards for the given string starting at the given
846  * position.
847  *
848  * @param s The C string to search for.
849  * @param pos The starting position within this string.
850  * @param s_n The number of characters to compare.
851  * @return the offset of \a s or \c npos if not found.
852  */
853  size_type rfind( const_pointer s, size_type pos, size_type s_n ) const;
854 
855  /**
856  * Searches this string backwards for the given character staring at the
857  * given position.
858  *
859  * @param c The character to search for.
860  * @param pos The starting position within this string.
861  * @return the offset of \a c or \c npos if not found.
862  */
863  size_type rfind( value_type c, size_type pos = npos ) const;
864 
865  ////////// insert ///////////////////////////////////////////////////////////
866 
867  /**
868  * Inserts the given string into this string at the given position.
869  *
870  * @param pos The position within this string to insert at.
871  * @param s The string to insert.
872  * @return this string.
873  */
874  String& insert( size_type pos, String const &s );
875 
876  /**
877  * Inserts the given string into this string at the given position.
878  *
879  * @param pos The position within this string to insert at.
880  * @param s The string to insert.
881  * @return this string.
882  */
883  String& insert( size_type pos, std::string const &s );
884 
885  /**
886  * Inserts the given string into this string at the given position.
887  *
888  * @param pos The position within this string to insert at.
889  * @param s The null-terminated string to insert.
890  * @return this string.
891  */
892  String& insert( size_type pos, const_pointer s );
893 
894  /**
895  * Inserts a substring of the given string into this string at the given
896  * position.
897  *
898  * @param pos The position within this string to insert at.
899  * @param s The null-terminated C string to insert.
900  * @param s_pos The starting position within \a s.
901  * @param s_n The numer of characters of \a s to insert.
902  * @return this string.
903  */
904  String& insert( size_type pos, String const &s, size_type s_pos,
905  size_type s_n );
906 
907  /**
908  * Inserts a substring of the given string into this string at the given
909  * position.
910  *
911  * @param pos The position within this string to insert at.
912  * @param s The null-terminated C string to insert.
913  * @param s_pos The starting position within \a s.
914  * @param s_n The numer of characters of \a s to insert.
915  * @return this string.
916  */
917  String& insert( size_type pos, std::string const &s, size_type s_pos,
918  size_type s_n );
919 
920  /**
921  * Inserts a substring of the given string into this string at the given
922  * position.
923  *
924  * @param pos The position within this string to insert at.
925  * @param s The C string to insert.
926  * @param s_n The numer of characters of \a s to insert.
927  * @return this string.
928  */
929  String& insert( size_type pos, const_pointer s, size_type s_n );
930 
931  /**
932  * Inserts \a n copies of \a c into this string at the given position.
933  *
934  * @param pos The position within this string to insert at.
935  * @param n The number of copies of \a c to insert.
936  * @param c The character to insert.
937  * @return this string.
938  */
939  String& insert( size_type pos, size_type n, value_type c );
940 
941  /**
942  * Inserts the given character into this string at the given position.
943  *
944  * @param pos The iterator marking the position within this string to insert
945  * at.
946  * @param c The character to insert.
947  * @return Returns an iterator positioned at the newly inserted character.
948  */
949  iterator insert( iterator pos, value_type c );
950 
951  /**
952  * Inserts \a n copies of \a c into this string at the given position.
953  *
954  * @param pos The iterator marking the position within this string to insert
955  * at.
956  * @param n The number of copies of \a c to insert.
957  * @param c The character to insert.
958  */
959  void insert( iterator pos, size_type n, value_type c );
960 
961  ////////// replace //////////////////////////////////////////////////////////
962 
963  /**
964  * Replaces \a n characters of this string starting at the given position
965  * with the given string.
966  *
967  * @param pos The position within this string to replace at.
968  * @param n The number of characters to replace.
969  * @param s The replacement string.
970  * @return this string.
971  */
972  String& replace( size_type pos, size_type n, String const &s );
973 
974  /**
975  * Replaces \a n characters of this string starting at the given position
976  * with the given string.
977  *
978  * @param pos The position within this string to replace at.
979  * @param n The number of characters to replace.
980  * @param s The replacement string.
981  * @return this string.
982  */
983  String& replace( size_type pos, size_type n, std::string const &s );
984 
985  /**
986  * Replaces \a n characters of this string starting at the given position
987  * with the given string.
988  *
989  * @param pos The position within this string to replace at.
990  * @param n The number of characters to replace.
991  * @param s The null-terminated replacement C string.
992  * @return this string.
993  */
994  String& replace( size_type pos, size_type n, const_pointer s );
995 
996  /**
997  * Replaces \a n characters of this string starting at the given position
998  * with a substring of the given string.
999  *
1000  * @param pos The position within this string to replace at.
1001  * @param n The number of characters to replace.
1002  * @param s The replacement string.
1003  * @param s_pos The starting position is \a s.
1004  * @param s_n The number of characters of \a s to use.
1005  * @return this string.
1006  */
1007  String& replace( size_type pos, size_type n, String const &s,
1008  size_type s_pos, size_type s_n );
1009 
1010  /**
1011  * Replaces \a n characters of this string starting at the given position
1012  * with a substring of the given string.
1013  *
1014  * @param pos The position within this string to replace at.
1015  * @param n The number of characters to replace.
1016  * @param s The replacement string.
1017  * @param s_pos The starting position is \a s.
1018  * @param s_n The number of characters of \a s to use.
1019  * @return this string.
1020  */
1021  String& replace( size_type pos, size_type n, std::string const &s,
1022  size_type s_pos, size_type s_n );
1023 
1024  /**
1025  * Replaces \a n characters of this string starting at the given position
1026  * with a substring of the given string.
1027  *
1028  * @param pos The position within this string to replace at.
1029  * @param n The number of characters to replace.
1030  * @param s The replacement C string.
1031  * @param s_n The number of characters of \a s to use.
1032  * @return this string.
1033  */
1034  String& replace( size_type pos, size_type n, const_pointer s, size_type s_n );
1035 
1036  /**
1037  * Replaces \a n characters of this string starting at the given position
1038  * with \a c_n copies of \a c.
1039  *
1040  * @param pos The position within this string to replace at.
1041  * @param n The number of characters to replace.
1042  * @param c_n The number of copies of \c to replace with.
1043  * @param c The character to replace with.
1044  * @return this string.
1045  */
1046  String& replace( size_type pos, size_type n, size_type c_n, value_type c );
1047 
1048  /**
1049  * Replaces the range of characters [i,j) of this string with the given
1050  * string.
1051  *
1052  * @param i The iterator marking the first character of the range.
1053  * @param j The iterator marking one past the last character of the range.
1054  * @param s The replacement string.
1055  * @return this string.
1056  */
1057  String& replace( iterator i, iterator j, String const &s );
1058 
1059  /**
1060  * Replaces the range of characters [i,j) of this string with the given
1061  * string.
1062  *
1063  * @param i The iterator marking the first character of the range.
1064  * @param j The iterator marking one past the last character of the range.
1065  * @param s The replacement string.
1066  * @return this string.
1067  */
1068  String& replace( iterator i, iterator j, std::string const &s );
1069 
1070  /**
1071  * Replaces the range of characters [i,j) of this string with the given
1072  * string.
1073  *
1074  * @param i The iterator marking the first character of the range.
1075  * @param j The iterator marking one past the last character of the range.
1076  * @param s The null-terminated replacement C string.
1077  * @return this string.
1078  */
1079  String& replace( iterator i, iterator j, const_pointer s );
1080 
1081  /**
1082  * Replaces the range of characters [i,j) of this string with a substring of
1083  * the given string.
1084  *
1085  * @param i The iterator marking the first character of the range.
1086  * @param j The iterator marking one past the last character of the range.
1087  * @param s The replacement C string.
1088  * @param s_n The number of characters of \a s to use.
1089  * @return this string.
1090  */
1091  String& replace( iterator i, iterator j, const_pointer s, size_type s_n );
1092 
1093  /**
1094  * Replaces the range of characters [i,j) of this string with \a c_n copies
1095  * of \a c.
1096  *
1097  * @param i The iterator marking the first character of the range.
1098  * @param j The iterator marking one past the last character of the range.
1099  * @param n The number of copies of \c to replace with.
1100  * @param c The character to replace with.
1101  * @return Returns this string.
1102  */
1103  String& replace( iterator i, iterator j, size_type n, value_type c );
1104 
1105  /**
1106  * Replaces the range of characters [i,j) of this string with the range of
1107  * characters [si,sj).
1108  *
1109  * @param i The iterator marking the first character of the range.
1110  * @param j The iterator marking one past the last character of the range.
1111  * @param si The iterator marking the first character of the range.
1112  * @param sj The iterator marking one past the last character of the range.
1113  * @return this string.
1114  */
1115  String& replace( iterator i, iterator j, iterator si, iterator sj );
1116 
1117  ////////// iterators ////////////////////////////////////////////////////////
1118 
1119  /**
1120  * Returns a read/write iterator positioned at the first character of the
1121  * string.
1122  *
1123  * @return said iterator.
1124  */
1125  iterator begin();
1126 
1127  /**
1128  * Returns a read-only iterator positioned at the first character of the
1129  * string.
1130  *
1131  * @return said iterator.
1132  */
1133  const_iterator begin() const;
1134 
1135  /**
1136  * Returns a read/write iterator positioned at one past the last character of
1137  * the string.
1138  *
1139  * @return said iterator.
1140  */
1141  iterator end();
1142 
1143  /**
1144  * Returns a read-only iterator positioned at one past the last character of
1145  * the string.
1146  *
1147  * @return said iterator.
1148  */
1149  const_iterator end() const;
1150 
1151  /**
1152  * Returns a read/write reverse iterator positioned at the first character of
1153  * the reversed string.
1154  *
1155  * @return said iterator.
1156  */
1157  reverse_iterator rbegin();
1158 
1159  /**
1160  * Returns a read-only reverse iterator positioned at the first character of
1161  * the reversed string.
1162  *
1163  * @return said iterator.
1164  */
1165  const_reverse_iterator rbegin() const;
1166 
1167  /**
1168  * Returns a read/write reverse iterator positioned at one past the last
1169  * character of the reversed string.
1170  *
1171  * @return said iterator.
1172  */
1173  reverse_iterator rend();
1174 
1175  /**
1176  * Returns a read-only reverse iterator positioned at one past the last
1177  * character of the reversed string.
1178  *
1179  * @return said iterator.
1180  */
1181  const_reverse_iterator rend() const;
1182 
1183  ////////// miscellaneous ////////////////////////////////////////////////////
1184 
1185  /**
1186  * Copies a substring to a C string buffer.
1187  *
1188  * @param buf The buffer to copy into.
1189  * @param n The number of characters to copy.
1190  * It's the caller's responsibility to ensure that the size of \a buf <= \a
1191  * n.
1192  * @param pos The position of the first character to copy.
1193  * @return the number of characters actually copied.
1194  * @throw std::out_of_range if \a pos >= size().
1195  */
1196  size_type copy( pointer buf, size_type n, size_type pos = 0 ) const;
1197 
1198  /**
1199  * Gets a pointer to a null-terminated array of characters representing the
1200  * string's contents.
1201  *
1202  * @return said pointer.
1203  * @see data()
1204  */
1205  const_pointer c_str() const;
1206 
1207  /**
1208  * Gets a pointer to the raw character data comprising the string, not
1209  * necessarily null-terminated.
1210  *
1211  * @return said pointer.
1212  * @see c_str()
1213  */
1214  const_pointer data() const;
1215 
1216  /**
1217  * Attemts to pre-allocated enough memory to contain the given number of
1218  * bytes.
1219  *
1220  * @param n The number of bytes.
1221  */
1222  void reserve( size_type n );
1223 
1224  /**
1225  * Resizes the string to the given number of characters.
1226  * If the number < size(), the string will be truncated;
1227  * if the number > size(), the string will be extended
1228  * and the new elements will be set to \a c.
1229  *
1230  * @param n The number of characters.
1231  * @param c Characters to fill any new positions.
1232  */
1233  void resize( size_type n, value_type c = value_type() );
1234 
1235  /**
1236  * Gets a \c std::string equivalent of this string.
1237  * (There intentionally is no <code>operator std::string() const</code> since
1238  * its convenient use would mask the expense of creating a new \c
1239  * std::string.)
1240  * This function is an extension to the std::string API.
1241  *
1242  * @return said \c std::string.
1243  */
1244  std::string str() const;
1245 
1246  /**
1247  * Creates a new string that is a substring of this string.
1248  *
1249  * @param pos The position in this string for first character of the new
1250  * string.
1251  * @param n The number of characters to extract.
1252  * @return the new string.
1253  * @throw std::out_of_range if \a pos >= size().
1254  */
1255  String substr( size_type pos = 0, size_type n = npos ) const;
1256 
1257  /**
1258  * Swaps the contents of this string with another.
1259  * This is an O(1) operation.
1260  *
1261  * @param s The string to swap with.
1262  */
1263  void swap( String &s );
1264 
1265  /////////////////////////////////////////////////////////////////////////////
1266 
1267 private:
1268  //
1269  // We need to use a struct in order to assert that its size >= the size of
1270  // the internal string class.
1271  //
1272  struct string_storage_type {
1273  //
1274  // We need to do this union weirdness so as not to break strict-aliasing
1275  // rules.
1276  //
1277  union {
1278  void *rep_;
1279  char storage_[1];
1280  };
1281 #ifdef ZORBA_DEBUG_STRING
1282  char *debug_str_;
1283 #endif /* ZORBA_DEBUG_STRING */
1284  };
1285 
1286  string_storage_type string_storage_;
1287 
1288  // Using a struct prevents void* ambiguity with char*.
1289  struct zstring_ptr { void const *ptr; };
1290 
1291  String( zstring_ptr );
1292  String& operator=( zstring_ptr );
1293 
1294  static void size_check();
1295 
1296  friend ZORBA_DLL_PUBLIC bool operator==( String const&, String const& );
1297  friend ZORBA_DLL_PUBLIC bool operator==( String const&, std::string const& );
1298  friend ZORBA_DLL_PUBLIC bool operator==( String const&, const_pointer );
1299 
1300  friend ZORBA_DLL_PUBLIC bool operator<( String const&, String const& );
1301  friend ZORBA_DLL_PUBLIC bool operator<( String const&, std::string const& );
1302  friend ZORBA_DLL_PUBLIC bool operator<( String const&, const_pointer );
1303  friend ZORBA_DLL_PUBLIC bool operator<( std::string const&, String const& );
1304  friend ZORBA_DLL_PUBLIC bool operator<( const_pointer, String const& );
1305 
1306  friend ZORBA_DLL_PUBLIC bool operator<=( String const&, String const& );
1307  friend ZORBA_DLL_PUBLIC bool operator<=( String const&, std::string const& );
1308  friend ZORBA_DLL_PUBLIC bool operator<=( String const&, const_pointer );
1309  friend ZORBA_DLL_PUBLIC bool operator<=( std::string const&, String const& );
1310  friend ZORBA_DLL_PUBLIC bool operator<=( const_pointer, String const& );
1311 
1312  friend ZORBA_DLL_PUBLIC String operator+( String const&, String const& );
1313  friend ZORBA_DLL_PUBLIC String operator+( String const&, std::string const& );
1314  friend ZORBA_DLL_PUBLIC String operator+( String const&, const_pointer );
1315  friend ZORBA_DLL_PUBLIC String operator+( std::string const&, String const& );
1316  friend ZORBA_DLL_PUBLIC String operator+( const_pointer, String const& );
1317 
1318  friend ZORBA_DLL_PUBLIC
1319  std::ostream& operator<<( std::ostream&, String const& );
1320 
1321  friend class Unmarshaller;
1322 };
1323 
1324 ////////// relational operators ///////////////////////////////////////////////
1325 
1326 ZORBA_DLL_PUBLIC bool operator==( String const &s1, String const &s2 );
1327 ZORBA_DLL_PUBLIC bool operator==( String const &s1, std::string const &s2 );
1328 ZORBA_DLL_PUBLIC bool operator==( String const &s1, String::const_pointer s2 );
1329 
1330 ZORBA_DLL_PUBLIC bool operator<( String const &s1, String const &s2 );
1331 ZORBA_DLL_PUBLIC bool operator<( String const &s1, std::string const &s2 );
1332 ZORBA_DLL_PUBLIC bool operator<( String const &s1, String::const_pointer s2 );
1333 ZORBA_DLL_PUBLIC bool operator<( std::string const &s1, String const &s2 );
1334 ZORBA_DLL_PUBLIC bool operator<( String::const_pointer s1, String const &s2 );
1335 
1336 ZORBA_DLL_PUBLIC bool operator<=( String const &s1, String const &s2 );
1337 ZORBA_DLL_PUBLIC bool operator<=( String const &s1, std::string const &s2 );
1338 ZORBA_DLL_PUBLIC bool operator<=( String const &s1, String::const_pointer s2 );
1339 ZORBA_DLL_PUBLIC bool operator<=( std::string const &s1, String const &s2 );
1340 ZORBA_DLL_PUBLIC bool operator<=( String::const_pointer s1, String const &s2 );
1341 
1342 inline bool operator==( std::string const &s1, String const &s2 ) {
1343  return s2 == s1;
1344 }
1345 
1346 inline bool operator==( String::const_pointer s1, String const &s2 ) {
1347  return s2 == s1;
1348 }
1349 
1350 inline bool operator!=( String const &s1, String const &s2 ) {
1351  return !(s1 == s2);
1352 }
1353 
1354 inline bool operator!=( String const &s1, std::string const &s2 ) {
1355  return !(s1 == s2);
1356 }
1357 
1358 inline bool operator!=( String const &s1, String::const_pointer s2 ) {
1359  return !(s1 == s2);
1360 }
1361 
1362 inline bool operator!=( std::string const &s1, String const &s2 ) {
1363  return !(s1 == s2);
1364 }
1365 
1366 inline bool operator!=( String::const_pointer s1, String const &s2 ) {
1367  return !(s1 == s2);
1368 }
1369 
1370 inline bool operator>=( String const &s1, String const &s2 ) {
1371  return !(s1 < s2);
1372 }
1373 
1374 inline bool operator>=( String const &s1, std::string const &s2 ) {
1375  return !(s1 < s2);
1376 }
1377 
1378 inline bool operator>=( String const &s1, String::const_pointer s2 ) {
1379  return !(s1 < s2);
1380 }
1381 
1382 inline bool operator>=( std::string const &s1, String const &s2 ) {
1383  return !(s1 < s2);
1384 }
1385 
1386 inline bool operator>=( String::const_pointer s1, String const &s2 ) {
1387  return !(s1 < s2);
1388 }
1389 
1390 inline bool operator>( String const &s1, String const &s2 ) {
1391  return !(s1 <= s2);
1392 }
1393 
1394 inline bool operator>( String const &s1, std::string const &s2 ) {
1395  return !(s1 <= s2);
1396 }
1397 
1398 inline bool operator>( String const &s1, String::const_pointer s2 ) {
1399  return !(s1 <= s2);
1400 }
1401 
1402 inline bool operator>( std::string const &s1, String const &s2 ) {
1403  return !(s1 <= s2);
1404 }
1405 
1406 inline bool operator>( String::const_pointer s1, String const &s2 ) {
1407  return !(s1 <= s2);
1408 }
1409 
1410 ////////// concatenation //////////////////////////////////////////////////////
1411 
1412 ZORBA_DLL_PUBLIC String operator+( String const &s1, String const &s2 );
1413 ZORBA_DLL_PUBLIC String operator+( String const &s1, std::string const &s2 );
1414 ZORBA_DLL_PUBLIC String operator+( String const &s1, String::const_pointer s2 );
1415 ZORBA_DLL_PUBLIC String operator+( std::string const &s1, String const &s2 );
1416 ZORBA_DLL_PUBLIC String operator+( String::const_pointer s1, String const &s2 );
1417 
1418 ////////// ostream insertion //////////////////////////////////////////////////
1419 
1420 ZORBA_DLL_PUBLIC std::ostream& operator<<( std::ostream &o, String const &s );
1421 
1422 ///////////////////////////////////////////////////////////////////////////////
1423 
1424 } // namespace zorba
1425 
1426 #endif /* ZORBA_STRING_API_H */
1427 /* vim:set et sw=2 ts=2: */
blog comments powered by Disqus