The inplace_merge, stable_sort, and stable_partition algorithms require the use of a temporary buffer. Two methods are available for allocating this buffer:

• Preallocate 16K bytes of space on the stack
• Allocate the required amount of storage dynamically

By default, the current DEC C++ library makes use of the preallocated buffer, which avoids the overhead of run-time allocation. If your application requires a buffer that exceeds 16K, it can not take advantage of this default.

If you are concerned with minimizing the use of stack space in your program, or if your application requires a buffer that exceeds 16K, define the __DEC_DYN_ALLOC macro to enable dynamic buffering. Do this by adding the following to your compile command line:

-D__DEC_DYN_ALLOC

6.5 The basic_string Library

DEC C++ provides an implementation of the basic_string Library that consists of the basic_string template class, with parameters for the following:

• Character type
• Character traits type (specified by the template class, char_traits)
• Allocator type

The basic_string Library also declares a string typedef to represent the typical usage, which is a string of normal (skinny) characters. For example:

#include <string> string str("abc"); // create a string containing "abc" str.append('d'); // str now contains "abcd" cout << s << endl; // print str to cout

The wide character typedef (wstring) is not yet supported.

6.5.1 The basic_string Member Functions

The basic_string class can be used as character text, as an array of characters, or as an STL-like sequence of characters. The string member functions described below support these alternative uses.

6.5.1.1 Constructors/Destructors/Assignment

basic_string(const Allocator& a = Allocator());

Constructs an empty string.

basic_string(const basic_string& str, size_type pos = 0, size_type n = npos, const Allocator& a = Allocator());

Constructs a string by copying all elements from str, starting at position pos in str and ending at position pos + n.

basic_string(const charT* s, size_type n,const Allocator& a = Allocator());

basic_string(const charT* s, const Allocator& a = Allocator());

Constructs a string from s. If n is supplied it copies only the first n characters from s.

basic_string(size_type n, charT c, const Allocator& a = Allocator());

Constructs a string with n copies of c; that is: string(4,'a') would construct a string of aaaa.

basic_string(iterator begin, iterator end, const Allocator& a = Allocator());

Constructs a string from the characters between begin and end.

~basic_string();

Destroys the string and frees all associated memory.

basic_string& operator=(const basic_string& str);
basic_string& operator=(const charT* s);

basic_string& operator=(charT c);

Assigns str, s, or c to the current string.

size_type size() const;

size_type length() const;

Returns a count of the number of characters in the string.

size_type max_size() const;

Specifies the maximum number of elements that can be in the string, usually limited by the amount of available memory.

void resize(size_type n);

If n is less than the current value of size(), resize() truncates the string to length n. If n is greater than the current value of size(), resize() expands the string to length n and pads the string with null characters.

void resize(size_type n, charT c);

If n is less than the current value of size(), resize() truncates the string to length n. If n is greater than the current value of size(), resize() expands the string to length n and pads the string with c characters.

size_type capacity() const;

Returns the number of elements allocated in the string.

void reserve(size_type res_arg);

Reallocates the string if the current capacity is less than res_arg. Invalidates all iterators, pointers, and references to the string.

bool empty() const;

Returns true if length is zero, otherwise returns false.

charT operator[](size_type pos) const;
reference operator[](size_type pos);

charT at(size_type pos) const;
reference at(size_type pos);

The subscript operator returns the character at position pos in the string. The at() function is similar except it throws an out-of-range exception if pos is invalid, that is, if it is greater than the current length of the string.

basic_string& operator+=(const basic_string& str);
basic_string& operator+=(const charT* s); basic_string& operator+=(charT c);

basic_string& append(const basic_string& str);
basic_string& append(const charT* s);

Appends str, s, or c to the string and returns *this.

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

Appends a string constructed by copying all elements from str onto the string, starting at position pos in str and ending at position pos + n. Returns *this.

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

Appends onto the string the string created from the first n characters of s. Returns *this.

basic_string& append(size_type n, charT c);

Appends onto the string n number of the value of c. Returns *this.

basic_string& append(iterator first, iterator last);

Appends onto the current string the string constructed from the elements in the range first to last. Returns *this.

basic_string& assigns(const basic_string& str);

basic_string& assigns(const charT* s);

Assigns str or s to the current string. Returns *this.

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

Assigns a string constructed by copying onto the current string all elements from str, starting at position pos in str and ending at position pos + n. Returns *this.

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

Assigns the string created from the first n characters of s to the current string. Returns *this.

basic_string& assign(size_type n, charT c);

Assigns n number of values of c to the string. Returns *this.

basic_string& assign(iterator first, iterator last);

Assigns to the current string the string constructed from the elements in the range first to last. Returns *this.

