Classe ios_base

  • Artigo

A classe descreve as funções membro e de armazenamento comuns aos fluxos de entrada e de saída que não dependem dos parâmetros do modelo. (O modelo de classe basic_ios descreve o que é comum e depende dos parâmetros do modelo.)

Um objeto da classe ios_base armazena informações de formatação, que são compostas por:

  • Sinalizadores de formato em um objeto do tipo fmtflags.

  • Uma máscara de exceção em um objeto do tipo iostate.

  • Uma largura de campo em um objeto do tipo int.

  • Uma precisão de exibição em um objeto do tipo int.

  • Um objeto locale em um objeto do tipo locale.

  • Duas matrizes extensíveis, com elementos do tipo long e o ponteiro void.

Um objeto da classe ios_base também armazena informações de estado de fluxo, em um objeto do tipo iostate, e uma pilha de retorno de chamada.

Membros

Construtores

Nome Descrição
ios_base Constrói objetos ios_base.

Typedefs

Nome Descrição
event_callback Descreve uma função passada para register_call.
fmtflags Constantes para especificar a aparência da saída.
iostate Define constantes que descrevem o estado de um fluxo.
openmode Descreve como interagir com um fluxo.
seekdir Especifica o ponto de início para operações de deslocamento.

Enumerações

Nome Descrição
event Especifica tipos de evento.

Constantes

Nome Descrição
adjustfield Um bitmask definido como internal | left | right.
app Especifica a busca até o final de um fluxo antes de cada inserção.
ate Especifica a busca até o final de um fluxo quando seu objeto de controle é criado.
badbit Registra uma perda de integridade do buffer do fluxo.
basefield Um bitmask definido como dec | hex | oct.
beg Especifica a busca relativa ao início de uma sequência.
binary Especifica que um arquivo deve ser lido como um fluxo binário, em vez de um fluxo de texto.
boolalpha Especifica a inserção ou extração de objetos do tipo bool como nomes (como true e false), e não como valores numéricos.
cur Especifica a busca em relação à posição atual dentro de uma sequência.
dec Especifica a inserção ou extração de valores inteiros em formato decimal.
end Especifica a busca relativa ao final de uma sequência.
eofbit Registra o final do arquivo durante a extração de um fluxo.
failbit Registra uma falha ao extrair um campo válido de um fluxo.
fixed Especifica a inserção de valores de ponto flutuante no formato de ponto fixo (sem nenhum campo expoente).
floatfield Um bitmask definido como fixed | scientific
goodbit Todos os bits de estado são limpos.
hex Especifica a inserção ou extração de valores inteiros em formato hexadecimal.
in Especifica a extração de um fluxo.
internal Preenche uma largura de campo inserindo caracteres de preenchimento em um ponto interno de um campo numérico gerado.
left Especifica a justificação à esquerda.
oct Especifica a inserção ou extração de valores inteiros em formato octal.
out Especifica a inserção em um fluxo.
right Especifica a justificação à direita.
scientific Especifica a inserção de valores de ponto flutuante no formato científico (com um campo expoente).
showbase Especifica a inserção de um prefixo que revela a base de um campo inteiro gerado.
showpoint Especifica a inserção incondicional de um ponto decimal em um campo de ponto flutuante gerado.
showpos Especifica a inserção de um sinal de adição em um campo numérico gerado não negativo.
skipws Especifica ignorar o espaço em branco à esquerda antes de determinadas extrações.
trunc Especifica excluir o conteúdo de um arquivo existente quando seu objeto de controle é criado.
unitbuf Faz com que a saída seja liberada após cada inserção.
uppercase Especifica a inserção de equivalentes maiúsculas de letras minúsculas em determinadas inserções.

Funções

