Clase basic_istream

Describe un objeto que controla la extracción de elementos y objetos codificados de un búfer de flujo con elementos de tipo Char_T, también conocido como char_type, cuyos rasgos de caracteres están determinados por la clase Tr, también conocida como traits_type.

Sintaxis

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

Comentarios

La mayoría de las funciones miembro que sobrecargan operator>> son funciones de entrada con formato. Siguen el patrón:

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);

Muchas otras funciones miembro son funciones de entrada sin formato. Siguen el patrón:

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 grupos de funciones llaman a setstate(eofbit) si encuentran el final del archivo al extraer los elementos. Para obtener más información, vea setstate.

Un objeto de clase basic_istream<Char_T, Tr> almacena:

  • Un objeto base público virtual de clase basic_ios<Char_T, Tr>. Para obtener más información, vea basic_ios.

  • Un recuento de extracción de la última operación de entrada sin formato (denominada count en el código anterior).

Ejemplo

Vea el ejemplo de la clase basic_ifstreampara obtener más información sobre los flujos de entrada.

Constructores

Constructor Descripción
basic_istream Construye un objeto de tipo basic_istream.

Funciones miembro

Función de miembro Descripción
gcount Devuelve el número de caracteres leídos durante la última entrada sin formato.
get Lee uno o varios caracteres del flujo de entrada.
getline Lee una línea del flujo de entrada.
ignore Hace que se omita una serie de elementos desde la posición de lectura actual.
peek Devuelve el siguiente carácter que se debe leer.
putback Coloca un carácter especificado en la secuencia.
read Lee un número especificado de caracteres de la secuencia y los almacena en una matriz.
readsome Solo lee del búfer.
seekg Mueve la posición de lectura de una secuencia.
sentry La clase anidada describe un objeto cuya declaración estructura las funciones de entrada con y sin formato.
swap Intercambia este objeto basic_istream por el parámetro del objeto basic_istream proporcionado.
sync Sincroniza el dispositivo de entrada asociado a la secuencia con el búfer de la secuencia.
tellg Notifica la posición de lectura actual en la secuencia.
unget Devuelve el último carácter leído a la secuencia.

Operadores

Operador Descripción
operator>> Llama a una función del flujo de entrada o lee datos con formato del flujo de entrada.
operator= Asigna a este objeto el basic_istream de la parte derecha del operador. Se trata de una asignación de movimiento con una referencia a rvalue que no deja ninguna copia.

Requisitos

Encabezado<istream>:

Espacio de nombres:std

basic_istream::basic_istream

Construye un objeto de tipo basic_istream.

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

basic_istream(basic_istream&& right);

Parámetros

strbuf
Objeto de tipo basic_streambuf.

_Isstd
true si se trata de un flujo estándar; de lo contrario, false.

right
Objeto basic_istream que se va a copiar.

Comentarios

El primer constructor inicializa la clase base al llamar a init(strbuf). También almacena cero en el recuento de extracción. Para obtener más información, vea init. Para más información sobre este recuento de extracción, consulte la sección Comentarios de introducción a la clase basic_istream.

El segundo constructor inicializa la clase base al llamar a move(right). También almacena right.gcount() en el recuento de extracción y almacena cero en el recuento de extracción para right.

Ejemplo

Vea el ejemplo de basic_ifstream::basic_ifstream para más información sobre los flujos de entrada.

basic_istream::gcount

Devuelve el número de caracteres leídos durante la última entrada sin formato.

streamsize gcount() const;

Valor devuelto

Recuento de extracción.

Comentarios

Use basic_istream::get para leer caracteres sin formato.

Ejemplo

// 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

Lee uno o varios caracteres del flujo 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
Número de caracteres que se van a leer desde strbuf.

delimiter
Carácter que debe finalizar la lectura si se encuentra antes de count.

str
Cadena en la que se va a escribir.

Ch
Carácter que se va a obtener.

strbuf
Búfer en el que se va a escribir.

Valor devuelto

El formato sin parámetros de get devuelve el elemento read como un entero o el final del archivo. Los formularios restantes devuelven el flujo (*this).

Comentarios

