strstreambuf, classe

Décrit une mémoire tampon de flux qui contrôle la transmission d'éléments vers et à partir d'une séquence d'éléments stockée dans un objet de tableau char.

Syntaxe

class strstreambuf : public streambuf

Notes

Selon la façon dont l'objet est construit, il peut être alloué, étendu et libéré en fonction des modifications apportées à la séquence.

Un objet de classe strstreambuf stocke plusieurs bits d'information de mode en tant que mode strstreambuf. Ces bits indiquent si la séquence contrôlée :

• a été allouée et doit être libérée par la suite ;

• est modifiable ;

• est extensible en réallouant le stockage ;

• a été figée et doit donc être défigée avant que l'objet soit détruit, ou libérée (si elle a été allouée) par une agence autre que l'objet.

Vous ne pouvez pas modifier ou étendre une séquence contrôlée figée, quel que soit l'état de ces bits de mode distincts.

L'objet stocke également des pointeurs vers deux fonctions qui contrôlent l'allocation de strstreambuf. Si ces pointeurs sont null, l'objet définit sa propre méthode d'allocation et de libération du stockage pour la séquence contrôlée.

Constructeurs

Fonctions Membre

Spécifications

Header :<strstream>

Espace de noms : std

strstreambuf ::freeze

Fait en sorte qu'une mémoire tampon de flux soit indisponible via des opérations de mémoire tampon de flux.

void freeze(bool _Freezeit = true);

Paramètres

_Freezeit
bool indiquant si vous souhaitez que le flux soit gelé.

Notes

Si _Freezeit a la valeur true, la fonction modifie le mode stocké strstreambuf pour que la séquence contrôlée soit figée. Dans le cas contraire, elle rend la séquence contrôlée non gelée.

str implique freeze.

Exemple

// strstreambuf_freeze.cpp
// compile with: /EHsc

#include <iostream>
#include <strstream>

using namespace std;

void report(strstream &x)
{
    if (!x.good())
        cout << "stream bad" << endl;
    else
        cout << "stream good" << endl;
}

int main()
{
    strstream x;

    x << "test1";
    cout << "before freeze: ";
    report(x);

    // Calling str freezes stream.
    cout.write(x.rdbuf()->str(), 5) << endl;
    cout << "after freeze: ";
    report(x);

    // Stream is bad now, wrote on frozen stream
    x << "test1.5";
    cout << "after write to frozen stream: ";
    report(x);

    // Unfreeze stream, but it is still bad
    x.rdbuf()->freeze(false);
    cout << "after unfreezing stream: ";
    report(x);

    // Clear stream
    x.clear();
    cout << "after clearing stream: ";
    report(x);

    x << "test3";
    cout.write(x.rdbuf()->str(), 10) << endl;

    // Clean up.  Failure to unfreeze stream will cause a
    // memory leak.
    x.rdbuf()->freeze(false);
}

before freeze: stream good
test1
after freeze: stream good
after write to frozen stream: stream bad
after unfreezing stream: stream bad
after clearing stream: stream good
test1test3

strstreambuf ::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.

virtual int overflow(int _Meta = EOF);

Paramètres

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

Valeur de retour

Si la fonction ne peut pas réussir, elle retourne EOF. Sinon, si _MetaEOF == , elle retourne une valeur autre que .EOF Sinon, elle retourne _Meta.

Notes

Si _Meta != EOF, la fonction membre virtuelle protégée tente d’insérer l’élément (char)_Meta dans 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.

• Si le mode strstreambuf stocké indique que la séquence contrôlée est modifiable, extensible et non gelée, la fonction peut proposer une position d’écriture en en allouant une nouvelle pour la mémoire tampon de sortie. Cette façon d’étendre la mémoire tampon de sortie permet également d’étendre les mémoires tampons d’entrée associées.

strstreambuf ::p backfail

Fonction membre virtuelle protégée qui tente de replacer un élément dans le flux d’entrée, puis d’en faire l’élément actif (vers lequel pointe le pointeur suivant).

virtual int pbackfail(int _Meta = EOF);

Paramètres

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

Valeur de retour

Si la fonction ne peut pas réussir, elle retourne EOF. Sinon, si _MetaEOF == , elle retourne une valeur autre que .EOF Sinon, elle retourne _Meta.

Notes