Nome Descrição
failure A classe membro serve como a classe base para todas as exceções geradas pela função membro clear no modelo de classe basic_ios.
flags Define ou retorna as configurações de sinalizador atuais.
getloc Retorna o objeto locale armazenado.
imbue Altera a localidade.
Init Cria os objetos iostream padrão quando construídos.
iword Atribui um valor a ser armazenado como um iword.
precision Especifica o número de dígitos a serem exibidos em um número de ponto flutuante.
pword Atribui um valor a ser armazenado como um pword.
register_callback Especifica uma função de retorno de chamada.
setf Define os sinalizadores especificados.
sync_with_stdio Garante que operações de iostream e da biblioteca de runtime de C ocorram na ordem em que aparecem no código-fonte.
unsetf Faz com que os sinalizadores especificados sejam desativados.
width Define o tamanho do fluxo de saída.
xalloc Especifica que uma variável deve ser parte do fluxo.

Operadores

Nome Descrição
operator= O operador de atribuição para objetos ios_base.

Requisitos

Cabeçalho: <ios>

Namespace: std

event

Especifica tipos de evento.

enum event {
    erase_event,
    imbue_event,
    copyfmt_event};

Comentários

O tipo é um tipo enumerado que descreve um objeto que pode armazenar o evento de retorno de chamada usado como argumento para uma função registrada com register_callback. Os valores de eventos distintos são:

  • copyfmt_event, para identificar um retorno de chamada que ocorre próximo ao final de uma chamada para copyfmt, logo antes da máscara de exceção ser copiada.

  • erase_event, para identificar um retorno de chamada que ocorre no início de uma chamada para copyfmt, ou no início de uma chamada para o destruidor para *this.

  • imbue_event, para identificar um retorno de chamada que ocorre no final de uma chamada para imbue, logo antes da função ser retornada.

Exemplo

Para ver um exemplo, consulte register_callback.

event_callback

Descreve uma função passada para register_call.

typedef void (__cdecl *event_callback)(
    event _E,
    ios_base& _Base,
    int _I);

Parâmetros

_E
O event.

_Base
O fluxo no qual o evento foi chamado.

_I
Um número definido pelo usuário.

Comentários

O tipo descreve um ponteiro para uma função que pode ser registrada com register_callback. Esse tipo de função não deve gerar uma exceção.

Exemplo

Confira register_call para ver um exemplo que usa event_callback.

failure

A classe failure define a classe base para os tipos de todos os objetos gerados como exceções, por funções na biblioteca iostreams, para relatar erros detectados durante operações de buffer de fluxo.

namespace std {
    class failure : public system_error {
    public:
        explicit failure(
            const string& _Message,
            const error_code& _Code = io_errc::stream);

        explicit failure(
            const char* str,
            const error_code& _Code = io_errc::stream);
    };
}

Comentários

O valor retornado por what() é uma cópia de _Message, possivelmente aumentada com um teste baseado em _Code. Se _Code não for especificado, o valor padrão será make_error_code(io_errc::stream).

Exemplo

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

int main ( )
{
    using namespace std;
    fstream file;
    file.exceptions(ios::failbit);
    try
    {
        file.open( "rm.txt", ios_base::in );
        // Opens nonexistent file for reading
    }
    catch( ios_base::failure f )
    {
        cout << "Caught an exception: " << f.what() << endl;
    }
}

Caught an exception: ios_base::failbit set

flags

Define ou retorna as configurações de sinalizador atuais.

fmtflags flags() const;
fmtflags flags(fmtflags fmtfl);

Parâmetros

fmtfl
A nova configuração fmtflags.

Valor de retorno

A configuração fmtflags anterior ou atual.

Comentários

Confira ios_base::fmtflags para ver uma lista dos sinalizadores.

A primeira função membro retorna os sinalizadores de formato armazenados. A segunda função membro armazena fmtfl nos sinalizadores de formato e retorna seu valor armazenado anterior.

Exemplo

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

int main ( )
{
    using namespace std;
    cout << cout.flags( ) << endl;
    cout.flags( ios::dec | ios::boolalpha );
    cout << cout.flags( );
}

513
16896

fmtflags

