Classe basic_streambuf

Descreve uma classe base abstrata para derivar um buffer de fluxo, que controla a transmissão de elementos de e para uma representação específica de um fluxo.

Sintaxe

template <class Elem, class Tr = char_traits<Elem>>
class basic_streambuf;

Parâmetros

Elem
Um char_type.

Tr
O caractere traits_type.

Comentários

O modelo de classe descreve uma classe base abstrata para derivar um buffer de fluxo, que controla a transmissão de elementos de e para uma representação específica de um fluxo. Um objeto da classe basic_streambuf ajuda a controlar um fluxo com elementos do tipo Tr, também conhecido como char_type, cujas características de caractere são determinadas pela classe char_traits, também conhecida como traits_type.

Todo buffer de fluxo controla conceitualmente dois fluxos independentes: um para extrações (entrada) e outro para inserções (saída). Uma representação específica pode, no entanto, tornar um ou ambos esses fluxos inacessíveis. Normalmente, mantém alguma relação entre os dois fluxos. O que você insere no fluxo de saída de um objeto basic_stringbuf<Elem, Tr>, por exemplo, é o que você mais tarde extrai do fluxo de entrada. Ao posicionar um fluxo de um objeto basic_filebuf<Elem, Tr>, você posiciona o outro fluxo em tandem.

A interface pública para o modelo de classe basic_streambuf fornece as operações que são comuns a todos os buffers de fluxo, por mais especializados que sejam. A interface protegida fornece as operações necessárias para uma representação específica de um fluxo para fazer seu trabalho. As funções membro virtuais protegidas permitem personalizar o comportamento de um buffer de fluxo derivado para uma representação específica de um fluxo. Cada buffer de fluxo derivado nesta biblioteca descreve como especializa o comportamento de suas funções membro virtual protegidas. O comportamento padrão para a classe base, que costuma não fazer nada, é descrito neste artigo.

As funções membro protegidas restantes controla a cópia para e de qualquer armazenamento fornecido para transmissões de buffer para e de fluxos. Um buffer de entrada, por exemplo, é caracterizado por:

• eback, um ponteiro para o início do buffer.

• gptr, um ponteiro para o próximo elemento a ler.

• egptr, um ponteiro logo após o término do buffer.

Da mesma forma, um buffer de saída é caracterizado por:

• pbase, um ponteiro para o início do buffer.

• pptr, um ponteiro para o próximo elemento a gravar.

• epptr, um ponteiro logo após o término do buffer.

Para qualquer buffer, o seguinte protocolo é usado:

• Se o próximo ponteiro for nulo, nenhum buffer existirá. Caso contrário, todos os três ponteiros apontam para a mesma sequência. Eles podem ser comparados com segurança para ordem.

• Para um buffer de saída, se o ponteiro seguinte comparar menos que o ponteiro final, você poderá armazenar um elemento na posição de gravação designada pelo ponteiro seguinte.

• Para um buffer de entrada, se o ponteiro seguinte comparar menos que o ponteiro final, você poderá ler um elemento na posição de leitura designada pelo ponteiro seguinte.

• Para um buffer de entrada, se o ponteiro inicial comparar menos que o ponteiro seguinte, você pode colocar um elemento de volta na posição putback designada pelo próximo ponteiro decrementado.

Quaisquer funções membro virtuais protegidas que você escreve para uma classe derivada de basic_streambuf<Elem, Tr> precisa cooperar para manter esse protocolo.

Um objeto da classe basic_streambuf<Elem, Tr> armazena os seis ponteiros descritos anteriormente. Ele também armazena um objeto de localidade em um objeto do tipo localidade para uso potencial por um buffer de fluxo derivado.

Construtores

Construtor	Descrição
basic_streambuf	Constrói um objeto do tipo basic_streambuf.

Typedefs

Nome do tipo	Descrição
char_type	Associa um nome de tipo ao parâmetro de modelo Elem.
int_type	Associa um nome de tipo dentro do escopo de basic_streambuf ao parâmetro do modelo Elem.
off_type	Associa um nome de tipo dentro do escopo de basic_streambuf ao parâmetro do modelo Elem.
pos_type	Associa um nome de tipo dentro do escopo de basic_streambuf ao parâmetro do modelo Elem.
traits_type	Associa um nome de tipo ao parâmetro de modelo Tr.

Funções de membro

