basic_filebuf, classe

Décrit une mémoire tampon de flux qui contrôle la transmission d’éléments de type Char_T, dont les caractéristiques de caractère sont déterminées par la classe Tr, vers et à partir d’une séquence d’éléments stockés dans un fichier externe.

Syntaxe

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

Paramètres

Char_T
Élément de base de la mémoire tampon de fichier.

Tr
Caractéristiques de l’élément de base de la mémoire tampon de fichier (généralement char_traits<Char_T>).

Notes

Le modèle de classe décrit une mémoire tampon de flux qui contrôle la transmission d’éléments de type Char_T, dont les caractéristiques de caractère sont déterminées par la classe Tr, vers et à partir d’une séquence d’éléments stockés dans un fichier externe.

Un objet de classe basic_filebuf<Char_T, Tr> stocke un pointeur de fichier, qui désigne l’objet FILE qui contrôle le flux associé à un fichier ouvert. Il stocke également des pointeurs vers deux facettes de conversion de fichier utilisables par les fonctions membres protégées overflow et underflow. Pour plus d’informations, consultez basic_filebuf::open.

Exemple

L'exemple suivant montre comment forcer un objet de type basic_filebuf<wchar_t> à stocker des caractères Unicode dans sa mémoire tampon interne en appelant la méthode 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...........

Constructeurs

Constructeur	Description
basic_filebuf	Construit un objet de type basic_filebuf.

Typedefs

Nom de type	Description
char_type	Associe un nom de type au paramètre de modèle Char_T.
int_type	Rend ce type dans la portée de basic_filebuf équivalent au type du même nom dans la portée de Tr.
off_type	Rend ce type dans la portée de basic_filebuf équivalent au type du même nom dans la portée de Tr.
pos_type	Rend ce type dans la portée de basic_filebuf équivalent au type du même nom dans la portée de Tr.
traits_type	Associe un nom de type au paramètre de modèle Tr.

Fonctions Membre

Fonction membre	Description
close	Ferme un fichier.
is_open	Indique si un fichier est ouvert.
open	Ouvre un fichier.
overflow	Fonction virtuelle protégée qui peut être appelée quand un nouveau caractère est inséré dans une mémoire tampon saturée.
pbackfail	La fonction membre virtuelle protégée tente de remettre un élément dans le flux d'entrée, puis d'en faire l'élément actif (vers lequel pointe le pointeur suivant).
seekoff	La fonction membre virtuelle protégée tente de modifier les positions actuelles des flux contrôlés.
seekpos	La fonction membre virtuelle protégée tente de modifier les positions actuelles des flux contrôlés.
setbuf	La fonction membre virtuelle protégée effectue une opération spécifique à chaque mémoire tampon de flux dérivée.
Swap	Échange le contenu de ce basic_filebuf avec le contenu du paramètre basic_filebuf fourni.
sync	La fonction virtuelle protégée tente de synchroniser les flux contrôlés avec n’importe quel flux externe associé.
uflow	Fonction virtuelle protégée pour extraire l'élément actif du flux d'entrée.
underflow	Fonction virtuelle protégée pour extraire l'élément actif du flux d'entrée.

Spécifications

Header :<fstream>

Espace de noms : std

basic_filebuf ::basic_filebuf

Construit un objet de type basic_filebuf.

basic_filebuf();

basic_filebuf(basic_filebuf&& right);

Notes

Le premier constructeur stocke un pointeur null dans tous les pointeurs contrôlant la mémoire tampon d’entrée et la mémoire tampon de sortie. Il stocke également un pointeur null dans le pointeur de fichier.

Le deuxième constructeur initialise l’objet avec le contenu de right, traité comme une référence rvalue.

basic_filebuf ::char_type

Associe un nom de type au paramètre de modèle Char_T.

typedef Char_T char_type;

basic_filebuf ::close

Ferme un fichier.

basic_filebuf<Char_T, Tr> *close();

Valeur de retour

La fonction membre retourne un pointeur null si le pointeur de fichier est un pointeur null.

Notes

close appelle fclose(fp). Si cette fonction retourne une valeur différente de zéro, la fonction retourne un pointeur null. Sinon, elle retourne this pour indiquer que le fichier a été correctement fermé.

