Classe basic_istream

Descreve um objeto que controla a extração de elementos e objetos codificados de um buffer de fluxo com elementos do tipo Char_T, também conhecido como char_type, cujas características de caractere são determinadas pela classe Tr, também conhecida como traits_type.

Sintaxe

template <class Char_T, class Tr = char_traits<Char_T>>
class basic_istream : virtual public basic_ios<Char_T, Tr>

Comentários

A maioria das funções de membro que sobrecarrega operator>> é composta por funções de entrada formatadas. Elas seguem o padrão:

iostate state = goodbit;
const sentry ok(*this);

if (ok)
{
    try
    {
        /*extract elements and convert
            accumulate flags in state.
            store a successful conversion*/
    }
    catch (...)
    {
        try
        {
            setstate(badbit);

        }
        catch (...)
        {
        }
        if ((exceptions()& badbit) != 0)
            throw;
    }
}
setstate(state);

return (*this);

Muitas outras funções membro são funções de entrada sem formatação. Elas seguem o padrão:

iostate state = goodbit;
count = 0;    // the value returned by gcount
const sentry ok(*this, true);

if (ok)
{
    try
    {
        /* extract elements and deliver
            count extracted elements in count
            accumulate flags in state */
    }
    catch (...)
    {
        try
        {
            setstate(badbit);

        }
        catch (...)
        {
        }
        if ((exceptions()& badbit) != 0)
            throw;
    }
}
setstate(state);

Ambos os grupos de funções chamam setstate(eofbit) se encontrarem o final do arquivo ao extrair elementos. Para obter mais informações, consulte setstate.

Um objeto da classe basic_istream<Char_T, Tr> armazena:

  • Um objeto base público virtual da classe basic_ios<Char_T, Tr>. Para obter mais informações, consulte basic_ios.

  • Uma contagem de extração para a última operação de entrada sem formatação (chamada count no código anterior).

Exemplo

Veja o exemplo da Classe basic_ifstream para saber mais sobre fluxos de entrada.

Construtores

Construtor Descrição
basic_istream Constrói um objeto do tipo basic_istream.

Funções de membro

Função de membro Descrição
gcount Retorna o número de caracteres lidos durante a última entrada sem formatação.
get Lê um ou mais caracteres do fluxo de entrada.
getline Lê uma linha do fluxo de entrada.
ignore Faz vários elementos serem ignorados na posição de leitura atual.
peek Retorna o próximo caractere a ser lido.
putback Coloca um caractere especificado no fluxo.
read Lê um número especificado de caracteres do fluxo e armazena-os em uma matriz.
readsome Ler apenas do buffer.
seekg Move a posição de leitura em um fluxo.
sentry A classe aninhada descreve um objeto cuja declaração estrutura as funções de entrada formatadas e as funções de entrada não formatadas.
swap Troca esse objeto basic_istream pelo parâmetro do objeto basic_istream fornecido.
sync Sincroniza o dispositivo de entrada associado ao fluxo com o buffer do fluxo.
tellg Relata a atual posição de leitura no fluxo.
unget Coloca o caractere lido mais recentemente de volta no fluxo.

Operadores

Operador Descrição
operator>> Chama uma função no fluxo de entrada ou lê dados formatados do fluxo de entrada.
operator= Atribui o basic_istream no lado direito do operador para esse objeto. Essa é uma atribuição de movimentação que envolve uma referência rvalue que não deixa uma cópia.

Requisitos

Cabeçalho: <istream>

Namespace: std

basic_istream::basic_istream

Constrói um objeto do tipo basic_istream.

explicit basic_istream(
    basic_streambuf<Char_T, Tr>* strbuf,
    bool _Isstd = false);

basic_istream(basic_istream&& right);

Parâmetros

strbuf
Um objeto do tipo basic_streambuf.

_Isstd
true se esse for um fluxo padrão; caso contrário, false.

right
Um objeto basic_istream a ser copiado.

Comentários

O primeiro construtor inicializa a classe base chamando init(strbuf). Ele também armazena zero na contagem de extração. Para obter mais informações, consulte init. E para obter mais informações sobre essa contagem de extração, consulte a seção Comentários do tópico de visão geral da Classe basic_istream.

