Classe basic_filebuf

Descrive un buffer di flusso che controlla la trasmissione di elementi di tipo Char_T, i cui tratti di carattere sono determinati dalla classe Tr, da e verso una sequenza di elementi archiviati in un file esterno.

Sintassi

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

Parametri

Char_T
L'elemento di base del buffer di file.

Tr
Tratti dell'elemento di base del buffer di file (in genere char_traits<Char_T>).

Osservazioni:

Il modello di classe descrive un buffer di flusso che controlla la trasmissione di elementi di tipo Char_T, i cui tratti di carattere sono determinati dalla classe Tr, da e verso una sequenza di elementi archiviati in un file esterno.

Un oggetto della classe basic_filebuf<Char_T, Tr> archivia un puntatore di file, che definisce l'oggetto FILE che controlla il flusso associato a un file aperto. Archivia anche i puntatori a due facet di conversione di file usati dalle funzioni membro protetto overflow e underflow. Per ulteriori informazioni, vedere basic_filebuf::open.

Esempio

L'esempio seguente illustra come forzare un oggetto di tipo basic_filebuf<wchar_t> per archiviare i caratteri Unicode nel buffer interno chiamando il metodo 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...........

Costruttori

Costruttore	Descrizione
basic_filebuf	Costruisce un oggetto di tipo basic_filebuf.

Typedef

Nome tipo	Descrizione
char_type	Associa un nome di tipo al parametro di modello Char_T.
int_type	Rende questo tipo all'interno dell'ambito di basic_filebuf equivalente al tipo con lo stesso nome nell'ambito Tr.
off_type	Rende questo tipo all'interno dell'ambito di basic_filebuf equivalente al tipo con lo stesso nome nell'ambito Tr.
pos_type	Rende questo tipo all'interno dell'ambito di basic_filebuf equivalente al tipo con lo stesso nome nell'ambito Tr.
traits_type	Associa un nome di tipo al parametro di modello Tr.

Funzioni membro

Funzione membro	Descrizione
close	Chiude un file.
is_open	Indica se un file è aperto.
open	Apre un file.
overflow	Una funzione virtuale protetta che può essere chiamata quando viene inserito un nuovo carattere in un buffer pieno.
pbackfail	La funzione membro virtuale protetta prova a usare un elemento in un flusso di input, quindi renderlo l'elemento corrente (a cui punta il puntatore successivo).
seekoff	La funzione membro virtuale protetta prova a modificare le posizioni correnti per i flussi di controllati.
seekpos	La funzione membro virtuale protetta prova a modificare le posizioni correnti per i flussi di controllati.
setbuf	La funzione membro virtuale protetta esegue una particolare operazione per ogni buffer del flusso derivato.
Swap	Scambia il contenuto di questo basic_filebuf con il contenuto del parametro basic_filebuf fornito.
sync	Funzione virtuale protetta che prova a sincronizzare i flussi controllati con qualsiasi flusso esterno associato.
uflow	Funzione virtuale protetta per estrarre l'elemento corrente dal flusso di input.
underflow	Funzione virtuale protetta per estrarre l'elemento corrente dal flusso di input.

Requisiti

Header:<fstream>

Spazio dei nomi: std

basic_filebuf::basic_filebuf

Costruisce un oggetto di tipo basic_filebuf.

basic_filebuf();

basic_filebuf(basic_filebuf&& right);

Osservazioni:

Il primo costruttore archivia un puntatore null in tutti i puntatori che controllano il buffer di input e il buffer di output. Archivia anche un puntatore null nel puntatore del file.

Il secondo costruttore inizializza l'oggetto con il contenuto di right, considerato come riferimento rvalue.

basic_filebuf::char_type

Associa un nome di tipo al parametro di modello Char_T.

typedef Char_T char_type;

basic_filebuf::close

Chiude un file.

basic_filebuf<Char_T, Tr> *close();

Valore restituito

La funzione membro restituisce un puntatore null se il puntatore del file è un puntatore null.

Osservazioni:

close chiama fclose(fp). Se la funzione restituisce un valore diverso da zero, la funzione restituisce un puntatore null. In caso contrario, viene restituito this per indicare che il file è stato chiuso correttamente.

