Partilhar via

Classe basic_filebuf

  • Artigo

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.

Observação

Objetos do tipo basic_filebuf são criados com um buffer interno do tipo char* independentemente do char_type especificado pelo parâmetro de tipo 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 buffer do tipo wchar_t e defina-o usando o método basic_streambuf::pubsetbuf(). Para ver um exemplo que demonstra esse comportamento, consulte abaixo.

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