Funções <string>

  • Artigo

getline
stod
stof
stoi
stol
stold
stoll
stoul
stoull
swap
to_string
to_wstring

getline

Extrai cadeias de caracteres do fluxo de entrada linha por linha.

// (1) delimiter as parameter
template <class CharType, class Traits, class Allocator>
basic_istream<CharType, Traits>& getline(
    basic_istream<CharType, Traits>& in_stream,
    basic_string<CharType, Traits, Allocator>& str,
    CharType delimiter);

template <class CharType, class Traits, class Allocator>
basic_istream<CharType, Traits>& getline(
    basic_istream<CharType, Traits>&& in_stream,
    basic_string<CharType, Traits, Allocator>& str,
    const CharType delimiter);

// (2) default delimiter used
template <class CharType, class Traits, class Allocator>
basic_istream<CharType, Traits>& getline(
    basic_istream<CharType, Traits>& in_stream,
    basic_string<CharType, Traits, Allocator>& str);

template <class Allocator, class Traits, class Allocator>
basic_istream<Allocator, Traits>& getline(
    basic_istream<Allocator, Traits>&& in_stream,
    basic_string<Allocator, Traits, Allocator>& str);

Parâmetros

in_stream
O fluxo de entrada do qual uma cadeia de caracteres será extraída.

str
A cadeia de caracteres na qual são lidos os caracteres do fluxo de entrada.

delimiter
O delimitador de linha.

Valor de Devolução

O fluxo de entrada in_stream.

Comentários

O par de assinaturas de função marcado (1) extrai caracteres de in_stream até que delimiter seja encontrado, armazenando-os em str.

O par de assinaturas de função marcado (2) usa nova linha como delimitador de linha padrão e se comporta como getline(in_stream, str, in_stream. widen('\n')).

A segunda função de cada par é análoga à primeira para dar suporte a referências rvalue.

A extração é interrompida quando ocorre uma das seguintes situações:

  • No final do arquivo, caso em que o estado interno do sinalizador de in_stream está definido como ios_base::eofbit.

  • Depois que a função extrai um elemento que se compara como igual a delimiter. O elemento não é colocado nem acrescentado à sequência controlada.

  • Depois que a função extrai elementos str.max_size. O estado interno do sinalizador de in_stream está definido como ios_base::failbit.

  • Algum outro erro que não os listados anteriormente; o sinalizador de estado interno de in_stream é definido como ios_base::badbit.

Para informações sobre os sinalizadores de estado interno, confira ios_base::iostate.

Se a função não extrair elementos, o estado interno do sinalizador de in_stream será definido como ios_base::failbit. Em qualquer caso, getline retorna in_stream.

Se uma exceção for gerada, in_stream e str serão deixados em um estado válido.

Exemplo

O código a seguir demonstra getline() em dois modos: primeiro com o delimitador padrão (nova linha) e a segundo com um espaço em branco como delimitador. O caractere de final de arquivo (CTRL-Z no teclado) é usado para controlar a terminação de loops while. Esse valor define o sinalizador de estado interno de cin para eofbit, que deve ser limpo com basic_ios::clear() antes que o segundo, enquanto o loop funcionará corretamente.

// compile with: /EHsc /W4
#include <string>
#include <iostream>
#include <vector>

using namespace std;

int main()
{
    string str;
    vector<string> v1;
    cout << "Enter a sentence, press ENTER between sentences. (Ctrl-Z to stop): " << endl;
    // Loop until end-of-file (Ctrl-Z) is input, store each sentence in a vector.
    // Default delimiter is the newline character.
    while (getline(cin, str)) {
        v1.push_back(str);
    }

    cout << "The following input was stored with newline delimiter:" << endl;
    for (const auto& p : v1) {
        cout << p << endl;
    }

    cin.clear();

    vector<string> v2;
    // Now try it with a whitespace delimiter
    while (getline(cin, str, ' ')) {
        v2.push_back(str);
    }

    cout << "The following input was stored with whitespace as delimiter:" << endl;
    for (const auto& p : v2) {
        cout << p << endl;
    }
}

stod

Converte uma sequência de caracteres em um double.

double stod(
    const string& str,
    size_t* idx = 0);

