Classe basic_filebuf

Descreve um buffer de fluxo que controla a transmissão de elementos do tipo Char_T, cujas características dos caracteres são determinadas pela classe Tr, para e de 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 no buffer de arquivo (geralmente char_traits<Char_T>).

Comentários

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

Um objeto da classe basic_filebuf<Char_T, Tr> armazena um ponteiro de arquivo, que designa o objeto FILE 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.
abrir	Abre um arquivo.
overflow	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.
Swap	Troca o conteúdo deste basic_filebuf pelo o conteúdo do parâmetro basic_filebuf fornecido.
sync	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 de right, 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::fechar

Fecha um arquivo.

basic_filebuf<Char_T, Tr> *close();

Valor de retorno

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, retornará this para indicar que o arquivo foi fechado com êxito.

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

Exemplo

O seguinte exemplo pressupõe que há dois arquivos no diretório atual: basic_filebuf_close.txt (o conteúdo é "testing") 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

Faz com que esse tipo no escopo basic_filebuf seja equivalente ao tipo com o mesmo nome no escopo Tr.

typedef typename traits_type::int_type int_type;

basic_filebuf::is_open

Indica se um arquivo está aberto.

bool is_open() const;

Valor de retorno

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

Faz com que esse tipo no escopo basic_filebuf seja equivalente ao tipo com o mesmo nome no escopo Tr.

typedef typename traits_type::off_type off_type;

basic_filebuf::abrir

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 de retorno

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

Comentários

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

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

Se mode & ios_base::binary for diferente de zero, a função acrescentará b a strmode para abrir um fluxo binário em vez de um fluxo de texto. Se mode & ios_base::ate for diferente de 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::state_type> >(getloc), para uso por underflow e overflow.

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

Exemplo

Confira basic_filebuf::close para ver 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.

basic_filebuf& operator=(basic_filebuf&& right);

Parâmetros

direita
Uma referência rvalue para um objeto basic_filebuf.

Valor de retorno

Retorna *this.

Comentários

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

basic_filebuf::estouro

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 de retorno

Se a função não tiver êxito, 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 protegida tentará inserir o elemento ch = traits_type::to_char_type(_Meta) no 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 de conversão de arquivo fac para chamar fac.out conforme necessário. Cada elemento ch do tipo char produzido é gravado no fluxo associado designado pelo ponteiro de arquivo fp, como se fosse por chamadas sucessivas da forma fputc(ch, fp). Se alguma conversão ou gravação falhar, a função não será bem-sucedida.

basic_filebuf::p backfail

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 de retorno

Se a função não tiver êxito, 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::eof, o elemento a ser recuado será 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 posição putback estiver disponível e o elemento armazenado lá for comparável a ch, ela pode diminuir o próximo ponteiro para o buffer de entrada.

• Se a função puder disponibilizar uma posição putback, ela poderá fazer isso, definir o ponteiro seguinte para apontar para aquela posição e armazenar ch nela.

• Se a função puder enviar um elemento para o fluxo de entrada, ela poderá fazer isso, como chamar ungetc um elemento do tipo char.

basic_filebuf::p os_type

Faz com que esse tipo no escopo basic_filebuf seja equivalente ao tipo com o mesmo nome no escopo Tr.

typedef typename traits_type::pos_type pos_type;

basic_filebuf::Busca

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 para o relativo 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 de retorno

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 dos fluxos controlados. Para um objeto da 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 as informações de estado necessárias analisar um fluxo grande. 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 extração, chame pubseekoff ou pubseekpos. Chamadas para pubseekoff (e, portanto, para seekoff) têm várias limitações para fluxos de texto, fluxos binários e fluxos largos.

Se o ponteiro do arquivo fp 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 resultante fposn puder ser determinada chamando fgetpos(fp, &fposn), a função será bem-sucedida. Se a função for bem-sucedida, ela retornará um valor do tipo pos_type contendo fposn. 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 de retorno

Se o ponteiro do arquivo fp for um ponteiro nulo, a função falhará. Caso contrário, ela tentará alterar a posição do fluxo chamando fsetpos(fp, &fposn), em que fposn é o objeto fpos_t 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 membro virtual protegida tenta alterar as posições atuais dos fluxos controlados. Para um objeto da 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 as informações de estado necessárias analisar um fluxo grande. 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 extração, chame pubseekoff ou pubseekpos. 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 alguma inserção tiver ocorrido desde que o fluxo foi aberto ou desde a última chamada para streampos, a função chamará overflow. Ela também insere qualquer sequência necessária para restaurar o estado de conversão inicial usando a faceta de conversão de arquivo fac para chamar fac.unshift, conforme necessário. Cada elemento byte do tipo char produzido é gravado no fluxo associado designado pelo ponteiro de arquivo fp como se fosse por chamadas sucessivas da forma fputc(byte, fp). Se a chamada para fac.unshift ou 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.

count
O tamanho do buffer .

Valor de retorno

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 elementos count começando no_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, retornará this para indicar o sucesso.

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::sincronização

Tenta sincronizar os fluxos controlados com quaisquer fluxos externos associados.

virtual int sync();

Valor de retorno

Retornará zero se o ponteiro do arquivo fp for nulo. Caso contrário, retornará zero somente se chamadas para overflow e para fflush(fp) tiverem êxito ao liberar saídas pendentes 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 de retorno

Se a função não tiver êxito, ela retornará traits_type::eof. Caso contrário, retornará ch, convertido conforme descrito na seção Comentários.

Comentários

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

• Se uma posição de leitura estiver disponível, ela pegará ch como o elemento armazenado na posição leitura e avançará o próximo ponteiro para o buffer de entrada.

• Ela 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 utilizando a faceta de conversão de arquivo fac para chamar fac.in conforme necessário. Se alguma leitura ou conversão falhar, a função não será bem-sucedida.

Confira também

<fstream>
Acesso Thread-Safe na Biblioteca Padrão C++
Programação de iostream
Convenções de iostreams