Classe basic_filebuf

Artigo
05/02/2022
15 minutos para o fim da leitura

Descreve um buffer de fluxo que controla a transmissão de elementos do tipo Char_T, cujas características de caractere são determinadas pela classe Tr, de e para uma sequência de elementos armazenados em um arquivo externo.

Sintaxe

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

Parâmetros

Char_T
O elemento básico no buffer de arquivo.

Tr
As características do elemento básico do buffer de arquivo (geralmente char_traits<Char_T>).

Comentários

O modelo de classe descreve um buffer de fluxo que controla a transmissão de elementos do tipo Char_T, cujas características de caractere são determinadas pela classe Tr, de e para uma sequência de elementos armazenados em um arquivo externo.

Observação

Objetos de tipo basic_filebuf são criados com um buffer interno do tipo char* independentemente do char_type parâmetro de tipo especificado Char_T. Isso significa que uma cadeia de caracteres Unicode (contendo wchar_t caracteres) será convertida em uma cadeia de caracteres ANSI (contendo char caracteres) antes de ser gravada no buffer interno. Para armazenar cadeias de caracteres Unicode no buffer, crie um novo buffer de tipo wchar_t e defina-o usando o basic_streambuf::pubsetbuf() método. Para ver um exemplo que demonstra esse comportamento, consulte abaixo.

Um objeto de classe basic_filebuf<Char_T, Tr> armazena um ponteiro de arquivo, que designa o FILE objeto que controla o fluxo associado a um arquivo aberto. Ele também armazena ponteiros para duas facetas de conversão de arquivo para uso pelas funções membro protegidas estouro e estouro negativo. Para obter mais informações, consulte basic_filebuf::open.

Exemplo

O exemplo a seguir demonstra como forçar um objeto do tipo basic_filebuf<wchar_t> a armazenar caracteres Unicode em seu buffer interno chamando o método 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...........

Construtores

Construtor	Descrição
basic_filebuf	Constrói um objeto do tipo `basic_filebuf`.

Typedefs

Nome do tipo	Descrição
char_type	Associa um nome de tipo ao parâmetro de modelo `Char_T`.
int_type	Faz com que esse tipo no escopo de `basic_filebuf` seja equivalente ao tipo com o mesmo nome no escopo de `Tr`.
off_type	Faz com que esse tipo no escopo de `basic_filebuf` seja equivalente ao tipo com o mesmo nome no escopo de `Tr`.
pos_type	Faz com que esse tipo no escopo de `basic_filebuf` seja equivalente ao tipo com o mesmo nome no escopo de `Tr`.
traits_type	Associa um nome de tipo ao parâmetro de modelo `Tr`.

Funções de membro

Função de membro	Descrição
close	Fecha um arquivo.
is_open	Indica se um arquivo está aberto.
open	Abre um arquivo.
Estouro	Uma função virtual protegida que pode ser chamada quando um novo caractere é inserido em um buffer cheio.
pbackfail	Uma função membro virtual protegida que tenta colocar um elemento de volta no fluxo de entrada, então torná-lo elemento atual (apontando para o ponteiro seguinte).
seekoff	A função membro virtual protegida tenta alterar as posições atuais para os fluxos controlados.
seekpos	A função membro virtual protegida tenta alterar as posições atuais para os fluxos controlados.
setbuf	A função membro virtual protegida executa uma operação que específica para cada buffer de fluxo derivado.
Trocar	Troca o conteúdo deste `basic_filebuf` pelo o conteúdo do parâmetro `basic_filebuf` fornecido.
Sincronização	A função virtual protegida tenta sincronizar os fluxos controlados com quaisquer fluxos externos associados.
uflow	Função virtual protegida para extrair o elemento atual do fluxo de entrada.
underflow	Função virtual protegida para extrair o elemento atual do fluxo de entrada.

Requisitos

Cabeçalho:< fstream>

Namespace: std

