Класс basic_istream

Описывает объект, который управляет извлечением элементов и закодированными объектами из буфера потока с элементами типа Char_T, также известным как char_type, признаки символов которого определяются классом Tr, также известным как traits_type.

Синтаксис

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

Замечания

Большинство функций-членов, которые перегружены operator>> , форматируют входные функции. Они следуют этому шаблону:

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

Многие другие функции-члены — это неформатированные входные функции. Они следуют этому шаблону:

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

Обе группы функций вызываются setstate(eofbit) при обнаружении конца файла при извлечении элементов. Дополнительные сведения см. в разделе setstate.

Объект класса basic_istream<Char_T, Tr> хранит:

  • Виртуальный общедоступный базовый объект класса basic_ios<Char_T, Tr>. Дополнительные сведения см. в разделе basic_ios.

  • Счетчик извлечения для последней неформатированных входных операций (вызывается count в предыдущем коде).

Пример

Дополнительные сведения о входных потоках см. в примере basic_ifstream класса .

Конструкторы

Конструктор Description
basic_istream Создает объект типа basic_istream.

Функции элементов

Функция-член Description
gcount Возвращает число символов, считанных во время последнего неформатированного ввода.
get Считывает один или несколько символов из входного потока.
getline Считывает строку из входного потока.
ignore Пропускает несколько элементов после текущей позиции чтения.
peek Возвращает следующий символ для чтения.
putback Помещает указанный символ в поток.
read Считывает указанное количество символов из потока и сохраняет их в массиве.
readsome Чтение только из буфера.
seekg Перемещает позицию чтения в потоке.
sentry Вложенный класс описывает объект, объявление которого структурирует форматированные и неформатированные входные функции.
swap Меняет местами этот объект basic_istream с указанным параметром объекта basic_istream.
sync Синхронизирует связанное с потоком устройство ввода с буфером потока.
tellg Сообщает текущую позицию чтения в потоке.
unget Помещает самый последний считанный символ обратно в поток.

Операторы

Operator Description
operator>> Вызывает функцию для входного потока или считывает форматированные данные из входного потока.
operator= Назначает basic_istream справа от оператора этому объекту. Это назначение перемещения, включающее ссылку rvalue , которая не оставляет копию позади.

Требования

Заголовок.<istream>

Пространство именstd:

basic_istream::basic_istream

Создает объект типа basic_istream.

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

basic_istream(basic_istream&& right);

Параметры

strbuf
Объект типа basic_streambuf.

_Isstd
true Значение , если это стандартный поток; falseв противном случае .

right
Объект basic_istream для копирования.

Замечания

Первый конструктор инициализирует базовый класс путем вызова init(strbuf). Он также хранит нуль в счетчике извлечений. Дополнительные сведения см. в разделе init. Дополнительные сведения об этом количестве извлечения см. в разделе "Примечания" в обзоре basic_istream класса .

Второй конструктор инициализирует базовый класс путем вызова move(right). Он также сохраняет в счетчике извлечения и сохраняет right.gcount() ноль в счетчике извлечения для right.

Пример

Дополнительные сведения о входных потоках см. в примере basic_ifstream::basic_ifstream .

basic_istream::gcount

Возвращает число символов, считанных во время последнего неформатированного ввода.

streamsize gcount() const;

Возвращаемое значение

Счетчик извлечений.

Замечания

Используется basic_istream::get для чтения неформатированных символов.

Пример

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

Считывает один или несколько символов из входного потока.

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

Параметры

count
Число символов для чтения из strbuf.

delimiter
Символ, который должен завершить чтение, если он обнаружен раньше count.

str
Строка, в которую должна выполняться запись.

Ch
Символ для получения.

strbuf
Буфер, в который должна выполняться запись.

Возвращаемое значение

Без параметров форма get возвращает элемент, считываемый как целое число или конец файла. Остальные формы возвращают поток (*this).

Замечания

