Класс basic_filebuf

  • Статья

Описывает буфер потока, который управляет передачей элементов типа Char_T, признаки символов которых определяются классом Tr, в последовательность элементов, хранящихся во внешнем файле.

Синтаксис

template <class Char_T, class Tr = char_traits<Char_T>>
class basic_filebuf : public basic_streambuf<Char_T, Tr>

Параметры

Char_T
Базовый элемент буфера файла.

Tr
Признаки базового элемента буфера файла (обычно char_traits<Char_T>).

Замечания

Шаблон класса описывает буфер потока, который управляет передачей элементов типа Char_T, признаки символов которых определяются классом Tr, в последовательность элементов, хранящихся во внешнем файле.

Примечание.

Объекты типа basic_filebuf создаются с внутренним буфером типа char* независимо от char_type указанного параметром типа Char_T. Это означает, что строка в Юникоде (количество символов: wchar_t) будет преобразована в строку ANSI (количество символов: char) перед записью во внутренний буфер. Чтобы сохранить строки Юникода в буфере, создайте новый буфер типа wchar_t и задайте его с помощью basic_streambuf::pubsetbuf() метода. Ниже приведен пример, демонстрирующий такие действия.

Объект класса basic_filebuf<Char_T, Tr> хранит указатель файла, который обозначает FILE объект, который управляет потоком, связанным с открытым файлом. Он также содержит указатели на два аспекта преобразования файла для использования защищенными функциями-членами overflow и underflow. Дополнительные сведения см. в разделе basic_filebuf::open.

Пример

Следующий пример демонстрирует способ использования объекта типа basic_filebuf<wchar_t> для хранения символов Юникода в своем внутреннем буфере, с помощью метода pubsetbuf().

// unicode_basic_filebuf.cpp
// compile with: /EHsc

#include <iostream>
#include <string>
#include <fstream>
#include <iomanip>
#include <memory.h>
#include <string.h>

#define IBUFSIZE 16

using namespace std;

void hexdump(const string& filename);

int main()
{
    wchar_t* wszHello = L"Hello World";
    wchar_t wBuffer[128];

    basic_filebuf<wchar_t> wOutFile;

    // Open a file, wcHello.txt, then write to it, then dump the
    // file's contents in hex
    wOutFile.open("wcHello.txt",
        ios_base::out | ios_base::trunc | ios_base::binary);
    if(!wOutFile.is_open())
    {
        cout << "Error Opening wcHello.txt\n";
        return -1;
    }
    wOutFile.sputn(wszHello, (streamsize)wcslen(wszHello));
    wOutFile.close();
    cout << "Hex Dump of wcHello.txt - note that output is ANSI chars:\n";
    hexdump(string("wcHello.txt"));

    // Open a file, wwHello.txt, then set the internal buffer of
    // the basic_filebuf object to be of type wchar_t, then write
    // to the file and dump the file's contents in hex
    wOutFile.open("wwHello.txt",
        ios_base::out | ios_base::trunc | ios_base::binary);
    if(!wOutFile.is_open())
    {
        cout << "Error Opening wwHello.txt\n";
        return -1;
    }
    wOutFile.pubsetbuf(wBuffer, (streamsize)128);
    wOutFile.sputn(wszHello, (streamsize)wcslen(wszHello));
    wOutFile.close();
    cout << "\nHex Dump of wwHello.txt - note that output is wchar_t chars:\n";
    hexdump(string("wwHello.txt"));

    return 0;
}

// dump contents of filename to stdout in hex
void hexdump(const string& filename)
{
    fstream ifile(filename.c_str(),
        ios_base::in | ios_base::binary);
    char *ibuff = new char[IBUFSIZE];
    char *obuff = new char[(IBUFSIZE*2)+1];
    int i;

    if(!ifile.is_open())
    {
        cout << "Cannot Open " << filename.c_str()
             << " for reading\n";
        return;
    }
    if(!ibuff || !obuff)
    {
        cout << "Cannot Allocate buffers\n";
        ifile.close();
        return;
    }

    while(!ifile.eof())
    {
        memset(obuff,0,(IBUFSIZE*2)+1);
        memset(ibuff,0,IBUFSIZE);
        ifile.read(ibuff,IBUFSIZE);

        // corner case where file is exactly a multiple of
        // 16 bytes in length
        if(ibuff[0] == 0 && ifile.eof())
            break;

        for(i = 0; i < IBUFSIZE; i++)
        {
            if(ibuff[i] >= ' ')
                obuff[i] = ibuff[i];
            else
                obuff[i] = '.';

            cout << setfill('0') << setw(2) << hex
                 << (int)ibuff[i] << ' ';
        }
        cout << "  " << obuff << endl;
    }
    ifile.close();
}