Função de membro	Descrição
eback	Uma função protegida que retorna um ponteiro para o início do buffer de entrada.
egptr	Uma função protegida que retorna um ponteiro logo após o final do buffer de entrada.
epptr	Uma função protegida que retorna um ponteiro logo após o final do buffer de saída.
gbump	Uma função protegida que adiciona count ao próximo ponteiro para o buffer de entrada.
getloc	Obtém a localidade do objeto basic_streambuf.
gptr	Uma função protegida que retorna um ponteiro para o próximo elemento do buffer de entrada.
imbue	Uma função virtual protegida chamada por pubimbue.
in_avail	Retorna o número de elementos que estão prontos para serem lidos do buffer.
overflow	Uma função virtual protegida que pode ser chamada quando um novo caractere é inserido em um buffer cheio.
pbackfail	Uma função membro virtual protegida que tenta colocar um elemento de volta no fluxo de entrada, então torná-lo elemento atual (apontando para o ponteiro seguinte).
pbase	Uma função protegida que retorna um ponteiro para o início do buffer de saída.
pbump	Uma função protegida que adiciona count ao próximo ponteiro para o buffer de saída.
pptr	Uma função protegida que retorna um ponteiro para o próximo elemento do buffer de saída.
pubimbue	Define a localidade do objeto basic_streambuf.
pubseekoff	Chama seekoff, uma função virtual protegida que é substituída em uma classe derivada.
pubseekpos	Chama seekpos, uma função virtual protegida que é substituída em uma classe derivada e redefine a posição atual do ponteiro.
pubsetbuf	Chama setbuf, uma função virtual protegida que é substituída em uma classe derivada.
pubsync	Chama sync, uma função virtual protegida que é substituída em uma classe derivada e atualiza o fluxo externo associado a esse buffer.
sbumpc	Lê e retorna o elemento atual, movendo o ponteiro de fluxo.
seekoff	A função membro virtual protegida tenta alterar as posições atuais para os fluxos controlados.
seekpos	A função membro virtual protegida tenta alterar as posições atuais para os fluxos controlados.
setbuf	A função membro virtual protegida executa uma operação que específica para cada buffer de fluxo derivado.
setg	Uma função protegida que armazena _Gbeg no ponteiro de início, _Gnext no próximo ponteiro e _Gend no ponteiro final para o buffer de entrada.
setp	Uma função protegida que armazena _Pbeg no ponteiro inicial e _Pend no ponteiro final para o buffer de saída.
sgetc	Retorna o elemento atual sem alterar a posição no fluxo.
sgetn	Retorna o número de elementos lidos.
showmanyc	Função membro virtual protegida que retorna uma contagem do número de caracteres que pode ser extraído do fluxo de entrada. Ela também garante que o programa não estará sujeito a uma espera indefinida.
snextc	Lê o elemento atual e retorna o elemento seguinte.
sputbackc	Coloca um char_type no fluxo.
sputc	Coloca um caractere no fluxo.
sputn	Coloca uma cadeia de caracteres no fluxo.
stossc	Move-se além do elemento atual no fluxo.
sungetc	Obtém um caractere do fluxo.
troca	Troca os valores nesse objeto pelos valores do parâmetro do objeto basic_streambuf fornecido.
sync	Uma função virtual protegida que tenta sincronizar os fluxos controlados com quaisquer fluxos externos associados.
uflow	Função virtual protegida que extrai o elemento atual do fluxo de entrada.
underflow	Função virtual protegida que extrai o elemento atual do fluxo de entrada.
xsgetn	Uma função virtual protegida que extrai elementos de fluxo de entrada.
xsputn	Uma função virtual protegida que insere elementos no fluxo de saída.

Operadores

Operador	Descrição
operator=	Atribui os valores deste objeto de outro objeto basic_streambuf.

Requisitos

Cabeçalho:<streambuf>

Namespace: std

basic_streambuf::basic_streambuf

Constrói um objeto do tipo basic_streambuf.

basic_streambuf();

basic_streambuf(const basic_streambuf& right);

Parâmetros

direita
Uma referência lvalue para o objeto basic_streambuf usada para definir os valores a esse objeto basic_streambuf.

Comentários

O primeiro construtor protegido armazena um ponteiro nulo em todos os ponteiros controlando o buffer de entrada e o buffer de saída. Ele também armazena locale::classic no objeto de localidade. Para obter mais informações, consulte Locale::classic.

O segundo construtor protegido copia os ponteiros e a localidade de right.

basic_streambuf::char_type

Associa um nome de tipo ao parâmetro do modelo Elem.

typedef Elem char_type;

basic_streambuf::eback

Uma função protegida que retorna um ponteiro para o início do buffer de entrada.

char_type *eback() const;

Valor de retorno

Um ponteiro para o início do buffer de entrada.

basic_streambuf::egptr

Uma função protegida que retorna um ponteiro logo após o final do buffer de entrada.