Constantes para especificar a aparência da saída.

class ios_base {
public:
   typedef implementation-defined-bitmask-type fmtflags;
   static const fmtflags boolalpha;
   static const fmtflags dec;
   static const fmtflags fixed;
   static const fmtflags hex;
   static const fmtflags internal;
   static const fmtflags left;
   static const fmtflags oct;
   static const fmtflags right;
   static const fmtflags scientific;
   static const fmtflags showbase;
   static const fmtflags showpoint;
   static const fmtflags showpos;
   static const fmtflags skipws;
   static const fmtflags unitbuf;
   static const fmtflags uppercase;
   static const fmtflags adjustfield;
   static const fmtflags basefield;
   static const fmtflags floatfield;
   // ...
};

Comentários

Dá suporte aos manipuladores em ios.

O tipo é um tipo de bitmask que descreve um objeto que pode armazenar sinalizadores de formato. Os valores de sinalizador (elementos) distintos são:

  • dec, para inserir ou extrair valores inteiros em formato decimal.

  • hex, para inserir ou extrair valores inteiros em formato hexadecimal.

  • oct, para inserir ou extrair valores inteiros em formato octal.

  • showbase, para inserir um prefixo que revela a base de um campo inteiro gerado.

  • internal, para preencher uma largura de campo inserindo caracteres de preenchimento em um ponto interno de um campo numérico gerado. (Para obter informações sobre como configurar a largura do campo, consulte setw).

  • left, para preencher uma largura de campo, conforme necessário, inserindo caracteres de preenchimento no final de um campo gerado (justificação à esquerda).

  • right, para preencher uma largura de campo, conforme necessário, inserindo caracteres de preenchimento no início de um campo gerado (justificação à direita).

  • boolalpha, para inserir ou extrair objetos do tipo bool como nomes (como true e false), e não como valores numéricos.

  • fixed, para inserir valores de ponto flutuante no formato de ponto fixo (sem nenhum campo expoente).

  • scientific, para inserir valores de ponto flutuante no formato científico (com um campo expoente).

  • showpoint, para inserir de forma incondicional um ponto decimal em um campo de ponto flutuante gerado.

  • showpos, para inserir um sinal de adição em um campo numérico gerado não negativo.

  • skipws, para ignorar o espaço em branco à esquerda antes de determinadas extrações.

  • unitbuf, para liberar a saída após cada inserção.

  • uppercase, para inserir equivalentes maiúsculas de letras minúsculas em determinadas inserções.

Além disso, diversos valores úteis são:

  • adjustfield, um bitmask definido como internal | left | right

  • basefield, definido como dec | hex | oct

  • floatfield, definido como fixed | scientific

Para ver exemplos de funções que modificam esses sinalizadores de formato, consulte <iomanip>.

getloc

Retorna o objeto locale armazenado.

locale getloc() const;

Valor de retorno

O objeto locale armazenado.

Exemplo

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

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

C

imbue

Altera a localidade.

locale imbue(const locale& _Loc);

Parâmetros

_Loc
A nova configuração de localidade.

Valor de retorno

A localidade anterior.

Comentários

A função membro armazena _Loc no objeto locale e, em seguida, relata o evento de retorno de chamada e imbue_event. Ela retorna o valor armazenado anterior.

Exemplo

Consulte basic_ios::imbue para obter um exemplo.

Init

Cria os objetos iostream padrão quando construídos.

class Init { };

Comentários

A classe aninhada descreve um objeto cuja construção garante que os objetos iostream padrão sejam construídos adequadamente, mesmo antes da execução de um construtor para um objeto estático arbitrário.

ios_base

Constrói objetos ios_base.

ios_base();

Comentários

O construtor (protegido) não faz nada. Uma chamada posterior para basic_ios::init deverá inicializar o objeto antes de ser destruída com segurança. Sendo assim, o único uso seguro da classe ios_base é como uma classe base para a o modelo de classe basic_ios.

iostate