basic_filebuf::basic_filebuf

Constrói um objeto do tipo basic_filebuf.

basic_filebuf();

basic_filebuf(basic_filebuf&& right);

Comentários

O primeiro construtor armazena um ponteiro nulo em todos os ponteiros que controlam o buffer de entrada e o buffer de saída. Ele também armazena um ponteiro nulo no ponteiro do arquivo.

O segundo construtor inicializa o objeto com o conteúdo da direita, tratado como uma referência rvalue.

basic_filebuf::char_type

Associa um nome de tipo ao parâmetro de modelo Char_T.

typedef Char_T char_type;

basic_filebuf::close

Fecha um arquivo.

basic_filebuf<Char_T, Tr> *close();

Valor Retornado

A função membro retornará um ponteiro nulo se o ponteiro de arquivo for um ponteiro nulo.

Comentários

close chama fclose(fp). Se essa função retornar um valor diferente de zero, a função retornará um ponteiro nulo. Caso contrário, ele retornará this para indicar que o arquivo foi fechado com êxito.

Para um fluxo largo, se alguma inserção tiver ocorrido desde que o fluxo foi aberto ou desde a última chamada para streampos, a função chamará overflow. Ele também insere qualquer sequência necessária para restaurar o estado de conversão inicial usando a faceta fac de conversão de arquivo para chamar fac.unshift conforme necessário. Cada elemento de tipo bytechar produzido é gravado no fluxo associado designado pelo ponteiro fp do arquivo como se por chamadas sucessivas do formulário fputc(byte, fp). Se a chamada ou fac.unshift qualquer gravação falhar, a função não terá êxito.

Exemplo

