Classe strstreambuf

Descrive il buffer di un flusso che controlla la trasmissione di elementi da e verso una sequenza di elementi archiviati in un oggetto matrice char.

Sintassi

class strstreambuf : public streambuf

Osservazioni:

A seconda del modo in cui è costruito, l'oggetto può essere allocato, esteso e liberato in base alle modifiche necessarie nella sequenza.

Un oggetto della classe strstreambuf archivia diversi bit di informazioni sulla modalità come modalità strstreambuf. Questi bit indicano se la sequenza controllata:

• È stata allocata e deve essere liberata alla fine.

• È modificabile.

• È estendibile attraverso la riallocazione dell'archiviazione.

• È stata bloccata e di conseguenza deve essere sbloccata prima dell'eliminazione dell'oggetto oppure deve essere liberata (se allocata) da un'agenzia diversa dall'oggetto.

Una sequenza controllata bloccata non può essere modificata o estesa, indipendentemente dallo stato di questi bit di modalità separati.

L'oggetto archivia anche puntatori a due funzioni che controllano l'allocazione di strstreambuf. Se si tratta di puntatori Null, l'oggetto individua il proprio metodo per allocare e liberare archiviazione per la sequenza controllata.

Costruttori

Funzioni membro

Requisiti

Header:<strstream>

Spazio dei nomi: std

strstreambuf::freeze

Fa sì che un buffer del flusso non sia disponibile tramite le operazioni di buffer del flusso.

void freeze(bool _Freezeit = true);

Parametri

_Freezeit
Oggetto bool che indica se si vuole bloccare il flusso.

Osservazioni:

Se _Freezeit è true, la funzione modifica la modalità archiviata strstreambuf per bloccare la sequenza controllata. In caso contrario, la sequenza controllata non viene bloccata.

str implica freeze.

Esempio

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

Una funzione virtuale protetta che può essere chiamata quando viene inserito un nuovo carattere in un buffer pieno.

virtual int overflow(int _Meta = EOF);

Parametri

_Meta
Carattere da inserire nel buffer o EOF.

Valore restituito

Se la funzione non può essere eseguita correttamente, restituisce EOF. In caso contrario, se _MetaEOF == , restituisce un valore diverso da .EOF In caso contrario, restituisce _Meta.

Osservazioni:

Se _Meta != EOF, la funzione membro virtuale protetta tenta di inserire l'elemento (char)_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.

• Se in base alla modalità strstreambuf archiviata la sequenza controllata è modificabile, estendibile e non bloccata, la funzione può rendere disponibile una posizione di scrittura allocando nuova memoria per il buffer di output. Questa estensione del buffer di output estende anche eventuali buffer di input associati.

strstreambuf::p backfail

Funzione membro virtuale protetta che tenta di reinserire un elemento nel flusso di input e quindi di impostarlo come elemento corrente a cui punta il puntatore successivo.

virtual int pbackfail(int _Meta = EOF);

Parametri

_Meta
Carattere da inserire nel buffer o EOF.

Valore restituito

Se la funzione non può essere eseguita correttamente, restituisce EOF. In caso contrario, se _MetaEOF == , restituisce un valore diverso da .EOF In caso contrario, restituisce _Meta.

Osservazioni:

La funzione membro virtuale protetta prova a reinserire un elemento nel buffer di input e quindi di renderlo l'elemento corrente a cui punta il puntatore successivo.

Se _Meta == EOF, l'elemento di cui eseguire il push è effettivamente quello già presente nel flusso prima dell'elemento corrente. In caso contrario, tale elemento viene sostituito da ch = (char)_Meta. La funzione può reinserire un elemento in vari modi:

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

• Se è disponibile una posizione di putback e se la modalità strstreambuf indica che la sequenza controllata è modificabile, la funzione può archiviare ch nella posizione di putback e decrementare il puntatore successivo per il buffer di input.

strstreambuf::p count

Restituisce un conteggio del numero di elementi scritti nella sequenza controllata.

streamsize pcount() const;

Valore restituito

Conteggio del numero di elementi scritti nella sequenza controllata.

Osservazioni:

In particolare, se pptr è un puntatore null, la funzione restituisce zero. In caso contrario, restituisce pptr - pbase.

Esempio

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

Funzione membro virtuale protetta che prova a modificare le posizioni correnti per i flussi controllati.

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

Se la funzione modifica correttamente una o entrambe le posizioni del flusso, restituisce la risultante posizione del flusso. In caso contrario, ha esito negativo e restituisce una posizione del flusso non valida.

Osservazioni:

La funzione membro virtuale protetto tenta di modificare le posizioni correnti per i flussi controllati. Per un oggetto della classe strstreambuf, una posizione del flusso è costituita essenzialmente da un offset del flusso. L'offset zero designa il primo elemento della sequenza controllata.

La nuova posizione è determinata nel modo seguente:

• Se _Way == ios_base::beg, la nuova posizione è l'inizio del flusso più _Off.

• Se _Way == ios_base::cur, la nuova posizione è la posizione corrente del flusso più _Off.

• Se _Way == ios_base::end, la nuova posizione è la fine del flusso più _Off.