char_type *egptr() const;

Valor de retorno

Um ponteiro logo após o final do buffer de entrada.

basic_streambuf::epptr

Uma função protegida que retorna um ponteiro logo após o final do buffer de saída.

char_type *epptr() const;

Valor de retorno

Um ponteiro após o final do buffer de saída.

basic_streambuf::gbump

Uma função protegida que adiciona count ao próximo ponteiro para o buffer de entrada.

void gbump(int count);

Parâmetros

count
O valor pelo qual avançar o ponteiro.

basic_streambuf::getloc

Obtém a localidade do objeto basic_streambuf.

locale getloc() const;

Valor de retorno

O objeto de localidade armazenado.

Comentários

Para obter informações relacionadas, consulte ios_base::getloc.

Exemplo

// basic_streambuf_getloc.cpp
// compile with: /EHsc
#include <iostream>

int main( )
{
   using namespace std;
   cout << cout.rdbuf( )->getloc( ).name( ).c_str( ) << endl;
}

C

basic_streambuf::GPTR

Uma função protegida que retorna um ponteiro para o próximo elemento do buffer de entrada.

char_type *gptr() const;

Valor de retorno

Um ponteiro para o próximo elemento do buffer de entrada.

basic_streambuf::imbue

Uma função virtual protegida chamada por pubimbue.

virtual void imbue(const locale& _Loc);

Parâmetros

_Loc
Uma referência a uma localidade.

Comentários

O comportamento padrão é não fazer nada.

basic_streambuf::in_avail

Retorna o número de elementos que estão prontos para serem lidos do buffer.

streamsize in_avail();

Valor de retorno

O número de elementos que estão prontos para serem lidos do buffer.

Comentários

Se uma posição de leitura estiver disponível, a função membro retornará egptr - gptr. Caso contrário, retorna showmanyc.

Exemplo

// basic_streambuf_in_avail.cpp
// compile with: /EHsc
#include <iostream>

int main( )
{
   using namespace std;
   char c;
   // cin's buffer is empty, in_avail will return 0
   cout << cin.rdbuf( )->in_avail( ) << endl;
   cin >> c;
   cout << cin.rdbuf( )->in_avail( ) << endl;
}

basic_streambuf::int_type

Associa um nome de tipo dentro do escopo de basic_streambuf a um dos tipos em um parâmetro de modelo.

typedef typename traits_type::int_type int_type;

basic_streambuf::off_type

Associa um nome de tipo dentro do escopo de basic_streambuf a um dos tipos em um parâmetro de modelo.

typedef typename traits_type::off_type off_type;

basic_streambuf::operador=

Atribui os valores deste objeto de outro objeto basic_streambuf.

basic_streambuf& operator=(const basic_streambuf& right);

Parâmetros

direita
Uma referência lvalue para o objeto basic_streambuf usada para atribuir valores a esse objeto.

Comentários

O operador membro protegido copia de right os ponteiros que controlam o buffer de entrada e o buffer de saída. Também armazena right.getloc() no locale object. Ele retorna *this.

basic_streambuf::estouro

Uma função virtual protegida que pode ser chamada quando um novo caractere é inserido em um buffer cheio.

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

Parâmetros

_Meta
O caractere a ser inserido no buffer, ou traits_type::eof.

Valor de retorno

Se a função não conseguir obter sucesso, ela retornará traits_type::eof ou gerará uma exceção. Caso contrário, retornará traits_type::not_eof(_ Meta). O comportamento padrão é retornar traits_type::eof.

Comentários

Se _Meta não for equivalente a traits_type::eof, a função membro virtual protegida buscará inserir o elemento traits_type::to_char_type(Meta) no fluxo de saída. Isso pode ser feito de várias maneiras:

• Se write position estiver disponível, ela poderá armazenar o elemento na posição de gravação e incrementar o próximo ponteiro para o buffer de saída.

• Ele pode disponibilizar uma posição de gravação alocando armazenamento novo ou adicional ao buffer de saída.

• Ele pode disponibilizar uma posição de gravação gravando, em algum destino externo, alguns ou todos os elementos entre os ponteiros inicial e seguinte para o buffer de saída.

A função de estouro virtual, junto com as funções sync e underflow, definem as características da classe derivada streambuf. Cada classe derivada pode implementar o estouro de forma diferente, mas a interface com a classe de fluxo de chamada é a mesma.

A função overflow frequentemente é chamada por funções streambuf públicas como sputc e sputn quando a área put está cheia, mas outras classes, incluindo as classes de fluxo, podem chamar overflow a qualquer momento.

