<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<META NAME="Author" CONTENT="Zafir Anjum">
<TITLE>MFC Programmer's SourceBook : STL Programmer's Guide</TITLE>
<META name="description"
content="A freely available implementation
of the C++ Standard Template Library, including
hypertext documentation.">
<META name="keywords"
content="generic programming, STL, standard template library">
</HEAD>
<SCRIPT LANGUAGE="JavaScript"><!--
var adcategory = "cpp";
// -->
</SCRIPT>
<body background="../../fancyhome/back.gif" bgcolor="#FFFFFF" >
<SCRIPT LANGUAGE="JavaScript"><!--
var nfrm = location.href.indexOf("_nfrm_");
var validframes = (top.frames.length > 0 && top.frames['ad'] && top.frames['logo'] );
var random = Math.random();
if( !validframes && nfrm == -1 )
{
var dclkPage = "www.codeguru.com/";
if( self.adcategory )
dclkPage += adcategory;
else
dclkPage += "mfc";
document.write('<nolayer><center>');
document.write('<iframe src="http://ad.doubleclick.net/adi/' + dclkPage + ';ord='
+ random + '" width=470 height=62 marginwidth=0 marginheight=0 hspace=0 vspace=0 '
+ 'frameborder=0 scrolling=no bordercolor="#000000">');
document.write('<a href="http://ad.doubleclick.net/jump/' + dclkPage + ';ord='
+ random + '">');
document.write('<img src="http://ad.doubleclick.net/ad/' + dclkPage + ';ord='
+ random + '" height=60 width=468>' + '</a>');
document.write('</iframe>');
document.write('</center></nolayer>');
document.write('<layer src="http://ad.doubleclick.net/adl/' + dclkPage +
';ord=' + random + '"></layer>');
document.write('<ilayer visibility=hide width=468 height=83></ilayer>');
}
// top.location = "/show.cgi?" + adcategory + "=" + location.pathname;
// -->
</SCRIPT>
<noscript>
<p align="center">
<a href="http://ad.doubleclick.net/jump/www.codeguru.com/cpp;ord=NupaYNFCY34AAHgAhi4">
<img src="http://ad.doubleclick.net/ad/www.codeguru.com/cpp;ord=NupaYNFCY34AAHgAhi4"></a>
</p>
</noscript>
<BR Clear>
<H1>basic_string<charT, traits, Alloc></H1>
<Table CellPadding=0 CellSpacing=0 width=100%>
<TR>
<TD Align=left><Img src = "containers.gif" Alt="" WIDTH = "194" HEIGHT = "38" ></TD>
<TD Align=right><Img src = "type.gif" Alt="" WIDTH = "194" HEIGHT = "39" ></TD>
</TR>
<TR>
<TD Align=left VAlign=top><b>Category</b>: containers</TD>
<TD Align=right VAlign=top><b>Component type</b>: type</TD>
</TR>
</Table>
<h3>Description</h3>
The <tt>basic_string</tt> class represents a <A href="Sequence.html">Sequence</A> of characters.
It contains all the usual operations of a <A href="Sequence.html">Sequence</A>, and, additionally,
it contains standard string operations such as search and concatenation.
<P>
The <tt>basic_string</tt> class is parameterized by character type, and by
that type's <A href="character_traits.html">Character Traits</A>. Most of the time, however, there is
no need to use the <tt>basic_string</tt> template directly. The types
<tt>string</tt> and <tt>wstring</tt> are typedefs for, respectively,
<tt>basic_string<char></tt> and <tt>basic_string<wchar_t></tt>.
<P>
Some of <tt>basic_string</tt>'s member functions use an unusual method of
specifying positions and ranges. In addition to the conventional
method using iterators, many of <tt>basic_string</tt>'s member functions use
a single value <tt>pos</tt> of type <tt>size_type</tt> to represent a position (in
which case the position is <tt>begin() + pos</tt>, and many of
<tt>basic_string</tt>'s member functions use two values, <tt>pos</tt> and <tt>n</tt>, to
represent a range. In that case <tt>pos</tt> is the beginning of the range
and <tt>n</tt> is its size. That is, the range is <tt>[begin() + pos, begin() +
pos + n)</tt>.
<P>
Note that the C++ standard does not specify the complexity of
<tt>basic_string</tt> operations. In this implementation, <tt>basic_string</tt>
has performance characteristics very similar to those of <tt><A href="Vector.html">vector</A></tt>:
access to a single character is <i>O(1</i>), while copy and concatenation
are <i>O(N</i>). By contrast, <tt><A href="Rope.html">rope</A></tt> has very different performance
characteristics: most <tt><A href="Rope.html">rope</A></tt> operations have logarithmic complexity.
<P>
Note also that, according to the C++ standard, <tt>basic_string</tt> has very
unusual iterator invalidation semantics. Iterators may be invalidated
by <tt>swap</tt>, <tt>reserve</tt>, <tt>insert</tt>, and <tt>erase</tt> (and by functions that are
equivalent to <tt>insert</tt> and/or <tt>erase</tt>, such as <tt>clear</tt>, <tt>resize</tt>,
<tt>append</tt>, and <tt>replace</tt>). Additionally, however, the first call to
<i>any</i> non-const member function, including the non-const version of
<tt>begin()</tt> or <tt>operator[]</tt>, may invalidate iterators. (The intent of
these iterator invalidation rules is to give implementors greater
freedom in implementation techniques.) In this implementation,
<tt>begin()</tt>, <tt>end()</tt>, <tt>rbegin()</tt>, <tt>rend()</tt>, <tt>operator[]</tt>, <tt>c_str()</tt>, and
<tt>data()</tt> do not invalidate iterators. In this implementation,
iterators are only invalidated by member functions that explicitly
change the string's contents.
<h3>Example</h3>
<pre>
int main() {
string s(10u, ' '); // Create a string of ten blanks.
const char* A = "this is a test";
s += A;
cout << "s = " << (s + '\n');
cout << "As a null-terminated sequence: " << s.c_str() << endl;
cout << "The sixteenth character is " << s[15] << endl;
reverse(s.begin(), s.end());
s.push_back('\n');
cout << s;
}
</pre>
<h3>Definition</h3>
Defined in <A href="string/index.htm">string</A>.
<h3>Template parameters</h3>
<Table border>
<TR>
<TH>
Parameter
</TH>
<TH>
Description
</TH>
<TH>
Default
</TH>
</TR>
<TR>
<TD VAlign=top>
<tt>charT</tt>
</TD>
<TD VAlign=top>
The string's value type: the type of character it contains.
</TD>
<TD VAlign=top>
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>traits</tt>
</TD>
<TD VAlign=top>
The <A href="character_traits.html">Character Traits</A> type, which encapsulates basic character
operations.
</TD>
<TD VAlign=top>
<tt>char_traits<charT></tt>
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>Alloc</tt>
</TD>
<TD VAlign=top>
The string's allocator, used for internal memory management.
</TD>
<TD VAlign=top>
<tt>alloc</tt>
</TD>
</tr>
</table>
<h3>Model of</h3>
<A href="RandomAccessContainer.html">Random Access Container</A>,
<A href="Sequence.html">Sequence</A>.
<h3>Type requirements</h3>
In addition to the type requirements imposed by
<A href="RandomAccessContainer.html">Random Access Container</A> and <A href="Sequence.html" tppabs="http://www.sgi.com/Technology/STL/Sequence.shtml">Sequence</A>:
<UL>
<LI>
<tt>charT</tt> is a POD ("plain 'ol data") type.
<LI>
<tt>traits</tt> is a <A href="character_traits.html">Character Traits</A> type whose value type is
<tt>charT</tt>
</UL>
<h3>Public base classes</h3>
None.
<h3>Members</h3>
<Table border>
<TR>
<TH>
Member
</TH>
<TH>
Where defined
</TH>
<TH>
Description
</TH>
</TR>
<TR>
<TD VAlign=top>
<tt>value_type</tt>
</TD>
<TD VAlign=top>
<A href="Container.html">Container</A>
</TD>
<TD VAlign=top>
The type of object, <tt>CharT</tt>, stored in the string.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>pointer</tt>
</TD>
<TD VAlign=top>
<A href="Container.html">Container</A>
</TD>
<TD VAlign=top>
Pointer to <tt>CharT</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>reference</tt>
</TD>
<TD VAlign=top>
<A href="Container.html">Container</A>
</TD>
<TD VAlign=top>
Reference to <tt>CharT</tt>
</TD>
</TR>
<TR>