La primera función de entrada sin formato extrae un elemento, si es posible, como si devolviera rdbuf->sbumpc. De lo contrario, devuelve traits_type::eof. Si la función no extrae ningún elemento, llama a setstate(failbit). Para obtener más información, vea setstate.

La segunda función extrae el elemento int_typemeta del mismo modo. Si meta se compara en relación de igualdad con traits_type::eof, la función llama a setstate(failbit). De lo contrario, almacena traits_type::to_char_type(meta) en Ch. La función devuelve *this. Para obtener más información, vea to_char_type.

La tercera función devuelve get(str, count, widen('\n')).

La cuarta función extrae hasta count - 1 elementos y los almacena en la matriz a partir de str. Siempre almacena char_type después de cualquier elemento extraído que almacene. Para realizar pruebas, la extracción se detiene:

  • Al final del archivo.

  • Después de que la función extraiga un elemento que resulta igual a delimiter. En este caso, el elemento se vuelve a colocar en la secuencia controlada.

  • Después de que la función extraiga count - 1 elementos.

Si la función no extrae ningún elemento, llama a setstate(failbit). En cualquier caso, devuelve *this.

La quinta función devuelve get(strbuf, widen('\n')).

La sexta función extrae los elementos y los inserta en strbuf. La extracción se detiene al final del archivo o en un elemento que se compara con relación de igualdad con delimiter, que no se extrae. También se detiene sin extraer el elemento en cuestión si se produce un error en una inserción o si se inicia una excepción (que se detecta pero no vuelve a iniciarse). Si la función no extrae ningún elemento, llama a setstate(failbit). En cualquier caso, la función devuelve *this.

Ejemplo

// 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

Obtiene una línea del flujo 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
Número de caracteres que se van a leer desde strbuf.

delimiter
Carácter que debe finalizar la lectura si se encuentra antes de count.

str
Cadena en la que se va a escribir.

Valor devuelto

La secuencia (*this).

Comentarios

La primera de estas funciones de entrada sin formato devuelve getline(str, count, widen('\n')).

La segunda función extrae hasta count - 1 elementos y los almacena en la matriz a partir de str. Siempre almacena el carácter de fin de cadena después de los elementos extraídos que almacena. Para realizar pruebas, la extracción se detiene:

  • Al final del archivo.

  • Después de que la función extraiga un elemento que resulta igual a delimiter. En este caso, el elemento no se devuelve y no se anexa a la secuencia controlada.

  • Después de que la función extraiga count - 1 elementos.

Si la función no extrae ningún elemento o elementos count - 1, llama a setstate(failbit). En cualquier caso, devuelve *this. Para obtener más información, vea setstate.

Ejemplo

// 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

Hace que se omita una serie de elementos desde la posición de lectura actual.

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

Parámetros

count
Número de elementos que se van a omitir desde la posición de lectura actual.

delimiter
Elemento que, si se encuentra antes del recuento, provoca la devolución de ignore y permite que todos los elementos después de delimiter se lean.

Valor devuelto

La secuencia (*this).

Comentarios

La función de entrada sin formato extrae hasta count elementos y los descarta. Pero si count es igual a numeric_limits<int>::max, se toma como arbitrariamente grande. La extracción se detiene anticipadamente al final del archivo o en un elemento Ch, de modo que traits_type::to_int_type(Ch) se compara con relación de igualdad con delimiter (que también se extrae). La función devuelve *this. Para obtener más información, vea to_int_type.

Ejemplo

// 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>>

Llama a una función del flujo de entrada o lee datos con formato del flujo 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
Puntero de función.

strbuf
Objeto de tipo stream_buf.

val
Valor que se va a leer desde el flujo.

Valor devuelto

La secuencia (*this).

Comentarios

El encabezado <istream> también define varios operadores de extracción globales. Para obtener más información, vea operator>> (\<istream>).

La primera función miembro garantiza que una expresión con el formato istr >> ws llame a ws(istr) y luego devuelva *this. Para obtener más información, vea ws.

Las funciones segunda y tercera garantizan que los demás manipuladores, como hex, se comporten de forma similar. Las funciones restantes son las funciones de entrada con formato.