Первая неформатированная входная функция извлекает элемент, если это возможно, как будто возвращается rdbuf->sbumpc. В противном случае возвращается значение traits_type::eof. Если функция извлекает элемент без элемента, вызывается setstate(failbit). Дополнительные сведения см. в разделе setstate.

Вторая функция извлекает int_type элемент meta таким же образом. Если meta сравнивается равным traits_type::eof, вызывается setstate(failbit)функция. В противном случае он хранится traits_type::to_char_type(meta) в Ch. Функция возвращает *this. Дополнительные сведения см. в разделе to_char_type.

Третья функция возвращается get(str, count, widen('\n')).

Четвертая функция извлекает элементы count - 1 и сохраняет их в массиве, начиная с str. Она всегда сохраняет char_type после сохранения всех извлеченных элементов. В целях тестирования извлечение останавливается:

  • в конце файла;

  • После извлечения элемента, который сравнивается с delimiter. В этом случае элемент возвращается к управляемой последовательности.

  • После извлечения count - 1 элементов функции.

Если функция не извлекает ни один элемент, она вызывает setstate(failbit). В любом случае она возвращает *this.

Возвращается пятая функция get(strbuf, widen('\n')).

Шестая функция извлекает элементы и вставляет их в strbuf. Извлечение останавливается в конце файла или на элементе, который сравнивается с равным delimiter, который не извлекается. Оно также останавливается без извлечения соответствующего элемента, если вставка завершается неудачно или создает исключение (которое перехватывается, но не создается повторно). Если функция не извлекает ни один элемент, она вызывает setstate(failbit). В любом случае функция возвращается *this.

Пример

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

Получает строку из входного потока.

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

Параметры

count
Число символов для чтения из strbuf.

delimiter
Символ, который должен завершить чтение, если он обнаружен раньше count.

str
Строка, в которую должна выполняться запись.

Возвращаемое значение

Поток (*this).

Замечания

Первая из этих неформатированных входных функций возвращается getline(str, count, widen('\n')).

Вторая функция извлекает элементы count - 1 и сохраняет их в массиве, начиная с str. Она всегда сохраняет символ окончания строки после сохранения всех извлеченных элементов. В целях тестирования извлечение останавливается:

  • в конце файла;

  • После извлечения элемента, который сравнивается с delimiter. В этом случае элемент не помещается обратно, и он не добавляется к управляемой последовательности.

  • После извлечения count - 1 элементов функции.

Если функция извлекает элементы или count - 1 элементы, вызывается setstate(failbit). В любом случае она возвращает *this. Дополнительные сведения см. в разделе setstate.

Пример

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

Пропускает несколько элементов после текущей позиции чтения.

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

Параметры

count
Количество пропускаемых элементов от текущей позиции чтения.

delimiter
Элемент, который, если обнаружен до подсчета, вызывает ignore возврат и разрешение всех элементов после delimiter чтения.

Возвращаемое значение

Поток (*this).

Замечания

Неформатированная входная функция извлекает до count элементов и удаляет их. Однако если count равно numeric_limits<int>::max, оно принимается как произвольно большое. Извлечение останавливается рано на конце файла или на элементе Ch , который traits_type::to_int_type(Ch) сравнивается с delimiter (который также извлекается). Функция возвращает *this. Дополнительные сведения см. в разделе to_int_type.

Пример

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

Вызывает функцию для входного потока или считывает форматированные данные из входного потока.

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

Параметры

Pfn
Указатель функции.

strbuf
Объект типа stream_buf.

val
Значение для чтения из потока.

Возвращаемое значение

Поток (*this).

Замечания

Заголовок <istream> также определяет несколько глобальных операторов извлечения. Дополнительные сведения см. в разделе operator>> (\<istream>).

Первая функция-член гарантирует, что выражение вызовов ws(istr)формistr >> ws, а затем возвращается*this. Дополнительные сведения см. в разделе ws.

Второй и третий функции обеспечивают аналогичное поведение других манипуляторов, таких как hex. Остальные функции — это отформатированные входные функции.

Функция :

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