O segundo construtor inicializa a classe base chamando move(right). Ele também armazena right.gcount() na contagem de extração e armazena zero na contagem de extração para right.

Exemplo

Veja o exemplo de basic_ifstream::basic_ifstream para saber mais sobre fluxos de entrada.

basic_istream::gcount

Retorna o número de caracteres lidos durante a última entrada sem formatação.

streamsize gcount() const;

Valor de retorno

A contagem de extração.

Comentários

Use basic_istream::get para ler caracteres não formatados.

Exemplo

// basic_istream_gcount.cpp
// compile with: /EHsc
#include <iostream>
using namespace std;

int main( )
{
   cout << "Type the letter 'a': ";

   ws( cin );
   char c[10];

   cin.get( &c[0],9 );
   cout << c << endl;

   cout << cin.gcount( ) << endl;
}
a
Type the letter 'a': a
1

basic_istream::get

Lê um ou mais caracteres do fluxo de entrada.

int_type get();

basic_istream<Char_T, Tr>& get(Char_T& Ch);
basic_istream<Char_T, Tr>& get(Char_T* str, streamsize count);
basic_istream<Char_T, Tr>& get(Char_T* str, streamsize count, Char_T delimiter);

basic_istream<Char_T, Tr>& get(basic_streambuf<Char_T, Tr>& strbuf);
basic_istream<Char_T, Tr>& get(basic_streambuf<Char_T, Tr>& strbuf, Char_T delimiter);

Parâmetros

count
O número de caracteres a serem lidos de strbuf.

delimiter
O caractere que deve terminar a leitura se for encontrado antes de count.

str
Uma cadeia de caracteres na qual gravar.

Ch
Um caractere a obter.

strbuf
Um buffer no qual gravar.

Valor de retorno

O formulário sem parâmetros de get retorna o elemento read como um inteiro ou fim do arquivo. Os formulários restantes retornaram o fluxo (*this).

Comentários

A primeira função de entrada não formatada extrai um elemento, se possível, como se retornando por rdbuf->sbumpc. Caso contrário, ele retornará traits_type::eof. Se a função não extrair nenhum elemento, ela chamará setstate(failbit). Para obter mais informações, consulte setstate.

A segunda função extrai o elemento int_type meta da mesma maneira. Se a comparação de meta for igual a traits_type::eof, a função chama setstate(failbit). Caso contrário, ela armazena traits_type::to_char_type(meta) em Ch. A função retorna *this. Para obter mais informações, consulte to_char_type.

A terceira função retorna get(str, count, widen('\n')).

A quarta função extrai até count - 1 elementos e armazena-os na matriz que começa em str. Ela sempre armazena char_type após quaisquer elementos extraídos que armazene. Em ordem de teste, a extração é interrompida:

  • Ao final do arquivo.

  • Depois que a função extrai um elemento que se compara como igual a delimiter. Nesse caso, o elemento é colocado de volta na sequência controlada.

  • Depois que a função extrai elementos count - 1.

Se a função não extrair nenhum elemento, ela chamará setstate(failbit). Em qualquer caso, retorna *this.

A quinta função retorna get(strbuf, widen('\n')).

A sexta função extrai elementos e insere-os em strbuf. A extração para no fim do arquivo ou em um elemento que é comparável a delimiter, que não é extraído. Ele também interrompe, sem extrair o elemento em questão, se uma inserção falhar ou gerar uma exceção (que é detectada, mas não gerada novamente). Se a função não extrair nenhum elemento, ela chamará setstate(failbit). Em qualquer caso, a função retorna *this.

Exemplo

// basic_istream_get.cpp
// compile with: /EHsc
#include <iostream>
using namespace std;

int main( )
{
   char c[10];

   c[0] = cin.get( );
   cin.get( c[1] );
   cin.get( &c[2],3 );
   cin.get( &c[4], 4, '7' );

   cout << c << endl;
}
1111

basic_istream::getline

Obtém uma linha do fluxo de entrada.

basic_istream<Char_T, Tr>& getline(
    char_type* str,
    streamsize count);

basic_istream<Char_T, Tr>& getline(
    char_type* str,
    streamsize count,
    char_type delimiter);

Parâmetros

count
O número de caracteres a serem lidos de strbuf.