La fonction membre virtuelle protégée tente de replacer un élément dans la mémoire tampon d’entrée, puis d’en faire l’élément actif (vers lequel pointe le pointeur suivant).

Si _Meta == EOF, l’élément à renvoyer est effectivement celui déjà présent dans le flux avant l’élément actuel. Sinon, cet élément est remplacé par ch = (char)_Meta. La fonction peut remettre un élément de différentes manières :

• Si une position de putback 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 une position de putback est disponible et si le mode strstreambuf indique que la séquence contrôlée est modifiable, la fonction peut stocker ch dans la position de putback et décrémenter le pointeur suivant pour la mémoire tampon d’entrée.

strstreambuf ::p count

Retourne le nombre d'éléments écrits dans la séquence contrôlée.

streamsize pcount() const;

Valeur de retour

Un décompte du nombre d’éléments écrits dans la séquence contrôlée.

Notes

En particulier, si pptr est un pointeur Null, la fonction retourne zéro. Sinon, elle retourne pptr - pbase.

Exemple

// strstreambuf_pcount.cpp
// compile with: /EHsc
#include <iostream>
#include <strstream>
using namespace std;

int main( )
{
   strstream x;
   x << "test1";
   cout << x.rdbuf( )->pcount( ) << endl;
   x << "test2";
   cout << x.rdbuf( )->pcount( ) << endl;
}

strstreambuf ::seekoff

Fonction membre virtuelle protégée qui tente de modifier les positions actuelles des flux contrôlés.