basic_string& insert(size_type pos1, const basic_string& str);

Inserts str into the string after position pos1. Returns *this. If pos1 is greater than the size of the string, this function throws a length-error exception. Returns *this.

basic_string& insert(size_type pos1, const basic_string& str, size_type pos2, size_type n);

Inserts into the string after position pos1 the elements of str beginning at position pos2 and ending at either pos2+n or the end of str (whichever is smallest). If pos1 is greater than the size of the string or pos2 is greater than the size of str, this function throws a length-error exception. Returns *this.

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

Inserts the character string s into the string beginning after position pos. Returns *this.

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

Inserts the first n characters of the character string s into the string after position pos. Returns *this.

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

Inserts n copies of the character c into the string after position pos. Returns *this.

iterator insert(iterator p, charT c);

Inserts the character c into the string before the character referred to by p and returns an iterator pointing at the element immediately following p prior to the element being inserted.

void insert(iterator p, size_type n, charT c);

Inserts the n copies of the character c into the string before the character referred to by p.

void insert(iterator p, iterator first, iterator last);

Inserts before the character referred to by p the characters in the string from first up to but not including last

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

Erases from the string the characters beginning at position pos and ending at position n. Returns *this.

iterator erase(iterator pos);

Erases the character in the string at pos and returns an iterator pointing at the element immediately following p prior to the element being erased.

iterator erase(iterator first, iterator last);

Erases the characters in the string from first up to but not including last and returns an iterator pointing at the element immediately following last prior to the element being erased.

basic_string& replace(size_type pos1, size_type n1, const basic_string& str);

Removes the characters in the string from pos1 to pos1+n1 or to the end of the string (whichever is smaller). Inserts str into the string at pos1. Returns *this. If pos1 is greater than the size of the string, this function throws an out-of-range exception.

basic_string& replace(size_type pos1, size_type n1, const basic_string& str, size_type pos2, size_type n);

Removes the characters in the string from pos1 to pos1+n1 or to the end of the string (whichever is smaller). Inserts the string created by using the characters in str from pos2 to pos2+n or the end of str (whichever is less) into the string at pos1. Returns *this. If pos1 is greater than the size of the string or pos2 is greater than str, this function throws an out-of-range exception. If the size of the string minus the size of the string to be removed is greater than the npos minus the size of the string to be inserted, this function throws an length-error exception.

basic_string& replace(size_type pos1, size_type n1, const charT* s);

Removes the characters in the string from pos1 to pos1+n1 or to the end of the string (whichever is smaller). Inserts s into the string at pos1. Returns *this. If pos1 is greater than the size of the string, this function throws an out-of-range exception.

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

Removes the characters in the string from pos1 to pos1+n1 or to the end of the string (whichever is smaller). Inserts the string created by copying the first n2 characters of s into the string at pos1. Returns *this. If pos1 is greater than the size of the string, this function throws an out-of-range exception.

basic_string& replace(size_type pos1, size_type n1, size_type n2,
charT c);

Removes the characters in the string from pos1 to pos1+n1 or to the end of the string (whichever is smaller). Inserts the string created by copying the first n2 characters of the character c into the string at pos1. Returns *this. If pos1 is greater than the size of the string, this function throws an out-of-range exception.

basic_string& replace(iterator i1, iterator i2, const basic_string& str);

Removes the characters in the range i1 to i2 and inserts str at i1. Returns *this.

basic_string& replace(iterator i1, iterator i2, const charT* s);

Removes the characters in the range i1 to i2 and inserts s at i1. Returns *this.

basic_string& replace(iterator i1, iterator i2, const charT* s, size_type n);

Removes the characters in the range i1 to i2 and inserts n characters of s at i1. Returns *this.

basic_string& replace(iterator i1, iterator i2, size_type n, charT c);

Removes the characters in the range i1 to i2 and inserts n copies of the character c at i1. Returns *this.

basic_string& replace(iterator i1, iterator i2, iterator i3, iterator i4);

Removes the characters in the range i1 to i2 and inserts the characters in the range i3 to i4. Returns *this.

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

Replaces s with the elements from the string beginning at position pos and ending at either pos+n or the end of the string (whichever is smaller). If pos is greater than the value of size(), this function throws an out-of-range exception. It returns the size of the new string s. Before calling the copy() function, s must have already been allocated to have as least as many elements as needed to hold the results of the copy.

void swap(basic_string<charT, traits, Allocator>& s);

Swaps the contents (that is, the data members) of s and *this.

const charT* c_str() const;

const charT* data() const;

Returns a pointer to the char* representation of the string.

const allocator_type& get_allocator() const;

Returns a reference to the string's allocator object.