delimiter
O caractere que deve terminar a leitura se for encontrado antes de count.

str
Uma cadeia de caracteres na qual gravar.

Valor de retorno

O fluxo (*this).

Comentários

A primeira dessas funções de entrada não formatadas retorna getline(str, count, widen('\n')).

A segunda função extrai até count - 1 elementos e armazena-os na matriz que começa em str. Ela sempre armazena o caractere de terminação de cadeia de caracteres depois de quaisquer os elementos extraídos que ela armazene. Em ordem de teste, a extração é interrompida:

  • Ao final do arquivo.

  • Depois que a função extrai um elemento que se compara como igual a delimiter. Nesse caso, o elemento não é colocado novamente e não é acrescentado à sequência controlada.

  • Depois que a função extrai elementos count - 1.

Se a função não extrair nenhum elemento ou elementos count - 1, ela chamará setstate(failbit). Em qualquer caso, retorna *this. Para obter mais informações, consulte setstate.

Exemplo

// basic_istream_getline.cpp
// compile with: /EHsc
#include <iostream>
using namespace std;

int main( )
{
   char c[10];

   cin.getline( &c[0], 5, '2' );
   cout << c << endl;
}
121

basic_istream::ignore

Faz vários elementos serem ignorados na posição de leitura atual.

basic_istream<Char_T, Tr>& ignore(
    streamsize count = 1,
    int_type delimiter = traits_type::eof());

Parâmetros

count
O número de elementos a ignorar da posição atual de leitura.

delimiter
O elemento que, se encontrado antes da contagem, faz com que ignore retorne, permitindo que todos os elementos após delimiter sejam lidos.

Valor de retorno

O fluxo (*this).

Comentários

A função de entrada não formatada extrai até count elementos e descarta-os. No entanto, se count for igual a numeric_limits<int>::max, é considerado como arbitrariamente grande. A extração para cedo no fim do arquivo ou em um elemento Ch, de modo que traits_type::to_int_type(Ch) é comparável a delimiter (que também é extraído). A função retorna *this. Para obter mais informações, consulte to_int_type.

Exemplo

// basic_istream_ignore.cpp
// compile with: /EHsc
#include <iostream>
int main( )
{
   using namespace std;
   char chararray[10];
   cout << "Type 'abcdef': ";
   cin.ignore( 5, 'c' );
   cin >> chararray;
   cout << chararray;
}
Type 'abcdef': abcdef
def

basic\_istream::operator>>

Chama uma função no fluxo de entrada ou lê dados formatados do fluxo de entrada.

basic_istream& operator>>(basic_istream& (* Pfn)(basic_istream&));
basic_istream& operator>>(ios_base& (* Pfn)(ios_base&));
basic_istream& operator>>(basic_ios<Char_T, Tr>& (* Pfn)(basic_ios<Char_T, Tr>&));
basic_istream& operator>>(basic_streambuf<Char_T, Tr>* strbuf);
basic_istream& operator>>(bool& val);
basic_istream& operator>>(short& val);
basic_istream& operator>>(unsigned short& val);
basic_istream& operator>>(int& val);
basic_istream& operator>>(unsigned int& val);
basic_istream& operator>>(long& val);
basic_istream& operator>>(unsigned long& val);
basic_istream& operator>>(long long& val);
basic_istream& operator>>(unsigned long long& val);
basic_istream& operator>>(void *& val);
basic_istream& operator>>(float& val);
basic_istream& operator>>(double& val);
basic_istream& operator>>(long double& val);

Parâmetros

Pfn
Um ponteiro de função.

strbuf
Um objeto do tipo stream_buf.

val
O valor a ser lido do fluxo.

Valor de retorno

O fluxo (*this).

Comentários

O cabeçalho <istream> também define vários operadores de extração global. Para obter mais informações, consulte operator>> (\<istream>).

A primeira função de membro garante que uma expressão do formulário istr >> ws chame ws(istr) e, em seguida, retorne *this. Para obter mais informações, consulte ws.

A segunda e a terceira funções garantem que outros manipuladores, como hex, comportem-se de modo semelhante. As funções restantes são as funções de entrada formatadas.

A função :

basic_istream& operator>>(
    basic_streambuf<Char_T, Tr>* strbuf);

