basic_string<charT,traits,Alloc>

Category:containers

Componenttype:type

Description
Thebasic_stringclassrepresentsaSequenceofcharacters.ItcontainsalltheusualoperationsofaSequence,and,
additionally,itcontainsstandardstringoperationssuchassearchandconcatenation.
Thebasic_stringclassisparameterizedbycharactertype,andbythattype'sCharacterTraits.Mostofthetime,
however,thereisnoneedtousethebasic_stringtemplatedirectly.Thetypesstringandwstringaretypedefs
for,respectively,basic_string<char>andbasic_string<wchar_t>.
Someofbasic_string'smemberfunctionsuseanunusualmethodofspecifyingpositionsandranges.Inaddition
totheconventionalmethodusingiterators,manyofbasic_string'smemberfunctionsuseasinglevalueposof
typesize_typetorepresentaposition(inwhichcasethepositionisbegin()+pos,andmanyofbasic_string's
memberfunctionsusetwovalues,posandn,torepresentarange.Inthatcaseposisthebeginningoftherangeand
nisitssize.Thatis,therangeis[begin()+pos,begin()+pos+n).
NotethattheC++standarddoesnotspecifythecomplexityofbasic_stringoperations.Inthisimplementation,
basic_stringhasperformancecharacteristicsverysimilartothoseofvector:accesstoasinglecharacterisO(1),
whilecopyandconcatenationareO(N).Bycontrast,ropehasverydifferentperformancecharacteristics:most
ropeoperationshavelogarithmiccomplexity.
Notealsothat,accordingtotheC++standard,basic_stringhasveryunusualiteratorinvalidationsemantics.
Iteratorsmaybeinvalidatedbyswap,reserve,insert,anderase(andbyfunctionsthatareequivalenttoinsert
and/orerase,suchasclear,resize,append,andreplace).Additionally,however,thefirstcalltoanynonconst
memberfunction,includingthenonconstversionofbegin()oroperator[],mayinvalidateiterators.(Theintent
oftheseiteratorinvalidationrulesistogiveimplementorsgreaterfreedominimplementationtechniques.)Inthis
implementation,begin(),end(),rbegin(),rend(),operator[],c_str(),anddata()donotinvalidateiterators.In
thisimplementation,iteratorsareonlyinvalidatedbymemberfunctionsthatexplicitlychangethestring'scontents.

Example
intmain(){
strings(10u,'');//Createastringoftenblanks.
constchar*A="thisisatest";
s+=A;
cout<<"s="<<(s+'\n');
cout<<"Asanullterminatedsequence:"<<s.c_str()<<endl;
cout<<"Thesixteenthcharacteris"<<s[15]<<endl;

reverse(s.begin(),s.end());
s.push_back('\n');
cout<<s;

Definition
Definedinthestandardheaderstring.

Templateparameters
Parameter
charT
traits
Alloc

Description
Thestring'svaluetype:thetypeofcharacteritcontains.

Default

TheCharacterTraitstype,whichencapsulatesbasiccharacteroperations. char_traits<charT>
alloc
Thestring'sallocator,usedforinternalmemorymanagement.

Modelof
RandomAccessContainer,Sequence.

Typerequirements
InadditiontothetyperequirementsimposedbyRandomAccessContainerandSequence:
charTisaPOD("plainol'data")type.
traitsisaCharacterTraitstypewhosevaluetypeischarT

Publicbaseclasses
None.

Members
Member

Where
defined

Description

value_type

Container

Thetypeofobject,CharT,
storedinthestring.

pointer

Container

PointertoCharT.

reference

Container

ReferencetoCharT

const_reference
size_type

Container
Container

ConstreferencetoCharT
Anunsignedintegraltype.

difference_type

Container

Asignedintegraltype.

staticconstsize_typenpos

basic_string

Thelargestpossiblevalueof
typesize_type.Thatis,
size_type(1).

iterator

Container

Iteratorusedtoiterate
throughastring.A
basic_stringsupplies
RandomAccessIterators.

const_iterator

Container

Constiteratorusedtoiterate
throughastring.

reverse_iterator

Reversible
Container

Iteratorusedtoiterate
backwardsthroughastring.

const_reverse_iterator

Reversible
Container

Constiteratorusedtoiterate
backwardsthroughastring.

iteratorbegin()

Container

Returnsaniteratorpointing
tothebeginningofthestring.

iteratorend()

Container

Returnsaniteratorpointing
totheendofthestring.

const_iteratorbegin()const

Container

const_iteratorend()const

Container

Returnsaconst_iterator
pointingtothebeginningof
thestring.
Returnsaconst_iterator
pointingtotheendofthe
string.

reverse_iteratorrbegin()

Reversible
Container

Returnsareverse_iterator
pointingtothebeginningof
thereversedstring.

reverse_iteratorrend()

Reversible
Container

const_reverse_iteratorrbegin()const

Reversible
Container

Returnsareverse_iterator
pointingtotheendofthe
reversedstring.
Returnsa

const_reverse_iteratorrend()const

Reversible
Container

const_reverse_iterator

pointingtothebeginningof
thereversedstring.
Returnsa
const_reverse_iterator

size_typesize()const

Container

pointingtotheendofthe
reversedstring.
Returnsthesizeofthestring.

size_typelength()const

basic_string

Synonymforsize().

size_typemax_size()const

Container

size_typecapacity()const

Returnsthelargestpossible
sizeofthestring.
basic_string Seebelow.

boolempty()const

Container

trueifthestring'ssizeis0.

referenceoperator[](size_typen)

Random
Access
Container

Returnsthen'thcharacter.

const_referenceoperator[](size_typen)const

Random
Access
Container

Returnsthen'thcharacter.

constcharT*c_str()const

basic_string

Returnsapointertoanull
terminatedarrayofcharacters
representingthestring's
contents.

constcharT*data()const

basic_string

Returnsapointertoanarray
ofcharacters(notnecessarily
nullterminated)representing
thestring'scontents.

basic_string()
basic_string(constbasic_string&s,
size_typepos=0,size_typen=npos)
basic_string(constcharT*)

Container
Container,

Createsanemptystring.
Generalizationofthecopy
basic_string constructor.
basic_string Constructastringfroma
nullterminatedcharacter
array.

basic_string(constcharT*s,size_typen)

basic_string

Constructastringfroma
characterarrayandalength.

basic_string(size_typen,charTc)

Sequence

Createastringwithncopies
ofc.

template<classInputIterator>
basic_string(InputIteratorfirst,InputIteratorlast)

Sequence

Createastringfromarange.

~basic_string()

Container

Thedestructor.

basic_string&operator=(constbasic_string&)

Container

Theassignmentoperator

basic_string&operator=(constcharT*s)

basic_string

Assignanullterminated
characterarraytoastring.

basic_string&operator=(charTc)

basic_string

Assignasinglecharactertoa
string.

voidreserve(size_t)

basic_string

voidswap(basic_string&)

Container

Seebelow.
Swapsthecontentsoftwo
strings.

iteratorinsert(iteratorpos,
constT&x)

Sequence

Insertsxbeforepos.

template<classInputIterator>
voidinsert(iteratorpos,
InputIteratorf,InputIteratorl)

Sequence

Insertstherange[first,
last)beforepos.

voidinsert(iteratorpos,
size_typen,constT&x)

Sequence

Insertsncopiesofxbefore
pos.

basic_string&insert(size_typepos,constbasic_string&s)

basic_string

Insertssbeforepos.

basic_string&insert(size_typepos,
constbasic_string&s,
size_typepos1,size_typen)

basic_string

Insertsasubstringofsbefore
pos.

basic_string&insert(size_typepos,constcharT*s)

basic_string

Insertssbeforepos.

Insertsthefirstncharacters
ofsbeforepos.
basic_string Insertsncopiesofcbefore
pos.

basic_string&insert(size_typepos,constcharT*s,size_type basic_string
n)
basic_string&insert(size_typepos,size_typen,charTc)
basic_string&append(constbasic_string&s)

basic_string

Appendsto*this.

basic_string&append(constbasic_string&s,
size_typepos,size_typen)

basic_string

Appendasubstringofsto
*this.

basic_string&append(constcharT*s)

basic_string

Appendsto*this.

basic_string&append(constcharT*s,size_typen)

basic_string

basic_string&append(size_typen,charTc)

Appendthefirstncharacters
ofsto*this.
basic_string Appendncopiesofcto
*this.

template<classInputIterator>
basic_string
basic_string&append(InputIteratorfirst,InputIteratorlast)

Appendarangeto*this.

basic_string&operator+=(constbasic_string&s)

Appendasinglecharacterto
*this.
basic_string Equivalenttoappend(s).

basic_string&operator+=(constcharT*s)

basic_string

Equivalenttoappend(s)

basic_string&operator+=(charTc)

basic_string

Equivalenttopush_back(c)

iteratorerase(iteratorp)

Sequence

Erasesthecharacterat
positionp

iteratorerase(iteratorfirst,iteratorlast)

Sequence

Erasestherange[first,

voidpush_back(charTc)

basic_string

last)
basic_string&erase(size_typepos=0,size_typen=npos)

basic_string

Erasesarange.

voidclear()

Sequence

Erasestheentirecontainer.

voidresize(size_typen,charTc=charT())

Sequence

Appendscharacters,orerases
charactersfromtheend,as
necessarytomakethestring's
lengthexactlyncharacters.

basic_string&assign(constbasic_string&)

basic_string

Synonymforoperator=

basic_string&assign(constbasic_string&s,
size_typepos,size_typen)

basic_string

Assignsasubstringofsto

basic_string&assign(constcharT*s,size_typen)

basic_string

Assignsthefirstncharacters
ofsto*this.

basic_string&assign(constcharT*s)

basic_string

Assignsanullterminated
arrayofcharactersto*this.

basic_string&assign(size_typen,charTc)

Sequence

Erasestheexistingcharacters
andreplacesthembyncopies
ofc.

template<classInputIterator>
basic_string&assign(InputIteratorfirst,InputIteratorlast)

Sequence

Erasestheexistingcharacters
andreplacesthemby[first,

*this

last)
basic_string&replace(size_typepos,size_typen,
constbasic_string&s)

basic_string

Replacesasubstringof*this
withthestrings.

basic_string&replace(size_typepos,size_typen,
constbasic_string&s,
size_typepos1,size_typen1)

basic_string

Replacesasubstringof*this
withasubstringofs.

basic_string&replace(size_typepos,size_typen,
constcharT*s,size_typen1)

basic_string

Replacesasubstringof*this
withthefirstn1charactersof
s.

basic_string&replace(size_typepos,size_typen,
constcharT*s)

basic_string

Replacesasubstringof*this
withanullterminated
characterarray.

basic_string&replace(size_typepos,size_typen,
size_typen1,charTc)

basic_string

basic_string&replace(iteratorfirst,iteratorlast,
constbasic_string&s)

Replacesasubstringof*this
withn1copiesofc.
basic_string Replacesasubstringof*this
withthestrings.

basic_string&replace(iteratorfirst,iteratorlast,
constcharT*s,size_typen)

basic_string

Replacesasubstringof*this
withthefirstncharactersof
s.

basic_string&replace(iteratorfirst,iteratorlast,
constcharT*s)

basic_string

Replacesasubstringof*this
withanullterminated

basic_string&replace(iteratorfirst,iteratorlast,
size_typen,charTc)

characterarray.
basic_string Replacesasubstringof*this
withncopiesofc.

template<classInputIterator>
basic_string&replace(iteratorfirst,iteratorlast,
InputIteratorf,InputIteratorl)

basic_string

Replacesasubstringof*this
withtherange[f,l)

size_typecopy(charT*buf,size_typen,size_typepos=0)
const

basic_string

Copiesasubstringof*thisto
abuffer.

size_typefind(constbasic_string&s,size_typepos=0)
const

basic_string

size_typefind(constcharT*s,size_typepos,size_typen)
const

Searchesforsasasubstring
of*this,beginningat
characterposof*this.
basic_string Searchesforthefirstn
charactersofsasasubstring
of*this,beginningat
characterposof*this.

size_typefind(constcharT*s,size_typepos=0)const

basic_string

Searchesforanullterminated
characterarrayasasubstring
of*this,beginningat
characterposof*this.

size_typefind(charTc,size_typepos=0)const

basic_string

Searchesforthecharacterc,
beginningatcharacter
positionpos.

size_typerfind(constbasic_string&s,size_typepos=npos)
const

basic_string

Searchesbackwardforsasa
substringof*this,beginning
atcharacterpositionmin(pos,
size())

size_typerfind(constcharT*s,size_typepos,size_typen)
const

basic_string

Searchesbackwardforthe
firstncharactersofsasa
substringof*this,beginning
atcharacterpositionmin(pos,
size())

size_typerfind(constcharT*s,size_typepos=npos)const

basic_string

Searchesbackwardforanull
terminatedcharacterarrayas
asubstringof*this,
beginningatcharacter
min(pos,size())

size_typerfind(charTc,size_typepos=npos)const

basic_string

Searchesbackwardforthe
characterc,beginningat
characterpositionmin(pos,
size().

size_typefind_first_of(constbasic_string&s,size_typepos
=0)const

basic_string

Searcheswithin*this,
beginningatpos,forthefirst
characterthatisequaltoany
characterwithins.

size_typefind_first_of(constcharT*s,size_typepos,
size_typen)const

basic_string

Searcheswithin*this,
beginningatpos,forthefirst
characterthatisequaltoany
characterwithinthefirstn
charactersofs.

size_typefind_first_of(constcharT*s,size_typepos=0)
const

basic_string

Searcheswithin*this,
beginningatpos,forthefirst

size_typefind_first_of(charTc,size_typepos=0)const

size_typefind_first_not_of(constbasic_string&s,size_type
pos=0)const

size_typefind_first_not_of(constcharT*s,size_typepos,
size_typen)const

characterthatisequaltoany
characterwithins.
basic_string Searcheswithin*this,
beginningatpos,forthefirst
characterthatisequaltoc.
Searcheswithin*this,
beginningatpos,forthefirst
characterthatisnotequalto
anycharacterwithins.
basic_string Searcheswithin*this,
beginningatpos,forthefirst
characterthatisnotequalto
anycharacterwithinthefirst
ncharactersofs.
basic_string

basic_string

Searcheswithin*this,
beginningatpos,forthefirst
characterthatisnotequalto
anycharacterwithins.

size_typefind_first_not_of(charTc,size_typepos=0)const basic_string

Searcheswithin*this,
beginningatpos,forthefirst
characterthatisnotequalto
c.

size_typefind_first_not_of(constcharT*s,size_typepos=
0)const

size_typefind_last_of(constbasic_string&s,size_typepos= basic_string Searchesbackwardwithin

npos)const
*this,beginningatmin(pos,
size()),forthefirstcharacter

thatisequaltoanycharacter
withins.
size_typefind_last_of(constcharT*s,size_typepos,
size_typen)const

basic_string

Searchesbackwardwithin
*this,beginningatmin(pos,
size()),forthefirstcharacter
thatisequaltoanycharacter
withinthefirstncharactersof
s.

size_typefind_last_of(constcharT*s,size_typepos=npos)
const

basic_string

Searchesbackward*this,
beginningatmin(pos,
size()),forthefirstcharacter
thatisequaltoanycharacter
withins.

size_typefind_last_of(charTc,size_typepos=npos)const

basic_string

Searchesbackward*this,
beginningatmin(pos,
size()),forthefirstcharacter
thatisequaltoc.

size_typefind_last_not_of(constbasic_string&s,size_type
pos=npos)const

basic_string

Searchesbackwardwithin
*this,beginningatmin(pos,
size()),forthefirstcharacter
thatisnotequaltoany
characterwithins.

size_typefind_last_not_of(constcharT*s,size_typepos,
size_typen)const

basic_string

Searchesbackwardwithin
*this,beginningatmin(pos,
size()),forthefirstcharacter
thatisnotequaltoany

size_typefind_last_not_of(constcharT*s,size_typepos=
npos)const

characterwithinthefirstn
charactersofs.
basic_string Searchesbackward*this,
beginningatmin(pos,
size()),forthefirstcharacter
thatisnotequaltoany
characterwithins.

size_typefind_last_not_of(charTc,size_typepos=npos)
const

basic_string

Searchesbackward*this,
beginningatmin(pos,
size()),forthefirstcharacter
thatisnotequaltoc.

basic_stringsubstr(size_typepos=0,size_typen=npos)
const

basic_string

Returnsasubstringof*this.

intcompare(constbasic_string&s)const

basic_string

Threewaylexicographical
comparisonofsand*this.

intcompare(size_typepos,size_typen,constbasic_string&
s)const

basic_string

Threewaylexicographical
comparisonofsanda
substringof*this.

intcompare(size_typepos,size_typen,constbasic_string&
s,size_typepos1,size_typen1)const

basic_string

Threewaylexicographical
comparisonofasubstringof
sandasubstringof*this.

intcompare(constcharT*s)const

basic_string

Threewaylexicographical
comparisonofsand*this.

intcompare(size_typepos,size_typen,constcharT*s,
size_typelen=npos)const

basic_string

Threewaylexicographical
comparisonofthefirst
min(len,traits::length(s)
charactersofsanda
substringof*this.

template<classcharT,classtraits,classAlloc>
basic_string<charT,traits,Alloc>
operator+(constbasic_string<charT,traits,Alloc>&s1,
constbasic_string<charT,traits,Alloc>&s2)

basic_string

Stringconcatenation.A
globalfunction,notamember
function.

template<classcharT,classtraits,classAlloc>
basic_string<charT,traits,Alloc>
operator+(constcharT*s1,
constbasic_string<charT,traits,Alloc>&s2)

basic_string

Stringconcatenation.A
globalfunction,notamember
function.

template<classcharT,classtraits,classAlloc>
basic_string<charT,traits,Alloc>
operator+(constbasic_string<charT,traits,Alloc>&s1,
constcharT*s2)

basic_string

Stringconcatenation.A
globalfunction,notamember
function.

template<classcharT,classtraits,classAlloc>
basic_string<charT,traits,Alloc>
operator+(charTc,
constbasic_string<charT,traits,Alloc>&s2)

basic_string

Stringconcatenation.A
globalfunction,notamember
function.

template<classcharT,classtraits,classAlloc>
basic_string<charT,traits,Alloc>
operator+(constbasic_string<charT,traits,Alloc>&s1,
charTc)

basic_string

Stringconcatenation.A
globalfunction,notamember
function.

template<classcharT,classtraits,classAlloc>
booloperator==(constbasic_string<charT,traits,Alloc>&s1,
constbasic_string<charT,traits,Alloc>&s2)

Container

Stringequality.Aglobal
function,notamember
function.

template<classcharT,classtraits,classAlloc>
basic_string
booloperator==(constcharT*s1,
constbasic_string<charT,traits,Alloc>&s2)

Stringequality.Aglobal
function,notamember
function.

template<classcharT,classtraits,classAlloc>
basic_string
booloperator==(constbasic_string<charT,traits,Alloc>&s1,
constcharT*s2)
template<classcharT,classtraits,classAlloc>
booloperator!=(constbasic_string<charT,traits,Alloc>&s1,
constbasic_string<charT,traits,Alloc>&s2)

Container

Stringequality.Aglobal
function,notamember
function.
Stringinequality.Aglobal
function,notamember
function.

template<classcharT,classtraits,classAlloc>
basic_string
booloperator!=(constcharT*s1,
constbasic_string<charT,traits,Alloc>&s2)

Stringinequality.Aglobal
function,notamember
function.

template<classcharT,classtraits,classAlloc>
basic_string
booloperator!=(constbasic_string<charT,traits,Alloc>&s1,
constcharT*s2)

Stringinequality.Aglobal
function,notamember
function.

template<classcharT,classtraits,classAlloc>
booloperator<(constbasic_string<charT,traits,Alloc>&s1,
constbasic_string<charT,traits,Alloc>&s2)

Container

Stringcomparison.Aglobal
function,notamember
function.

template<classcharT,classtraits,classAlloc>
booloperator<(constcharT*s1,
constbasic_string<charT,traits,Alloc>&s2)

basic_string

Stringcomparison.Aglobal
function,notamember
function.

template<classcharT,classtraits,classAlloc>
booloperator<(constbasic_string<charT,traits,Alloc>&s1,
constcharT*s2)

basic_string

Stringcomparison.Aglobal
function,notamember
function.

template<classcharT,classtraits,classAlloc>
voidswap(basic_string<charT,traits,Alloc>&s1,
basic_string<charT,traits,Alloc>&s2)

Container

Swapsthecontentsoftwo
strings.

template<classcharT,classtraits,classAlloc>
basic_istream<charT,traits>&
operator>>(basic_istream<charT,traits>&is,
basic_string<charT,traits,Alloc>&s)

basic_string

Readssfromtheinputstream

template<classcharT,classtraits,classAlloc>
basic_ostream(charT,traits)&
operator<<(basic_ostream<charT,traits>&os,
basic_string<charT,traits,Alloc>&s)

basic_string

template<classcharT,classtraits,classAlloc>
basic_istream<charT,traits>&
getline(basic_istream<charT,traits>&is,
basic_string<charT,traits,Alloc>&s,
charTdelim)

basic_string

Readsastringfromtheinput
streamis,stoppingwhenit
reachesdelim

template<classcharT,classtraits,classAlloc>
basic_istream<charT,traits>&
getline(basic_istream<charT,traits>&is,
basic_string<charT,traits,Alloc>&s)

basic_string

Readsasinglelinefromthe
inputstreamis

is

Writesstotheoutputstream
os

Newmembers
ThesemembersarenotdefinedintheRandomAccessContainerandSequence:requirements,butarespecificto
basic_string.
Member
Description
staticconstsize_typenpos

Thelargestpossiblevalueof
typesize_type.Thatis,
size_type(1).

size_typelength()const

Equivalenttosize().

size_typecapacity()const

constcharT*c_str()const

Numberofelementsforwhich
memoryhasbeenallocated.
Thatis,thesizetowhichthe
stringcangrowbefore
memorymustbereallocated.
capacity()isalwaysgreater
thanorequaltosize().
Returnsapointertoanull
terminatedarrayofcharacters
representingthestring's
contents.Foranystringsitis
guaranteedthatthefirst
s.size()charactersinthe
arraypointedtobys.c_str()
areequaltothecharacterins,
andthats.c_str()[s.size()]
isanullcharacter.Note,
however,thatitnotnecessarily
thefirstnullcharacter.
Characterswithinastringare
permittedtobenull.

constcharT*data()const

Returnsapointertoanarrayof
characters,notnecessarily
nullterminated,representing
thestring'scontents.data()is
permitted,butnotrequired,to
beidenticaltoc_str().The
firstsize()charactersofthat
arrayareguaranteedtobe
identicaltothecharactersin
*this.Thereturnvalueof
data()isneveranullpointer,
evenifsize()iszero.

basic_string(constbasic_string&s,size_typepos=0,size_typen=npos)

Constructsastringfroma
substringofs.Thesubstring
beginsatcharacterpositionpos
andterminatesatcharacter
positionpos+norattheend
ofs,whichevercomesfirst.
Thisconstructorthrows
out_of_rangeifpos>
s.size().Notethatwhenpos
andnhavetheirdefaultvalues,
thisisjustacopyconstructor.

basic_string(constcharT*s)

Equivalenttobasic_string(s,
s+traits::length(s)).

basic_string(constcharT*s,size_typen)

Equivalenttobasic_string(s,
s+n).

basic_string&operator=(constcharT*s)

Equivalenttooperator=
(basic_string(s)).

basic_string&operator=(charTc)

Assignsto*thisastring
whosesizeis1andwhose

voidreserve(size_tn)

basic_string&insert(size_typepos,constbasic_string&s)

basic_string&insert(size_typepos,
constbasic_string&s,
size_typepos1,size_typen)

contentsisthesinglecharacter
c.
Requeststhatthestring's
capacitybechangedthe
postconditionforthismember
functionisthat,afteritis
called,capacity()>=n.You
mayrequestthatastring
decreaseitscapacitybycalling
reserve()withanargument
lessthanthecurrentcapacity.
(Ifyoucallreserve()withan
argumentlessthanthestring's
size,however,thecapacity
willonlybereducedtosize().
Astring'ssizecanneverbe
greaterthanitscapacity.)
reserve()throws
length_errorifn>
max_size().
Ifpos>size(),throws
out_of_range.Otherwise,
equivalenttoinsert(begin()
+pos,s.begin(),s.end()).
Ifpos>size()orpos1>
s.size(),throws
out_of_range.Otherwise,
equivalenttoinsert(begin()
+pos,s.begin()+pos1,
s.begin()+pos1+min(n,
s.size()pos1)).

basic_string&insert(size_typepos,constcharT*s)

Ifpos>size(),throws
out_of_range.Otherwise,
equivalenttoinsert(begin()
+pos,s,s+
traits::length(s))

basic_string&insert(size_typepos,constcharT*s,size_typen)

Ifpos>size(),throws
out_of_range.Otherwise,
equivalenttoinsert(begin()
+pos,s,s+n).

basic_string&insert(size_typepos,size_typen,charTc)

Ifpos>size(),throws
out_of_range.Otherwise,
equivalenttoinsert(begin()
+pos,n,c).

basic_string&append(constbasic_string&s)

Equivalenttoinsert(end(),
s.begin(),s.end()).

basic_string&append(constbasic_string&s,
size_typepos,size_typen)

Ifpos>s.size(),throws
out_of_range.Otherwise,
equivalenttoinsert(end(),
s.begin()+pos,s.begin()+
pos+min(n,s.size()
pos)).

basic_string&append(constcharT*s)

basic_string&append(constcharT*s,size_typen)

Equivalenttoinsert(end(),
s,s+traits::length(s)).
Equivalenttoinsert(end(),
s,s+n).

basic_string&append(size_typen,charTc)

Equivalenttoinsert(end(),
n,c).

template<classInputIterator>
basic_string&append(InputIteratorfirst,InputIteratorlast)

Equivalenttoinsert(end(),
first,last).
Equivalenttoinsert(end(),

voidpush_back(charTc)

c)
basic_string&operator+=(constbasic_string&s)

Equivalenttoappend(s).

basic_string&operator+=(constcharT*s)

Equivalenttoappend(s)

basic_string&operator+=(charTc)

Equivalenttopush_back(c)

basic_string&erase(size_typepos=0,size_typen=npos)

Ifpos>size(),throws
out_of_range.Otherwise,
equivalenttoerase(begin()+
pos,begin()+pos+min(n,
size()pos)).

basic_string&assign(constbasic_string&s)

Synonymforoperator=

basic_string&assign(constbasic_string&s,
size_typepos,size_typen)

Equivalentto(butprobably
fasterthan)clear()followed
byinsert(0,s,pos,n).

basic_string&assign(constcharT*s,size_typen)

Equivalentto(butprobably
fasterthan)clear()followed
byinsert(0,s,n).

basic_string&assign(constcharT*s)

Equivalentto(butprobably
fasterthan)clear()followed
byinsert(0,s).

basic_string&replace(size_typepos,size_typen,
constbasic_string&s)

Equivalenttoerase(pos,n)
followedbyinsert(pos,s).

basic_string&replace(size_typepos,size_typen,
constbasic_string&s,size_typepos1,size_typen1)

Equivalenttoerase(pos,n)
followedbyinsert(pos,s,
pos1,n1).

basic_string&replace(size_typepos,size_typen,
constcharT*s,size_typen1)

Equivalenttoerase(pos,n)
followedbyinsert(pos,s,
n1).

basic_string&replace(size_typepos,size_typen,
constcharT*s)

Equivalenttoerase(pos,n)
followedbyinsert(pos,s).

basic_string&replace(size_typepos,size_typen,
size_typen1,charTc)

Equivalenttoerase(pos,n)
followedbyinsert(pos,n1,
c).

basic_string&replace(iteratorfirst,iteratorlast,
constbasic_string&s)

Equivalentto

basic_string&replace(iteratorfirst,iteratorlast,
constcharT*s,size_typen)

Equivalentto

basic_string&replace(iteratorfirst,iteratorlast,

insert(erase(first,last),
s.begin(),s.end()).
insert(erase(first,last),
s,s+n).

constcharT*s)

Equivalentto
insert(erase(first,last),
s,s+traits::length(s)).

basic_string&replace(iteratorfirst,iteratorlast,
size_typen,charTc)

Equivalentto

template<classInputIterator>
basic_string&replace(iteratorfirst,iteratorlast,
InputIteratorf,InputIteratorl)

Equivalentto

size_typecopy(charT*buf,size_typen,size_typepos=0)const

Copiesatmostncharacters
from*thistoacharacter
array.Throwsout_of_rangeif
pos>size().Otherwise,
equivalenttocopy(begin()+

insert(erase(first,last),
n,c).
insert(erase(first,last),
f,l).

pos,begin()+pos+min(n,
size()),buf).Notethatthis

memberfunctiondoesnothing
otherthancopycharacters
from*thistobufin
particular,itdoesnotterminate
bufwithanullcharacter.
size_typefind(constbasic_string&s,size_typepos=0)const

Searchesforsasasubstringof
*this,beginningatcharacter
positionpos.Itisalmostthe
sameassearch,exceptthat
searchtestselementsfor
equalityusingoperator==ora
userprovidedfunctionobject,
whilethismemberfunction
usestraits::eq.Returnsthe
lowestcharacterpositionN
suchthatpos<=Nandpos+
s.size()<=size()andsuch
that,foreveryilessthan
s.size(),(*this)[N+i]
comparesequaltos[i].
Returnsnposifnosuch
positionNexists.Notethatitis
legaltocallthismember
functionwithargumentssuch
thats.size()>size()pos,
butsuchasearchwillalways
fail.

size_typefind(constcharT*s,size_typepos,size_typen)const

Searchesforthefirstn
charactersofsasasubstring
of*this,beginningat
characterposof*this.Thisis
equivalentto
find(basic_string(s,n),
pos).

size_typefind(constcharT*s,size_typepos=0)const

Searchesforanullterminated
characterarrayasasubstring
of*this,beginningat

size_typefind(charTc,size_typepos=0)const

characterposof*this.Thisis
equivalentto
find(basic_string(s),pos).
Searchesforthecharacterc,
beginningatcharacterposition
pos.Thatis,returnsthefirst
characterpositionNgreater
thanorequaltopos,andless
thansize(),suchthat(*this)
[N]comparesequaltoc.
Returnsnposifnosuch
characterpositionNexists.

size_typerfind(constbasic_string&s,size_typepos=npos)const

Searchesbackwardforsasa
substringof*this.Itisalmost
thesameasfind_end,except
thatfind_endtestselements
forequalityusingoperator==
orauserprovidedfunction
object,whilethismember
functionusestraits::eq.This
memberfunctionreturnsthe
largestcharacterpositionN
suchthatN<=posandN+
s.size()<=size(),andsuch
that,foreveryilessthan
s.size(),(*this)[N+i]
comparesequaltos[i].
Returnsnposifnosuch
positionNexists.Notethatitis
legaltocallthismember
functionwithargumentssuch
thats.size()>size(),but
suchasearchwillalwaysfail.

size_typerfind(constcharT*s,size_typepos,size_typen)const

Searchesbackwardforthefirst
ncharactersofsasasubstring
of*this.Equivalentto
rfind(basic_string(s,n),
pos).

size_typerfind(constcharT*s,size_typepos=npos)const

Searchesbackwardforanull
terminatedcharacterarrayasa
substringof*this.Equivalent
torfind(basic_string(s),
pos).

size_typerfind(charTc,size_typepos=npos)const

Searchesbackwardforthe
characterc.Thatis,returnsthe
largestcharacterpositionN
suchthatN<=posandN<
size(),andsuchthat(*this)
[N]comparesequaltoc.
Returnsnposifnosuch
characterpositionexists.

size_typefind_first_of(constbasic_string&s,size_typepos=0)const

Searcheswithin*this,

beginningatpos,forthefirst
characterthatisequaltoany
characterwithins.Thisis
similartothestandard
algorithmfind_first_of,but
differsbecausefind_first_of
comparescharactersusing
operator==orauserprovided
functionobject,whilethis
memberfunctionuses
traits::eq.Returnsthe
smallestcharacterpositionN
suchthatpos<=N<size(),
andsuchthat(*this)[N]
comparesequaltosome
characterwithins.Returns
nposifnosuchcharacter
positionexists.
size_typefind_first_of(constcharT*s,size_typepos,size_typen)const

Searcheswithin*this,
beginningatpos,forthefirst
characterthatisequaltoany
characterwithintherange[s,
s+n).Thatis,returnsthe
smallestcharacterpositionN
suchthatpos<=N<size(),
andsuchthat(*this)[N]
comparesequaltosome
characterin[s,s+n).Returns
nposifnosuchcharacter
positionexists.

size_typefind_first_of(constcharT*s,size_typepos=0)const

Equivalentto
find_first_of(s,pos,
traits::length(s)).

size_typefind_first_of(charTc,size_typepos=0)const

Equivalenttofind(c,pos).

size_typefind_first_not_of(constbasic_string&s,size_typepos=0)
const

Searcheswithin*this,
beginningatpos,forthefirst
characterthatisnotequalto
anycharacterwithins.Returns
thesmallestcharacterposition
Nsuchthatpos<=N<size(),
andsuchthat(*this)[N]does
notcompareequaltoany
characterwithins.Returns
nposifnosuchcharacter
positionexists.

size_typefind_first_not_of(constcharT*s,size_typepos,size_typen)
const

Searcheswithin*this,
beginningatpos,forthefirst
characterthatisnotequalto
anycharacterwithintherange
[s,s+n).Thatis,returnsthe
smallestcharacterpositionN
suchthatpos<=N<size(),

size_typefind_first_not_of(constcharT*s,size_typepos=0)const

andsuchthat(*this)[N]does
notcompareequaltoany
characterin[s,s+n).Returns
nposifnosuchcharacter
positionexists.
Equivalentto
find_first_not_of(s,pos,
traits::length(s)).

size_typefind_first_not_of(charTc,size_typepos=0)const

Returnsthesmallestcharacter
positionNsuchthatpos<=N<
size(),andsuchthat(*this)
[N]doesnotcompareequalto
c.Returnsnposifnosuch
characterpositionexists.

size_typefind_last_of(constbasic_string&s,size_typepos=npos)const

Searchesbackwardwithin
*thisforthefirstcharacter
thatisequaltoanycharacter
withins.Thatis,returnsthe
largestcharacterpositionN
suchthatN<=posandN<
size(),andsuchthat(*this)
[N]comparesequaltosome
characterwithins.Returns
nposifnosuchcharacter
positionexists.

size_typefind_last_of(constcharT*s,size_typepos,size_typen)const

Searchesbackwardwithin
*thisforthefirstcharacter
thatisequaltoanycharacter
withintherange[s,s+n).
Thatis,returnsthelargest
characterpositionNsuchthatN
<=posandN<size(),and
suchthat(*this)[N]compares
equaltosomecharacterwithin
[s,s+n).Returnsnposifno
suchcharacterpositionexists.

size_typefind_last_of(constcharT*s,size_typepos=npos)const

Equivalenttofind_last_of(s,
pos,traits::length(s)).

size_typefind_last_of(charTc,size_typepos=npos)const

Equivalenttorfind(c,pos).

size_typefind_last_not_of(constbasic_string&s,size_typepos=npos)
const

Searchesbackwardwithin
*thisforthefirstcharacter
thatisnotequaltoany
characterwithins.Thatis,
returnsthelargestcharacter
positionNsuchthatN<=pos
andN<size(),andsuchthat
(*this)[N]doesnotcompare
equaltoanycharacterwithins.
Returnsnposifnosuch
characterpositionexists.

size_typefind_last_not_of(constcharT*s,size_typepos,size_typen)
const

Searchesbackwardwithin
*thisforthefirstcharacter

size_typefind_last_not_of(constcharT*s,size_typepos=npos)const

thatisnotequaltoany
characterwithin[s,s+n).
Thatis,returnsthelargest
characterpositionNsuchthatN
<=posandN<size(),and
suchthat(*this)[N]doesnot
compareequaltoanycharacter
within[s,s+n).Returnsnpos
ifnosuchcharacterposition
exists.
Equivalenttofind_last_of(s,
pos,traits::length(s)).

size_typefind_last_not_of(charTc,size_typepos=npos)const

Searchesbackward*thisfor
thefirstcharacterthatisnot
equaltoc.Thatis,returnsthe
largestcharacterpositionN
suchthatN<=posandN<
size(),andsuchthat(*this)
[N]doesnotcompareequalto
c.

basic_stringsubstr(size_typepos=0,size_typen=npos)const

Equivalentto
basic_string(*this,pos,n).

intcompare(constbasic_string&s)const

Threewaylexicographical
comparisonofsand*this,
muchlikestrcmp.If
traits::compare(data,
s.data(),min(size(),
s.size()))isnonzero,thenit

intcompare(size_typepos,size_typen,constbasic_string&s)const

intcompare(size_typepos,size_typen,constbasic_string&s,size_type
pos1,size_typen1)const

returnsthatnonzerovalue.
Otherwisereturnsanegative
numberifsize()<s.size(),
apositivenumberifsize()>
s.size(),andzeroifthetwo
areequal.
Threewaylexicographical
comparisonofsanda
substringof*this.Equivalent
tobasic_string(*this,pos,
n).compare(s).
Threewaylexicographical
comparisonofasubstringofs
andasubstringof*this.
Equivalentto
basic_string(*this,pos,
n).compare(basic_string(s,
pos1,n1)).

intcompare(constcharT*s)const

Threewaylexicographical
comparisonofsand*this.
Equivalentto
compare(basic_string(s)).

intcompare(size_typepos,size_typen,constcharT*s,size_typelen=
npos)const

Threewaylexicographical
comparisonofthefirst
min(len,traits::length(s)

charactersofsandasubstring
of*this.Equivalentto
basic_string(*this,pos,
n).compare(basic_string(s,
min(len,
traits::length(s)))).
template<classcharT,classtraits,classAlloc>
basic_string<charT,traits,Alloc>
operator+(constbasic_string<charT,traits,Alloc>&s1,
constbasic_string<charT,traits,Alloc>&s2)

Stringconcatenation.
Equivalenttocreatinga
temporarycopyofs,
appendings2,andthen
returningthetemporarycopy.

template<classcharT,classtraits,classAlloc>
basic_string<charT,traits,Alloc>
operator+(constcharT*s1,
constbasic_string<charT,traits,Alloc>&s2)

Stringconcatenation.
Equivalenttocreatinga
temporarybasic_stringobject
froms1,appendings2,and
thenreturningthetemporary
object.

template<classcharT,classtraits,classAlloc>
basic_string<charT,traits,Alloc>
operator+(constbasic_string<charT,traits,Alloc>&s1,
constcharT*s2)

Stringconcatenation.
Equivalenttocreatinga
temporarycopyofs,
appendings2,andthen
returningthetemporarycopy.

template<classcharT,classtraits,classAlloc>
basic_string<charT,traits,Alloc>
operator+(charTc,
constbasic_string<charT,traits,Alloc>&s2)

Stringconcatenation.
Equivalenttocreatinga
temporaryobjectwiththe
constructorbasic_string(1,
c),appendings2,andthen
returningthetemporaryobject.

template<classcharT,classtraits,classAlloc>
basic_string<charT,traits,Alloc>
operator+(constbasic_string<charT,traits,Alloc>&s1,
charTc)

Stringconcatenation.
Equivalenttocreatinga
temporaryobject,appendingc
withpush_back,andthen
returningthetemporaryobject.

template<classcharT,classtraits,classAlloc>
booloperator==(constcharT*s1,
constbasic_string<charT,traits,Alloc>&s2)

Stringequality.Equivalentto

template<classcharT,classtraits,classAlloc>
booloperator==(constbasic_string<charT,traits,Alloc>&s1,
constcharT*s2)

Stringequality.Equivalentto

template<classcharT,classtraits,classAlloc>
booloperator!=(constcharT*s1,
constbasic_string<charT,traits,Alloc>&s2)

Stringinequality.Equivalentto

template<classcharT,classtraits,classAlloc>
booloperator!=(constbasic_string<charT,traits,Alloc>&s1,
constcharT*s2)

Stringinequality.Equivalentto

template<classcharT,classtraits,classAlloc>
booloperator<(constcharT*s1,
constbasic_string<charT,traits,Alloc>&s2)

Stringcomparison.Equivalent
to`(s1==s2)`.
Inadditionreturnswhetheror
nots1islexographicallylesser
thans2.

template<classcharT,classtraits,classAlloc>

Stringcomparison.Equivalent

basic_string(s1).compare(s2)
==0.
basic_string(s1).compare(s2)
==0.

basic_string(s1).compare(s2)
!=0.
basic_string(s1).compare(s2)
!=0.

booloperator<(constbasic_string<charT,traits,Alloc>&s1,
constcharT*s2)

to`(s1==s2)`.
Inadditionreturnswhetheror
nots1islexographicallylesser
thans2.

template<classcharT,classtraits,classAlloc>
basic_istream<charT,traits>&
operator>>(basic_istream<charT,traits>&is,
basic_string<charT,traits,Alloc>&s)

Readssfromtheinputstream
is.Specifically,itskips
whitespace,andthenreplaces
thecontentsofswith
charactersreadfromtheinput
stream.Itcontinuesreading
charactersuntilitencountersa
whitespacecharacter(inwhich
casethatcharacterisnot
extracted),oruntilendoffile,
or,ifis.width()isnonzero,
untilithasreadis.width()
characters.Thismember
functionresetsis.width()to
zero.

template<classcharT,classtraits,classAlloc>
basic_ostream<charT,traits>&
operator<<(basic_ostream<charT,traits>&is,
constbasic_string<charT,traits,Alloc>&s)

Writesstotheoutputstream
is.Itwritesmax(s.size(),
is.width())characters,
paddingasnecessary.This
memberfunctionresets
is.width()tozero.

template<classcharT,classtraits,classAlloc>
basic_istream<charT,traits>&
getline(basic_istream<charT,traits>&is,
basic_string<charT,traits,Alloc>&s,
charTdelim)

Replacesthecontentsofswith
charactersreadfromtheinput
stream.Itcontinuesreading
charactersuntilitencounters
thecharacterdelim(inwhich
casethatcharacterisextracted
butnotstoredins),oruntil
endoffile.Notethatgetline,
unlikeoperator>>,doesnot
skipwhitespace.Asthename
suggests,itismostcommonly
usedtoreadanentirelineof
textpreciselyastheline
appearsinaninputfile.
Equivalenttogetline(is,s,
is.widen('\n\)).

template<classcharT,classtraits,classAlloc>
basic_istream<charT,traits>&
getline(basic_istream<charT,traits>&is,
basic_string<charT,traits,Alloc>&s)

Notes
Seealso
rope,vector,CharacterTraits

STLMainPage

ContactUs|SiteMap|Trademarks|Privacy|UsingthissitemeansyouacceptitsTermsofUse
Copyright20092014SiliconGraphicsInternational.Allrightsreserved.