Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is an old version of boost. Click here for the latest version's documentation home page.
PrevUpHomeNext

Class template basic_string

boost::interprocess::basic_string

Synopsis

template<typename CharT, typename Traits, typename A> 
class basic_string {
public:
  // types
  typedef A allocator_type;
  typedef allocator_type                          stored_allocator_type;   // The stored allocator type. 
  typedef CharT                                   value_type;              // The type of object, CharT, stored in the string. 
  typedef Traits                                  traits_type;             // The second template parameter Traits. 
  typedef A::pointer                              pointer;                 // Pointer to CharT. 
  typedef A::const_pointer                        const_pointer;           // Const pointer to CharT. 
  typedef A::reference                            reference;               // Reference to CharT. 
  typedef A::const_reference                      const_reference;         // Const reference to CharT. 
  typedef A::size_type                            size_type;               // An unsigned integral type. 
  typedef A::difference_type                      difference_type;         // A signed integral type. 
  typedef pointer                                 iterator;                // Iterator used to iterate through a string. It's a Random Access Iterator. 
  typedef const_pointer                           const_iterator;          // Const iterator used to iterate through a string. It's a Random Access Iterator. 
  typedef std::reverse_iterator< iterator >       reverse_iterator;        // Iterator used to iterate backwards through a string. 
  typedef std::reverse_iterator< const_iterator > const_reverse_iterator;  // Const iterator used to iterate backwards through a string. 

  // construct/copy/destruct
  basic_string(reserve_t, std::size_t, 
               const allocator_type & = allocator_type());
  basic_string(const allocator_type & = allocator_type());
  basic_string(const basic_string &);
  basic_string(unspecified);
  basic_string(const basic_string &, size_type, size_type = npos, 
               const allocator_type & = allocator_type());
  basic_string(const CharT *, size_type, 
               const allocator_type & = allocator_type());
  basic_string(const CharT *, const allocator_type & = allocator_type());
  basic_string(size_type, CharT, const allocator_type & = allocator_type());
  template<typename InputIterator> 
    basic_string(InputIterator, InputIterator, 
                 const allocator_type & = allocator_type());
  basic_string& operator=(const basic_string &);
  basic_string& operator=(unspecified);
  basic_string& operator=(const CharT *);
  basic_string& operator=(CharT);
  ~basic_string();