extrai elementos se strbuf não for um ponteiro nulo e insere-os em strbuf. A extração para no fim do arquivo. Ela também parará sem extrair o elemento em questão se uma inserção falhar ou gerar uma exceção (que é detectada, mas não gerada novamente). Se a função não extrair nenhum elemento, ela chamará setstate(failbit). Em qualquer caso, a função retorna *this. Para obter mais informações, consulte setstate.

A função :

basic_istream& operator>>(bool& val);

extrai um campo e converte-o em um valor booliano chamando use_facet< num_get<Char_T, InIt>(getloc).get( InIt(rdbuf), Init(0), *this, getloc, val). Aqui, InIt é definido como istreambuf_iterator<Char_T, Tr>. A função retorna *this.

Para obter mais informações, consulte use_facet, getloc, get, rdbuf e istreambuf_iterator.

Cada uma das funções:

basic_istream& operator>>(short& val);
basic_istream& operator>>(unsigned short& val);
basic_istream& operator>>(int& val);
basic_istream& operator>>(unsigned int& val);
basic_istream& operator>>(long& val);
basic_istream& operator>>(unsigned long& val);
basic_istream& operator>>(long long& val);
basic_istream& operator>>(unsigned long long& val);
basic_istream& operator>>(void *& val);

extraem cada uma um campo e convertem-no em um valor numérico chamando use_facet<num_get<Char_T, InIt>(getloc).get(InIt(rdbuf), Init(0), *this, getloc, val). Aqui, InIt é definido como istreambuf_iterator<Char_T, Tr>, e val tem tipo long, unsigned long ou void *, conforme necessário.

Se o valor convertido não puder ser representado como o tipo de val, a função chamará setstate(failbit). Em qualquer caso, a função retorna *this. Para obter mais informações, consulte setstate.

Cada uma das funções:

basic_istream& operator>>(float& val);
basic_istream& operator>>(double& val);
basic_istream& operator>>(long double& val);

extraem cada uma um campo e convertem-no em um valor numérico chamando use_facet<num_get<Char_T, InIt>(getloc).get(InIt(rdbuf), Init(0), *this, getloc, val). Aqui, InIt é definido como istreambuf_iterator<Char_T, Tr>, e val tem tipo double ou long double, conforme necessário.

Se o valor convertido não puder ser representado como o tipo de val, a função chamará setstate(failbit). Em qualquer caso, retorna *this.

Exemplo

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

using namespace std;

ios_base& hex2( ios_base& ib )
{
   ib.unsetf( ios_base::dec );
   ib.setf( ios_base::hex );
   return ib;
}

basic_istream<char, char_traits<char> >& somefunc(basic_istream<char, char_traits<char> > &i)
{
   if ( i == cin )
   {
      cerr << "i is cin" << endl;
   }
   return i;
}

int main( )
{
   int i = 0;
   cin >> somefunc;
   cin >> i;
   cout << i << endl;
   cin >> hex2;
   cin >> i;
   cout << i << endl;
}

basic_istream::operator=

Atribui o basic_istream no lado direito do operador para esse objeto. Essa é uma atribuição de movimentação que envolve uma referência rvalue que não deixa uma cópia.

basic_istream& operator=(basic_istream&& right);

Parâmetros

right
Uma referência rvalue a um objeto basic_ifstream.

Valor de retorno

Retorna *this.

Comentários

O operador do membro chama swap(right).

basic_istream::peek

Retorna o próximo caractere a ser lido.

int_type peek();

Valor de retorno

O próximo caractere que será lido.

Comentários

A função de entrada não formatada extrai um elemento, se possível, como se estivesse retornando rdbuf->sgetc. Caso contrário, ele retornará traits_type::eof. Para obter mais informações, consulte sgetc e eof.

Exemplo

// basic_istream_peek.cpp
// compile with: /EHsc
#include <iostream>
using namespace std;

int main( )
{
   char c[10], c2;
   cout << "Type 'abcde': ";

   c2 = cin.peek( );
   cin.getline( &c[0], 9 );

   cout << c2 << " " << c << endl;
}
abcde
Type 'abcde': abcde
a abcde

basic_istream::putback

Coloca um caractere especificado no fluxo.

basic_istream<Char_T, Tr>& putback(
    char_type Ch);