Se _Which & ios_base::in è diverso da zero e il buffer di input esiste, la funzione modifica la posizione successiva da leggere nel buffer di input. Se _Which & ios_base::out è anche diverso da zero, _Way != ios_base::cure il buffer di output esiste, la funzione imposta anche la posizione successiva da scrivere in modo che corrisponda alla posizione successiva da leggere.

In caso contrario, se _Which & ios_base::out è diverso da zero ed è presente il buffer di output, la funzione modifica la posizione successiva per la scrittura nel buffer di output. In caso contrario, l'operazione di posizionamento avrà esito negativo. Affinché un'operazione di posizionamento abbia esito positivo, è necessario che la risultante posizione del flusso si trovi all'interno della sequenza controllata.

strstreambuf::seekpos

Funzione membro virtuale protetta che prova a modificare le posizioni correnti per i flussi controllati.

virtual streampos seekpos(streampos _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 la funzione modifica correttamente una o entrambe le posizioni del flusso, restituisce la risultante posizione del flusso. In caso contrario, ha esito negativo e restituisce una posizione del 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 protetto tenta di modificare le posizioni correnti per i flussi controllati. Per un oggetto della classe strstreambuf, una posizione del flusso è costituita essenzialmente da un offset del flusso. L'offset zero designa il primo elemento della sequenza controllata. La nuova posizione è determinata da _Sp.

Se _Which & ios_base::in è diverso da zero e il buffer di input esiste, la funzione modifica la posizione successiva da leggere nel buffer di input. Se _Which & ios_base::out è diverso da zero e il buffer di output esiste, la funzione imposta anche la posizione successiva da scrivere in modo che corrisponda alla posizione successiva da leggere. In caso contrario, se _Which & ios_base::out è diverso da zero e il buffer di output esiste, la funzione modifica la posizione successiva da scrivere nel buffer di output. In caso contrario, l'operazione di posizionamento avrà esito negativo. Affinché un'operazione di posizionamento abbia esito positivo, è necessario che la risultante posizione del flusso si trovi all'interno della sequenza controllata.

strstreambuf::str

Chiama freeze e quindi restituisce un puntatore all'inizio della sequenza controllata.

char *str();

Valore restituito

Puntatore all'inizio della sequenza controllata.

Osservazioni:

Non è presente alcun elemento di terminazione null, a meno che non ne venga esplicitamente inserito uno.

Esempio

Vedere strstreambuf::freeze per un esempio d'uso di str.

strstreambuf::strstreambuf

Costruisce un oggetto di tipo 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);

Parametri

alloc_func
Funzione usata per allocare memoria del buffer.

count
Determina la lunghezza del buffer a cui punta getptr. Se getptr non è un argomento (primo modulo del costruttore), dimensioni di allocazione suggerite per i buffer.

_Freefunc
Funzione usata per liberare memoria del buffer.

getptr
Buffer usato per l'input.

putptr
Buffer usato per l'output.

Osservazioni:

Il primo costruttore archivia un puntatore null in tutti i puntatori che controllano il buffer di input, il buffer di output e l'allocazione strstreambuf. Imposta la modalità strstreambuf archiviata in modo da rendere la sequenza controllata modificabile ed estendibile. Accetta anche il conteggio come dimensione iniziale consigliata per l'allocazione.

Il secondo costruttore si comporta come il primo, ad eccezione del fatto che archivia alloc_func come puntatore alla funzione per chiamare per allocare spazio di archiviazione e free_func come puntatore alla funzione da chiamare per liberare tale archiviazione.

I tre costruttori seguenti:

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

si comportano anche come il primo, ad eccezione del fatto che getptr designa l'oggetto matrice usato per contenere la sequenza controllata. Di conseguenza, non deve essere un puntatore Null. Il numero di elementi N nella matrice viene determinato nel modo seguente:

• Se (conteggio> 0), n è conteggio.

• Se (count == 0), N è strlen((const char *) getptr ).

• Se (conteggio< 0), N è INT_MAX.

Se putptr è un puntatore Null, la funzione stabilisce solo un buffer di input eseguendo:

setg(getptr,
    getptr,
    getptr + N);

In caso contrario, stabilisce sia il buffer di input che quello di output mediante il codice seguente:

setg(getptr,
    getptr,
    putptr);

setp(putptr,
    getptr + N);

In questo caso, putptr deve essere nell'intervallo [ getptr, getptr + N].

Infine, i tre costruttori seguenti:

strstreambuf(const char *getptr,
    streamsize count);

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

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

si comportano tutti allo stesso modo di:

streambuf((char *)getptr, count);

tranne per il fatto che la modalità archiviata non rende la sequenza controllata né modificabile né estendibile.

strstreambuf::underflow

Funzione virtuale protetta per estrarre l'elemento corrente dal flusso di input.

virtual int underflow();

Valore restituito

Se la funzione non può essere eseguita correttamente, restituisce EOF. In caso contrario, restituisce l'elemento corrente nel flusso di input, convertito come descritto in precedenza.

Osservazioni:

La funzione membro virtuale protetta tenta di estrarre l'elemento ch corrente dal buffer di input, quindi avanzare la posizione corrente del flusso e restituire l'elemento come (int)(unsigned char)ch. Può farlo in un solo modo: 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.

Vedi anche

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