Pour un flux large, si des insertions se sont produites depuis l’ouverture du flux, ou depuis le dernier appel à streampos, la fonction appelle overflow. Il insère également toute séquence nécessaire pour restaurer l’état de conversion initial, à l’aide de la facette fac de conversion de fichier pour appeler fac.unshift si nécessaire. Chaque élément byte de type char produit est écrit dans le flux associé désigné par le pointeur fp de fichier comme s’il s’agit d’appels successifs du formulaire fputc(byte, fp). Si l’appel à fac.unshift ou l’écriture échoue, la fonction ne réussit pas.

Exemple

L’exemple suivant suppose deux fichiers dans le répertoire actif : basic_filebuf_close.txt (le contenu est « test ») et iotest.txt (le contenu est « 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

Rend ce type dans l’étendue basic_filebuf équivalente au type du même nom dans l’étendue Tr .

typedef typename traits_type::int_type int_type;

basic_filebuf ::is_open

Indique si un fichier est ouvert.

bool is_open() const;

Valeur de retour

true si le pointeur de fichier n’est pas null.

Exemple

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

Rend ce type dans l’étendue basic_filebuf équivalente au type du même nom dans l’étendue Tr .

typedef typename traits_type::off_type off_type;

basic_filebuf ::open

Ouvre un fichier.

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

Paramètres

nom_fichier
Nom du fichier à ouvrir.

mode
L’une des énumérations dans ios_base::openmode.

protection
Protection d’ouverture de fichier par défaut, équivalente au paramètre shflag dans _fsopen, _wfsopen.

Valeur de retour

Si la mémoire tampon est déjà ouverte ou si le pointeur de fichier est un pointeur Null, la fonction retourne un pointeur Null. Sinon, thisest retourné.

Notes

Cette fonction utilise une FILE * fonction pour revenir en arrière comme basic_filebuf si vous aviez appelé fopen/wfopen(filename, strmode). strmodeest déterminé à partir de mode & ~()ate | binary:

• ios_base::in devient "r" (ouvrir un fichier existant pour la lecture).
• ios_base ::out ou ios_base::out | ios_base::trunc devient "w" (tronquer le fichier existant ou créer pour l’écriture).
• ios_base::out | app devient "a" (ouvrez le fichier existant pour ajouter toutes les écritures).
• ios_base::in | ios_base::out devient "r+" (ouvrir un fichier existant pour la lecture et l’écriture).
• ios_base::in | ios_base::out | ios_base::trunc devient "w+" (tronquer le fichier existant ou créer pour la lecture et l’écriture).
• ios_base::in | ios_base::out | ios_base::app devient "a+" (ouvrez le fichier existant pour lire et ajouter toutes les écritures).

Si mode & ios_base::binary elle n’est pas différente de zéro, la fonction ajoute b pour strmode ouvrir un flux binaire au lieu d’un flux de texte. S’il mode & ios_base::ate n’est pas différent de zéro et que le fichier a été correctement ouvert, l’emplacement actuel du flux est positionné à la fin du fichier. En cas d’échec, le fichier est fermé.

Si les opérations ci-dessus se sont terminées avec succès, la facette de conversion de fichier est déterminée : use_facet<codecvt<Char_T, char, traits_type::state_type> >(getloc)pour une utilisation par sous-flux et dépassement de capacité.

Si le fichier n’a pas pu être correctement ouvert, nullptr est retourné.

Exemple

Consultez basic_filebuf::close un exemple qui utilise open.

basic_filebuf ::operator=

Affecter le contenu de cet objet de mémoire tampon de flux. Il s’agit d’une affectation de déplacement impliquant une rvalue qui ne laisse pas de copie derrière elle.

basic_filebuf& operator=(basic_filebuf&& right);

Paramètres

right
Référence rvalue à un objet basic_filebuf.

Valeur de retour

Retourne *this.

Notes

L'opérateur membre remplace le contenu de l'objet à l'aide du contenu de right, traité comme une référence rvalue. Pour plus d'informations, consultez Déclarateur de référence rvalue : &&.

basic_filebuf ::overflow

Appelé quand un nouveau caractère est inséré dans une mémoire tampon saturée.

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

Paramètres

_Méta
Caractère à insérer dans la mémoire tampon ou traits_type::eof.

Valeur de retour

Si la fonction ne peut pas réussir, elle retourne traits_type::eof. Sinon, traits_type::not_eof(_Meta)est retourné.

Notes

Si _Meta != traits_type::eof, la fonction membre virtuelle protégée tente d’insérer l’élément(_Meta) ch = traits_type::to_char_typedans la mémoire tampon de sortie. Elle peut le faire de différentes manières :

• Si une position d’écriture est disponible, elle peut stocker l’élément dans la position d’écriture et incrémenter le pointeur suivant pour la mémoire tampon de sortie.

• Elle peut rendre disponible une position d’écriture en allouant du stockage nouveau ou supplémentaire à la mémoire tampon de sortie.

• Il peut convertir n’importe quelle sortie en attente dans la mémoire tampon de sortie, suivie par ch, à l’aide de la facette fac de conversion de fichier pour appeler fac.out si nécessaire. Chaque élément ch produit de type char est écrit dans le flux associé désigné par le pointeur fp de fichier comme s’il s’agit d’appels successifs du formulaire fputc(ch, fp). Si une conversion ou écriture échoue, la fonction ne réussit pas.

basic_filebuf ::p backfail

Tente de remettre un élément dans le flux d’entrée, puis d’en faire l’élément actuel (désigné par le pointeur suivant).

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

Paramètres

_Méta
Caractère à insérer dans la mémoire tampon, ou traits_type::eof.

Valeur de retour

Si la fonction ne peut pas réussir, elle retourne traits_type::eof. Sinon, traits_type::not_eof(_Meta)est retourné.

Notes

La fonction membre virtuelle protégée remet un élément dans la mémoire tampon d’entrée, puis en fait l’élément actuel (désigné par le pointeur suivant). Si _Meta == traits_type::eof, l’élément à renvoyer est effectivement celui déjà dans le flux avant l’élément actuel. Sinon, cet élément est remplacé par ch = traits_type::to_char_type(_Meta). La fonction peut remettre un élément de différentes manières :

• Si une putback position est disponible et que l’élément stocké y est égal ch, il peut décrémenter le pointeur suivant pour la mémoire tampon d’entrée.

• Si la fonction peut rendre une putback position disponible, elle peut le faire, définir le pointeur suivant sur ce pointeur et le stocker ch dans cette position.

• Si la fonction peut renvoyer un élément sur le flux d’entrée, elle peut le faire, par exemple en appelant ungetc un élément de type char.

basic_filebuf ::p os_type

Rend ce type dans l’étendue basic_filebuf équivalente au type du même nom dans l’étendue Tr .

typedef typename traits_type::pos_type pos_type;

basic_filebuf ::seekoff

Tente de modifier les positions actuelles des flux contrôlés.

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

Paramètres

_De
Position à rechercher par rapport à _Way.

_Manière
Point de départ des opérations de décalage. Consultez seekdir pour connaître les valeurs possibles.

_Quel
Spécifie le mode pour la position du pointeur. Par défaut, vous êtes autorisé à modifier les positions de lecture et d’écriture.

Valeur de retour

Retourne la nouvelle position ou une position de flux non valide.

Notes

La fonction membre virtuelle protégée tente de modifier les positions actuelles des flux contrôlés. Pour un objet de classe basic_filebuf<Char_T, Tr>, une position de flux peut être représentée par un objet de type fpos_t, qui stocke un décalage et toutes les informations d’état nécessaires pour analyser un flux large. Offset zéro fait référence au premier élément du flux. (Un objet de type pos_type stocke au moins un objet fpos_t.)

Dans le cas d’un fichier ouvert pour lecture et écriture, les flux d’entrée et de sortie sont positionnés en tandem. Pour basculer entre l’insertion et l’extraction, vous devez appeler l’une ou l’autre pubseekoff .pubseekpos Les appels à pubseekoff (et donc à seekoff) ont plusieurs limites pour les flux de texte, les flux binaires et les flux larges.

Si le pointeur de fichier est un pointeur fp Null, la fonction échoue. Sinon, il tente de modifier la position du flux en appelant fseek(fp, _Off, _Way). Si cette fonction réussit et que la position fposn résultante peut être déterminée en appelant fgetpos(fp, &fposn), la fonction réussit. Si la fonction réussit, elle retourne une valeur de type pos_type contenant fposn. Sinon, elle retourne une position de flux non valide.

basic_filebuf ::seekpos

Tente de modifier les positions actuelles des flux contrôlés.

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

Paramètres

_Sp
Position à rechercher.

_Quel
Spécifie le mode pour la position du pointeur. Par défaut, vous êtes autorisé à modifier les positions de lecture et d’écriture.

Valeur de retour

Si le pointeur de fichier est un pointeur fp Null, la fonction échoue. Sinon, il tente de modifier la position du flux en appelant fsetpos(fp, &fposn), où fposn est l’objet fpos_t stocké dans pos. Si la fonction réussit, elle retourne pos. Sinon, elle retourne une position de flux non valide. Pour déterminer si la position du flux est non valide, comparez la valeur de retour à pos_type(off_type(-1)).

Notes

La fonction membre virtuelle protégée tente de modifier les positions actuelles des flux contrôlés. Pour un objet de classe basic_filebuf<Char_T, Tr>, une position de flux peut être représentée par un objet de type fpos_t, qui stocke un décalage et toutes les informations d’état nécessaires pour analyser un flux large. Offset zéro fait référence au premier élément du flux. (Un objet de type pos_type stocke au moins un objet fpos_t.)

Dans le cas d’un fichier ouvert pour lecture et écriture, les flux d’entrée et de sortie sont positionnés en tandem. Pour basculer entre l’insertion et l’extraction, vous devez appeler l’une ou l’autre pubseekoff .pubseekpos Les appels à (et à pubseekoff seekoff) ont diverses limitations pour les flux de texte, les flux binaires et les flux larges.

Pour un flux large, si des insertions se sont produites depuis l’ouverture du flux, ou depuis le dernier appel à streampos, la fonction appelle overflow. Il insère également toute séquence nécessaire pour restaurer l’état de conversion initial, à l’aide de la facette fac de conversion de fichier pour appeler fac.unshift si nécessaire. Chaque élément byte de type char produit est écrit dans le flux associé désigné par le pointeur fp de fichier comme s’il s’agit d’appels successifs du formulaire fputc(byte, fp). Si l’appel à fac.unshift ou l’écriture échoue, la fonction ne réussit pas.

basic_filebuf ::setbuf

Effectue une opération spécifique pour chaque mémoire tampon de flux dérivée.

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

Paramètres

_Tampon
Pointeur vers une mémoire tampon.

count
Taille de la mémoire tampon.

Valeur de retour

La fonction membre protégée retourne un zéro si le pointeur de fichier fp est un pointeur null.

Notes

setbuf appels setvbuf( fp, (char*) _Buffer, _IOFBF, count * sizeof( Char_T)) pour offrir le tableau d’éléments count commençant à _Buffer en tant que mémoire tampon pour le flux. Si cette fonction retourne une valeur différente de zéro, la fonction retourne un pointeur null. Sinon, elle revient this à signaler la réussite.

basic_filebuf ::swap

Échange le contenu de ce basic_filebuf avec le contenu du basic_filebuf fourni.

void swap(basic_filebuf& right);

Paramètres

right
Référence lvalue à un autre basic_filebuf.

basic_filebuf ::sync

Tente de synchroniser les flux contrôlés avec n’importe quel flux externe associé.

virtual int sync();

Valeur de retour

Retourne zéro si le pointeur fp de fichier est un pointeur Null. Sinon, elle retourne zéro uniquement si les appels au dépassement de capacité et fflush(fp) réussissent à vider une sortie en attente dans le flux.

basic_filebuf ::traits_type

Associe un nom de type au paramètre de modèle Tr.

typedef Tr traits_type;

basic_filebuf ::underflow

Extrait l’élément actuel du flux d’entrée.

virtual int_type underflow();

Valeur de retour

Si la fonction ne peut pas réussir, elle retourne traits_type::eof. Sinon, elle retourne ch, convertie comme décrit dans la section Notes.

Notes

La fonction membre virtuelle protégée tente d’extraire l’élément ch actuel du flux d’entrée et de renvoyer l’élément en tant queto_int_typetraits_type::(ch) . Elle peut le faire de différentes manières :

• Si une position de lecture est disponible, elle prend ch comme élément stocké dans la position de lecture et avance le pointeur suivant pour la mémoire tampon d’entrée.

• Il peut lire un ou plusieurs éléments de type char, comme s’il s’agit d’appels successifs du formulaire fgetc(fp), et les convertir en élément ch de type Char_T à l’aide de la facette fac de conversion de fichier pour appeler fac.in si nécessaire. Si une lecture ou une conversion échoue, la fonction ne réussit pas.

Voir aussi

<fstream>
Sécurité des threads dans la bibliothèque C++ Standard
iostream, programmation
iostreams, conventions