A função consome os caracteres na área de put entre os ponteiros pbase e pptr e, em seguida, reinicializa a área put. A função overflow também deve consumir nCh (se nCh não for EOF) ou pode optar por colocar o caractere na nova área de put para que ele seja consumido na próxima chamada.

A definição de consumir varia entre as classes derivadas. Por exemplo, a classe filebuf grava seus caracteres em um arquivo, enquanto a classe strstreambuf os mantém em seu buffer e, se o buffer for designado como dinâmico, expande o buffer em resposta a uma chamada para estouro. Essa expansão é obtida liberando o buffer antigo e substituindo-o por um novo maior. Os ponteiros são ajustados conforme necessário.

basic_streambuf::p backfail

Uma função membro virtual protegida que tenta colocar um elemento de volta no fluxo de entrada, então torná-lo elemento atual (apontando para o ponteiro seguinte).

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

Parâmetros

_Meta
O caractere a ser inserido no buffer, ou traits_type::eof.

Valor de retorno

Se a função não conseguir obter sucesso, ela retornará traits_type::eof ou gerará uma exceção. Caso contrário, retorna algum outro valor. O comportamento padrão é retornar traits_type::eof.

Comentários

Se _Meta for comparável a traits_type::eof, o elemento a ser recuado será efetivamente aquele que já estava no fluxo antes do elemento atual. Caso contrário, esse elemento será substituído por traits_type::to_char_type(_Meta). A função pode colocar um elemento de volta de várias maneiras:

• Se uma posição putback estiver disponível, ela poderá armazenar o elemento na posição putback e diminuir o ponteiro seguinte para o buffer de entrada.

• Pode disponibilizar uma posição de putback alocando armazenamento novo ou adicional para o buffer de entrada.

• Para um buffer de fluxo com fluxos de entrada e saída comuns, ele pode disponibilizar uma posição de putback gravando, em algum destino externo, alguns ou todos os elementos entre os ponteiros inicial e seguintes para o buffer de saída.

basic_streambuf::p base

Uma função protegida que retorna um ponteiro para o início do buffer de saída.

char_type *pbase() const;

Valor de retorno

Um ponteiro para o início do buffer de saída.

basic_streambuf::p bump

Uma função protegida que adiciona count ao próximo ponteiro para o buffer de saída.

void pbump(int count);

Parâmetros

count
O número de caracteres pelo qual mover a posição de gravação para frente.

basic_streambuf::p tipo_os_

Associa um nome de tipo dentro do escopo de basic_streambuf a um dos tipos em um parâmetro de modelo.

typedef typename traits_type::pos_type pos_type;

basic_streambuf::p ptr

Uma função protegida que retorna um ponteiro para o próximo elemento do buffer de saída.

char_type *pptr() const;

Valor de retorno

Um ponteiro para o próximo elemento do buffer de saída.

basic_streambuf::p ubimbue

Define a localidade do objeto basic_streambuf.

locale pubimbue(const locale& _Loc);

Parâmetros

_Loc
Uma referência a uma localidade.

Valor de retorno

O valor anterior armazenado no objeto de localidade.

Comentários

A função membro armazena _ Loc no objeto de localidade e chama imbue.

Exemplo

Consulte basic_ios::imbue para obter um exemplo que usa pubimbue.

basic_streambuf::p ubseekoff

Chama seekoff, uma função virtual protegida que é substituída em uma classe derivada.

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

Parâmetros

_Off
A posição a ser buscada para o relativo a _Way.

_Way
O ponto de partida para operações de deslocamento. Consulte seekdir para valores possíveis.

_Which
Especifica o modo para a posição do ponteiro. O padrão é permitir que você modifique as posições de leitura e gravação.

Valor de retorno

Retorna a nova posição ou uma posição de fluxo inválida (seekoff(_ Off, _Way, _Which)).

Comentários

Move o ponteiro relativo a _Way.

basic_streambuf::p ubseekpos

Chama seekpos, uma função virtual protegida que é substituída em uma classe derivada e redefine a posição atual do ponteiro.

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

Parâmetros

_Sp
A posição pela qual buscar.

_Which
Especifica o modo para a posição do ponteiro. O padrão é permitir que você modifique as posições de leitura e gravação.

Valor de retorno

A nova posição ou uma posição de fluxo inválida. Para determinar se a posição de fluxo é inválida, compare o valor retornado com pos_type(off_type(-1)).

Comentários

A função membro retorna seekpos(_ Sp, _Which).

basic_streambuf::p ubsetbuf

Chama setbuf, uma função virtual protegida que é substituída em uma classe derivada.