O tipo das constantes que descrevem o estado de um fluxo.

class ios_base {
public:
   typedef implementation-defined-bitmask-type iostate;
   static const iostate badbit;
   static const iostate eofbit;
   static const iostate failbit;
   static const iostate goodbit;
   // ...
};

Comentários

O tipo é um tipo de bitmask que descreve um objeto que pode armazenar informações de estado do fluxo. Os valores de sinalizador (elementos) distintos são:

  • badbit, para registrar uma perda de integridade do buffer do fluxo.
  • eofbit, para registrar o final do arquivo durante a extração de um fluxo.
  • failbit, para registrar uma falha ao extrair um campo válido de um fluxo.

Além disso, um valor útil é goodbit, em que nenhum dos bits mencionados anteriormente são definidos (goodbit deverá ser zero).

iword

Atribui um valor a ser armazenado como um iword.

long& iword(int idx);

Parâmetros

idx
O índice do valor a ser armazenado como um iword.

Comentários

A função membro retorna uma referência ao elemento idx da matriz extensível com elementos do tipo long. Todos os elementos estão efetivamente presentes e inicialmente armazenam o valor zero. A referência retornada é inválida após a chamada seguinte para iword para o objeto, após o objeto ser alterado por uma chamada para basic_ios::copyfmt ou após o objeto ser destruído.

Se idx for negativo ou se um armazenamento exclusivo não estiver disponível para o elemento, a função chamará setstate(badbit) e retornará uma referência que pode não ser exclusiva.

Para obter um índice exclusivo, para uso em todos os objetos do tipo ios_base, chame xalloc.

Exemplo

Consulte xalloc para encontrar um exemplo de como usar iword.

openmode

Descreve como interagir com um fluxo.

class ios_base {
public:
   typedef implementation-defined-bitmask-type openmode;
   static const openmode  in;
   static const openmode  out;
   static const openmode  ate;
   static const openmode  app;
   static const openmode  trunc;
   static const openmode  binary;
   // ...
};

Comentários

O modo de abertura para vários objetos iostream. Os valores de sinalizador são:

Constante Efeito
app Buscar até o final do fluxo antes de cada gravação
ate Buscar até o final do fluxo imediatamente após abrir
binary Abrir no modo binário. (Confira fopen para ver uma descrição do modo binário.)
in Abrir para leitura
out Abrir para gravação
trunc Excluir o conteúdo do arquivo após abrir

Exemplo

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

int main ( )
{
    using namespace std;
    fstream file;
    file.open( "rm.txt", ios_base::out | ios_base::trunc );

    file << "testing";
}

operator=

O operador de atribuição para objetos ios_base.

ios_base& operator=(const ios_base& right);

Parâmetros

right
Um objeto do tipo ios_base.

Valor de retorno

O objeto ao qual a atribuição está sendo feita.

Comentários

O operador copia as informações de formatação armazenadas, fazendo uma nova cópia de qualquer matriz extensível. Em seguida, ele retorna *this. A pilha de retornos de chamada não é copiada.

Esse operador é usado apenas por classes derivadas de ios_base.

precision

Especifica o número de dígitos a serem exibidos em um número de ponto flutuante.

streamsize precision() const;
streamsize precision(streamsize _Prec);

Parâmetros

_Prec
O número de dígitos significativos a serem exibidos, ou o número de dígitos após o ponto decimal em notação fixa.

Valor de retorno

A primeira função membro retorna a precisão de exibição armazenada. A segunda função membro armazena _Prec na precisão de exibição e retorna seu valor armazenado anterior.

Comentários

Números de ponto flutuante são exibidos em notação fixa com fixed.

Exemplo

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

int main( )
{
    using namespace std;
    float i = 31.31234F;

    cout.precision( 3 );
    cout << i << endl;          // display three significant digits
    cout << fixed << i << endl; // display three digits after decimal
                                // point
}

31.3
31.312

pword

Atribui um valor a ser armazenado como um pword.