Per un flusso wide, se si sono verificati inserimenti dopo l'apertura del flusso o dall'ultima chiamata a streampos, la funzione chiama overflow. Inserisce anche qualsiasi sequenza necessaria per ripristinare lo stato di conversione iniziale, usando il facet fac di conversione del file per chiamare fac.unshift in base alle esigenze. Ogni elemento byte prodotto di tipo char viene scritto nel flusso associato designato dal puntatore fp al file come se tramite chiamate successive del modulo fputc(byte, fp). Se la chiamata a fac.unshift o qualsiasi scrittura ha esito negativo, la funzione non riesce.

Esempio

L'esempio seguente presuppone due file nella directory corrente: basic_filebuf_close.txt (il contenuto è "testing") e iotest.txt (il contenuto è "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

Rende questo tipo all'interno dell'ambito basic_filebuf equivalente al tipo dello stesso nome nell'ambito Tr .

typedef typename traits_type::int_type int_type;

basic_filebuf::is_open

Indica se un file è aperto.

bool is_open() const;

Valore restituito

true se il puntatore al file non è Null.

Esempio

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

Rende questo tipo all'interno dell'ambito basic_filebuf equivalente al tipo dello stesso nome nell'ambito Tr .

typedef typename traits_type::off_type off_type;

basic_filebuf::open

Apre un file.

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

Parametri

filename
Nome del file da aprire.

mode
Una delle enumerazioni in ios_base::openmode.

protezione
Protezione di apertura file predefinita, equivalente al parametro shflag in _fsopen, _wfsopen.

Valore restituito

Se il buffer è già aperto o se il puntatore al file è un puntatore Null, la funzione restituisce un puntatore Null. In caso contrario, viene restituito this.

Osservazioni:

Questa funzione usa un FILE * oggetto per eseguire il basic_filebuf backup di come se fosse stato chiamato fopen/wfopen(filename, strmode). strmodeè determinato da mode & ~(ate binary|):

