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, veabasic_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_ifstream
para 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_type
meta
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
, eof
y 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
, pubseekoff
y 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
Vea también
Seguridad para subprocesos en la biblioteca estándar de C++
Programación de iostream
Convenciones de iostreams