La función :

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

extrae elementos si strbuf no es un puntero nulo y los inserta en strbuf. La extracción se detiene al final del archivo. También se detiene sin extraer el elemento en cuestión si se produce un error en una inserción o si se inicia una excepción (que se detecta pero no vuelve a iniciarse). Si la función no extrae ningún elemento, llama a setstate(failbit). En cualquier caso, la función devuelve *this. Para obtener más información, vea setstate.

La función :

basic_istream& operator>>(bool& val);

extrae un campo y lo convierte en un valor booleano mediante una llamada a use_facet< num_get<Char_T, InIt>(getloc).get( InIt(rdbuf), Init(0), *this, getloc, val). Aquí, InIt se define como istreambuf_iterator<Char_T, Tr>. La función devuelve *this.

Para más información, consulte use_facet, getloc, get, rdbuf y istreambuf_iterator.

Cada una de las funciones:

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);

extrae un campo y lo convierte en un valor numérico llamando a use_facet<num_get<Char_T, InIt>(getloc).get(InIt(rdbuf), Init(0), *this, getloc, val). Aquí, InIt se define como istreambuf_iterator<Char_T, Tr> y val tiene el tipo long, unsigned long o void * según sea necesario.

Si el valor convertido no se puede representar como el tipo de val, la función llama a setstate(failbit). En cualquier caso, la función devuelve *this. Para obtener más información, vea setstate.

Cada una de las funciones:

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

extrae un campo y lo convierte en un valor numérico llamando a use_facet<num_get<Char_T, InIt>(getloc).get(InIt(rdbuf), Init(0), *this, getloc, val). Aquí, InIt se define como istreambuf_iterator<Char_T, Tr> y val tiene el tipo double o long double según sea necesario.

Si el valor convertido no se puede representar como el tipo de val, la función llama a setstate(failbit). En cualquier caso, devuelve *this.

Ejemplo

// 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=

Asigna a este objeto el basic_istream de la parte derecha del operador. Se trata de una asignación de movimiento con una referencia a rvalue que no deja ninguna copia.

basic_istream& operator=(basic_istream&& right);

Parámetros

right
Referencia rvalue a un objeto basic_ifstream.

Valor devuelto

Devuelve *this.

Comentarios

El operador miembro llama a swap(right).

basic_istream::peek

Devuelve el siguiente carácter que se debe leer.

int_type peek();

Valor devuelto

Siguiente carácter que se va a leer.

Comentarios

La función de entrada sin formato extrae un elemento, si es posible, como si devolviera rdbuf->sgetc. De lo contrario, devuelve traits_type::eof. Para obtener más información, vea sgetc y eof.

Ejemplo

// 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 un carácter especificado en la secuencia.

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

Parámetros

Ch
Carácter que se va a volver a colocar en el flujo.

Valor devuelto

La secuencia (*this).

Comentarios

La función de entrada sin formato vuelve a colocar Ch, si es posible, como si llamara a rdbuf->sputbackc. Si rdbuf es un puntero nulo o si la llamada a sputbackc devuelve traits_type::eof, la función llama a setstate(badbit). En cualquier caso, devuelve *this.

Para obtener más información, veardbuf, sputbackc, eofy setstate.

Ejemplo

// 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

Lee un número especificado de caracteres de la secuencia y los almacena en una matriz.

Este método es potencialmente inseguro, ya que se basa en el llamador para comprobar que los valores pasados son correctos.

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

Parámetros

str
Matriz en la que se van a leer los caracteres.

count
Número de caracteres que se va a leer.

Valor devuelto

Flujo (*this).

Comentarios

La función de entrada sin formato extrae hasta count elementos y los almacena en la matriz a partir de str. La extracción se detiene anticipadamente al final del archivo, en cuyo caso la función llama a setstate(failbit). En cualquier caso, devuelve *this. Para obtener más información, vea setstate.

Ejemplo

// 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

Lee el número especificado de valores de carácter.

Este método es potencialmente inseguro, ya que se basa en el llamador para comprobar que los valores pasados son correctos.

streamsize readsome(
    char_type* str,
    streamsize count);

Parámetros

