This chapter is a reference guide to the ANSI/ISO String class that describes components for manipulating sequences of characters, where characters may be of type char, wchar_t, or of a type defined in a C++ program.

Overview of Strings Classes

The strings library is based on the ANSI/ISO string class description and includes

• "21.1 Character traits" defines types and facilities for character manipulations
• "21.2 String Classes" lists string and character structures and classes
• ß"21.3 Class Basic_string" defines facilities for character sequence manipulations.
• "23.4 Null Terminated Sequence Utilities" lists facilities for Null terminated character sequence strings.

21.1 Character traits

This section defines a class template char_traits<charT> and two specializations for char and wchar_t types. These types are required by string and stream classes and are passed to these classes as formal parameters charT and traits.

The topics in this section are:

• "21.1.1 Character Trait Definitions"
• "21.1.2 Character Trait Requirements"
• "21.1.3 Character Trait Type Definitions"
• "21.1.4 struct char_traits<T>"

21.1.1 Character Trait Definitions

character

Any object when treated sequentially can represent text. This term is not restricted to just char and wchar_t types

character container type

A class or type used to represent a character. This object must be POD (Plain Old Data).

traits

A class that defines types and functions necessary for handling characteristics.

NTCTS

A null character termination string is a character sequence that proceeds the null character value charT(0).

21.1.2 Character Trait Requirements

These types are required by string and stream classes and are passed to these classes as formal parameters charT and traits.

assign

Used for character type assignment.

Prototype:

static void assign

eq

Used for bool equality checking.

Prototype:

static bool eg

lt

Used for bool less than checking.

Prototype:

static bool lt(const char_type&, const 
char_type&);

compare

Used for NTCTS comparison.

Prototype:

static int compare

length

Used when determining the length of a NTCTS.

Prototype:

static size_t length

find

Used to find a character type in an array

Prototype:

static const char_type* find

move

Used to move one NTCTS to another even if the receiver contains the sting already.

Prototype:

static char_type* move

copy

Used for copying a NTCTS that does not contain the NTCTS already.

Prototype:

static char_type* copy

not_eof

Used for bool inequality checking.

Prototype:

static int_type not_eof

to_char_type

Used to convert to a char type from an int_type

Prototype:

static char_type to_char_type

to_int_type

Used to convert from a char type to an int_type.

Prototype:

static int_type to_int_type

eq_int_type

Used to test for deletion.

Prototype:

static bool eq_int_type

get_state

Used to store the state of the file buffer.

Prototype:

static state_type get_state

eof

Used to test for the end of a file.

Prototype:

static int_type eof();

21.1.3 Character Trait Type Definitions

There are several types defined in the char_traits structure for both wide and conventional char types.

The functions are::

Type	Defined	Use
char	char_type	char values
int	int_type	integral values of char types including eof
streamoff	off_type	stream offset values
streampos	pos_type	stream position values
mbstate_t	state_type	file state values

21.1.4 struct char_traits<T>

The template structure is overloaded for both the wchar_t type struct char_traits<wchar_t>. This specialization is used for string and stream usage.

NOTE

The assign, eq and lt are the same as the =, == and < operators.

namespace std {

template<>

// struct char_traits<wchar_t>  or

struct char_traits<char> {

};

}

21.2 String Classes

The header <string> define string and trait classes used to manipulate character and wide character like template arguments.

  
Prototype:

namespace std {

template<class charT> struct char_traits;

template <> struct char_traits<char>;

template <> struct char_traits<wchar_t>;

template

<class charT, 

class traits =char_traits<charT>,

class Allocator = allocator<charT> >

class basic_string;

template

<class charT, class traits, class Allocator>

basic_string <charT,traits, Allocator>

operator+

template

<class charT, class traits, class Allocator>

basic_string<charT,traits,Allocator>

operator+

template

<class charT, class traits, class Allocator>

basic_string<charT,traits,Allocator>

operator+

template

<class charT, class traits, class Allocator>

basic_string<charT,traits,Allocator>

operator+

template

<class charT, class traits, class Allocator>

basic_string<charT,traits,Allocator>

operator+

template

<class charT, class traits, class Allocator>

bool operator==

template

<class charT, class traits, class Allocator>

bool operator==

template

<class charT, class traits, class Allocator>

bool operator==

template

<class charT, class traits, class Allocator>

bool operator!=

template

<class charT, class traits, class Allocator>

bool operator!=

template

<class charT, class traits, class Allocator>

bool operator!=

template

<class charT, class traits, class Allocator>

bool operator< 

template

<class charT, class traits, class Allocator>

bool operator< 

template

<class charT, class traits, class Allocator>

bool operator< 

template

<class charT, class traits, class Allocator>

bool operator> 

template

<class charT, class traits, class Allocator>

bool operator> 

template

<class charT, class traits, class Allocator>

bool operator> 

template

<class charT, class traits, class Allocator>

bool operator<=

template

<class charT, class traits, class Allocator>

bool operator<=

template

<class charT, class traits, class Allocator>

bool operator<=

template

<class charT, class traits, class Allocator>

bool operator>=

template

<class charT, class traits, class Allocator>

bool operator>=

template

<class charT, class traits, class Allocator>

bool operator>=

template

<class charT, class traits, class Allocator>

void swap

template

<class charT, class traits, class Allocator>

basic_istream<charT,traits>&

operator>>

template

<class charT, class traits, class Allocator>

basic_ostream<charT, traits>&

operator<<

template

<class charT, class traits, class Allocator>

basic_istream<charT,traits>&

getline

template

<class charT, class traits, class Allocator>

basic_istream<charT,traits>&

getline

typedef basic_string<char> string;

typedef basic_string<wchar_t> wstring;

};

}