size_type find(const basic_string& str, size_type pos = 0) const;

Returns the lowest position at which str is embedded in the string starting at position pos in the string; if no such position exists, the function returns npos.

size_type find(const charT* s, size_type pos = 0) const;

Returns the lowest position at which s is embedded in the string starting at position pos in the string; if no such position exists, the funtion returns npos.

size_type find(charT c, size_type pos = 0) const;

Returns the lowest position at which c is embedded in the string starting at position pos in the string; if no such position exists, the function returns npos.

size_type find(const charT* s, size_type pos, size_type n) const;

Returns the lowest position at which the first n characters of s are embedded in the string starting at position pos in the string; if no such position exists, the function returns npos.

The function rfind() is similar to the find() function except that it returns the highest position in the string.

size_type find_first_of(const basic_string<charT, traits, Allocator>& str,
size_type pos = npos);

Returns the first position in the string that matches one of the characters contained in the argument str. For example:

string s = "abcdef"; size_t index = s.find_first_of("cehb"); // index of 'b' is 2

If the pos argument is supplied, no character in the string beyond position pos will be considered.

size_type find_first_of(const charT* s, size_type pos = npos);

Calls the find_first_of() function (described above) constructing the str argument from s.

size_type find_first_of(const charT* s, size_type pos, size_type n);

Calls the find_first_of() function (described above) constructing the str argument from the first n characters of s.

size_type find_first_of(charT c, size_type pos = npos);

Calls the find_first_of() function (described above) constructing the str argument from the character c.

size_type find_last_of(const basic_string<charT, traits, Allocator>& str,
size_type pos = npos);

Returns the last position in the string that matches one of the characters contained in the argument str. For example:

string s = "abcdef"; size_t index = s.find_last_of("cehb"); // index of 'e' is 4

If the pos argument is supplied, no character in the string beyond position pos will be considered.

size_type find_last_of(const charT* s, size_type pos = npos);

Calls the find_last_of() function (described above) constructing the str argument from s.

size_type find_last_of(const charT* s, size_type pos, size_type n);

Calls the find_last_of() function (described above) constructing the str argument from the first n characters of s.

size_type find_last_of(charT c, size_type pos = npos);

Calls the find_last_of() function (described above) constructing the str argument from the character c.

The find_first_not_of() and find_last_not_of() functions are similar to the functions described above except that they return the first (or last) position of one of the characters not in the string. For example:

string s = "abcdef"; size_t index = s.find_last_not_of("cfehb"); // index of 'd' is 4 index = s.find_first_not_of("cda"); // index of 'b' is 2

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

Returns the substring from pos to n. If pos is greater than the current size of the string, this function throws an out-of-range exception.

int compare(const basic_string& str);

Compares each corresponding character starting at the beginning of the string and str. The number of elements used for the comparison is the smaller of the size of str or the size of the string. If the character in the string is less than the corresponding character in str, a negative value is returned. If the character in the string is greater than the corresponding character in str, a positive value is returned. If all of the elements are equal a negative value is returned if the value of the size of the string is less than the size of str, 0 if they are equal, and a positive value of the size if the string is greater than the size of str.

int compare(charT* s) const;

Calls the compare() function (described above) by constructing the string str out of s.

int compare(size_type pos, size_type n1, charT* s, size_type n2 = npos);

Calls the compare() function (described above). The string to compare is created from the first n1 elements of the string beginning at position pos, and the argument str is created from the first n2 elements of s.

int compare(size_type pos, size_type n1, const basic_string& str);

Calls the compare() function (described above). The string to compare is created from the first n1 elements of the string beginning at position pos and is compared to str.

int compare(size_type pos, size_type n1, const basic_string& str, size_type pos2, size_type n2);

Calls the compare() function (described above). The string to compare is created from the first n1 elements of the string beginning at position pos and the argument str is created from the first n2 elements of str beginning at position pos2.

iterator begin();
const_iterator begin() const;

iterator rbegin();
const_iterator rbegin() const;

Returns a random access iterator. Dereferencing the return value will give the character at the beginning of the string. The iterator returned by the begin() function will move forward through the string with operator++, while the rbegin() will move forward through the string with operator -- .

iterator end();
const_iterator end() const;

iterator rend();
const_iterator rend() const;

Returns a random access iterator to one-past the end of the string. Dereferencing the return value minus 1 will give the character at the end of the string. The iterator returned by the end() function will move backward through the string with operator -- , and the rend() function will move backward through the string with operator++.

The following is an example of a simple use of iterators:

#include <string> string str("azbzc"); int count = 0; // count the number of z's for (string::iterator iter = str.begin(); iter!= str.end(); iter++) if ((*(iter)=='z') count++;