virtual streampos seekoff(streamoff _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

Si la fonction réussit à modifier une ou les deux positions de flux, elle retourne la position de flux obtenue. Sinon, elle échoue et retourne une position de flux non valide.

Notes

La fonction membre virtuelle protégée s’efforce de modifier les positions actuelles des flux contrôlés. Pour un objet de classe strstreambuf, une position de flux se compose uniquement d’un décalage de flux. Le décalage zéro désigne le premier élément de la séquence contrôlée.

La nouvelle position est déterminée comme suit :

• Si _Way == ios_base::beg, la nouvelle position est le début du flux plus _Off.

• Si _Way == ios_base::cur, la nouvelle position est la position actuelle du flux plus _Off.

• Si _Way == ios_base::end, la nouvelle position est la fin du flux plus _Off.

Si _Which & ios_base::in elle n’est pas nulle et que la mémoire tampon d’entrée existe, la fonction modifie la position suivante pour lire dans la mémoire tampon d’entrée. Si _Which & ios_base::out elle n’est pas égale à zéro, _Way != ios_base::curet que la mémoire tampon de sortie existe, la fonction définit également la position suivante à écrire pour qu’elle corresponde à la position suivante à lire.

Dans le cas contraire, si _Which & ios_base::out est différent de zéro et que la mémoire tampon de sortie existe, la fonction modifie la position suivante d’écriture dans la mémoire tampon de sortie. Dans le cas contraire, l’opération de positionnement échoue. Pour qu’une opération de positionnement réussisse, la position de flux obtenue doit se trouver dans la séquence contrôlée.

strstreambuf ::seekpos

Fonction membre virtuelle protégée qui tente de modifier les positions actuelles des flux contrôlés.

virtual streampos seekpos(streampos _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 la fonction réussit à modifier une ou les deux positions de flux, elle retourne la position de flux obtenue. Sinon, elle échoue et 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 s’efforce de modifier les positions actuelles des flux contrôlés. Pour un objet de classe strstreambuf, une position de flux se compose uniquement d’un décalage de flux. Le décalage zéro désigne le premier élément de la séquence contrôlée. La nouvelle position est déterminée par _Sp.

Si _Which & ios_base ::in n’est pas zéro et que la mémoire tampon d’entrée existe, la fonction modifie la position suivante pour lire dans la mémoire tampon d’entrée. Si _Which & ios_base::out est différent de zéro et que la mémoire tampon de sortie existe, la fonction définit également la position suivante à écrire pour qu’elle corresponde à la position suivante à lire. Sinon, si _Which & est différent de ios_base::out zéro et que la mémoire tampon de sortie existe, la fonction modifie la position suivante pour écrire dans la mémoire tampon de sortie. Dans le cas contraire, l’opération de positionnement échoue. Pour qu’une opération de positionnement réussisse, la position de flux obtenue doit se trouver dans la séquence contrôlée.

strstreambuf ::str

Appelle freeze, puis retourne un pointeur vers le début de la séquence contrôlée.

char *str();

Valeur de retour

Pointeur vers le début de la séquence contrôlée.

Notes

Aucun élément Null de fin n’existe, à moins que n’en insériez explicitement un.

Exemple

Consultez strstreambuf::freeze pour obtenir un exemple qui utilise str.

strstreambuf ::strstreambuf

Construit un objet de type strstreambuf.

explicit strstreambuf(streamsize count = 0);

strstreambuf(void (* alloc_func)(size_t),
    void (* free_func)(void*));

strstreambuf(char* getptr,
    streamsize count,
    char* putptr = 0);

strstreambuf(signed char* getptr,
    streamsize count,
    signed char* putptr = 0);

strstreambuf(unsigned char* getptr,
    streamsize count,
    unsigned char* putptr = 0);

strstreambuf(const char* getptr,
    streamsize count);

strstreambuf(const signed char* getptr,
    streamsize count);

strstreambuf(const unsigned char* getptr,
    streamsize count);

Paramètres

alloc_func
Fonction utilisée pour allouer de la mémoire tampon.

count
Détermine la longueur de la mémoire tampon pointée par getptr. Si getptr n’est pas un argument (premier formulaire de constructeur), une taille d’allocation suggérée pour les mémoires tampons.

_Freefunc
Fonction utilisée pour libérer de la mémoire tampon.

getptr
Mémoire tampon utilisée pour l’entrée.

putptr
Mémoire tampon utilisée pour la sortie.

Notes

Le premier constructeur stocke un pointeur Null dans tous les pointeurs contrôlant la mémoire tampon d’entrée, la mémoire tampon de sortie et l’allocation strstreambuf. Il définit le mode strstreambuf stocké pour rendre la séquence contrôlée modifiable et extensible. Il accepte également le nombre comme taille d’allocation initiale suggérée.

Le deuxième constructeur se comporte comme le premier, sauf qu’il stocke alloc_func comme pointeur vers la fonction à appeler pour allouer le stockage et free_func comme pointeur vers la fonction pour appeler pour libérer ce stockage.

Les trois constructeurs :

strstreambuf(char *getptr,
    streamsize count,
    char *putptr = 0);

strstreambuf(signed char *getptr,
    streamsize count,
    signed char *putptr = 0);

strstreambuf(unsigned char *getptr,
    streamsize count,
    unsigned char *putptr = 0);

se comporte également comme le premier, sauf que getptr désigne l’objet de tableau utilisé pour contenir la séquence contrôlée. (Par conséquent, il ne doit pas s’agir d’un pointeur Null.) Le nombre d’éléments N dans le tableau est déterminé comme suit :

• Si (nombre> 0), N est le nombre.

• Si (nombre == 0), alors N est strlen((const char *) getptr ).

• Si (nombre< 0), N est INT_MAX.

Si putptr est un pointeur Null, la fonction établit simplement une mémoire tampon d’entrée en exécutant :

setg(getptr,
    getptr,
    getptr + N);

Sinon, elle établit des mémoires tampons d’entrée et de sortie en exécutant :

setg(getptr,
    getptr,
    putptr);

setp(putptr,
    getptr + N);

Dans ce cas, putptr doit être dans l’intervalle [ getptr, getptr + N].

Enfin, les trois constructeurs :

strstreambuf(const char *getptr,
    streamsize count);

strstreambuf(const signed char *getptr,
    streamsize count);

strstreambuf(const unsigned char *getptr,
    streamsize count);

se comportent tous comme :

streambuf((char *)getptr, count);

si ce n’est que le mode stocké ne rend la séquence contrôlée ni modifiable, ni extensible.

strstreambuf ::underflow

Fonction virtuelle protégée pour extraire l'élément actuel du flux d'entrée.

virtual int underflow();

Valeur de retour

Si la fonction ne peut pas réussir, elle retourne EOF. Sinon, elle retourne l’élément actuel dans le flux d’entrée, converti comme décrit ci-dessus.

Notes

La fonction membre virtuelle protégée s’efforce d’extraire l’élément ch actuel de la mémoire tampon d’entrée, puis d’avancer la position du flux actuel et de renvoyer l’élément en tant que (int)(unsigned char)ch. Il peut le faire d’une seule manière : 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.

Voir aussi

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