basic_filebuf (Clase)

Artículo
06/16/2023

Describe un búfer de secuencia que controla la transmisión de elementos de tipo Char_T, cuyos rasgos de caracteres están determinados por la clase Tr, a y desde una secuencia de elementos almacenados en un archivo externo.

Sintaxis

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

Parámetros

Char_T
Elemento básico del búfer del archivo.

Tr
Rasgos del elemento básico del búfer del archivo (normalmente char_traits<Char_T>).

Comentarios

La plantilla de clase describe un búfer de secuencia que controla la transmisión de elementos de tipo Char_T, cuyos rasgos de caracteres están determinados por la clase Tr, a y desde una secuencia de elementos almacenados en un archivo externo.

Nota:

Los objetos de tipo basic_filebuf se crean con un búfer interno de tipo char*, independientemente del char_type especificado por el parámetro de tipo Char_T. Esto significa que una cadena Unicode (que contiene caracteres wchar_t) se convertirá en una cadena ANSI (que contiene caracteres char) antes de que se escriba en el búfer interno. Para almacenar cadenas Unicode en el búfer, cree un nuevo búfer de tipo wchar_t y establézcalo mediante el método basic_streambuf::pubsetbuf(). Para ver un ejemplo que muestra este comportamiento, vea a continuación.

Un objeto de clase basic_filebuf<Char_T, Tr> almacena un puntero de archivo, que designa el objeto FILE que controla el flujo asociado a un archivo abierto. También almacena punteros a dos facetas de conversión de archivo para su uso por parte de las funciones miembro protegidas overflow y underflow. Para obtener más información, vea basic_filebuf::open.

Ejemplo

En el ejemplo siguiente se muestra cómo forzar un objeto de tipo basic_filebuf<wchar_t> para almacenar caracteres Unicode en su búfer interno mediante una llamada al 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...........

Constructores

Constructor	Descripción
basic_filebuf	Construye un objeto de tipo `basic_filebuf`.

Typedefs

Nombre de tipo	Descripción
char_type	Asocia un nombre de tipo con el parámetro de plantilla `Char_T`.
int_type	Hace que este tipo en el ámbito de `basic_filebuf` equivalga al tipo con el mismo nombre del ámbito `Tr`.
off_type	Hace que este tipo en el ámbito de `basic_filebuf` equivalga al tipo con el mismo nombre del ámbito `Tr`.
pos_type	Hace que este tipo en el ámbito de `basic_filebuf` equivalga al tipo con el mismo nombre del ámbito `Tr`.
traits_type	Asocia un nombre de tipo con el parámetro de plantilla `Tr`.

Funciones miembro

Función de miembro	Descripción
close	Cierra un archivo.
is_open	Indica si un archivo está abierto.
open	Abre un archivo.
overflow	Función virtual protegida a la que se puede llamar cuando se inserta un carácter nuevo en un búfer lleno.
pbackfail	La función miembro virtual protegida intenta colocar un elemento en el flujo de entrada y, a continuación, convertirlo en el elemento actual (indicado por el puntero siguiente).
seekoff	La función miembro virtual protegida trata de modificar las posiciones actuales de las secuencias controladas.
seekpos	La función miembro virtual protegida trata de modificar las posiciones actuales de las secuencias controladas.
setbuf	La función miembro virtual protegida realiza una determinada operación para cada búfer de secuencia derivado.
Swap	Intercambia el contenido de `basic_filebuf` por el contenido del parámetro `basic_filebuf` proporcionado.
sync	Función virtual protegida que intenta sincronizar las secuencias controladas con cualquier flujo externo asociado.
uflow	Función virtual protegida que extrae el elemento actual de la secuencia de entrada.
underflow	Función virtual protegida que extrae el elemento actual de la secuencia de entrada.

Requisitos

Encabezado:<fstream>

Espacio de nombres: std

basic_filebuf::basic_filebuf

Construye un objeto de tipo basic_filebuf.

basic_filebuf();

basic_filebuf(basic_filebuf&& right);

Comentarios

El primer constructor almacena un puntero nulo en todos los punteros que controlan el búfer de entrada y el de salida. También almacena un puntero nulo en el puntero de archivo.

El segundo constructor inicializa el objeto con el contenido de right, tratado como una referencia a un valor R.

basic_filebuf::char_type

Asocia un nombre de tipo con el parámetro de plantilla Char_T.

typedef Char_T char_type;

basic_filebuf::close

Cierra un archivo.

basic_filebuf<Char_T, Tr> *close();

Valor devuelto