void *& pword(int index);

Parâmetros

index
O índice do valor a ser armazenado como pword.

Comentários

A função membro retorna uma referência ao elemento index da matriz extensível com elementos do tipo ponteiro void. Todos os elementos estão efetivamente presentes e, inicialmente, armazenam o ponteiro nulo. A referência retornada é inválida após a chamada seguinte para pword para o objeto, após o objeto ser alterado por uma chamada para basic_ios::copyfmt ou após o objeto ser destruído.

Se index for negativo ou se um armazenamento exclusivo não estiver disponível para o elemento, a função chamará setstate(badbit) e retornará uma referência que pode não ser exclusiva.

Para obter um índice exclusivo, para uso em todos os objetos do tipo ios_base, chame xalloc.

Exemplo

Confira xalloc para ver um exemplo de como usar pword.

register_callback

Especifica uma função de retorno de chamada.

void register_callback(
    event_callback pfn, int idx);

Parâmetros

pfn
Ponteiro para a função de retorno.

idx
Um número definido pelo usuário.

Comentários

A função membro efetua push do par {pfn, idx} para a pilha de retornos de chamada armazenada pilha de retornos de chamada. Quando um evento de retorno de chamada ev é relatado, as funções são chamadas, na ordem inversa do registro, pela expressão (*pfn)(ev, *this, idx).

Exemplo

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

using namespace std;

void callback1( ios_base::event e, ios_base& stream, int arg )
{
    cout << "in callback1" << endl;
    switch ( e )
    {
    case ios_base::erase_event:
        cout << "an erase event" << endl;
        break;
    case ios_base::imbue_event:
        cout << "an imbue event" << endl;
        break;
    case ios_base::copyfmt_event:
        cout << "an copyfmt event" << endl;
        break;
    };
}

void callback2( ios_base::event e, ios_base& stream, int arg )
{
    cout << "in callback2" << endl;
    switch ( e )
    {
    case ios_base::erase_event:
        cout << "an erase event" << endl;
        break;
    case ios_base::imbue_event:
        cout << "an imbue event" << endl;
        break;
    case ios_base::copyfmt_event:
        cout << "an copyfmt event" << endl;
        break;
    };
}

int main( )
{
    // Make sure the imbue will not throw an exception
    // assert( setlocale( LC_ALL, "german" )!=NULL );

    cout.register_callback( callback1, 0 );
    cin.register_callback( callback2, 0 );

    try
    {
        // If no exception because the locale's not found,
        // generate an imbue_event on callback1
        cout.imbue(locale("german"));
    }
    catch(...)
    {
        cout << "exception" << endl;
    }

    // This will
    // (1) erase_event on callback1
    // (2) copyfmt_event on callback2
    cout.copyfmt(cin);

    // We get two erase events from callback2 at the end because
    // both cin and cout have callback2 registered when cin and cout
    // are destroyed at the end of program.
}

in callback1
an imbue event
in callback1
an erase event
in callback2
an copyfmt event
in callback2
an erase event
in callback2
an erase event

seekdir

Especifica o ponto de início para operações de deslocamento.

namespace std {
    class ios_base {
    public:
        typedef implementation-defined-enumerated-type seekdir;
        static const seekdir beg;
        static const seekdir cur;
        static const seekdir end;
        // ...
    };
}

Comentários

O tipo é um tipo enumerado que descreve um objeto que pode armazenar o modo de busca usado como um argumento para as funções membro de várias classes iostream. Os valores de sinalizador distintos são:

  • beg, para buscar (alterar a posição de leitura ou gravação atual) com relação ao início de uma sequência (matriz, fluxo ou arquivo).

  • cur, para buscar em relação à posição atual dentro de uma sequência.

  • end, para buscar em relação ao final de uma sequência.

Exemplo

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

int main ( )
{
    using namespace std;
    fstream file;
    file.open( "rm.txt", ios_base::out | ios_base::trunc );

    file << "testing";
    file.seekp( 0, ios_base::beg );
    file << "a";
    file.seekp( 0, ios_base::end );
    file << "a";
}