  // public member functions
  iterator begin() ;
  const_iterator begin() const;
  iterator end() ;
  const_iterator end() const;
  reverse_iterator rbegin() ;
  const_reverse_iterator rbegin() const;
  reverse_iterator rend() ;
  const_reverse_iterator rend() const;
  allocator_type get_allocator() const;
  size_type size() const;
  size_type length() const;
  size_type max_size() const;
  void resize(size_type, CharT) ;
  void resize(size_type) ;
  void reserve(size_type) ;
  size_type capacity() const;
  void clear() ;
  bool empty() const;
  reference operator[](size_type) ;
  const_reference operator[](size_type) const;
  reference at(size_type) ;
  const_reference at(size_type) const;
  basic_string & operator+=(const basic_string &) ;
  basic_string & operator+=(const CharT *) ;
  basic_string & operator+=(CharT) ;
  basic_string & append(const basic_string &) ;
  basic_string & append(const basic_string &, size_type, size_type) ;
  basic_string & append(const CharT *, size_type) ;
  basic_string & append(const CharT *) ;
  basic_string & append(size_type, CharT) ;
  template<typename InputIter> basic_string & append(InputIter, InputIter) ;
  void push_back(CharT) ;
  void pop_back() ;
  basic_string & assign(const basic_string &) ;
  basic_string & assign(unspecified) ;
  basic_string & assign(const basic_string &, size_type, size_type) ;
  basic_string & assign(const CharT *, size_type) ;
  basic_string & assign(const CharT *) ;
  basic_string & assign(size_type, CharT) ;
  template<typename InputIter> basic_string & assign(InputIter, InputIter) ;
  basic_string & assign(const CharT *, const CharT *) ;
  basic_string & insert(size_type, const basic_string &) ;
  basic_string & 
  insert(size_type, const basic_string &, size_type, size_type) ;
  basic_string & insert(size_type, const CharT *, size_type) ;
  basic_string & insert(size_type, const CharT *) ;
  basic_string & insert(size_type, size_type, CharT) ;
  iterator insert(iterator, CharT) ;
  void insert(iterator, std::size_t, CharT) ;
  template<typename InputIter> void insert(iterator, InputIter, InputIter) ;
  basic_string & erase(size_type = 0, size_type = npos) ;
  iterator erase(iterator) ;
  iterator erase(iterator, iterator) ;
  basic_string & replace(size_type, size_type, const basic_string &) ;
  basic_string & 
  replace(size_type, size_type, const basic_string &, size_type, size_type) ;
  basic_string & replace(size_type, size_type, const CharT *, size_type) ;
  basic_string & replace(size_type, size_type, const CharT *) ;
  basic_string & replace(size_type, size_type, size_type, CharT) ;
  basic_string & replace(iterator, iterator, const basic_string &) ;
  basic_string & replace(iterator, iterator, const CharT *, size_type) ;
  basic_string & replace(iterator, iterator, const CharT *) ;
  basic_string & replace(iterator, iterator, size_type, CharT) ;
  template<typename InputIter> 
    basic_string & replace(iterator, iterator, InputIter, InputIter) ;
  size_type copy(CharT *, size_type, size_type = 0) const;
  void swap(basic_string &) ;
  void swap(unspecified) ;
  const CharT * c_str() const;
  const CharT * data() const;
  size_type find(const basic_string &, size_type = 0) const;
  size_type find(const CharT *, size_type = 0) const;
  size_type find(const CharT *, size_type, size_type) const;
  size_type find(CharT, size_type = 0) const;
  size_type rfind(const basic_string &, size_type = npos) const;
  size_type rfind(const CharT *, size_type = npos) const;
  size_type rfind(const CharT *, size_type, size_type) const;
  size_type rfind(CharT, size_type = npos) const;
  size_type find_first_of(const basic_string &, size_type = 0) const;
  size_type find_first_of(const CharT *, size_type = 0) const;
  size_type find_first_of(const CharT *, size_type, size_type) const;
  size_type find_first_of(CharT, size_type = 0) const;
  size_type find_last_of(const basic_string &, size_type = npos) const;
  size_type find_last_of(const CharT *, size_type = npos) const;
  size_type find_last_of(const CharT *, size_type, size_type) const;
  size_type find_last_of(CharT, size_type = npos) const;
  size_type find_first_not_of(const basic_string &, size_type = 0) const;
  size_type find_first_not_of(const CharT *, size_type = 0) const;
  size_type find_first_not_of(const CharT *, size_type, size_type) const;
  size_type find_first_not_of(CharT, size_type = 0) const;
  size_type find_last_not_of(const basic_string &, size_type = npos) const;
  size_type find_last_not_of(const CharT *, size_type = npos) const;
  size_type find_last_not_of(const CharT *, size_type, size_type) const;
  size_type find_last_not_of(CharT, size_type = npos) const;
  basic_string substr(size_type = 0, size_type = npos) const;
  int compare(const basic_string &) const;
  int compare(size_type, size_type, const basic_string &) const;
  int compare(size_type, size_type, const basic_string &, size_type, 
              size_type) const;
  int compare(const CharT *) const;
  int compare(size_type, size_type, const CharT *, size_type = npos) const;
  static const size_type npos;
};

Description

The basic_string class represents a Sequence of characters. It contains all the usual operations of a Sequence, and, additionally, it contains standard string operations such as search and concatenation.

The basic_string class is parameterized by character type, and by that type's Character Traits.

This class has performance characteristics very much like vector<>, meaning, for example, that it does not perform reference-count or copy-on-write, and that concatenation of two strings is an O(N) operation.

