Класс 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
Здесь определяется как val
istreambuf_iterator<Char_T, Tr>
и имеет тип long
unsigned 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
. В противном случае fail
false
второй вызов 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.good
true
конструктор:
Вызовы
_Istr.tie->flush
, если_Istr.tie
не является пустым указателем.Фактически вызывается
ws(_Istr)
, если_Istr.flags & skipws
ненулевое значение.
Если после какой-либо такой подготовки, _Istr.good
false
конструктор вызывает _Istr.setstate(failbit)
. В любом случае конструктор сохраняет значение, возвращаемое _Istr.good
в status
. Последующий вызов для operator bool
доставки этого сохраненного значения.
Дополнительные сведения см. в разделе good
, , ws
tie
flush
, , 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->sungetc
rdbuf
, если это пустой указатель, или если вызов 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
Конвенций