setf

Define os sinalizadores especificados.

fmtflags setf(
    fmtflags _Mask
);
fmtflags setf(
    fmtflags _Mask,
    fmtflags _Unset
);

Parâmetros

_Mask
Os sinalizadores a serem ativados.

_Unset
Os sinalizadores a serem desativados.

Valor de retorno

Os sinalizadores de formato anteriores

Comentários

A primeira função membro chama flags(_Mask | _Flags) (definir bits selecionados) e retorna os sinalizadores de formato anteriores. A segunda função membro chama flags(_Mask & fmtfl, flags & ~_Mask) (substituir bits selecionados sob uma máscara) e retorna os sinalizadores de formato anteriores.

Exemplo

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

int main( )
{
    using namespace std;
    int i = 10;
    cout << i << endl;

    cout.unsetf( ios_base::dec );
    cout.setf( ios_base::hex );
    cout << i << endl;

    cout.setf( ios_base::dec );
    cout << i << endl;
    cout.setf( ios_base::hex, ios_base::dec );
    cout << i << endl;
}

sync_with_stdio

Garante que operações de iostream e da biblioteca de runtime de C ocorram na ordem em que aparecem no código-fonte.

static bool sync_with_stdio(
   bool _Sync = true
);

Parâmetros

_Sync
Se todos os fluxos estão sincronizados com stdio.

Valor de retorno

Configuração anterior dessa função.

Comentários

A função membro estática armazena um sinalizador de sincronização stdio, que inicialmente é true. Quando true, esse sinalizador garante que as operações no mesmo arquivo sejam sincronizadas corretamente entre as funções iostreams e as funções definidas na Biblioteca Padrão de C++. Caso contrário, a sincronização poderá ou não ser garantida, mas o desempenho poderá ser aprimorado. A função armazena _Sync no sinalizador de sincronização stdio e retorna seu valor armazenado anterior. Você pode chamá-la de modo confiável somente antes de executar operações nos fluxos padrão.

unsetf

Desativa os sinalizadores especificados.

void unsetf(
   fmtflags _Mask
);

Parâmetros

_Mask
Os sinalizadores que você deseja desativar.

Comentários

A função membro chama flags(~_Mask & flags) (limpar bits selecionados).

Exemplo

Consulte ios_base::setf para ver um exemplo de uso de unsetf.

width

Define o tamanho do fluxo de saída.

streamsize width( ) const;
streamsize width(
   streamsize _Wide
);

Parâmetros

_Wide
O tamanho desejado do fluxo de saída.

Valor de retorno

A configuração de largura atual.

Comentários

A primeira função membro retorna a largura do campo armazenado. A segunda função membro armazena _Wide na largura do campo e retorna seu valor armazenado anterior.

Exemplo

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

int main( ) {
    using namespace std;

    cout.width( 20 );
    cout << cout.width( ) << endl;
    cout << cout.width( ) << endl;
}

20
0

xalloc

Especifica que uma variável faz parte do fluxo.

static int xalloc( );

Valor de retorno

A função membro estática retorna um valor estático armazenado, que ela incrementa em cada chamada.

Comentários

Você pode usar o valor retornado como um argumento de índice exclusivo ao chamar as funções membro iword ou pword.

Exemplo

// ios_base_xalloc.cpp
// compile with: /EHsc
// Lets you store user-defined information.
// iword, jword, xalloc
#include <iostream>

int main( )
{
    using namespace std;

    static const int i = ios_base::xalloc();
    static const int j = ios_base::xalloc();
    cout.iword( i ) = 11;
    cin.iword( i ) = 13;
    cin.pword( j ) = "testing";
    cout << cout.iword( i ) << endl;
    cout << cin.iword( i ) << endl;
    cout << ( char * )cin.pword( j ) << endl;
}

11
13
testing

Confira também

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