Parâmetros

Ch
Um caractere a colocar de volta no fluxo.

Valor de retorno

O fluxo (*this).

Comentários

A função de entrada não formatada realoca Ch, se possível, como se estivesse chamando rdbuf->sputbackc. Se rdbuf for um ponteiro nulo ou se a chamada para sputbackc retornar traits_type::eof, a função chamará setstate(badbit). Em qualquer caso, retorna *this.

Para obter mais informações, consulte rdbuf, sputbackc, eof e setstate.

Exemplo

// basic_istream_putback.cpp
// compile with: /EHsc
#include <iostream>
using namespace std;

int main( )
{
   char c[10], c2, c3;

   c2 = cin.get( );
   c3 = cin.get( );
   cin.putback( c2 );
   cin.getline( &c[0], 9 );
   cout << c << endl;
}
qwq

basic_istream::read

Lê um número especificado de caracteres do fluxo e armazena-os em uma matriz.

Esse método pode não ser seguro, pois depende do chamador para verificar se os valores passados estão corretos.

basic_istream<Char_T, Tr>& read(
    char_type* str,
    streamsize count);

Parâmetros

str
A matriz na qual ler os caracteres.

count
O número de caracteres a serem lidos.

Valor de retorno

O fluxo ( *this).

Comentários

A função de entrada não formatada extrai até count elementos e armazena-os no início da matriz em str. A extração para cedo no fim do arquivo, caso em que a função chama setstate(failbit). Em qualquer caso, retorna *this. Para obter mais informações, consulte setstate.

Exemplo

// basic_istream_read.cpp
// compile with: /EHsc
#include <iostream>
using namespace std;

int main()
{
    char c[10];
    int count = 5;

    cout << "Type 'abcde': ";

    // Note: cin::read is potentially unsafe, consider
    // using cin::_Read_s instead.
    cin.read(&c[0], count);
    c[count] = 0;

    cout << c << endl;
}
abcde
Type 'abcde': abcde
abcde

basic_istream::readsome

Lê o número especificado de valores de caractere.

Esse método pode não ser seguro, pois depende do chamador para verificar se os valores passados estão corretos.

streamsize readsome(
    char_type* str,
    streamsize count);

Parâmetros

str
A matriz na qual readsome armazena os caracteres que lê.

count
O número de caracteres a serem lidos.

Valor de retorno

O número de caracteres de fato lidos, gcount.

Comentários

Essa função de entrada não formatada extrai até count elementos do fluxo de entrada e armazena-os na matriz str.

Essa função não aguarda entradas. Ela lê os dados que estão disponíveis.

Exemplo

// basic_istream_readsome.cpp
// compile with: /EHsc /W3
#include <iostream>
using namespace std;

int main( )
{
   char c[10];
   int count = 5;

   cout << "Type 'abcdefgh': ";

   // cin.read blocks until user types input.
   // Note: cin::read is potentially unsafe, consider
   // using cin::_Read_s instead.
   cin.read(&c[0], 2);

   // Note: cin::readsome is potentially unsafe, consider
   // using cin::_Readsome_s instead.
   int n = cin.readsome(&c[0], count);  // C4996
   c[n] = 0;
   cout << n << " characters read" << endl;
   cout << c << endl;
}

basic_istream::seekg

Move a posição de leitura em um fluxo.

basic_istream<Char_T, Tr>& seekg(pos_type pos);

basic_istream<Char_T, Tr>& seekg(off_type off, ios_base::seekdir way);

Parâmetros

pos
A posição absoluta na qual mover o ponteiro de leitura.

off
Um deslocamento para mover o ponteiro de leitura com relação a way.

way
Uma das enumerações de ios_base::seekdir.

Valor de retorno

O fluxo (*this).

Comentários

A primeira função membro realiza uma busca absoluta, a segunda função membro executa uma busca relativa.

Observação

Não use a segunda função membro com arquivos de texto, porque C++ Padrão não dá suporte a buscas relativas em arquivos de texto.

If fail for false, a primeira função de membro chama newpos = rdbuf->pubseekpos(pos) para algum objeto temporário pos_type newpos. Se fail for false, a segunda função chama newpos = rdbuf->pubseekoff( off, way). Em ambos os casos, se for (off_type)newpos == (off_type)(-1) (a operação de posicionamento falhar), a função chama istr.setstate(failbit). Ambas as funções retornam *this.