double stod(
    const wstring& str,
    size_t* idx = 0
;

Parâmetros

str
A sequência de caracteres a ser convertida.

idx
O valor de índice do primeiro caractere não convertido.

Valor de Devolução

O valor double.

Comentários

A função converte a sequência de elementos em str em um valor do tipo double como se fosse chamar strtod( str.c_str(), _Eptr), em que _Eptr é um objeto interno da função. Se str.c_str() == *_Eptr, gerará um objeto do tipo invalid_argument. Se tal chamada definir errno, gerará um objeto do tipo out_of_range. Caso contrário, se idx não for um ponteiro nulo, a função armazenará *_Eptr - str.c_str() em *idx e retornará o valor.

stof

Converte uma sequência de caracteres em um float.

float stof(
    const string& str,
    size_t* idx = 0);

float stof(
    const wstring& str,
    size_t* idx = 0);

Parâmetros

str
A sequência de caracteres a ser convertida.

idx
O valor de índice do primeiro caractere não convertido.

Valor de Devolução

O valor float.

Comentários

A função converte a sequência de elementos em str em um valor do tipo float como se fosse chamar strtof( str.c_str(), _Eptr), em que _Eptr é um objeto interno da função. Se str.c_str() == *_Eptr, gerará um objeto do tipo invalid_argument. Se tal chamada definir errno, gerará um objeto do tipo out_of_range. Caso contrário, se idx não for um ponteiro nulo, a função armazenará *_Eptr - str.c_str() em *idx e retornará o valor.

stoi

Converte uma sequência de caracteres em um número inteiro.

int stoi(
    const string& str,
    size_t* idx = 0,
    int base = 10);

int stoi(
    const wstring& str,
    size_t* idx = 0,
    int base = 10);

Valor de Devolução

O valor inteiro.

Parâmetros

str
A sequência de caracteres a ser convertida.

idx
O valor de índice do primeiro caractere não convertido.

base
O número base a usar.

Comentários

A função stoi converte a sequência de caracteres em str em um valor do tipo int e retorna o valor. Por exemplo, quando foi passada uma sequência de caracteres "10", o valor retornado por stoi é o inteiro 10.

stoi comporta-se de modo semelhante à função strtol para caracteres de byte único quando é chamado na forma strtol( str.c_str(), _Eptr, idx), em que _Eptr é um objeto interno à função; ou wcstol para caracteres largos, quando é chamado de maneira semelhante, wcstol(Str.c_str(), _Eptr, idx). Para mais informações, confira strtol, wcstol, _strtol_l, _wcstol_l.

Se str.c_str() == *_Eptr, stoi gera um objeto do tipo invalid_argument. Se tal chamada definir errno ou se o valor retornado não puder ser representado como um objeto do tipo int, ele gerará um objeto do tipo out_of_range. Caso contrário, se idx não for um ponteiro nulo, a função armazenará *_Eptr - str.c_str() em *idx.

stol

Converte uma sequência de caracteres em um long.

long stol(
    const string& str,
    size_t* idx = 0,
    int base = 10);

long stol(
    const wstring& str,
    size_t* idx = 0,
    int base = 10);

Parâmetros

str
A sequência de caracteres a ser convertida.

idx
O valor de índice do primeiro caractere não convertido.

base
O número base a usar.

Valor de Devolução

O valor de inteiro longo.

Comentários

A função converte a sequência de elementos em str em um valor do tipo long como se fosse chamar strtol( str.c_str(), _Eptr, idx), em que _Eptr é um objeto interno da função. Se str.c_str() == *_Eptr, gerará um objeto do tipo invalid_argument. Se tal chamada definir errno, gerará um objeto do tipo out_of_range. Caso contrário, se idx não for um ponteiro nulo, a função armazenará *_Eptr - str.c_str() em *idx e retornará o valor.

stold

Converte uma sequência de caracteres em um long double.

double stold(
    const string& str,
    size_t* idx = 0);

double stold(
    const wstring& str,
    size_t* idx = 0);

Parâmetros

str
A sequência de caracteres a ser convertida.

idx
O valor de índice do primeiro caractere não convertido.

Valor de Devolução

O valor long double.

Comentários

A função converte a sequência de elementos em str em um valor do tipo long double como se fosse chamar strtold( str.c_str(), _Eptr), em que _Eptr é um objeto interno da função. Se str.c_str() == *_Eptr, gerará um objeto do tipo invalid_argument. Se tal chamada definir errno, gerará um objeto do tipo out_of_range. Caso contrário, se idx não for um ponteiro nulo, a função armazenará *_Eptr - str.c_str() em *idx e retornará o valor.

stoll

Converte uma sequência de caracteres em um long long.

long long stoll(
    const string& str,
    size_t* idx = 0,
    int base = 10);

long long stoll(
    const wstring& str,
    size_t* idx = 0,
    int base = 10);

Parâmetros

str
A sequência de caracteres a ser convertida.

idx
O valor de índice do primeiro caractere não convertido.

base
O número base a usar.

Valor de Devolução

O valor long long.

Comentários

A função converte a sequência de elementos em str em um valor do tipo long long como se fosse chamar strtoll( str.c_str(), _Eptr, idx), em que _Eptr é um objeto interno da função. Se str.c_str() == *_Eptr, gerará um objeto do tipo invalid_argument. Se tal chamada definir errno, gerará um objeto do tipo out_of_range. Caso contrário, se não for um ponteiro nulo, a função armazenará na *_Eptr - str.c_str() e retornará *idx.

stoul

Converte uma sequência de caracteres em um unsigned long.

unsigned long stoul(
    const string& str,
    size_t* idx = 0,
    int base = 10);

unsigned long stoul(
    const wstring& str,
    size_t* idx = 0,
    int base = 10);

Parâmetros

str
A sequência de caracteres a ser convertida.

idx
O valor de índice do primeiro caractere não convertido.

base
O número base a usar.

Valor de Devolução

O valor de inteiro longo não marcado.

Comentários

A função converte a sequência de elementos em str em um valor do tipo unsigned long como se fosse chamar strtoul( str.c_str(), _Eptr, idx), em que _Eptr é um objeto interno da função. Se str.c_str() == *_Eptr, gerará um objeto do tipo invalid_argument. Se tal chamada definir errno, gerará um objeto do tipo out_of_range. Caso contrário, se não for um ponteiro nulo, a função armazenará na *_Eptr - str.c_str() e retornará *idx.

stoull

Converte uma sequência de caracteres em um unsigned long long.

unsigned long long stoull(
    const string& str,
    size_t* idx = 0,
    int base = 10);

unsigned long long stoull(
    const wstring& str,
    size_t* idx = 0,
    int base = 10);

Parâmetros

str
A sequência de caracteres a ser convertida.

idx
O valor de índice do primeiro caractere não convertido.

base
O número base a usar.

Valor de Devolução

O valor unsigned long long.

Comentários

A função converte a sequência de elementos em str em um valor do tipo unsigned long long como se fosse chamar strtoull( str.c_str(), _Eptr, idx), em que _Eptr é um objeto interno da função. Se str.c_str() == *_Eptr, gerará um objeto do tipo invalid_argument. Se tal chamada definir errno, gerará um objeto do tipo out_of_range. Caso contrário, se idx não for um ponteiro nulo, a função armazenará *_Eptr - str.c_str() em *idx e retornará o valor.

swap

Troca as matrizes de caracteres de duas cadeias de caracteres.

template <class Traits, class Allocator>
void swap(basic_string<CharType, Traits, Allocator>& left, basic_string<CharType, Traits, Allocator>& right);

Parâmetros

left
Uma cadeia de caracteres cujos elementos devem ser trocado pelos elementos de outra cadeia de caracteres.

right
A outra sequência cujos elementos devem ser trocados pela primeira cadeia de caracteres.

Comentários

A função de modelo executa a função de membro especializado left.swap (right) para cadeias de caracteres, que garante complexidade constante.

Exemplo

// string_swap.cpp
// compile with: /EHsc
#include <string>
#include <iostream>

int main( )
{
   using namespace std;
   // Declaring an object of type basic_string<char>
   string s1 ( "Tweedledee" );
   string s2 ( "Tweedledum" );
   cout << "Before swapping string s1 and s2:" << endl;
   cout << "The basic_string s1 = " << s1 << "." << endl;
   cout << "The basic_string s2 = " << s2 << "." << endl;

   swap ( s1 , s2 );
   cout << "\nAfter swapping string s1 and s2:" << endl;
   cout << "The basic_string s1 = " << s1 << "." << endl;
   cout << "The basic_string s2 = " << s2 << "." << endl;
}

Before swapping string s1 and s2:
The basic_string s1 = Tweedledee.
The basic_string s2 = Tweedledum.

After swapping string s1 and s2:
The basic_string s1 = Tweedledum.
The basic_string s2 = Tweedledee.

to_string

Converte um valor em uma string.

string to_string(int value);
string to_string(unsigned int value);
string to_string(long value);
string to_string(unsigned long value);
string to_string(long long value);
string to_string(unsigned long long value);
string to_string(float value);
string to_string(double value);
string to_string(long double value);

Parâmetros

value
O valor a ser convertido.

Valor de Devolução

A string que representa o valor.

Comentários

A função converte value em uma sequência de elementos armazenados em um objeto de matriz Buf interna para a função como na chamada de sprintf(Buf, Fmt, value), em que Fmt será

  • "%d" se value for do tipo int

  • "%u" se value for do tipo unsigned int

  • "%ld" se value for do tipo long

  • "%lu" se value for do tipo unsigned long

  • "%lld" se value for do tipo long long

  • "%llu" se value for do tipo unsigned long long

  • "%f" se value for do tipo float ou double

  • "%Lf" se value for do tipo long double

A função retorna string(Buf).

to_wstring

Converte um valor em uma cadeia de caracteres larga.

wstring to_wstring(int value);
wstring to_wstring(unsigned int value);
wstring to_wstring(long value);
wstring to_wstring(unsigned long value);
wstring to_wstring(long long value);
wstring to_wstring(unsigned long long value);
wstring to_wstring(float value);
wstring to_wstring(double value);
wstring to_wstring(long double value);

Parâmetros

value
O valor a ser convertido.

Valor de Devolução

A cadeia de caracteres larga que representa o valor.

Comentários

A função converte value em uma sequência de elementos armazenados em um objeto de matriz Buf interna para a função como na chamada de swprintf(Buf, Len, Fmt, value), em que Fmt será

  • L"%d" se value for do tipo int

  • L"%u" se value for do tipo unsigned int

  • L"%ld" se value for do tipo long

  • L"%lu" se value for do tipo unsigned long

  • L"%lld" se value for do tipo long long

  • L"%llu" se value for do tipo unsigned long long

  • L"%f" se value for do tipo float ou double

  • L"%Lf" se value for do tipo long double

A função retorna wstring(Buf).

Confira também

<string>