Hex Dump of wcHello.txt - note that output is ANSI chars:
48 65 6c 6c 6f 20 57 6f 72 6c 64 00 00 00 00 00   Hello World.....

Hex Dump of wwHello.txt - note that output is wchar_t chars:
48 00 65 00 6c 00 6c 00 6f 00 20 00 57 00 6f 00   H.e.l.l.o. .W.o.
72 00 6c 00 64 00 00 00 00 00 00 00 00 00 00 00   r.l.d...........

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

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

Определения типов

Введите имя Description
char_type Связывает имя типа с параметром шаблона Char_T.
int_type Делает этот тип в области basic_filebuf эквивалентным типу с таким же именем в области Tr.
off_type Делает этот тип в области basic_filebuf эквивалентным типу с таким же именем в области Tr.
pos_type Делает этот тип в области basic_filebuf эквивалентным типу с таким же именем в области Tr.
traits_type Связывает имя типа с параметром шаблона Tr.

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

Функция-член Description
close Закрывает файл.
is_open Указывает, открыт ли файл.
open Открывает файл.
overflow Защищенная виртуальная функция, которая может вызываться при вставке нового символа в полный буфер.
pbackfail Защищенная виртуальная функция-член пытается поместить элемент обратно во входной поток, затем делает его текущим (на него указывает следующий указатель).
seekoff Защищенная виртуальная функция-член пытается изменить текущие положения управляемых потоков.
seekpos Защищенная виртуальная функция-член пытается изменить текущие положения управляемых потоков.
setbuf Защищенная виртуальная функция-член выполняет операции, относящиеся непосредственно к каждому производному буферу потока.
Swap Меняет местами содержимое этого basic_filebuf и содержимое указанного параметра basic_filebuf.
sync Защищенная виртуальная функция пытается синхронизировать управляемые потоки с любыми связанными внешними потоками.
uflow Защищенная виртуальная функция для извлечения текущего элемента из входного потока.
underflow Защищенная виртуальная функция для извлечения текущего элемента из входного потока.

Requirements

Заголовок:<fstream>

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

basic_filebuf::basic_filebuf

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

basic_filebuf();

basic_filebuf(basic_filebuf&& right);

Замечания

Первый конструктор сохраняет пустой указатель во всех указателях, управляющих входным и выходным буферами. Он также сохраняет пустой указатель в указателе файла.

Второй конструктор инициализирует объект с содержимым right, что рассматривается как ссылка rvalue.

basic_filebuf::char_type

Связывает имя типа с параметром шаблона Char_T.

typedef Char_T char_type;

basic_filebuf::close

Закрывает файл.

basic_filebuf<Char_T, Tr> *close();

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

Функция-член возвращает указатель null, если указатель файла является указателем null.

Замечания

close вызывает fclose(fp). Если эта функция возвращает ненулевое значение, то возвращается пустой указатель. В противном случае возвращается this значение, указывающее, что файл был успешно закрыт.

Для широкого потока, если с момента открытия потока произошли какие-либо вставки или с момента последнего вызова streamposфункции overflow. Он также вставляет любую последовательность, необходимую для восстановления начального состояния преобразования, используя аспект fac преобразования файлов для вызова fac.unshift по мере необходимости. Каждый созданный элемент byte типа char записывается в связанный поток, назначенный указателем fp файла, как будто последовательными вызовами формы fputc(byte, fp). Если вызов или fac.unshift запись завершается ошибкой, функция не завершается успешно.

Пример

В следующем примере предполагается, что два файла в текущем каталоге: basic_filebuf_close.txt (содержимое — testing) и iotest.txt (содержимое — ssss).

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