Se fail for true, as funções de membro não farão nada.

Para obter mais informações, consulte rdbuf, pubseekpos, pubseekoff e setstate.

Exemplo

// basic_istream_seekg.cpp
// compile with: /EHsc
#include <iostream>
#include <fstream>

int main ( )
{
   using namespace std;
   ifstream file;
   char c, c1;

   file.open( "basic_istream_seekg.txt" );
   file.seekg(2);   // seek to position 2
   file >> c;
   cout << c << endl;
}

basic_istream::sentry

A classe aninhada descreve um objeto cuja declaração estrutura as funções de entrada formatadas e não formatadas.

class sentry {
   public:
   explicit sentry(
      basic_istream<Char_T, Tr>& _Istr,
      bool _Noskip = false);
   operator bool() const;
   };

Comentários

Se _Istr.good for true, o construtor:

  • Chama _Istr.tie->flush se _Istr.tie não for um ponteiro nulo.

  • Efetivamente chama ws(_Istr) se _Istr.flags & skipws não for zero.

Se após tal preparação, _Istr.good for false o construtor chamará _Istr.setstate(failbit). Em qualquer caso, o construtor armazena o valor retornado por _Istr.good em status. Uma chamada posterior para operator bool entrega esse valor armazenado.

Para obter mais informações, consulte good, tie, flush, ws, flags, skipws e setstate.

basic_istream::swap

Troca o conteúdo de dois basic_istream objetos.

void swap(basic_istream& right);

Parâmetros

right
Uma referência lvalue a um objeto basic_istream.

Comentários

Essa função membro chama basic_ios::swap(right). Ela também troca a contagem de extração com a contagem de extração para right. Para obter mais informações, consulte basic_ios::swap.

basic_istream::sync

Sincroniza o dispositivo de entrada associado ao fluxo com o buffer do fluxo.

int sync();

Valor de retorno

Se rdbuf for um ponteiro nulo, a função retornará -1. Caso contrário, ela chamará rdbuf->pubsync. Se essa chamada retornar -1, a função chamará setstate(badbit) e retornará -1. Caso contrário, a função retorna zero. Para obter mais informações, consulte pubsync e setstate.

basic_istream::tellg

Relata a atual posição de leitura no fluxo.

pos_type tellg();

Valor de retorno

A posição atual no fluxo.

Comentários

Se fail for false, a função de membro retornará rdbuf->pubseekoff(0, cur, in). Caso contrário, ele retornará pos_type(-1). Para obter mais informações, consulte rdbuf e pubseekoff.

Exemplo

// basic_istream_tellg.cpp
// compile with: /EHsc
#include <iostream>
#include <fstream>

int main()
{
    using namespace std;
    ifstream file;
    char c;
    streamoff i;

    file.open("basic_istream_tellg.txt");
    i = file.tellg();
    file >> c;
    cout << c << " " << i << endl;

    i = file.tellg();
    file >> c;
    cout << c << " " << i << endl;
}

basic_istream::unget

Coloca o caractere lido mais recentemente de volta no fluxo.

basic_istream<Char_T, Tr>& unget();

Valor de retorno

O fluxo (*this).

Comentários

A função de entrada não formatada coloca de volta o elemento anterior no fluxo, se possível, como se estivesse chamando rdbuf->sungetc. Se rdbuf for um ponteiro nulo ou se a chamada para sungetc retornar traits_type::eof, a função chamará setstate(badbit). Em qualquer caso, retorna *this.

Para obter mais informações, consulte sungetc, eof e setstate. E para obter informações sobre como unget pode falhar, consulte basic_streambuf::sungetc.

Exemplo

// basic_istream_unget.cpp
// compile with: /EHsc
#include <iostream>
using namespace std;

int main( )
{
   char c[10], c2;

   cout << "Type 'abc': ";
   c2 = cin.get( );
   cin.unget( );
   cin.getline( &c[0], 9 );
   cout << c << endl;
}
abc
Type 'abc': abc
abc

Confira também

Acesso Thread-Safe na Biblioteca Padrão C++
Programação iostream
Convenções iostreams