Funções `<string>`

Artigo
08/04/2024

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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>

Compartilhar via

Funções <string>

getline

Parâmetros

Valor de retorno

Comentários

Exemplo

stod

Parâmetros

Valor de retorno

Comentários

stof

Parâmetros

Valor de retorno

Comentários

stoi

Valor de retorno

Parâmetros

Comentários

stol

Parâmetros

Valor de retorno

Comentários

stold

Parâmetros

Valor de retorno

Comentários

stoll

Parâmetros

Valor de retorno

Comentários

stoul

Parâmetros

Valor de retorno

Comentários

stoull

Parâmetros

Valor de retorno

Comentários

swap

Parâmetros

Comentários

Exemplo

to_string

Parâmetros

Valor de retorno

Comentários

to_wstring

Parâmetros

Valor de retorno

Comentários

Confira também

Comentários

Recursos adicionais

Funções `<string>`

`getline`

`stod`

`stof`

`stoi`

`stol`

`stold`

`stoll`

`stoul`

`stoull`

`swap`

`to_string`

`to_wstring`