int main() {
   using namespace std;
   ifstream file;
   basic_ifstream <wchar_t> wfile;
   char c;
   // Open and close with a basic_filebuf
   file.rdbuf()->open( "basic_filebuf_close.txt", ios::in );
   file >> c;
   cout << c << endl;
   file.rdbuf( )->close( );

   // Open/close directly
   file.open( "iotest.txt" );
   file >> c;
   cout << c << endl;
   file.close( );

   // open a file with a wide character name
   wfile.open( L"iotest.txt" );

   // Open and close a nonexistent with a basic_filebuf
   file.rdbuf()->open( "ziotest.txt", ios::in );
   cout << file.fail() << endl;
   file.rdbuf( )->close( );

   // Open/close directly
   file.open( "ziotest.txt" );
   cout << file.fail() << endl;
   file.close( );
}

t
s
0
1

basic_filebuf::int_type

Делает этот тип в basic_filebuf область эквивалентным типу того же имени в Tr область.

typedef typename traits_type::int_type int_type;

basic_filebuf::is_open

Указывает, открыт ли файл.

bool is_open() const;

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

true Значение NULL, если указатель файла не имеет значения NULL.

Пример

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

int main( )
{
   using namespace std;
   ifstream file;
   cout << boolalpha << file.rdbuf( )->is_open( ) << endl;

   file.open( "basic_filebuf_is_open.cpp" );
   cout << file.rdbuf( )->is_open( ) << endl;
}

false
true

basic_filebuf::off_type

Делает этот тип в basic_filebuf область эквивалентным типу того же имени в Tr область.

typedef typename traits_type::off_type off_type;

basic_filebuf::open

Открывает файл.

basic_filebuf<Char_T, Tr> *open(
    const char* filename,
    ios_base::openmode mode,
    int protection = (int)ios_base::_Openprot);

basic_filebuf<Char_T, Tr> *open(
    const char* filename,
    ios_base::openmode mode);

basic_filebuf<Char_T, Tr> *open(
    const wchar_t* filename,
    ios_base::openmode mode,
    int protection = (int)ios_base::_Openprot);

basic_filebuf<Char_T, Tr> *open(
    const wchar_t* filename,
    ios_base::openmode mode);

Параметры

filename
Имя файла, который необходимо открыть.

mode
Одно из перечислений в ios_base::openmode.

Защиты
Защита от открытия файла по умолчанию, эквивалентная параметру shflag в _fsopen, _wfsopen.

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

Если буфер уже открыт или если указатель файла является пустым указателем, функция возвращает пустой указатель. В противном случае возвращается значение this.

Замечания

Эта функция использует FILE * функцию для обратного basic_filebuf вызова, как если бы вы не вызвали fopen/wfopen(filename, strmode). strmodeопределяется из mode & ~(atebinary|):

  • ios_base::in становится "r" (открытие существующего файла для чтения).
  • ios_base::out или ios_base::out | ios_base::trunc становится "w" (усечение существующего файла или создание для записи).
  • ios_base::out | app становится "a" (откройте существующий файл для добавления всех записей).
  • ios_base::in | ios_base::out становится "r+" (открытие существующего файла для чтения и записи).
  • ios_base::in | ios_base::out | ios_base::trunc становится "w+" (усечение существующего файла или создание для чтения и записи).
  • ios_base::in | ios_base::out | ios_base::app становится "a+" (открытие существующего файла для чтения и добавления всех записей).

Если mode & ios_base::binary это ненулевое значение, функция добавляется b для strmode открытия двоичного потока вместо текстового потока. Если mode & ios_base::ate файл не является ненулевой и файл был успешно открыт, текущее расположение в потоке размещается в конце файла. Если это не удается, файл закрывается.