Some of basic_string's member functions use an unusual method of specifying positions and ranges. In addition to the conventional method using iterators, many of basic_string's member functions use a single value pos of type size_type to represent a position (in which case the position is begin() + pos, and many of basic_string's member functions use two values, pos and n, to represent a range. In that case pos is the beginning of the range and n is its size. That is, the range is [begin() + pos, begin() + pos + n).

Note that the C++ standard does not specify the complexity of basic_string operations. In this implementation, basic_string has performance characteristics very similar to those of vector: access to a single character is O(1), while copy and concatenation are O(N).

In this implementation, begin(), end(), rbegin(), rend(), operator[], c_str(), and data() do not invalidate iterators. In this implementation, iterators are only invalidated by member functions that explicitly change the string's contents.

basic_string public types

  1. typedef A allocator_type;

    The allocator type

basic_string public construct/copy/destruct

  1. basic_string(reserve_t, std::size_t n, 
                 const allocator_type & a = allocator_type());
  2. basic_string(const allocator_type & a = allocator_type());

    Effects: Constructs a basic_string taking the allocator as parameter.

    Throws: If allocator_type's copy constructor throws.

  3. basic_string(const basic_string & s);

    Effects: Copy constructs a basic_string.

    Postcondition: x == *this.

    Throws: If allocator_type's default constructor or copy constructor throws.

  4. basic_string(unspecified s);

    Effects: Move constructor. Moves mx's resources to *this.

    Throws: If allocator_type's copy constructor throws.

    Complexity: Constant.

  5. basic_string(const basic_string & s, size_type pos, size_type n = npos, 
                 const allocator_type & a = allocator_type());

    Effects: Constructs a basic_string taking the allocator as parameter, and is initialized by a specific number of characters of the s string.

  6. basic_string(const CharT * s, size_type n, 
                 const allocator_type & a = allocator_type());

    Effects: Constructs a basic_string taking the allocator as parameter, and is initialized by a specific number of characters of the s c-string.

  7. basic_string(const CharT * s, const allocator_type & a = allocator_type());

    Effects: Constructs a basic_string taking the allocator as parameter, and is initialized by the null-terminated s c-string.

  8. basic_string(size_type n, CharT c, 
                 const allocator_type & a = allocator_type());

    Effects: Constructs a basic_string taking the allocator as parameter, and is initialized by n copies of c.

  9. template<typename InputIterator> 
      basic_string(InputIterator f, InputIterator l, 
                   const allocator_type & a = allocator_type());

    Effects: Constructs a basic_string taking the allocator as parameter, and a range of iterators.

  10. basic_string& operator=(const basic_string & s);

    Effects: Copy constructs a string.

    Postcondition: x == *this.

    Complexity: Linear to the elements x contains.

  11. basic_string& operator=(unspecified ms);

    Effects: Move constructor. Moves mx's resources to *this.

    Throws: If allocator_type's copy constructor throws.

    Complexity: Constant.

  12. basic_string& operator=(const CharT * s);
    Effects
  13. basic_string& operator=(CharT c);
    Effects
  14. ~basic_string();

    Effects: Destroys the basic_string. All used memory is deallocated.

    Throws: Nothing.

    Complexity: Constant.

basic_string public member functions

  1. iterator begin() ;

    Effects: Returns an iterator to the first element contained in the vector.

    Throws: Nothing.

    Complexity: Constant.

  2. const_iterator begin() const;

    Effects: Returns a const_iterator to the first element contained in the vector.

    Throws: Nothing.

    Complexity: Constant.

  3. iterator end() ;

    Effects: Returns an iterator to the end of the vector.

    Throws: Nothing.

    Complexity: Constant.

  4. const_iterator end() const;

    Effects: Returns a const_iterator to the end of the vector.

    Throws: Nothing.

    Complexity: Constant.

  5. reverse_iterator rbegin() ;

    Effects: Returns a reverse_iterator pointing to the beginning of the reversed vector.

    Throws: Nothing.

    Complexity: Constant.

  6. const_reverse_iterator rbegin() const;

    Effects: Returns a const_reverse_iterator pointing to the beginning of the reversed vector.

    Throws: Nothing.

    Complexity: Constant.

  7. reverse_iterator rend() ;

    Effects: Returns a reverse_iterator pointing to the end of the reversed vector.

    Throws: Nothing.

    Complexity: Constant.

  8. const_reverse_iterator rend() const;

    Effects: Returns a const_reverse_iterator pointing to the end of the reversed vector.

    Throws: Nothing.

    Complexity: Constant.

  9. allocator_type get_allocator() const;

    Effects: Returns a copy of the internal allocator.

    Throws: If allocator's copy constructor throws.

    Complexity: Constant.

  10. size_type size() const;

    Effects: Returns the number of the elements contained in the vector.

    Throws: Nothing.

    Complexity: Constant.

  11. size_type length() const;

    Effects: Returns the number of the elements contained in the vector.

    Throws: Nothing.

    Complexity: Constant.

  12. size_type max_size() const;

    Effects: Returns the largest possible size of the vector.

    Throws: Nothing.

    Complexity: Constant.

  13. void resize(size_type n, CharT c) ;

    Effects: Inserts or erases elements at the end such that the size becomes n. New elements are copy constructed from x.

    Throws: If memory allocation throws, or T's copy constructor throws.

    Complexity: Linear to the difference between size() and new_size.

  14. void resize(size_type n) ;

    Effects: Inserts or erases elements at the end such that the size becomes n. New elements are default constructed.

    Throws: If memory allocation throws, or T's copy constructor throws.

    Complexity: Linear to the difference between size() and new_size.

  15. void reserve(size_type res_arg) ;

    Effects: If n is less than or equal to capacity(), this call has no effect. Otherwise, it is a request for allocation of additional memory. If the request is successful, then capacity() is greater than or equal to n; otherwise, capacity() is unchanged. In either case, size() is unchanged.

    Throws: If memory allocation allocation throws or T's copy constructor throws.

  16. size_type capacity() const;

    Effects: Number of elements for which memory has been allocated. capacity() is always greater than or equal to size().

    Throws: Nothing.

    Complexity: Constant.

  17. void clear() ;

    Effects: Erases all the elements of the vector.

    Throws: Nothing.

    Complexity: Linear to the number of elements in the vector.

  18. bool empty() const;

    Effects: Returns true if the vector contains no elements.

    Throws: Nothing.

    Complexity: Constant.

  19. reference operator[](size_type n) ;

    Requires: size() < n.

    Effects: Returns a reference to the nth element from the beginning of the container.

    Throws: Nothing.

    Complexity: Constant.

  20. const_reference operator[](size_type n) const;

    Requires: size() < n.

    Effects: Returns a const reference to the nth element from the beginning of the container.

    Throws: Nothing.

    Complexity: Constant.

  21. reference at(size_type n) ;

    Requires: size() < n.

    Effects: Returns a reference to the nth element from the beginning of the container.

    Throws: std::range_error if n >= size()

    Complexity: Constant.

  22. const_reference at(size_type n) const;

    Requires: size() < n.

    Effects: Returns a const reference to the nth element from the beginning of the container.

    Throws: std::range_error if n >= size()

    Complexity: Constant.

  23. basic_string & operator+=(const basic_string & s) ;
    Effects
  24. basic_string & operator+=(const CharT * s) ;
    Effects
  25. basic_string & operator+=(CharT c) ;
    Effects
  26. basic_string & append(const basic_string & s) ;
    Effects
  27. basic_string & append(const basic_string & s, size_type pos, size_type n) ;
    Effects
  28. basic_string & append(const CharT * s, size_type n) ;
    Effects
  29. basic_string & append(const CharT * s) ;
    Effects
  30. basic_string & append(size_type n, CharT c) ;
    Effects
  31. template<typename InputIter> 
      basic_string & append(InputIter first, InputIter last) ;
    Effects
  32. void push_back(CharT c) ;
    Effects
  33. void pop_back() ;
    Effects
  34. basic_string & assign(const basic_string & s) ;
    Effects
  35. basic_string & assign(unspecified ms) ;
    Effects
  36. basic_string & assign(const basic_string & s, size_type pos, size_type n) ;
    Effects
  37. basic_string & assign(const CharT * s, size_type n) ;
    Effects
  38. basic_string & assign(const CharT * s) ;
    Effects
  39. basic_string & assign(size_type n, CharT c) ;
    Effects
  40. template<typename InputIter> 
      basic_string & assign(InputIter first, InputIter last) ;
    Effects
  41. basic_string & assign(const CharT * f, const CharT * l) ;
    Effects
  42. basic_string & insert(size_type pos, const basic_string & s) ;
    Effects
  43. basic_string & 
    insert(size_type pos, const basic_string & s, size_type beg, size_type n) ;
    Effects
  44. basic_string & insert(size_type pos, const CharT * s, size_type n) ;
    Effects
  45. basic_string & insert(size_type pos, const CharT * s) ;
    Effects
  46. basic_string & insert(size_type pos, size_type n, CharT c) ;
    Effects
  47. iterator insert(iterator position, CharT c) ;
    Effects
  48. void insert(iterator position, std::size_t n, CharT c) ;
    Effects
  49. template<typename InputIter> 
      void insert(iterator p, InputIter first, InputIter last) ;
    Effects
  50. basic_string & erase(size_type pos = 0, size_type n = npos) ;
    Effects
  51. iterator erase(iterator position) ;
    Effects
  52. iterator erase(iterator first, iterator last) ;
    Effects
  53. basic_string & replace(size_type pos, size_type n, const basic_string & s) ;
    Effects
  54. basic_string & 
    replace(size_type pos1, size_type n1, const basic_string & s, size_type pos2, 
            size_type n2) ;
    Effects
  55. basic_string & 
    replace(size_type pos, size_type n1, const CharT * s, size_type n2) ;
    Effects
  56. basic_string & replace(size_type pos, size_type n1, const CharT * s) ;
    Effects
  57. basic_string & replace(size_type pos, size_type n1, size_type n2, CharT c) ;
    Effects
  58. basic_string & replace(iterator first, iterator last, const basic_string & s) ;
    Effects
  59. basic_string & 
    replace(iterator first, iterator last, const CharT * s, size_type n) ;
    Effects
  60. basic_string & replace(iterator first, iterator last, const CharT * s) ;
    Effects
  61. basic_string & replace(iterator first, iterator last, size_type n, CharT c) ;
    Effects
  62. template<typename InputIter> 
      basic_string & 
      replace(iterator first, iterator last, InputIter f, InputIter l) ;
    Effects
  63. size_type copy(CharT * s, size_type n, size_type pos = 0) const;
    Effects
  64. void swap(basic_string & s) ;
    Effects
  65. void swap(unspecified ms) ;
    Effects
  66. const CharT * c_str() const;

    Returns: Returns a pointer to a null-terminated array of characters representing the string's contents. For any string s it is guaranteed that the first s.size() characters in the array pointed to by s.c_str() are equal to the character in s, and that s.c_str()[s.size()] is a null character. Note, however, that it not necessarily the first null character. Characters within a string are permitted to be null.

  67. const CharT * data() const;

    Returns: Returns a pointer to an array of characters, not necessarily null-terminated, representing the string's contents. data() is permitted, but not required, to be identical to c_str(). The first size() characters of that array are guaranteed to be identical to the characters in *this. The return value of data() is never a null pointer, even if size() is zero.

  68. size_type find(const basic_string & s, size_type pos = 0) const;

    Effects: Searches for s as a substring of *this, beginning at character pos of *this.

  69. size_type find(const CharT * s, size_type pos = 0) const;

    Effects: Searches for a null-terminated character array as a substring of *this, beginning at character pos of *this.

  70. size_type find(const CharT * s, size_type pos, size_type n) const;

    Effects: Searches for the first n characters of s as a substring of *this, beginning at character pos of *this.

  71. size_type find(CharT c, size_type pos = 0) const;

    Effects: Searches for the character c, beginning at character position pos.

  72. size_type rfind(const basic_string & s, size_type pos = npos) const;

    Effects: Searches backward for s as a substring of *this, beginning at character position min(pos, size())

  73. size_type rfind(const CharT * s, size_type pos = npos) const;

    Effects: Searches backward for a null-terminated character array as a substring of *this, beginning at character min(pos, size())

  74. size_type rfind(const CharT * s, size_type pos, size_type n) const;

    Effects: Searches backward for the first n characters of s as a substring of *this, beginning at character position min(pos, size()).

  75. size_type rfind(CharT c, size_type pos = npos) const;

    Effects: Searches backward for a null-terminated character array as a substring of *this, beginning at character min(pos, size()).

  76. size_type find_first_of(const basic_string & s, size_type pos = 0) const;

    Effects: Searches within *this, beginning at pos, for the first character that is equal to any character within s.

  77. size_type find_first_of(const CharT * s, size_type pos = 0) const;

    Effects: Searches within *this, beginning at pos, for the first character that is equal to any character within s.

  78. size_type find_first_of(const CharT * s, size_type pos, size_type n) const;

    Effects: Searches within *this, beginning at pos, for the first character that is equal to any character within the first n characters of s.

  79. size_type find_first_of(CharT c, size_type pos = 0) const;

    Effects: Searches within *this, beginning at pos, for the first character that is equal to c.

  80. size_type find_last_of(const basic_string & s, size_type pos = npos) const;

    Effects: Searches backward within *this, beginning at min(pos, size()), for the first character that is equal to any character within s.

  81. size_type find_last_of(const CharT * s, size_type pos = npos) const;

    Effects: Searches backward *this, beginning at min(pos, size()), for the first character that is equal to any character within s.

  82. size_type find_last_of(const CharT * s, size_type pos, size_type n) const;

    Effects: Searches backward within *this, beginning at min(pos, size()), for the first character that is equal to any character within the first n characters of s.

  83. size_type find_last_of(CharT c, size_type pos = npos) const;

    Effects: Searches backward *this, beginning at min(pos, size()), for the first character that is equal to c.

  84. size_type find_first_not_of(const basic_string & s, size_type pos = 0) const;

    Effects: Searches within *this, beginning at pos, for the first character that is not equal to any character within s.

  85. size_type find_first_not_of(const CharT * s, size_type pos = 0) const;

    Effects: Searches within *this, beginning at pos, for the first character that is not equal to any character within s.

  86. size_type find_first_not_of(const CharT * s, size_type pos, size_type n) const;

    Effects: Searches within *this, beginning at pos, for the first character that is not equal to any character within the first n characters of s.

  87. size_type find_first_not_of(CharT c, size_type pos = 0) const;

    Effects: Searches within *this, beginning at pos, for the first character that is not equal to c.

  88. size_type find_last_not_of(const basic_string & s, size_type pos = npos) const;

    Effects: Searches backward within *this, beginning at min(pos, size()), for the first character that is not equal to any character within s.

  89. size_type find_last_not_of(const CharT * s, size_type pos = npos) const;

    Effects: Searches backward *this, beginning at min(pos, size()), for the first character that is not equal to any character within s.

  90. size_type find_last_not_of(const CharT * s, size_type pos, size_type n) const;

    Effects: Searches backward within *this, beginning at min(pos, size()), for the first character that is not equal to any character within the first n characters of s.

  91. size_type find_last_not_of(CharT c, size_type pos = npos) const;

    Effects: Searches backward *this, beginning at min(pos, size()), for the first character that is not equal to c.

  92. basic_string substr(size_type pos = 0, size_type n = npos) const;
    Effects
  93. int compare(const basic_string & s) const;
    Effects
  94. int compare(size_type pos1, size_type n1, const basic_string & s) const;

    Effects: Three-way lexicographical comparison of s and a substring of *this.

  95. int compare(size_type pos1, size_type n1, const basic_string & s, 
                size_type pos2, size_type n2) const;

    Effects: Three-way lexicographical comparison of a substring of s and a substring of *this.

  96. int compare(const CharT * s) const;
    Effects
  97. int compare(size_type pos1, size_type n1, const CharT * s, 
                size_type n2 = npos) const;

    Effects: Three-way lexicographical comparison of the first min(len, traits::length(s) characters of s and a substring of *this.


PrevUpHomeNext