Class template basic_string

| Home | Libraries | People | FAQ | More

## Class template basic_string

boost::interprocess::basic_string

## Synopsis

    // In header: <boost/interprocess/containers/string.hpp>

    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(basic_string &&);
      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=(basic_string &&);
      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(basic_string &&) ;
      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 &&) ;
      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(basic_string && 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=(basic_string && 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(basic_string && 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 && x) ;

    Effects

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

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

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

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

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

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

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

71.     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())

72.     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())

73.     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()).

74.     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()).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    Effects

92.     int compare(const basic_string & s) const;

    Effects

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

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

95.     int compare(const CharT * s) const;

    Effects

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