• ios_base::in diventa "r" (aprire il file esistente per la lettura).
• ios_base::out o ios_base::out | ios_base::trunc diventa "w" (tronca il file esistente o crea per la scrittura).
• ios_base::out | app diventa "a" (aprire il file esistente per accodare tutte le scritture).
• ios_base::in | ios_base::out diventa "r+" (aprire il file esistente per la lettura e la scrittura).
• ios_base::in | ios_base::out | ios_base::trunc diventa "w+" (tronca il file esistente o crea per la lettura e la scrittura).
• ios_base::in | ios_base::out | ios_base::app diventa "a+" (aprire il file esistente per la lettura e per l'aggiunta di tutte le scritture).

Se mode & ios_base::binary è diverso da zero, la funzione aggiunge b a strmode per aprire un flusso binario anziché un flusso di testo. Se mode & ios_base::ate è diverso da zero e il file è stato aperto correttamente, il percorso corrente nel flusso viene posizionato alla fine del file. In caso di errore, il file viene chiuso.

Se le operazioni precedenti sono state completate correttamente, il facet di conversione dei file viene determinato: use_facet<codecvt<Char_T, char, traits_type::state_type)> >(getloc, per l'uso da underflow e overflow.

Se non è stato possibile aprire correttamente il file, nullptr viene restituito .

Esempio

Vedere basic_filebuf::close per un esempio che usa open.

basic_filebuf::operator=

Assegna il contenuto di questo oggetto buffer del flusso. Si tratta di un'assegnazione di spostamento che coinvolge un rvalue che non lascia una copia dietro.

basic_filebuf& operator=(basic_filebuf&& right);

Parametri

right
Riferimento rvalue a un oggetto basic_filebuf.

Valore restituito

Restituisce *this.

Osservazioni:

L'operatore del membro sostituisce i contenuti dell'oggetto usando i contenuti di right, gestiti come un riferimento rvalue. Per altre informazioni, vedere Dichiaratore di riferimento Rvalue: &&.

basic_filebuf::overflow

Chiamato quando viene inserito un nuovo carattere in un buffer completo.

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

Parametri

_Meta
Carattere da inserire nel buffer o traits_type::eof.

Valore restituito

Se la funzione non riesce, restituisce traits_type::eof. In caso contrario, viene restituito traits_type::not_eof(_Meta).

Osservazioni:

Se _Meta != traits_type::eof, la funzione membro virtuale protetta tenta di inserire l'elemento ch = traits_type::to_char_type(_Meta) nel buffer di output. Questa operazione può essere eseguita in vari modi:

• Se è disponibile una posizione di scrittura, può archiviare l'elemento in tale posizione e incrementare il puntatore successivo per il buffer di output.

• Una posizione di scrittura può essere resa disponibile allocando spazio di archiviazione nuovo o aggiuntivo per il buffer di output.

• Può convertire qualsiasi output in sospeso nel buffer di output, seguito da ch, usando il facet fac di conversione file per chiamare fac.out in base alle esigenze. Ogni elemento ch prodotto di tipo char viene scritto nel flusso associato designato dal puntatore fp al file come se tramite chiamate successive del modulo fputc(ch, fp). Se una conversione o una scrittura ha esito negativo, la funzione non riesce.

basic_filebuf::p backfail

Tenta di reinserire un elemento in un flusso di input, quindi lo imposta come elemento corrente (a cui punta il puntatore successivo).

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

Parametri

_Meta
Carattere da inserire nel buffer o traits_type::eof.

Valore restituito

Se la funzione non riesce, restituisce traits_type::eof. In caso contrario, viene restituito traits_type::not_eof(_Meta).

Osservazioni:

La funzione membro virtuale protetta reinserisce un elemento nel buffer di input e quindi lo imposta come elemento corrente (a cui punta il puntatore successivo). Se _Meta == traits_type::eof, l'elemento di cui eseguire il pushback è effettivamente quello già presente nel flusso prima dell'elemento corrente. In caso contrario, tale elemento viene sostituito da ch = traits_type::to_char_type(_Meta). La funzione può reinserire un elemento in vari modi:

• Se è disponibile una putback posizione e l'elemento archiviato è uguale a ch, può decrementare il puntatore successivo per il buffer di input.

• Se la funzione può rendere disponibile una putback posizione, può farlo, impostare il puntatore successivo in modo che punti a tale posizione e archiviarlo ch in tale posizione.

• Se la funzione può eseguire il push di un elemento nel flusso di input, può farlo, ad esempio chiamando ungetc per un elemento di tipo char.

basic_filebuf::p os_type

Rende questo tipo all'interno dell'ambito basic_filebuf equivalente al tipo dello stesso nome nell'ambito Tr .

typedef typename traits_type::pos_type pos_type;

basic_filebuf::seekoff

Tenta di modificare le posizioni correnti per i flussi di controllati.

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

Parametri

_Spento
Posizione da cercare rispetto a _Way.

_Maniera
Punto iniziale per le operazioni di offset. Vedere seekdir per i valori possibili.

_Che
Specifica la modalità per la posizione del puntatore. L'impostazione predefinita consente di modificare le posizioni di lettura e scrittura.

Valore restituito

Restituisce la nuova posizione o una posizione di flusso non valida.

Osservazioni:

La funzione membro virtuale protetta tenta di modificare le posizioni correnti per i flussi controllati. Per un oggetto della classe basic_filebuf<Char_T, Tr>, una posizione del flusso può essere rappresentata da un oggetto di tipo fpos_t, che archivia un offset e qualsiasi informazione sullo stato necessaria per analizzare un flusso wide. Offset zero fa riferimento al primo elemento del flusso. (Un oggetto di tipo pos_type archivia almeno un oggetto fpos_t).

Per un file aperto per la lettura e la scrittura, entrambi i flussi di input e output vengono posizionati in parallelo. Per passare dall'inserimento all'estrazione, è necessario chiamare pubseekoff o pubseekpos. Le chiamate a pubseekoff, e di conseguenza a seekoff, presentano diverse limitazioni per i flussi di testo, i flussi binari e i flussi wide.

Se il puntatore fp al file è un puntatore Null, la funzione ha esito negativo. In caso contrario, tenta di modificare la posizione del flusso chiamando fseek(fp, _Off, _Way). Se la funzione ha esito positivo e la posizione fposn risultante può essere determinata chiamando fgetpos(fp, &fposn), la funzione ha esito positivo. Se la funzione ha esito positivo, restituisce un valore di tipo pos_type contenente fposn. In caso contrario, restituisce una posizione di flusso non valida.

basic_filebuf::seekpos

Tenta di modificare le posizioni correnti per i flussi di controllati.

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

Parametri

_Sp
Posizione da cercare.

_Che
Specifica la modalità per la posizione del puntatore. L'impostazione predefinita consente di modificare le posizioni di lettura e scrittura.

Valore restituito

Se il puntatore fp al file è un puntatore Null, la funzione ha esito negativo. In caso contrario, tenta di modificare la posizione del flusso chiamando fsetpos(fp, &fposn), dove fposn è l'oggetto fpos_t archiviato in pos. Se tale funzione ha esito positivo, la funzione restituisce pos. In caso contrario, restituisce una posizione di flusso non valida. Per stabilire se la posizione del flusso non è valida, confrontare il valore restituito con pos_type(off_type(-1)).

Osservazioni:

La funzione membro virtuale protetta tenta di modificare le posizioni correnti per i flussi controllati. Per un oggetto della classe basic_filebuf<Char_T, Tr>, una posizione del flusso può essere rappresentata da un oggetto di tipo fpos_t, che archivia un offset e qualsiasi informazione sullo stato necessaria per analizzare un flusso wide. Offset zero fa riferimento al primo elemento del flusso. (Un oggetto di tipo pos_type archivia almeno un oggetto fpos_t).

Per un file aperto per la lettura e la scrittura, entrambi i flussi di input e output vengono posizionati in parallelo. Per passare dall'inserimento all'estrazione, è necessario chiamare pubseekoff o pubseekpos. Le chiamate a pubseekoff (e a seekoff) presentano varie limitazioni per flussi di testo, flussi binari e flussi wide.

Per un flusso wide, se si sono verificati inserimenti dopo l'apertura del flusso o dall'ultima chiamata a streampos, la funzione chiama overflow. Inserisce anche qualsiasi sequenza necessaria per ripristinare lo stato di conversione iniziale, usando il facet fac di conversione del file per chiamare fac.unshift in base alle esigenze. Ogni elemento byte prodotto di tipo char viene scritto nel flusso associato designato dal puntatore fp al file come se tramite chiamate successive del modulo fputc(byte, fp). Se la chiamata a fac.unshift o qualsiasi scrittura ha esito negativo, la funzione non riesce.

basic_filebuf::setbuf

Esegue una particolare operazione in ogni buffer del flusso derivato.

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

Parametri

_Buffer
Puntatore a un buffer.

count
Dimensioni del buffer .

Valore restituito

La funzione membro protetto restituisce zero se il puntatore del file fp è un puntatore null.

Osservazioni:

setbuf chiama setvbuf( fp, (char*) _Buffer, _IOFBF, count * sizeof( Char_T)) per offrire la matrice di count elementi a partire da _Buffer come buffer per il flusso. Se la funzione restituisce un valore diverso da zero, la funzione restituisce un puntatore null. In caso contrario, restituisce this un segnale di esito positivo.

basic_filebuf::swap

Scambia il contenuto di questo basic_filebuf con il contenuto dell'oggetto basic_filebuf fornito.

void swap(basic_filebuf& right);

Parametri

right
Riferimento lvalue a un altro basic_filebufoggetto .

basic_filebuf::sync

Tenta di sincronizzare i flussi controllati con qualsiasi flusso esterno associato.

virtual int sync();

Valore restituito

Restituisce zero se il puntatore fp al file è un puntatore Null. In caso contrario, restituisce zero solo se le chiamate a overflow e fflush(fp) hanno esito positivo nello scaricamento di qualsiasi output in sospeso nel flusso.

basic_filebuf::traits_type

Associa un nome di tipo al parametro di modello Tr.

typedef Tr traits_type;

basic_filebuf::underflow

Estrae l'elemento corrente dal flusso di input.

virtual int_type underflow();

Valore restituito

Se la funzione non riesce, restituisce traits_type::eof. In caso contrario, restituisce ch, convertito come descritto nella sezione Osservazioni.

Osservazioni:

La funzione membro virtuale protetta tenta di estrarre l'elemento ch corrente dal flusso di input e restituisce l'elemento cometo_int_typetraits_type::(ch) . Questa operazione può essere eseguita in vari modi:

• Se è disponibile una posizione di lettura, accetta ch come elemento archiviato nella posizione di lettura e avanza il puntatore successivo per il buffer di input.

• Può leggere uno o più elementi di tipo char, come se tramite chiamate successive del modulo fgetc(fp)e convertirle in un elemento ch di tipo Char_T usando il facet fac di conversione file per chiamare fac.in in base alle esigenze. Se una qualsiasi conversione o lettura ha esito negativo, la funzione non riesce.

Vedi anche

<fstream>
Thread Safety in the C++ Standard Library (Sicurezza dei thread nella libreria standard C++)
Programmazione iostream
iostreams Conventions (Convenzioni di iostream)