извлекает элементы, если strbuf не является пустым указателем, и вставляет их в strbuf. Извлечение останавливается в конце файла. Оно также останавливается без извлечения соответствующего элемента, если вставка завершается неудачно, или создает исключение (которое перехватывается, но не создается повторно). Если функция не извлекает ни один элемент, она вызывает setstate(failbit). В любом случае функция возвращается *this. Дополнительные сведения см. в разделе setstate.

Функция :

basic_istream& operator>>(bool& val);

извлекает поле и преобразует его в логическое значение путем вызова use_facet< num_get<Char_T, InIt>(getloc).get( InIt(rdbuf), Init(0), *this, getloc, val). InIt Здесь определяется как istreambuf_iterator<Char_T, Tr>. Функция возвращает *this.

Дополнительные сведения см. в разделе use_facet, getloc, get, rdbufи istreambuf_iterator.

Каждая из функций:

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

извлеките поле и преобразуйте его в числовое значение путем вызова use_facet<num_get<Char_T, InIt>(getloc).get(InIt(rdbuf), Init(0), *this, getloc, val). InIt Здесь определяется как valistreambuf_iterator<Char_T, Tr>и имеет тип longunsigned longили void * по мере необходимости.

Если преобразованное значение не может быть представлено как тип val, вызывается setstate(failbit)функция. В любом случае функция возвращается *this. Дополнительные сведения см. в разделе setstate.

Каждая из функций:

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

извлеките поле и преобразуйте его в числовое значение путем вызова use_facet<num_get<Char_T, InIt>(getloc).get(InIt(rdbuf), Init(0), *this, getloc, val). InIt Здесь определяется как istreambuf_iterator<Char_T, Tr>val и имеет тип double или long double по мере необходимости.

Если преобразованное значение не может быть представлено как тип val, вызывается setstate(failbit)функция. В любом случае она возвращает *this.

Пример

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

Назначает basic_istream справа от оператора этому объекту. Это назначение перемещения, включающее ссылку rvalue , которая не оставляет копию позади.

basic_istream& operator=(basic_istream&& right);

Параметры

right
Ссылка rvalue на объект basic_ifstream.

Возвращаемое значение

Возвращает *this.

Замечания

Оператор-член вызывает swap(right).

basic_istream::peek

Возвращает следующий символ для чтения.

int_type peek();

Возвращаемое значение

Следующий символ для чтения.

Замечания

Неформатированная входная функция извлекает элемент, если это возможно, как будто возвращается rdbuf->sgetc. В противном случае возвращается значение traits_type::eof. Дополнительные сведения см. в разделах sgetc и eof.

Пример

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

Помещает указанный символ в поток.

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

Параметры

Ch
Символ для помещения обратно в поток.

Возвращаемое значение

Поток (*this).

Замечания

Неформатированные входные функции возвращаются Ch, если это возможно, как при вызове rdbuf->sputbackc. Если rdbuf имеет значение NULL, или если вызов sputbackc возвращается traits_type::eof, функция вызывается setstate(badbit). В любом случае она возвращает *this.

Дополнительные сведения см. в разделе rdbuf, sputbackc, eof, и setstate.

Пример

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

Считывает указанное количество символов из потока и сохраняет их в массиве.

Этот метод является потенциально опасным, так как зависит от вызывающего объекта при проверке правильности переданных значений.

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

Параметры

str
Массив, из которого должны считываться символы.

count
Число символов для чтения.

Возвращаемое значение

Поток ( *this).

Замечания

Неформатированная входная функция извлекает элементы count и сохраняет их в массиве, начиная с str. Извлечение останавливается рано в конце файла, в этом случае вызовы setstate(failbit)функции. В любом случае она возвращает *this. Дополнительные сведения см. в разделе setstate.

Пример

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

Считывает указанное число значений символов.

Этот метод является потенциально опасным, так как зависит от вызывающего объекта при проверке правильности переданных значений.

streamsize readsome(
    char_type* str,
    streamsize count);

Параметры

str
Массив, в котором readsome сохраняет символы, которые считывает.

count
Число символов для чтения.

Возвращаемое значение