str
Matriz en la que readsome almacena los caracteres que lee.

count
Número de caracteres que se va a leer.

Valor devuelto

Número de caracteres que realmente se va a leer, gcount

Comentarios

Esta función de entrada sin formato extrae hasta count elementos del flujo de entrada y los almacena en la matriz str.

Esta función no espera a la entrada. Lee aquellos datos que estén disponibles.

Ejemplo

// 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

Mueve la posición de lectura de una secuencia.

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
Posición absoluta a la que se va a mover el puntero de lectura.

off
Desplazamiento para mover el puntero de lectura en relación con way.

way
Una de las ios_base::seekdir enumeraciones.

Valor devuelto

La secuencia (*this).

Comentarios

La primera función miembro realiza una búsqueda absoluta y la segunda una búsqueda relativa.

Nota:

No use la segunda función miembro con archivos de texto, ya que el estándar de C++ no admite las búsquedas relativas en archivos de texto.

Si fail es false, la primera función miembro llama a newpos = rdbuf->pubseekpos(pos) para algún pos_type de objeto temporal newpos. Si fail es false, la segunda función llama a newpos = rdbuf->pubseekoff( off, way). En cualquier caso, si (off_type)newpos == (off_type)(-1) (se produce un error en la operación de posicionamiento), la función llama a istr.setstate(failbit). Ambas funciones devuelven *this.

Si fail es true, las funciones miembro no hacen nada.

Para obtener más información, veardbuf, pubseekpos, pubseekoffy setstate.

Ejemplo

// 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

La clase anidada describe un objeto cuya declaración estructura las funciones de entrada con y sin formato.

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

Comentarios

Si _Istr.good es true, el constructor:

  • Llama a _Istr.tie->flush si _Istr.tie no es un puntero nulo.

  • Llama eficazmente a ws(_Istr) si _Istr.flags & skipws no es cero.

Si después de dicha preparación, _Istr.good es false, el constructor llama a _Istr.setstate(failbit). En cualquier caso, el constructor almacena el valor devuelto por _Istr.good en status. Una llamada posterior a operator bool devuelve este valor almacenado.

Para más información, consulte good, tie, flush, ws, flags, skipws y setstate.

basic_istream::swap

Intercambia el contenido de dos objetos basic_istream.

void swap(basic_istream& right);

Parámetros

right
Referencia lvalue a un objeto basic_istream.

Comentarios

La función miembro llama a basic_ios::swap(right). También intercambia el recuento de extracción por el recuento de extracción de right. Para obtener más información, vea basic_ios::swap.

basic_istream::sync

Sincroniza el dispositivo de entrada asociado a la secuencia con el búfer de la secuencia.

int sync();

Valor devuelto

Si rdbuf es un puntero nulo, la función devuelve -1. En caso contrario, llama a rdbuf->pubsync. Si esa llamada devuelve -1, la función llama a setstate(badbit) y devuelve -1. De lo contrario, la función devuelve cero. Para obtener más información, vea pubsync y setstate.

basic_istream::tellg

Notifica la posición de lectura actual en la secuencia.

pos_type tellg();

Valor devuelto

La posición actual en la secuencia.

Comentarios

Si fail es false, la función miembro devuelve rdbuf->pubseekoff(0, cur, in). De lo contrario, devuelve pos_type(-1). Para obtener más información, vea rdbuf y pubseekoff.

Ejemplo

// 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

Devuelve el último carácter leído a la secuencia.

basic_istream<Char_T, Tr>& unget();

Valor devuelto

La secuencia (*this).

Comentarios

La función de entrada sin formato devuelve el elemento anterior en la secuencia, si es posible, como si llamara a rdbuf->sungetc. Si rdbuf es un puntero nulo o si la llamada a sungetc devuelve traits_type::eof, la función llama a setstate(badbit). En cualquier caso, devuelve *this.

Para obtener más información, vea sungetc, eof y setstate. Y para obtener información sobre cómo unget podría producir un error, consulte basic_streambuf::sungetc.

Ejemplo

// 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

Consulte también

Seguridad para subprocesos en la biblioteca estándar de C++
Programación de iostream
Convenciones de iostreams