basic_streambuf<Elem, Tr> *pubsetbuf(
    char_type* _Buffer,
    streamsize count);

Parâmetros

_Buffer
Um ponteiro para char_type para essa instanciação.

count
O tamanho do buffer.

Valor de retorno

Retorna setbuf( _Buffer, count).

basic_streambuf::p ubsync

Chama sync, uma função virtual protegida que é substituída em uma classe derivada e atualiza o fluxo externo associado a esse buffer.

int pubsync();

Valor de retorno

Retorna sync ou -1 em caso de falha.

basic_streambuf::sbumpc

Lê e retorna o elemento atual, movendo o ponteiro de fluxo.

int_type sbumpc();

Valor de retorno

O elemento atual.

Comentários

Se uma posição de leitura estiver disponível, a função membro retornará traits_type::to_int_type(*gptr) e incrementará o ponteiro seguinte para o buffer de entrada. Caso contrário, retorna uflow.

Exemplo

// basic_streambuf_sbumpc.cpp
// compile with: /EHsc
#include <iostream>

int main( )
{
   using namespace std;
   int i = 0;
   i = cin.rdbuf( )->sbumpc( );
   cout << i << endl;
}

3

33
51

basic_streambuf::Seekoff

Uma função de membro virtual protegida que tenta alterar as posições atuais para os fluxos 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
A posição a ser buscada para o relativo a _Way.

_Way
O ponto de partida para operações de deslocamento. Consulte seekdir para valores possíveis.

_Which
Especifica o modo para a posição do ponteiro. O padrão é permitir que você modifique as posições de leitura e gravação.

Valor de retorno

Retorna a nova posição ou uma posição de fluxo inválida (seekoff (_ Off, _Way, _Which)).

Comentários

A nova posição é determinada da seguinte forma:

• Se _Way == ios_base::beg, a nova posição é o início do fluxo mais _ Off.

• Se _Way == ios_base::cur, a nova posição é a posição atual do fluxo mais _ Off.

• Se _Way == ios_base::end, a nova posição é o final do fluxo mais _ Off.

Normalmente, se which & ios_base::in for diferente de zero, o fluxo de entrada será afetado; se which & ios_base::out for diferente de zero, o fluxo de saída será afetado. No entanto, o uso real desse parâmetro varia entre os buffers de fluxo derivados.

Se a função tiver êxito em alterar a posição ou as posições do fluxo, ela retornará a posição do fluxo resultante ou uma das posições do fluxo resultantes. Caso contrário, retorna uma posição de fluxo inválida. O comportamento padrão é retornar uma posição de fluxo inválida.

basic_streambuf::seekpos

Uma função de membro virtual protegida que tenta alterar as posições atuais para os fluxos controlados.

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

Parâmetros

_Sp
A posição pela qual buscar.

_Which
Especifica o modo para a posição do ponteiro. O padrão é permitir que você modifique as posições de leitura e gravação.

Valor de retorno

A nova posição ou uma posição de fluxo inválida. Para determinar se a posição de fluxo é inválida, compare o valor retornado com pos_type(off_type(-1)).

Comentários

A nova posição é _ Sp.

Normalmente, se which & ios_base::in for diferente de zero, o fluxo de entrada será afetado; se which & ios_base::out for diferente de zero, o fluxo de saída será afetado. No entanto, o uso real desse parâmetro varia entre os buffers de fluxo derivados.

Se a função tiver êxito em alterar a posição ou as posições do fluxo, ela retornará a posição do fluxo resultante ou uma das posições do fluxo resultantes. Caso contrário, retorna uma posição de fluxo inválida (-1). O comportamento padrão é retornar uma posição de fluxo inválida.

basic_streambuf::Setbuf

A função membro virtual protegida que executa uma operação específica para cada buffer de fluxo derivado.

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

Parâmetros

_Buffer
Ponteiro para um buffer.

count
O tamanho do buffer .

Valor de retorno

O comportamento padrão é retornar this.

Comentários

Consulte basic_filebuf. setbuf fornece uma área de memória para o objeto streambuf usar. Como o buffer é usado é definido nas classes derivadas.

basic_streambuf::setg

Uma função protegida que armazena _ Gbeg no ponteiro de início, _Gnext no próximo ponteiro e _Gend no ponteiro final para o buffer de entrada.

void setg(char_type* _Gbeg,
    char_type* _Gnext,
    char_type* _Gend);

Parâmetros

_Gbeg
Um ponteiro para o início do buffer.

_Gnext
Um ponteiro para algum lugar no meio do buffer.

_Gend
Um ponteiro para o fim do buffer.

basic_streambuf::setp