21.3 Class Basic_string

The class basic_string is used to store and manipulate a sequence of character like types of varying length known as strings.

Memory for a string is allocated and deallocated as necessary by member functions.

The first element of the sequence is at position zero.

The iterators used by basic_string are random iterators and as such qualifies as a reversible container

The topics in this section include:

• "21.3.1 Constructors and Assignments"
• "21.3.2 Iterator Support"
• "21.3.3 Capacity"
• "21.3.4 Element Access"
• "21.3.5 Modifiers"
• "21.3.6 String Operations"
• "23.3.7 Non-Member Functions and Operators"

NOTE

In general, the string size can be constrained by memory restrictions.

namespace std {

template

class basic_string {

typedef traits traits_type;

typedef typename traits::char_type value_type;

typedef Allocator allocator_type;

typedef typename Allocator::size_type size_type;

typedef typename Allocator::difference_type

typedef typename Allocator::reference reference;

typedef typename Allocator::const_reference

typedef typename Allocator::pointer pointer;

typedef typename Allocator::const_pointer

// typedef implementation defined iterator; 

// typedef implementation definedconst_iterator;

typedef std::reverse_iterator<iterator>

typedef std::reverse_iterator<const_iterator>

static const size_type npos = -1;

explicit basic_string

basic_string(const basic_string& str);

basic_string(const basic_string& str, 

basic_string

basic_string

basic_string

template<class InputIterator>

basic_string

~basic_string();

basic_string& operator= (const basic_string& str);

basic_string& operator=(const charT* s);

basic_string& operator=(charT c);

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;

size_type size() const;

size_type length() const;

size_type max_size() const;

void resize(size_type n, charT c);

void resize(size_type n);

size_type capacity() const;

void reserve(size_type res_arg = 0);

void clear();

bool empty() const;

const_reference operator[](size_type pos) const;

reference operator[](size_type pos);

const_reference at(size_type n) const;

reference at(size_type n);

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(

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

basic_string& append(const charT* s);

basic_string& append(size_type n, charT c);

template<class InputIterator>

basic_string& append

void push_back(const charT); Á

basic_string& assign(const basic_string&);

basic_string& assign

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

basic_string& assign(const charT* s);

basic_string& assign(size_type n, charT c);

template<class InputIterator>

basic_string& assign

basic_string& insert

basic_string& insert

basic_string& insert

basic_string& insert

basic_string& insert

iterator insert(iterator p, charT c = charT());

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

template<class InputIterator>

void insert

basic_string& erase

iterator erase(iterator position);

iterator erase(iterator first, iterator last);

basic_string& replace

basic_string& replace

basic_string& replace

basic_string& replace

basic_string& replace

basic_string& replace

basic_string& replace

basic_string& replace(

basic_string& replace

template<class InputIterator>

basic_string& replace

size_type copy

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

const charT* c_str() const; 

const charT* data() const;

allocator_type get_allocator() const;

size_type find 

size_type find 

size_type find 

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

size_type rfind

size_type rfind

size_type rfind

size_type rfind

size_type find_first_of

size_type find_first_of

size_type find_first_of

size_type find_first_of

size_type find_last_of 

size_type find_last_of 

size_type find_last_of 

size_type find_last_of 

size_type find_first_not_of

size_type find_first_not_of

size_type find_first_not_of

size_type find_first_not_of

size_type find_last_not_of 

size_type find_last_not_of 

size_type find_last_not_of 

size_type find_last_not_of

basic_string substr

int compare(const basic_string& str) const;

int compare(

int compare

int compare(const charT* s) const;

int compare(size_type pos1, size_type n1, 

int compare(size_type pos1, size_type n1, 

};

}

The class basic_string can have either of two implementations:

• Refcounted.
• Non-refcounted.

The interface and functionality are identical with both implementations. The only difference is performance. Which performs best is dependent upon usage patterns in each application.

The refcounted implementation ships as the default.

NOTE

To enable the non-refcounted implementation un-comment #define _MSL_NO_REFCOUNT_STRING in <mslconfig>. The C++ library and precompiled headers must be rebuilt after making this change.

21.3.1 Constructors and Assignments

Constructor, destructor and assignment operators and functions.

Constructors

The various basic_string constructors construct a string object for character sequence manipulations. All constructors include an -Allocator argument that is used for memory allocation.

Prototype:

explicit basic_string

This default constructor, constructs an empty string. A zero sized string that may be copied to is created.

Prototype:

basic_string

This constructor takes a string class argument and creates a copy of that string, with size of the length of that string and a capacity at least as large as that string.

• An exception is thrown upon failure Prototype:

  basic_string

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

This constructor takes a const char array argument and creates a copy of that array with the size limited to the size_type argument.

The charT* argument shall not be a null pointer An exception is thrown upon failure Prototype:

basic_string

This constructor takes an const char array argument. The size is determined by the size of the char array.

The charT* argument shall not be a null pointer Prototype:

basic_string

This constructor creates a string of size_type n size repeating charT c as the filler.

Alength_error is thrown if n is less than npos. Prototype:

template<class InputIterator>

basic_string

This iterator string takes InputIterator arguments and creates a string with its first position starts with begin and its ending position is end. Size is the distance between beginning and end.

Destructor

Deallocates the memory referenced by the basic_string object.

Prototype:

~basic_string ();

Assignment Operator

Assigns the input string, char array or char type to the current string.

Prototype:

basic_string& operator= (const basic_string& str);

If *this and str are the same object has it has no effect.

Prototype:

basic_string& operator=(const charT* s);

Used to assign a NCTCS to a string.

Prototype:

basic_string& operator=(charT c);

Used to assign a single char type to a string.

Assignment & Addition Operator basic_string

Appends the string rhs to the current string.

Prototype:

string& operator+= (const string& rhs);

string& operator+= (const charT* s);

string& operator+= (charT s);

Both of the overloaded functions construct a string object from the input s, and append it to the current string.

Return:

The assignment operator returns the this pointer.

21.3.2 Iterator Support

Member functions for string iterator support.

begin

Returns an iterator to the first character in the string

Prototype:

iterator begin();

const_iterator begin() const;

end

Returns an iterator that is past the end value.

iterator end();

const_iterator end() const;

rbegin

Returns an iterator that is equivalent to

Prototype:

reverse_iterator(end()).

reverse_iterator rbegin();

const_reverse_iterator rbegin() const;

rend

Returns an iterator that is equivalent to

Prototype:

reverse_iterator(-begin()).

reverse_iterator rend();

const_reverse_iterator rend() const;

21.3.3 Capacity

Member functions for determining a strings capacity.

size

Returns the size of the string.

Prototype:

size_type size() const;

length

Returns the length of the string

Prototype:

size_type length() const;

max_size

Returns the maximum size of the string.

Prototype:

size_type max_size() const;

resize

Resizes the string to size n.

Prototype:

void resize(size_type n);

void resize(size_type n, charT c);

If the size of the string is longer than size_type n, it shortens the string to n, if the size of the string is shorter than n it appends the string to size n with charT c or charT() if no filler is specified.

capacity

Returns the memory storage capacity.

Prototype:

size_type capacity() const;

reserve

A directive that indicates a planned change is memory size to allow for better memory management.

Prototype:

void reserve(size_type res_arg = 0);

clear

Erases from begin() to end().

Prototype:

void clear();

empty

Empties the string stored.

Prototype:

bool empty() const;

Returns true if the size is equal to zero, otherwise false.

21.3.4 Element Access

Member functions and operators for accessing individual string elements.

operator[]

An operator used to access an indexed element of the string.

Prototype:

const_reference operator[](size_type pos) const;

reference operator[](size_type pos);

at

A function used to access an indexed element of the string.

Prototype:

const_reference at(size_type n) const;

reference at(size_type n);

21.3.5 Modifiers

Operators for appending a string.

21.3.5.1 operator+=

An Operator used to append to the end of a string.

Prototype:

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

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

basic_string& operator+=(charT c);

21.3.5.2 append

Member functions for appending to the end of a string.

A function used to append to the end of a string.

Prototype:

basic_string& append(const basic_string& str);

basic_string& append(

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

basic_string& append(const charT* s);

basic_string& append(size_type n, charT c);

template<class InputIterator>

basic_string& append

21.5.3.3 assign

Assigns a string, Null Terminated Character Type Sequence or char type to the string.

Prototype:

basic_string& assign(const basic_string&);

basic_string& assign

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

basic_string& assign(const charT* s);

basic_string& assign(size_type n, charT c);

template<class InputIterator>

basic_string& assign

If there is a size argument whichever is smaller the string size or argument value will be assigned.

21.3.5.4 insert

Inserts a string, Null Terminated Character Type Sequence or char type into the string.

Prototype:

basic_string& insert

basic_string& insert

basic_string& insert

basic_string& insert

basic_string& insert

iterator insert(iterator p, charT c = charT());

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

template<class InputIterator>

void insert

May throw an exception,

21.3.5.5 erase

Erases the string

Prototype:

basic_string& erase

iterator erase(iterator position);

iterator erase(iterator first, iterator last);

May throw an exception,

21.3.5.6 replace

Replaces the string with a string, Null Terminated Character Type Sequence or char type.

Prototype:

basic_string& replace

basic_string& replace

basic_string& replace

basic_string& replace

basic_string& replace

basic_string& replace

basic_string& replace

basic_string& replace(

basic_string& replace

template<class InputIterator>

basic_string& replace

May throw an exception,

21.3.5.7 copy

Copies a Null Terminated Character Type Sequence to a string up to the size designated.

Prototype:

size_type copy

The function copy does not pad the string with 
Null characters.

21.3.5.8 swap

Swaps one string for another.

Prototype:

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

21.3.6 String Operations

Member functions for sequences of character operations.

c_str

Returns the string as a Null terminated character type sequence.

Prototype:

const charT* c_str() const; 

data

Returns the string as an array without a Null terminator.

Prototype:

const charT* data() const;

get_allocator

Returns a copy of the allocator object used to create the string.

Prototype:

allocator_type get_allocator() const;

21.3.6.1 find

Finds a string, Null Terminated Character Type Sequence or char type in a string starting from the beginning.

Prototype:

size_type find 

size_type find 

size_type find 

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

The found position or npos if not found.

21.3.6.2 rfind

Finds a string, Null Terminated Character Type Sequence or char type in a string testing backwards from the end.

Prototype:

size_type rfind

size_type rfind

size_type rfind

size_type rfind

The found position or npos if not found.

21.6.3.3 find_first_of

Finds the first position of one of the elements in the function's argument starting from the beginning.

Prototype:

size_type find_first_of

size_type find_first_of

size_type find_first_of

size_type find_first_of

The found position or npos if not found.

21.3.6.4 find_last_of

Finds the last position of one of the elements in the function's argument starting from the beginning.

Prototype:

size_type find_last_of 

size_type find_last_of 

size_type find_last_of 

size_type find_last_of 

The found position or npos if not found.

21.3.6.5 find_first_not_of

Finds the first position that is not one of the elements in the function's argument starting from the beginning.

Prototype:

size_type find_first_not_of

size_type find_first_not_of

size_type find_first_not_of

size_type find_first_not_of

The found position or npos if not found.

21.3.6.6 find_last_not_of

Finds the last position that is not one of the elements in the function's argument starting from the beginning.

Prototype:

size_type find_last_not_of 

size_type find_last_not_of 

size_type find_last_not_of 

size_type find_last_not_of

The found position or npos if not found.

21.3.6.7 substr

Returns a string if possible from beginning at the first arguments position to the last position.

Prototype:

basic_string substr

May throw an exception,

21.3.6.8 compare

Compares a string, substring or Null Terminated Character Type Sequence with a lexicographical comparison.

Prototype:

int compare(const basic_string& str) const;

int compare(

int compare

int compare(const charT* s) const;

int compare

Less than zero if the string is smaller than the argument lexicographically, zero if the string is the same size as the argument lexicographically and greater than zero if the string is larger than the argument lexicographically.

23.3.7 Non-Member Functions and Operators

21.3.7.1 operator+

Appends one string to another.

Prototype:

template

operator+

template

operator+

template

operator+

template

operator+

template

operator+

The combined strings.

21.3.7.2 operator==

Test for lexicographical equality.

Prototype:

template

bool operator==

template

bool operator==

template

bool operator==

True if the strings match otherwise false.

21.3.7.3 operator!=

Test for lexicographical inequality.

Prototype:

template

bool operator!=

template

bool operator!=

template

bool operator!=

True if the strings do not match otherwise false.

21.3.7.4 operator<

Tests for a lexicographically less than condition.

Prototype:

template

bool operator<

template

bool operator< 

template

bool operator< 

True if the first argument is lexicographically less than the second argument otherwise false.

21.3.7.5 operator>

Tests for a lexicographically greater than condition.

Prototype:

template

bool operator> 

template

bool operator> 

template

bool operator> 

True if the first argument is lexicographically greater than the second argument otherwise false.

21.3.7.6 operator<=

Tests for a lexicographically less than or equal to condition.

Prototype:

template

bool operator<=

template

bool operator<=

template

bool operator<=

True if the first argument is lexicographically less than or equal to the second argument otherwise false.

21.3.7.7 operator>=

Tests for a lexicographically greater than or equal to condition.

Prototype:

template

bool operator>=

template

bool operator>=

template

bool operator>=

True if the first argument is lexicographically greater than or equal to the second argument otherwise false.

21.3.7.8 swap

This non member swap exchanges the first and second arguments.

Prototype:

template

void swap

21.3.7.9 Inserters and extractors

Overloaded inserters and extractors for basic_string types.

operator>>

Overloaded extractor for stream input operations.

Prototype:

template

operator>>

Characters are extracted and appended until n characters are stored or end-of-file occurs on the input sequence;

operator<<

Inserts characters from a string object from into a output stream.

Prototype:

template

operator<<

getline

Extracts characters from a stream and appends them to a string.

Prototype:

template

getline

template

getline

Extracts characters from a stream and appends them to the string until the end-of-file occurs on the input sequence (in which case, the getline function calls setstate(eofbit) or the delimiter is encountered in which case, the delimiter is extracted but not appended.

If the function extracts no characters, it calls setstate(failbit) in which case it may throw an exception.

23.4 Null Terminated Sequence Utilities

The standard requires C++ versions of the standard libraries for use with characters and Null Terminated Character Type Sequences.

Character Support

The standard provides for namespace and character type support.

Headers <cctype.h> and <cwtype.h>:

<cctype.h>	<cwctype.h>	<cctype.h>	<cwctype.h>
isalnum	iswalnum	isprint	iswprint
isalpha	iswalpha	ispunct	iswpunct
iscntrl	iswcntrl	isspace	iswspace
isdigit	iswdigit	isupper	iswupper
isgraph	iswgraph	isxdigit	iswxdigit
islower	iswlower
tolower	towlower	toupper	towupper
	wctype		iswctype
	wctrans		towctrans
Macros		EOF	WEOF

String Support

The standard provides for namespace and wide character type for Null Terminated Character Type Sequence functionality.

Headers <cstring.h> and <wchar.h>:

<cstring.h>	<wchar.h>	<cstring.h>	<wchar.h>
memchr	wmemchr	strerror
memcmp	wmemcmp	strlen	wcslen
memcpy	wmemcpy	strncat	wcsncat
memmove	wmemmove	strncmp	wcsncmp
memset	wmemset	strncpy	wcsncpy
strcat	wcscat	strpbrk	wcspbrk
strchr	wcschr	strrchr	wcsrchr
strcmp	wcscmp	strspn	wcsspn
strcoll	wcscoll	strstr	wcsstr
strcpy	wcscpy	strtok	wcstok
strcspn	wcscspn	strxfrm	wcsxfrm
Type	mbstate_t	size_t	wint_t
Macro	NULL	NULL	WCHAR_MAX
Macro			WCHAR_MIN

Input and Output Manipulations

The standard provides for namespace and wide character support for manipulation and conversions of input and output and character and character sequences.

Additional <wchar.h> and <stdlib.h> support:

wchar.h	wchar.h	wchar.h	<cstdlib.h>
btowc	mbrtowc	wcrtomb	atol
fgetwc	mbsinit	wcscoll	atof
fgetws	mbsrtowcs	wcsftime	atoi
fputwc	putwc	wcstod	mblen
fputws	putwchar	wcstol	mbstowcs
fwide	swscanf	wcsrtombs	mbtowc
fwprintf	swprintf	wcstoul	strtod
fwscanf	ungetwc	wctob	strtol
getwc	vfwprintf	wprintf	strtoul
getwchar	vwprintf	wscanf	wctomb
mbrlen	vswprintf		wcstombs