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. 

  struct reserve_t {
  };

  // 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

typedef A allocator_type;

The allocator type

`basic_string` public construct/copy/destruct

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

```
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.
```
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.
```
basic_string(unspecified s);
```
Effects: Move constructor. Moves mx's resources to *this.

Throws: If allocator_type's copy constructor throws.

Complexity: Constant.

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.

```
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.
```
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.

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.

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.

```
basic_string& operator=(const basic_string & s);
```
Effects: Copy constructs a string.

Postcondition: x == *this.

Complexity: Linear to the elements x contains.
```
basic_string& operator=(unspecified ms);
```
Effects: Move constructor. Moves mx's resources to *this.

Throws: If allocator_type's copy constructor throws.

Complexity: Constant.

basic_string& operator=(const CharT * s);

Effects

```
basic_string& operator=(CharT c);
```
Effects
```
~basic_string();
```
Effects: Destroys the basic_string. All used memory is deallocated.

Throws: Nothing.

Complexity: Constant.

`basic_string` public member functions

```
iterator begin() ;
```
Effects: Returns an iterator to the first element contained in the vector.

Throws: Nothing.

Complexity: Constant.
```
const_iterator begin() const;
```
Effects: Returns a const_iterator to the first element contained in the vector.

Throws: Nothing.

Complexity: Constant.
```
iterator end() ;
```
Effects: Returns an iterator to the end of the vector.

Throws: Nothing.

Complexity: Constant.
```
const_iterator end() const;
```
Effects: Returns a const_iterator to the end of the vector.

Throws: Nothing.

Complexity: Constant.
```
reverse_iterator rbegin() ;
```
Effects: Returns a reverse_iterator pointing to the beginning of the reversed vector.

Throws: Nothing.

Complexity: Constant.
```
const_reverse_iterator rbegin() const;
```
Effects: Returns a const_reverse_iterator pointing to the beginning of the reversed vector.

Throws: Nothing.

Complexity: Constant.
```
reverse_iterator rend() ;
```
Effects: Returns a reverse_iterator pointing to the end of the reversed vector.

Throws: Nothing.

Complexity: Constant.
```
const_reverse_iterator rend() const;
```
Effects: Returns a const_reverse_iterator pointing to the end of the reversed vector.

Throws: Nothing.

Complexity: Constant.
```
allocator_type get_allocator() const;
```
Effects: Returns a copy of the internal allocator.

Throws: If allocator's copy constructor throws.

Complexity: Constant.
```
size_type size() const;
```
Effects: Returns the number of the elements contained in the vector.

Throws: Nothing.

Complexity: Constant.
```
size_type length() const;
```
Effects: Returns the number of the elements contained in the vector.

Throws: Nothing.

Complexity: Constant.
```
size_type max_size() const;
```
Effects: Returns the largest possible size of the vector.

Throws: Nothing.

Complexity: Constant.
```
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.
```
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.
```
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.
```
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.
```
void clear() ;
```
Effects: Erases all the elements of the vector.

Throws: Nothing.

Complexity: Linear to the number of elements in the vector.
```
bool empty() const;
```
Effects: Returns true if the vector contains no elements.

Throws: Nothing.

Complexity: Constant.
```
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.
```
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.
```
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.
```
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.

basic_string & operator+=(const basic_string & s) ;

Effects

basic_string & operator+=(const CharT * s) ;

Effects

```
basic_string & operator+=(CharT c) ;
```
Effects

basic_string & append(const basic_string & s) ;

Effects

basic_string & append(const basic_string & s, size_type pos, size_type n) ;

Effects

basic_string & append(const CharT * s, size_type n) ;

Effects

basic_string & append(const CharT * s) ;

Effects

basic_string & append(size_type n, CharT c) ;

Effects

template<typename InputIter> 
  basic_string & append(InputIter first, InputIter last) ;

Effects

```
void push_back(CharT c) ;
```
Effects
```
void pop_back() ;
```
Effects

basic_string & assign(const basic_string & s) ;

Effects

```
basic_string & assign(unspecified ms) ;
```
Effects

basic_string & assign(const basic_string & s, size_type pos, size_type n) ;

Effects

basic_string & assign(const CharT * s, size_type n) ;

Effects

basic_string & assign(const CharT * s) ;

Effects

basic_string & assign(size_type n, CharT c) ;

Effects

template<typename InputIter> 
  basic_string & assign(InputIter first, InputIter last) ;

Effects

basic_string & assign(const CharT * f, const CharT * l) ;

Effects

basic_string & insert(size_type pos, const basic_string & s) ;

Effects

basic_string & 
insert(size_type pos, const basic_string & s, size_type beg, size_type n) ;

Effects

basic_string & insert(size_type pos, const CharT * s, size_type n) ;

Effects

basic_string & insert(size_type pos, const CharT * s) ;

Effects

basic_string & insert(size_type pos, size_type n, CharT c) ;

Effects

iterator insert(iterator position, CharT c) ;

Effects

void insert(iterator position, std::size_t n, CharT c) ;

Effects

template<typename InputIter> 
  void insert(iterator p, InputIter first, InputIter last) ;

Effects

basic_string & erase(size_type pos = 0, size_type n = npos) ;

Effects

```
iterator erase(iterator position) ;
```
Effects

iterator erase(iterator first, iterator last) ;

Effects

basic_string & replace(size_type pos, size_type n, const basic_string & s) ;

Effects

basic_string & 
replace(size_type pos1, size_type n1, const basic_string & s, size_type pos2, 
        size_type n2) ;

Effects

basic_string & 
replace(size_type pos, size_type n1, const CharT * s, size_type n2) ;

Effects

basic_string & replace(size_type pos, size_type n1, const CharT * s) ;

Effects

basic_string & replace(size_type pos, size_type n1, size_type n2, CharT c) ;

Effects

basic_string & replace(iterator first, iterator last, const basic_string & s) ;

Effects

basic_string & 
replace(iterator first, iterator last, const CharT * s, size_type n) ;

Effects

basic_string & replace(iterator first, iterator last, const CharT * s) ;

Effects

basic_string & replace(iterator first, iterator last, size_type n, CharT c) ;

Effects

template<typename InputIter> 
  basic_string & 
  replace(iterator first, iterator last, InputIter f, InputIter l) ;

Effects

size_type copy(CharT * s, size_type n, size_type pos = 0) const;

Effects

```
void swap(basic_string & s) ;
```
Effects
```
void swap(unspecified ms) ;
```
Effects
```
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.
```
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.
```
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.
```
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.
```
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.
```
size_type find(CharT c, size_type pos = 0) const;
```
Effects: Searches for the character c, beginning at character position pos.
```
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())
```
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())
```
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()).
```
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()).
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.

basic_string substr(size_type pos = 0, size_type n = npos) const;

Effects

int compare(const basic_string & s) const;

Effects

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.

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.

```
int compare(const CharT * s) const;
```
Effects
```
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.

Boost C++ Libraries