Uma função protegida que armazena _Pbeg no ponteiro inicial e _Pend no ponteiro final para o buffer de saída.

void setp(char_type* _Pbeg, char_type* _Pend);

Parâmetros

_Pbeg
Um ponteiro para o início do buffer.

_Pend
Um ponteiro para o fim do buffer.

basic_streambuf::sgetc

Retorna o elemento atual sem alterar a posição no fluxo.

int_type sgetc();

Valor de retorno

O elemento atual.

Comentários

Se uma posição de leitura estiver disponível, a função membro retornará traits_type::to_int_type( *gptr). Caso contrário, retorna underflow.

Exemplo

// basic_streambuf_sgetc.cpp
// compile with: /EHsc
#include <iostream>
#include <fstream>

int main( )
{
   using namespace std;
   ifstream myfile( "basic_streambuf_sgetc.txt", ios::in );

   char i = myfile.rdbuf( )->sgetc( );
   cout << i << endl;
   i = myfile.rdbuf( )->sgetc( );
   cout << i << endl;
}

basic_streambuf::sgetn

Extrai até count caracteres do buffer de entrada e armazena-os no buffer ptr fornecido.

Esse método pode não ser seguro, pois depende do chamador para verificar se os valores passados estão corretos.

streamsize sgetn(
    char_type* ptr,
    streamsize count);

Parâmetros

ptr
O buffer que deve conter os caracteres extraídos.

count
O número de elementos a serem lidos.

Valor de retorno

O número de elementos lidos. Para obter mais informações, confira streamsize.

Comentários

A função membro retorna xsgetn( ptr, count).

Exemplo

// basic_streambuf_sgetn.cpp
// compile with: /EHsc /W3
#include <iostream>
#include <fstream>

int main()
{
    using namespace std;

    ifstream myfile("basic_streambuf_sgetn.txt", ios::in);
    char a[10];

    // Extract 3 characters from myfile and store them in a.
    streamsize i = myfile.rdbuf()->sgetn(&a[0], 3);  // C4996
    a[i] = myfile.widen('\0');

    // Display the size and contents of the buffer passed to sgetn.
    cout << i << " " << a << endl;

    // Display the contents of the original input buffer.
    cout << myfile.rdbuf() << endl;
}

basic_streambuf::showmanyc

Uma função membro virtual protegida que retorna uma contagem do número de caracteres que pode ser extraído do fluxo de entrada e garante que o programa não esteja sujeito a uma espera indefinida.

virtual streamsize showmanyc();

Valor de retorno

O comportamento padrão é retornar zero.

basic_streambuf::Snextc

Lê o elemento atual e retorna o elemento seguinte.

int_type snextc();

Valor de retorno

O próximo elemento no fluxo.

Comentários

A função membro chama sbumpc e, se essa função retornar traits_type::eof, retornará traits_type::eof. Caso contrário, retorna sgetc.

Exemplo

// basic_streambuf_snextc.cpp
// compile with: /EHsc
#include <iostream>
int main( )
{
   using namespace std;
   int i = 0;
   i = cin.rdbuf( )->snextc( );
   // cout << ( int )char_traits<char>::eof << endl;
   cout << i << endl;
}

aa

aa97

basic_streambuf::sputbackc

Coloca um char_type no fluxo.

int_type sputbackc(char_type _Ch);

Parâmetros

_Ch
O caractere.

Valor de retorno

Retorna o caractere ou a falha.

Comentários

Se houver uma posição putback estiver disponível e _Ch for comparável ao caractere armazenado nessa posição, a função membro diminuirá o ponteiro seguinte para o buffer de entrada e retornará traits_type::to_int_type( _Ch). Caso contrário, retorna pbackfail( _Ch).

Exemplo

// basic_streambuf_sputbackc.cpp
// compile with: /EHsc
#include <iostream>
#include <fstream>

int main( )
{
    using namespace std;

    ifstream myfile("basic_streambuf_sputbackc.txt",
        ios::in);

    int i = myfile.rdbuf()->sbumpc();
    cout << (char)i << endl;
    int j = myfile.rdbuf()->sputbackc('z');
    if (j == 'z')
    {
        cout << "it worked" << endl;
    }
    i = myfile.rdbuf()->sgetc();
    cout << (char)i << endl;
}

basic_streambuf::sputc

Coloca um caractere no fluxo.

int_type sputc(char_type _Ch);

Parâmetros

_Ch
O caractere.

Valor de retorno

Retorna o caractere, se for bem-sucedido.

Comentários

Se um write position estiver disponível, a função membro armazenará _Ch na posição de gravação, incrementará o ponteiro seguinte para o buffer de saída e retornará traits_type::to_int_type( _Ch). Caso contrário, retorna overflow( _Ch).