Если описанные выше операции выполнены успешно, аспект преобразования файлов определяется следующим образом: use_facet<codecvt<Char_T, char, traits_type::state_type)getloc> >(для использования при переполнении и переполнении.

Если файл не удалось открыть, nullptr возвращается.

Пример

Пример basic_filebuf::close использования open.

basic_filebuf::operator=

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

basic_filebuf& operator=(basic_filebuf&& right);

Параметры

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

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

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

Замечания

Оператор-член заменяет содержимое объекта при помощи содержимого right, которое обрабатывается как ссылка rvalue. Дополнительные сведения см . в справочнике Rvalue: &>.

basic_filebuf::переполнение

Вызывается при вставке нового символа в полный буфер.

virtual int_type overflow(int_type _Meta = traits_type::eof);

Параметры

_Мета
Символ для вставки в буфер или traits_type::eof.

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

Если функция не может завершиться успешно, она возвращается traits_type::eof. В противном случае возвращается значение traits_type::not_eof(_Meta).

Замечания

Если _Meta != traits_type::eofфункция защищенного виртуального члена пытается вставить элемент(_Meta)ch = traits_type::to_char_typeв выходной буфер. Для этого существует несколько способов.

  • Если позиция записи доступна, можно сохранить элемент в позиции записи и увеличить следующий указатель для выходного буфера.

  • Можно сделать позицию записи доступной, выделяя новое или дополнительное хранилище для выходного буфера.

  • Он может преобразовать все ожидающие выходные данные в выходном буфере, за которым следует ch, используя аспект fac преобразования файла для вызова fac.out по мере необходимости. Каждый созданный элемент chтипа char записывается в связанный поток, назначенный указателем fp файла, как будто последовательными вызовами формы fputc(ch, fp). Если преобразование или запись завершается ошибкой, функция не завершается успешно.

basic_filebuf::p backfail

Пытается поместить элемент обратно во входной поток, затем делает его текущим (на него указывает следующий указатель).

virtual int_type pbackfail(int_type _Meta = traits_type::eof);

Параметры

_Мета
Символ для вставки в буфер или traits_type::eof.

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

Если функция не может завершиться успешно, она возвращается traits_type::eof. В противном случае возвращается значение traits_type::not_eof(_Meta).

Замечания

Защищенная виртуальная функция-член помещает элемент обратно во входной буфер, а затем делает его текущим (на него указывает следующий указатель). Если _Meta == traits_type::eofэлемент, отталкиваемый назад, фактически является тем, который уже находится в потоке до текущего элемента. В противном случае этот элемент заменяется ch = traits_type::to_char_type(_Meta). Функция может передать элемент обратно различными способами.

  • putback Если позиция доступна, и элемент, хранящийся там, сравнивается сch, он может уменьшать следующий указатель для входного буфера.

  • Если функция может сделать позицию доступной putback , она может сделать это, задайте для следующего указателя указатель на эту позицию и сохраните ch его в этой позиции.

  • Если функция может отправить элемент в входной поток, он может сделать это, например путем вызова ungetc элемента типа char.

basic_filebuf::p os_type

Делает этот тип в basic_filebuf область эквивалентным типу того же имени в Tr область.

typedef typename traits_type::pos_type pos_type;

basic_filebuf::seekoff

Пытается изменить текущие положения для управляемых потоков.

virtual pos_type seekoff(
    off_type _Off,
    ios_base::seekdir _Way,
    ios_base::openmode _Which = ios_base::in | ios_base::out);

Параметры

_Off
Позиция, требуемая относительно _Way.

_Путь
Начальная точка для операций смещения. Возможные значения см. в разделе seekdir.

_Который
Задает режим для положения указателя. По умолчанию разрешается изменять позиции чтения и записи.

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

Возвращает новую позицию или недопустимую позицию потока.

Замечания

Защищенная виртуальная функция-член пытается изменить текущие позиции для управляемых потоков. Для объекта класса basic_filebuf<Char_T, Tr>позиция потока может быть представлена объектом типа fpos_t, в котором хранятся смещение и все сведения о состоянии, необходимые для анализа широкого потока. Ноль смещения относится к первому элементу потока. (Объект типа pos_type хранит по крайней мере объект fpos_t.)

Для файла, открытого для чтения и записи, входной и выходной потоки располагаются вместе. Чтобы переключиться между вставками и извлечением, необходимо вызвать либо pubseekoffpubseekpos. Вызовы pubseekoff (и соответственно seekoff) имеют различные ограничения для текстовых потоков, двоичных потоков и широких потоков.

Если указатель fp файла является пустым указателем, функция завершается ошибкой. В противном случае он пытается изменить положение потока путем вызова fseek(fp, _Off, _Way). Если эта функция успешно выполнена, а результирующая позиция fposn может быть определена путем вызова fgetpos(fp, &fposn), функция завершается успешно. Если функция успешно выполнена, она возвращает значение типа pos_type , содержащего fposn. В противном случае она возвращает недопустимую позицию потока.

basic_filebuf::seekpos

Пытается изменить текущие положения для управляемых потоков.

virtual pos_type seekpos(
    pos_type _Sp,
    ios_base::openmode _Which = ios_base::in | ios_base::out);

Параметры

_Sp
Позиция для поиска.

_Который
Задает режим для положения указателя. По умолчанию разрешается изменять позиции чтения и записи.

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

Если указатель fp файла является пустым указателем, функция завершается ошибкой. В противном случае он пытается изменить положение потока путем вызова fsetpos(fp, &fposn), где fposn находится fpos_t объект, хранящийся в pos. Если эта функция выполняется успешно, функция возвращает pos. В противном случае она возвращает недопустимую позицию потока. Чтобы определить, является ли позиция потока недопустимой, сравните возвращаемое значение с pos_type(off_type(-1)).

Замечания

Защищенная виртуальная функция-член пытается изменить текущие позиции для управляемых потоков. Для объекта класса basic_filebuf<Char_T, Tr>позиция потока может быть представлена объектом типа fpos_t, в котором хранятся смещение и все сведения о состоянии, необходимые для анализа широкого потока. Ноль смещения относится к первому элементу потока. (Объект типа pos_type хранит по крайней мере объект fpos_t.)

Для файла, открытого для чтения и записи, входной и выходной потоки располагаются вместе. Чтобы переключиться между вставками и извлечением, необходимо вызвать либо pubseekoffpubseekpos. pubseekoff Вызовы (и) seekoffимеют различные ограничения для текстовых потоков, двоичных потоков и широких потоков.

Для широкого потока, если с момента открытия потока произошли какие-либо вставки или с момента последнего вызова streamposфункции overflow. Он также вставляет любую последовательность, необходимую для восстановления начального состояния преобразования, используя аспект fac преобразования файлов для вызова fac.unshift по мере необходимости. Каждый созданный элемент byte типа char записывается в связанный поток, назначенный указателем fp файла, как будто последовательными вызовами формы fputc(byte, fp). Если вызов или fac.unshift запись завершается ошибкой, функция не завершается успешно.

basic_filebuf::setbuf

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

virtual basic_streambuf<Char_T, Tr> *setbuf(
    char_type* _Buffer,
    streamsize count);

Параметры

_Буфера
Указатель на буфер.

count
Размер буфера.

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

Эта защищенная функция-член возвращает нуль, если указатель файла fp является пустым указателем.

Замечания

setbuf вызовы setvbuf( fp, (char*) _Buffer, _IOFBF, count * sizeof( Char_T)) для предложения массива count элементов, начиная с _Buffer в качестве буфера для потока. Если эта функция возвращает ненулевое значение, то возвращается пустой указатель. В противном случае возвращается this сигнал об успешном выполнении.

basic_filebuf::swap

Меняет местами содержимое этого объекта basic_filebuf с содержимым указанного объекта basic_filebuf.

void swap(basic_filebuf& right);

Параметры

right
Ссылка lvalue на другое basic_filebuf.

basic_filebuf::sync

Пытается синхронизировать управляемые потоки с любыми связанными внешними потоками.

virtual int sync();

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

Возвращает ноль, если указатель fp файла является пустым указателем. В противном случае возвращается ноль только в том случае, если вызовы переполнения и fflush(fp) успешно выполняется очистка всех ожидающих выходных данных в потоке.

basic_filebuf::traits_type

Связывает имя типа с параметром шаблона Tr.

typedef Tr traits_type;

basic_filebuf::underflow

Извлекает текущий элемент из входного потока.

virtual int_type underflow();

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

Если функция не может завершиться успешно, она возвращается traits_type::eof. В противном случае он возвращает chзначение, преобразованное, как описано в разделе "Примечания".

Замечания

Защищенная виртуальная функция-член пытается извлечь текущий элемент ch из входного потока и вернуть элемент какto_int_typetraits_type::(ch) . Для этого существует несколько способов.

  • Если доступно положение чтения, он принимает ch в качестве элемента, хранящегося в позиции чтения, и перемещает следующий указатель для входного буфера.

  • Он может считывать один или несколько элементов типа char, как будто путем последовательных вызовов формы fgetc(fp), и преобразовать их в элемент ch типа Char_T с помощью аспекта fac преобразования файлов для вызова fac.in по мере необходимости. Если сбой чтения или преобразования, функция не завершается успешно.

См. также

<fstream>
Потокобезопасность в стандартной библиотеке C++
Программирование iostream
Соглашения iostreams