La función miembro devuelve un puntero nulo si el puntero de archivo es un puntero nulo.

Comentarios

close llama a fclose(fp). Si esa función devuelve un valor distinto de cero, la función devuelve un puntero nulo. De lo contrario, devuelve this para indicar que el archivo se ha cerrado correctamente.

En un flujo ancho, si se han producido inserciones desde la apertura del flujo o desde la última llamada a streampos, la función llama a overflow. Además se inserta cualquier secuencia necesaria para restaurar el estado de conversión inicial mediante la faceta de conversión de archivo fac para llamar a fac.unshift según sea necesario. Cada elemento byte producido de tipo char se escribe en el flujo asociado designado por el puntero de archivo fp como si se hiciera mediante llamadas sucesivas del formato fputc(byte, fp). Si se produce un error en la llamada a fac.unshift o en cualquier escritura, la función no se ejecuta correctamente.

Ejemplo

En el ejemplo siguiente se asume que hay dos archivos en el directorio actual: basic_filebuf_close.txt (el contenido es "testing") e iotest.txt (el contenido es "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

Hace que este tipo en el ámbito de basic_filebuf equivalga al tipo con el mismo nombre del ámbito Tr.

typedef typename traits_type::int_type int_type;

basic_filebuf::is_open

Indica si un archivo está abierto.

bool is_open() const;

Valor devuelto

true si el puntero de archivo no es nulo.

Ejemplo

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

Hace que este tipo en el ámbito de basic_filebuf equivalga al tipo con el mismo nombre del ámbito Tr.

typedef typename traits_type::off_type off_type;

basic_filebuf::open

Abre un archivo.

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
Nombre del archivo que se va a abrir.

mode
Una de las enumeraciones de ios_base::openmode.

Protección
Protección predeterminada de apertura del archivo, equivalente al parámetroshflag en _fsopen, _wfsopen.

Valor devuelto

Si el búfer ya está abierto o si el puntero de archivo es un puntero nulo, la función devuelve un puntero nulo. De lo contrario, devuelve this.

Comentarios

Esta función usa un FILE * para volver a basic_filebuf como si hubiera llamado a fopen/wfopen(filename, strmode). strmodese determina a partir de mode & ~(ate|binary):

ios_base::inse convierte en "r" (abra un archivo existente para lectura).
ios_base::out o ios_base::out | ios_base::trunc se convierte en "w" (trunque el archivo existente o créelo para escritura).
ios_base::out | app se convierte en "a" (abra archivo existente para anexar todas las escrituras).
ios_base::in | ios_base::out se convierte en "r+" (abra un archivo existente para lectura y escritura).
ios_base::in | ios_base::out | ios_base::trunc se convierte en "w+" (trunque el archivo existente o créelo para lectura y escritura).
ios_base::in | ios_base::out | ios_base::app se convierte en "a+" (abra archivo existente para lectura para anexar todas las escrituras).

Si mode & ios_base::binary es distinto de cero, la función anexa b a strmode para abrir un flujo binario en lugar de un flujo de texto. Si mode & ios_base::ate es distinto de cero y el archivo se abrió correctamente, la ubicación actual de la secuencia se coloca al final del archivo. Si se produce un error, el archivo se cierra.

Si las operaciones anteriores se completaron correctamente, la faceta de conversión de archivos se determina: use_facet<codecvt<Char_T, char, traits_type::state_type> >(getloc), para su uso por flujo y desbordamiento.

Si el archivo no se pudo abrir correctamente, se devuelve nullptr.

Ejemplo

Consulte basic_filebuf::close para ver un ejemplo en el que se usa open.

basic_filebuf::operator=

Asigna el contenido de este objeto de búfer de secuencia. Se trata de una asignación de movimiento que implica un rvalue que no deja ninguna copia atrás.

basic_filebuf& operator=(basic_filebuf&& right);

Parámetros

right
Referencia a un valor R a un objeto basic_filebuf.

Valor devuelto

Devuelve *this.

Comentarios

El operador de miembro reemplaza el contenido del objeto por el contenido de right, que se trata como referencia rvalue. Para obtener más información, vea Rvalue reference declarator: &&.

basic_filebuf::overflow

Se llama cuando se inserta un nuevo carácter en un búfer lleno.

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

Parámetros

_Meta
El carácter que se va a insertar en el búfer o traits_type::eof.

Valor devuelto

Si la función no se puede ejecutar correctamente, devuelve traits_type::eof. De lo contrario, devuelve traits_type::not_eof(_Meta).

Comentarios

Si _Meta != traits_type::eof, la función miembro virtual protegida intenta insertar el elemento ch = traits_type::to_char_type(_Meta) en el búfer de salida. Puede hacerlo de varias maneras:

Si está disponible una posición de escritura, puede almacenar el elemento en la posición de escritura e incrementar el puntero siguiente para el búfer de salida.
Puede proporcionar una posición de escritura al asignar almacenamiento nuevo o adicional para el búfer de salida.
Puede convertir cualquier salida pendiente en el búfer de salida, seguida de ch, mediante la faceta de conversión de archivo fac para llamar a fac.out según sea necesario. Cada elemento ch producido de tipo char se escribe en el flujo asociado designado por el puntero de archivo fp como si se hiciera mediante llamadas sucesivas del formato fputc(ch, fp). Si se produce un error en cualquier conversión o escritura, la función no se ejecuta correctamente.

basic_filebuf::p backfail

Intenta volver a colocar un elemento en el flujo de entrada y luego convertirlo en el elemento actual (al que apunta el puntero siguiente).

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

Parámetros

_Meta
El carácter que se va a insertar en el búfer o traits_type::eof.

Valor devuelto

Si la función no se puede ejecutar correctamente, devuelve traits_type::eof. De lo contrario, devuelve traits_type::not_eof(_Meta).

Comentarios

La función miembro virtual protegida vuelve a colocar un elemento en el búfer de entrada y luego lo convierte en el elemento actual (al que apunta el siguiente puntero). Si _Meta == traits_type::eof, el elemento que se va a devolver es realmente el que ya está en el flujo por delante del elemento actual. De lo contrario, dicho elemento se sustituye por ch = traits_type::to_char_type(_Meta). La función puede devolver un elemento de distintas maneras:

Si hay disponible una posición putback y el elemento almacenado es igual a ch, puede disminuir el puntero siguiente para el búfer de entrada.
Si la función puede conseguir que haya una posición putback disponible, puede hacerlo, establecer el siguiente puntero para que apunte a esa posición y almacenar ch en ella.
Si la función puede insertar un elemento en el flujo de entrada, puede hacerlo, como llamando a ungetc para un elemento de tipo char.

basic_filebuf::p os_type

Hace que este tipo en el ámbito de basic_filebuf equivalga al tipo con el mismo nombre del ámbito Tr.

typedef typename traits_type::pos_type pos_type;

basic_filebuf::seekoff

Intenta modificar las posiciones actuales de los flujos 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
La posición que se va a buscar relativa a _Way.

_Way
El punto de partida de las operaciones de desplazamiento. Vea los valores posibles en seekdir.

_Which
Especifica el modo de la posición del puntero. El valor predeterminado es permitirle modificar las posiciones de lectura y escritura.

Valor devuelto

Devuelve la posición nueva o una posición de flujo no válida.

Comentarios

La función miembro virtual protegida trata de modificar las posiciones actuales de las secuencias controladas. Para un objeto de clase basic_filebuf<Char_T, Tr>, un objeto de tipo fpos_t puede representar una posición del flujo, que almacena un desplazamiento y cualquier información de estado que se necesite para analizar un flujo ancho. El desplazamiento cero se refiere al primer elemento del flujo. (Un objeto de tipo pos_type almacena al menos un objeto fpos_t).

En el caso de un archivo abierto para lectura y escritura, los flujos de entrada y salida se colocan en tándem. Para cambiar entre inserción y extracción, debe llamar a pubseekoff o a pubseekpos. Las llamadas a pubseekoff (y por tanto a seekoff) tienen varias limitaciones para flujos de texto, flujos binarios y flujos anchos.

Si el puntero de archivo fp es un puntero nulo, se produce un error al ejecutar la función. De lo contrario, intenta modificar la posición del flujo al llamar a fseek(fp, _Off, _Way). Si esa función se ejecuta correctamente y la posición resultante fposn se puede determinar mediante una llamada a fgetpos(fp, &fposn), la función se ejecuta correctamente. Si la función se ejecuta correctamente, devuelve un valor de tipo pos_type que contiene fposn. De lo contrario, devuelve una posición de flujo no válida.

basic_filebuf::seekpos

Intenta modificar las posiciones actuales de los flujos controlados.

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

Parámetros

_Sp
La posición que se va a buscar.

_Which
Especifica el modo de la posición del puntero. El valor predeterminado es permitirle modificar las posiciones de lectura y escritura.

Valor devuelto

Si el puntero de archivo fp es un puntero nulo, se produce un error al ejecutar la función. De lo contrario, intenta modificar la posición del flujo al llamar a fsetpos(fp, &fposn), donde fposn es el objeto fpos_t almacenado en pos. Si esa función se ejecuta correctamente, la función devuelve pos. De lo contrario, devuelve una posición de flujo no válida. Para determinar si la posición del flujo no es válida, compare el valor devuelto con pos_type(off_type(-1)).

Comentarios

En el caso de un archivo abierto para lectura y escritura, los flujos de entrada y salida se colocan en tándem. Para cambiar entre inserción y extracción, debe llamar a pubseekoff o a pubseekpos. Las llamadas a pubseekoff (y a seekoff) tienen varias limitaciones para flujos de texto, flujos binarios y flujos anchos.

basic_filebuf::setbuf

Realiza una determinada operación para cada búfer de flujo derivado.

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

Parámetros

_Buffer
Puntero a un búfer.

count
Tamaño del búfer.

Valor devuelto

La función miembro protegida devuelve cero si el puntero de archivo fp es un puntero nulo.

Comentarios

setbuf llama a setvbuf( fp, (char*) _Buffer, _IOFBF, count * sizeof( Char_T)) para ofrecer la matriz de los elementos count que empiezan en _Buffer como búfer de flujo. Si esa función devuelve un valor distinto de cero, la función devuelve un puntero nulo. De lo contrario, devuelve this para señalar el éxito.

basic_filebuf::swap

Intercambia el contenido de este basic_filebuf por el contenido del basic_filebuf proporcionado.

void swap(basic_filebuf& right);

Parámetros

right
Referencia lvalue a un objeto basic_filebuf.

basic_filebuf::sync

Intenta sincronizar los flujos controlados con cualquier flujo externo asociado.

virtual int sync();

Valor devuelto

Devuelve cero si el puntero de archivo fp es un puntero nulo. De lo contrario, devuelve cero solo si las llamadas a overflow y fflush(fp) logran vaciar todas las salidas pendientes en el flujo.

basic_filebuf::traits_type

Asocia un nombre de tipo con el parámetro de plantilla Tr.

typedef Tr traits_type;

basic_filebuf::underflow

Extrae el elemento actual del flujo de entrada.

virtual int_type underflow();

Valor devuelto

Si la función no se puede ejecutar correctamente, devuelve traits_type::eof. De lo contrario, devuelve ch, convertido como se describe en la sección Comentarios.

Comentarios

La función miembro virtual protegida intenta extraer el elemento actual ch del flujo de entrada y devolver el elemento como traits_type::to_int_type(ch). Puede hacerlo de varias maneras:

Si hay una posición de lectura disponible, toma ch como elemento almacenado en la posición de lectura y avanza el puntero siguiente del búfer de entrada.
Puede leer uno o más elementos de tipo char, como si lo hiciera mediante llamadas sucesivas del formato fgetc(fp), y convertirlos en un elemento ch de tipo Char_T mediante la faceta de conversión de archivo fac para llamar a fac.in según sea necesario. Si se produce un error en cualquier conversión o lectura, la función no se ejecuta correctamente.

Consulte también

<fstream>
Seguridad para subprocesos en la biblioteca estándar de C++
Programación con iostream
Convenciones de iostreams

basic_filebuf (Clase)

Sintaxis

Parámetros

Comentarios

Ejemplo

Constructores

Typedefs

Funciones miembro

Requisitos

basic_filebuf::basic_filebuf

Comentarios

basic_filebuf::char_type

basic_filebuf::close

Valor devuelto

Comentarios

Ejemplo

basic_filebuf::int_type

basic_filebuf::is_open

Valor devuelto

Ejemplo

basic_filebuf::off_type

basic_filebuf::open

Parámetros

Valor devuelto

Comentarios

Ejemplo

basic_filebuf::operator=

Parámetros

Valor devuelto

Comentarios

basic_filebuf::overflow

Parámetros

Valor devuelto

Comentarios

basic_filebuf::p backfail

Parámetros

Valor devuelto

Comentarios

basic_filebuf::p os_type

basic_filebuf::seekoff

Parámetros

Valor devuelto

Comentarios

basic_filebuf::seekpos

Parámetros

Valor devuelto

Comentarios

basic_filebuf::setbuf

Parámetros

Valor devuelto

Comentarios

basic_filebuf::swap

Parámetros

basic_filebuf::sync

Valor devuelto

basic_filebuf::traits_type

basic_filebuf::underflow

Valor devuelto

Comentarios

Consulte también

Comentarios

Comentarios

Recursos adicionales