Exemplo

// basic_streambuf_sputc.cpp
// compile with: /EHsc
#include <iostream>
#include <fstream>

int main( )
{
   using namespace std;

   int i = cout.rdbuf( )->sputc( 'a' );
   cout << endl << ( char )i << endl;
}

a
a

basic_streambuf::sputn

Coloca uma cadeia de caracteres no fluxo.

streamsize sputn(const char_type* ptr, streamsize count);

Parâmetros

ptr
A cadeia de caracteres.

count
A contagem de caracteres.

Valor de retorno

O número de caracteres inseridos no fluxo.

Comentários

A função membro retorna xsputn( ptr, count). Para obter mais informações, confira a seção Comentários desse membro.

Exemplo

// basic_streambuf_sputn.cpp
// compile with: /EHsc
#include <iostream>
#include <fstream>

int main()
{
    using namespace std;

    streamsize i = cout.rdbuf()->sputn("test", 4);
    cout << endl << i << endl;
}

test
4

basic_streambuf::STOSSC

Move-se além do elemento atual no fluxo.

void stossc();

Comentários

A função membro chama sbumpc. Para fornecer essa função membro, nenhuma implementação é exigida.

Exemplo

// basic_streambuf_stossc.cpp
// compile with: /EHsc
#include <iostream>
#include <fstream>

int main( )
{
   using namespace std;
   ifstream myfile( "basic_streambuf_stossc.txt", ios::in );

   myfile.rdbuf( )->stossc( );
   char i = myfile.rdbuf( )->sgetc( );
   cout << i << endl;
}

basic_streambuf::sungetc

Obtém um caractere do fluxo.

int_type sungetc();

Valor de retorno

Retorna o caractere ou a falha.

Comentários

Se uma posição de putback estiver disponível, a função membro diminuirá o ponteiro seguinte para o buffer de entrada e retornará traits_type::to_int_type( *gptr). No entanto, nem sempre é possível determinar o último caractere lido para que ele pode ser capturado no estado do buffer atual. Se isso for true, a função retornará pbackfail. Para evitar essa situação, acompanhe o caractere a ser colocado de volta e chame sputbackc(ch), que não falhará, desde que você não o chame no início do fluxo e não tente colocar mais de um caractere de volta.

Exemplo

// basic_streambuf_sungetc.cpp
// compile with: /EHsc
#include <iostream>
#include <fstream>

int main( )
{
   using namespace std;

   ifstream myfile( "basic_streambuf_sungetc.txt", ios::in );

   // Read and increment
   int i = myfile.rdbuf( )->sbumpc( );
   cout << ( char )i << endl;

   // Read and increment
   i = myfile.rdbuf( )->sbumpc( );
   cout << ( char )i << endl;

   // Decrement, read, and do not increment
   i = myfile.rdbuf( )->sungetc( );
   cout << ( char )i << endl;

   i = myfile.rdbuf( )->sungetc( );
   cout << ( char )i << endl;

   i = myfile.rdbuf( )->sbumpc( );
   cout << ( char )i << endl;
}

basic_streambuf::swap

Troca os valores nesse objeto pelos valores do objeto basic_streambuf fornecido.

void swap(basic_streambuf& right);

Parâmetros

direita
Uma referência lvalue para o objeto basic_streambuf usada para trocar valores.

Comentários

A função membro protegida troca com right todos os ponteiros controlando o input buffer e o output buffer. Também troca right.getloc() com o objeto locale.

basic_streambuf::sync

Uma função virtual protegida que tenta sincronizar os fluxos controlados com quaisquer fluxos externos associados.

virtual int sync();

Valor de retorno

Se a função não puder ser bem-sucedida, ela retornará -1. O comportamento padrão é retornar zero.

Comentários

sync envolve gravar quaisquer elementos entre os ponteiros inicial e seguinte para o buffer de saída. Ele não envolve colocar de volta nenhum elemento entre o próximo ponteiro e o ponteiro final para o buffer de entrada.

basic_streambuf::traits_type

Associa um nome de tipo ao parâmetro de modelo Tr.

typedef Tr traits_type;

basic_streambuf::uflow

Função virtual protegida que extrai o elemento atual do fluxo de entrada.

virtual int_type uflow();

Valor de retorno

O elemento atual.

Comentários

A função membro virtual protegida tenta extrair o elemento atual ch do fluxo de entrada, então avança a posição atual do fluxo e retorna o elemento como traits_type::to_int_type( ch). Isso pode ser feito de várias maneiras:

• Se houver uma posição de leitura estiver disponível, ela pegará ch como o elemento armazenado na posição leitura e avançará o próximo ponteiro para o buffer de entrada.

• Ele pode ler um elemento diretamente, de alguma fonte externa e entregá-lo como o valor ch.

• Para um buffer de fluxo com fluxos de entrada e saída comuns, ele pode disponibilizar uma posição de leitura gravando, em algum destino externo, alguns ou todos os elementos entre os ponteiros inicial e seguintes para o buffer de saída. Ou pode alocar armazenamento novo ou adicional para o buffer de entrada. A função então lê, de alguma fonte externa, um ou mais elementos.

Se a função não conseguir obter sucesso, ela retornará traits_type::eof ou gerará uma exceção. Caso contrário, retornará o elemento ch atual no fluxo de entrada, convertido conforme descrito acima e avançará o ponteiro seguinte para o buffer de entrada. O comportamento padrão é chamar underflow e, se essa função retornar traits_type::eof, retornar traits_type::eof. Caso contrário, a função retorna o elemento atual ch no fluxo de entrada, convertido conforme descrito anteriormente e avança o ponteiro seguinte para o buffer de entrada.

basic_streambuf::Fluxo inferior

Função virtual protegida para extrair o elemento atual do fluxo de entrada.

virtual int_type underflow();

Valor de retorno

O elemento atual.

Comentários

A função membro virtual protegida busca extrair o elemento atual ch do fluxo de entrada, sem avançar a posição de fluxo atual e retorná-la como traits_type::to_int_type( ch). Isso pode ser feito de várias maneiras:

• Se uma posição de leitura estiver disponível, ch será o elemento armazenado na posição de leitura. Para obter mais informações, consulte a seção Comentários da Classe basic_streambuf.

• Pode disponibilizar uma posição de leitura alocando armazenamento novo ou adicional para o buffer de entrada, então lendo, de alguma fonte externa, um ou mais elementos. Para obter mais informações, consulte a seção Comentários da Classe basic_streambuf.

Se a função não conseguir obter sucesso, ela retornará traits_type::eof() ou gerará uma exceção. Caso contrário, retornará o elemento atual no fluxo de entrada, convertido conforme descrito anteriormente. O comportamento padrão é retornar traits_type::eof().

A função underflow virtual, com as funções sync e overflow, define as características da classe derivada de streambuf. Cada classe derivada pode implementar underflow de forma diferente, mas a interface com a classe de fluxo de chamada é a mesma.

A função underflow frequentemente é chamada por funções streambuf públicas como sgetc e sgetn quando a área get está vazia, mas outras classes, incluindo as classes de fluxo, podem chamar underflow a qualquer momento.

A função underflow fornece a área de get caracteres da fonte de entrada. Se a área get contiver caracteres, underflow retornará o primeiro caractere. Se a área get estiver vazia, ela preencherá a área get e retornará o caractere seguinte (que deixa na área get). Não se houver mais nenhum caractere disponível, underflow retornará EOF e deixará a área get vazia.

Na classe strstreambuf, underflow ajusta o ponteiro egptr para acessar o armazenamento alocado dinamicamente por uma chamada para overflow.

basic_streambuf::xsgetn

Função virtual protegida para extrair elementos do fluxo de entrada.

Esse método pode não ser seguro, pois depende do chamador para verificar se os valores passados estão corretos.

virtual streamsize xsgetn(
    char_type* ptr,
    streamsize count);

Parâmetros

ptr
O buffer que deve conter os caracteres extraídos.

count
O número de elementos a extrair.

Valor de retorno

O número de elementos extraídos.

Comentários

A função membro virtual protegida extrai até count elementos do fluxo de entrada, como por chamadas repetidas a sbumpc e armazena-os na matriz que começa em ptr. Ela retorna o número de elementos extraídos.

basic_streambuf::xsputn

Função virtual protegida para inserir elementos no fluxo de saída.

virtual streamsize xsputn(const char_type* ptr, streamsize count);

Parâmetros

ptr
Ponteiro para elementos a inserir.

count
Número de elementos a inserir.

Valor de retorno

O número de elementos inseridos no fluxo.

Comentários

A função membro virtual protegida insere até count elementos no fluxo de saída, como se por chamadas repetidas a sputc, da matriz que começa em ptr. A inserção de caracteres no fluxo de saída para quando todos os caracteres count tiverem sido gravados ou se chamar sputc( count) retornaria traits::eof(). Retorna o número de elementos inseridos.

Confira também

Acesso Thread-Safe na Biblioteca Padrão C++
Programação de iostream
Convenções de iostreams