Количество символов, которые фактически считываются, gcount.

Замечания

Эта неформатированная входная функция извлекает до count элементов и сохраняет их в массив str.

Эта функция не ожидает входных данных. Она считывает все доступные данные.

Пример

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

Перемещает позицию чтения в потоке.

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

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

Параметры

pos
Абсолютное положение, в которое следует переместить указатель чтения.

off
Смещение для перемещения указателя чтения относительно way.

way
Одно из перечислений ios_base::seekdir .

Возвращаемое значение

Поток (*this).

Замечания

Первая функция-член выполняет как абсолютный поиск, вторая функция-член выполняет относительный поиск.

Примечание.

Не используйте вторую функцию-член с текстовыми файлами, так как стандартный C++ не поддерживает относительный поиск в текстовых файлах.

Если fail это false, первый вызов newpos = rdbuf->pubseekpos(pos)функции-член для некоторых временных pos_type объектов newpos. В противном случае failfalseвторой вызов newpos = rdbuf->pubseekoff( off, way)функции. В любом случае, если (off_type)newpos == (off_type)(-1) (операция размещения завершается ошибкой), вызов функции istr.setstate(failbit). Обе функции возвращают значение *this.

Если fail есть true, функции-члены ничего не делают.

Дополнительные сведения см. в разделе rdbuf, pubseekpos, pubseekoff, и setstate.

Пример

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

Вложенный класс описывает объект, объявление которого структурирует форматированные и неформатированные входные функции.

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

Замечания

В противном случае _Istr.goodtrueконструктор:

  • Вызовы _Istr.tie->flush , если _Istr.tie не является пустым указателем.

  • Фактически вызывается ws(_Istr) , если _Istr.flags & skipws ненулевое значение.

Если после какой-либо такой подготовки, _Istr.goodfalseконструктор вызывает _Istr.setstate(failbit). В любом случае конструктор сохраняет значение, возвращаемое _Istr.good в status. Последующий вызов для operator bool доставки этого сохраненного значения.

Дополнительные сведения см. в разделе good, , wstieflush, , flags, skipwsи setstate.

basic_istream::swap

Меняет местами содержимое двух объектов basic_istream.

void swap(basic_istream& right);

Параметры

right
Ссылка lvalue на объект basic_istream.

Замечания

Вызовы basic_ios::swap(right)функции-члены. Она также обменивает количество извлечения с соответствующим значением для right. Дополнительные сведения см. в разделе basic_ios::swap.

basic_istream::sync

Синхронизирует связанное с потоком устройство ввода с буфером потока.

int sync();

Возвращаемое значение

Если rdbuf имеет значение NULL, функция возвращает значение -1. В противном случае вызывается rdbuf->pubsync. Если этот вызов возвращает -1, функция вызывает setstate(badbit) и возвращает -1. В противном случае функция возвращает нуль. Дополнительные сведения см. в разделах pubsync и setstate.

basic_istream::tellg

Сообщает текущую позицию чтения в потоке.

pos_type tellg();

Возвращаемое значение

Текущая позиция в потоке.

Замечания

Если fail есть false, функция-член возвращается rdbuf->pubseekoff(0, cur, in). В противном случае возвращается значение pos_type(-1). Дополнительные сведения см. в разделах rdbuf и pubseekoff.

Пример

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

Помещает самый последний считанный символ обратно в поток.

basic_istream<Char_T, Tr>& unget();

Возвращаемое значение

Поток (*this).

Замечания

Неформатированная входная функция возвращает предыдущий элемент в потоке, если это возможно, как если бы вызывая rdbuf->sungetcrdbuf , если это пустой указатель, или если вызов sungetc возвращался traits_type::eof, функция вызывает setstate(badbit). В любом случае она возвращает *this.

Дополнительные сведения см. в статьях sungetc, eof и setstate. Сведения о том, как unget может завершиться сбоем, см. в статье basic_streambuf::sungetc.

Пример

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

См. также

Потокобезопасность в стандартной библиотеке C++
iostream Программирования
iostreams Конвенций