O exemplo a seguir pressupõe dois arquivos no diretório atual: basic_filebuf_close.txt (o conteúdo é "teste") e iotest.txt (o conteúdo é "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

Torna esse tipo dentro basic_filebuf do escopo equivalente ao tipo de mesmo nome no Tr escopo.

typedef typename traits_type::int_type int_type;

basic_filebuf::is_open

Indica se um arquivo está aberto.

bool is_open() const;

Valor Retornado

true se o ponteiro do arquivo não for nulo.

Exemplo

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

Torna esse tipo dentro basic_filebuf do escopo equivalente ao tipo de mesmo nome no Tr escopo.

typedef typename traits_type::off_type off_type;

basic_filebuf::open

Abre um arquivo.

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

Parâmetros

filename
O nome do arquivo a ser aberto.

mode
Uma das enumerações em ios_base::openmode.

proteção
A proteção de abertura de arquivo padrão, equivalente ao parâmetro shflag em _fsopen, _wfsopen.

Valor Retornado

Se o buffer já estiver aberto ou se o ponteiro do arquivo for um ponteiro nulo, a função retornará um ponteiro nulo. Caso contrário, ele retornará this.

Comentários

Essa função usa um FILE * para voltar como basic_filebuf se você tivesse chamado fopen/wfopen(filename, strmode). strmodeé determinado a partir demode & ~()ate|binary:

ios_base::in"r" torna-se (abrir arquivo existente para leitura).
ios_base::out ou ios_base::out | ios_base::trunc torna-se "w" (truncar arquivo existente ou criar para gravação).
ios_base::out | app"a" torna-se (abrir arquivo existente para acrescentar todas as gravações).
ios_base::in | ios_base::out"r+" torna-se (abrir arquivo existente para leitura e gravação).
ios_base::in | ios_base::out | ios_base::trunc"w+" torna-se (truncar arquivo existente ou criar para leitura e gravação).
ios_base::in | ios_base::out | ios_base::app"a+" torna-se (abra o arquivo existente para leitura e para acrescentar todas as gravações).

Se mode & ios_base::binary não for zero, a função será acrescentada b para strmode abrir um fluxo binário em vez de um fluxo de texto. Se mode & ios_base::ate não for zero e o arquivo tiver sido aberto com êxito, o local atual no fluxo será posicionado no final do arquivo. Se isso falhar, o arquivo será fechado.

Se as operações acima forem concluídas com êxito, a faceta de conversão de arquivo será determinada: use_facet<codecvt<Char_T, char, traits_type::getloc> >()state_type, para uso por fluxo inferior e estouro.

Se o arquivo não puder ser aberto com êxito, o nulo será retornado.

Exemplo

Consulte basic_filebuf::close um exemplo que usa open.

basic_filebuf::operator=

Atribua o conteúdo deste objeto de buffer de fluxo. Essa é uma atribuição de movimentação que envolve um rvalue que não deixa uma cópia para trás.

basic_filebuf& operator=(basic_filebuf&& right);

Parâmetros

direita
Uma referência rvalue para um objeto basic_filebuf.

Valor Retornado

Retorna *this.

Comentários

O operador membro substitui o conteúdo do objeto usando o conteúdo da direita, tratado como uma referência rvalue. Para obter mais informações, consulte o declarador de referência do Rvalue: &&.

basic_filebuf::overflow

Chamado quando um novo caractere é inserido em um buffer cheio.

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

Parâmetros

_Meta
O caractere a ser inserido no buffer ou traits_type::eof.

Valor Retornado

Se a função não puder ser bem-sucedida, ela retornará traits_type::eof. Caso contrário, ele retornará traits_type::not_eof(_Meta).

Comentários

Se_Meta != traits_type::eof, a função de membro virtual protegido tentar inserir o elemento(_Meta)ch = traits_type::to_char_typeno buffer de saída. Isso pode ser feito de várias maneiras:

Se houver uma posição de gravação disponível, ela poderá armazenar o elemento na posição de gravação e incrementar o próximo ponteiro para o buffer de saída.
Ele pode disponibilizar uma posição de gravação alocando armazenamento novo ou adicional ao buffer de saída.
Ele pode converter qualquer saída pendente no buffer de saída, seguido por ch, usando a faceta fac de conversão de arquivo para chamar fac.out conforme necessário. Cada elemento ch produzido do tipo char é gravado no fluxo associado designado pelo ponteiro fp do arquivo como se por chamadas sucessivas do formulário fputc(ch, fp). Se qualquer conversão ou gravação falhar, a função não será bem-sucedida.

basic_filebuf::pbackfail

Tenta colocar um elemento de volta no fluxo de entrada e torná-lo o elemento atual (apontado pelo ponteiro seguinte).

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

Parâmetros

_Meta
O caractere a ser inserido no buffer ou traits_type::eof.

Valor Retornado

Se a função não puder ser bem-sucedida, ela retornará traits_type::eof. Caso contrário, ele retornará traits_type::not_eof(_Meta).

Comentários

A função membro virtual protegida coloca um elemento de volta no buffer de entrada, então o torna o elemento atual (apontando para o ponteiro seguinte). Se _Meta == traits_type::eofo elemento a ser enviado para trás for efetivamente o que já está no fluxo antes do elemento atual. Caso contrário, esse elemento será substituído por ch = traits_type::to_char_type(_Meta). A função pode colocar um elemento de volta de várias maneiras:

Se uma putback posição estiver disponível e o elemento armazenado lá for igual a ch, ele poderá decrementar o próximo ponteiro para o buffer de entrada.
Se a função puder disponibilizar uma putback posição, ela poderá fazer isso, definir o próximo ponteiro para apontar para essa posição e armazenar ch nessa posição.
Se a função puder recuar um elemento para o fluxo de entrada, ela poderá pode fazer isso, como chamando ungetc para um elemento do tipo char.

basic_filebuf::pos_type

Torna esse tipo dentro basic_filebuf do escopo equivalente ao tipo de mesmo nome no Tr escopo.

typedef typename traits_type::pos_type pos_type;

basic_filebuf::seekoff

Tenta alterar as posições atuais para os fluxos controlados.

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

Parâmetros

_Off
A posição a ser buscada em relação a _Way.

_Way
O ponto de partida para operações de deslocamento. Consulte seekdir para valores possíveis.

_Which
Especifica o modo para a posição do ponteiro. O padrão é permitir que você modifique as posições de leitura e gravação.

Valor Retornado

Retorna a nova posição ou uma posição de fluxo inválida.

Comentários

A função membro virtual protegida tenta alterar as posições atuais para os fluxos controlados. Para um objeto de classe basic_filebuf<Char_T, Tr>, uma posição de fluxo pode ser representada por um objeto do tipo fpos_t, que armazena um deslocamento e todas as informações de estado necessárias para analisar um fluxo largo. Deslocamento zero refere-se ao primeiro elemento do fluxo. (Um objeto do tipo pos_type armazena a pelo menos um objeto fpos_t.)

Para um arquivo aberto para leitura e gravação, os fluxos de entrada e saída são posicionados em tandem. Para alternar entre a inserção e a extração, você deve chamar ou pubseekoffpubseekpos. As chamadas para pubseekoff (e, portanto) seekofftêm várias limitações para fluxos de texto, fluxos binários e fluxos largos.

Se o ponteiro fp do arquivo for um ponteiro nulo, a função falhará. Caso contrário, ele tentará alterar a posição do fluxo chamando fseek(fp, _Off, _Way). Se essa função for bem-sucedida e a posição fposn resultante puder ser determinada pela chamada fgetpos(fp, &fposn), a função terá êxito. Se a função for bem-sucedida, ela retornará um valor de tipo pos_type que fposncontém . Caso contrário, retorna uma posição de fluxo inválida.

basic_filebuf::seekpos

Tenta alterar as posições atuais para os fluxos controlados.

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

Parâmetros

_Sp
A posição pela qual buscar.

_Which
Especifica o modo para a posição do ponteiro. O padrão é permitir que você modifique as posições de leitura e gravação.

Valor Retornado

Se o ponteiro fp do arquivo for um ponteiro nulo, a função falhará. Caso contrário, ele tenta alterar a posição do fluxo chamando fsetpos(fp, &fposn), onde fposn está o fpos_t objeto armazenado em pos. Se essa função for bem-sucedida, a função retornará pos. Caso contrário, retorna uma posição de fluxo inválida. Para determinar se a posição de fluxo é inválida, compare o valor retornado com pos_type(off_type(-1)).

Comentários

A função de membro virtual protegida tenta alterar as posições atuais para os fluxos controlados. Para um objeto de classe basic_filebuf<Char_T, Tr>, uma posição de fluxo pode ser representada por um objeto do tipo fpos_t, que armazena um deslocamento e qualquer informação de estado necessária para analisar um fluxo largo. Deslocamento zero refere-se ao primeiro elemento do fluxo. (Um objeto do tipo pos_type armazena a pelo menos um objeto fpos_t.)

Para um arquivo aberto para leitura e gravação, os fluxos de entrada e saída são posicionados em tandem. Para alternar entre a inserção e a extração, você deve chamar um pubseekoff ou pubseekposoutro. As chamadas para pubseekoff (e para seekoff) têm várias limitações para fluxos de texto, fluxos binários e fluxos largos.

Para um fluxo amplo, se qualquer inserções tiverem ocorrido desde que o fluxo foi aberto ou desde a última chamada a streampos, as chamadas de função estourarão. Ele também insere qualquer sequência necessária para restaurar o estado de conversão inicial usando a faceta fac de conversão de arquivo para chamar fac.unshift conforme necessário. Cada elemento byte produzido do tipo char é gravado no fluxo associado designado pelo ponteiro fp do arquivo como se fosse por chamadas sucessivas do formulário fputc(byte, fp). Se a chamada ou fac.unshift qualquer gravação falhar, a função não terá êxito.

basic_filebuf::setbuf

Executa um operação específica para cada buffer de fluxo derivado.

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

Parâmetros

_Buffer
Ponteiro para um buffer.

contagem
O tamanho do buffer.

Valor Retornado

A função membro protegido retornará zero se o ponteiro do arquivo fp for um ponteiro nulo.

Comentários

setbuf chama setvbuf( fp, (char*) _Buffer, _IOFBF, count * sizeof( Char_T)) para oferecer a matriz de count elementos começando em _Buffer como um buffer para o fluxo. Se essa função retornar um valor diferente de zero, a função retornará um ponteiro nulo. Caso contrário, ele retornará this para sinalizar êxito.

basic_filebuf::swap

Troca o conteúdo desse basic_filebuf pelo conteúdo do basic_filebuf fornecido.

void swap(basic_filebuf& right);

Parâmetros

direita
Uma referência lvalue a outro basic_filebuf.

basic_filebuf::sync

Tenta sincronizar os fluxos controlados com quaisquer fluxos externos associados.

virtual int sync();

Valor Retornado

Retornará zero se o ponteiro fp do arquivo for um ponteiro nulo. Caso contrário, ele retornará zero somente se as chamadas para estouro e fflush(fp) tiverem êxito em liberar qualquer saída pendente para o fluxo.

basic_filebuf::traits_type

Associa um nome de tipo ao parâmetro de modelo Tr.

typedef Tr traits_type;

basic_filebuf::underflow

Extrai o elemento atual do fluxo de entrada.

virtual int_type underflow();

Valor Retornado

Se a função não puder ser bem-sucedida, ela retornará traits_type::eof. Caso contrário, ele retornará ch, convertido conforme descrito na seção Comentários.

Comentários

A função de membro virtual protegida tenta extrair o elemento ch atual do fluxo de entrada e retornar o elemento comoto_int_typetraits_type::(ch) . Isso pode ser feito de várias maneiras:

Se uma posição de leitura estiver disponível, ela usará ch como o elemento armazenado na posição de leitura e avançará o próximo ponteiro para o buffer de entrada.
Ele pode ler um ou mais elementos do tipo char, como se por chamadas sucessivas do formulário fgetc(fp), e convertê-los em um elemento ch do tipo Char_T usando a faceta fac de conversão de arquivo para chamar fac.in conforme necessário. Se qualquer leitura ou conversão falhar, a função não será bem-sucedida.

Confira também

<fstream>
Segurança de thread na Biblioteca Padrão do C++
Programação iostream
Convenções de iostreams

Classe basic_filebuf

Esta página é útil?

Sintaxe

Parâmetros

Comentários

Exemplo

Construtores

Typedefs

Funções de membro

Requisitos

basic_filebuf::basic_filebuf

Comentários

basic_filebuf::char_type

basic_filebuf::close

Valor Retornado

Comentários

Exemplo

basic_filebuf::int_type

basic_filebuf::is_open

Valor Retornado

Exemplo

basic_filebuf::off_type

basic_filebuf::open

Parâmetros

Valor Retornado

Comentários

Exemplo

basic_filebuf::operator=

Parâmetros

Valor Retornado

Comentários

basic_filebuf::overflow

Parâmetros

Valor Retornado

Comentários

basic_filebuf::pbackfail

Parâmetros

Valor Retornado

Comentários

basic_filebuf::pos_type

basic_filebuf::seekoff

Parâmetros

Valor Retornado

Comentários

basic_filebuf::seekpos

Parâmetros

Valor Retornado

Comentários

basic_filebuf::setbuf

Parâmetros

Valor Retornado

Comentários

basic_filebuf::swap

Parâmetros

basic_filebuf::sync

Valor Retornado

basic_filebuf::traits_type

basic_filebuf::underflow

Valor Retornado

Comentários

Confira também