Funções de membro de fluxo de arquivo de saída

Funções de membro de fluxo de saída têm três tipos: aqueles que são equivalentes aos manipuladores, aqueles que executam operações de gravação sem formatação e aqueles que modificam o fluxo do estado e não têm nenhum manipulador ou operador de inserção equivalente. Para saída sequencial e formatada, você pode usar somente os operadores de inserção e manipuladores. Para saída de disco binário de acesso aleatório, você usar outras funções de membro, com ou sem operadores de inserção.

A função open para fluxos de saída

Para usar um fluxo de arquivo de saída (ofstream), você deve associar esse fluxo a um arquivo de disco específico no construtor ou na função open. Se você usar a função open, poderá reutilizar o mesmo objeto de fluxo com uma série de arquivos. Em ambos os casos, os argumentos que descrevem o arquivo são os mesmos.

Ao abrir o arquivo associado a um fluxo de saída, geralmente você especifica um sinalizador open_mode. Você pode combinar esses sinalizadores, que são definidos como enumeradores na classe ios, com o operador OR bit a bit (|). Confira ios_base::openmode para obter uma lista dos enumeradores.

Três situações de fluxo de saída comuns envolvem as opções de modo:

• Criando um arquivo. Se o arquivo já existir, a versão antiga será excluída.

  ofstream ofile("FILENAME");
  // Default is ios::out
  
  ofstream ofile("FILENAME", ios::out);
  // Equivalent to above
  

• Anexando registros a um arquivo existente ou criando um se ele não existir.

  ofstream ofile("FILENAME", ios::app);
  

• Abrindo os dois arquivos, um de cada vez, no mesmo fluxo.

  ofstream ofile();
  ofile.open("FILE1", ios::in);
  // Do some output
  ofile.close();    // FILE1 closed
  ofile.open("FILE2", ios::in);
  // Do some more output
  ofile.close();    // FILE2 closed
  // When ofile goes out of scope it is destroyed.
  

A função put

A função put grava um caractere no fluxo de saída. As duas instruções a seguir são as mesmas por padrão, mas a segunda é afetada pelos argumentos de formatação do fluxo:

cout.put('A');

// Exactly one character written
cout <<'A'; // Format arguments 'width' and 'fill' apply

A função write

A função write grava um bloco de memória em um fluxo de arquivo de saída. O argumento de tamanho especifica o número de bytes gravados. Este exemplo cria um fluxo de arquivo de saída e grava o valor binário da estrutura Date nele:

// write_function.cpp
// compile with: /EHsc
#include <fstream>
using namespace std;

struct Date
{
   int mo, da, yr;
};

int main( )
{
   Date dt = { 6, 10, 92 };
   ofstream tfile( "date.dat" , ios::binary );
   tfile.write( (char *) &dt, sizeof dt );
}

A função write não é interrompida quando atinge um caractere NULL, portanto, a estrutura de classe completa é gravada. A função adota dois argumentos: um ponteiro char e uma contagem de caracteres a serem gravados. Observe a conversão necessária para char * antes do endereço do objeto de estrutura.

As funções seekp e tellp

Um fluxo de arquivo de saída mantém um ponteiro interno que aponta para a posição em que os dados serão serem gravados em seguida. A função membro seekp define esse ponteiro e, portanto, fornece a saída do arquivo de disco de acesso aleatório. A função membro tellp retorna a posição do arquivo. Para obter exemplos que usam os equivalentes de fluxo de entrada para seekp e tellp, confira As funções seekg e tellg.

A função close para fluxos de saída

A função de membro close fecha o arquivo de disco associado a um fluxo de arquivo de saída. O arquivo deve ser fechado para concluir todas as saídas de disco. Se necessário, o destruidor ofstream fecha o arquivo para você, mas você poderá usar a função close se precisar abrir um outro arquivo para o mesmo objeto de fluxo.

O destruidor de fluxo de saída fecha automaticamente um arquivo do fluxo somente se o construtor ou a função de membro open abriram o arquivo. Se você passar para o construtor um descritor de arquivo para um arquivo já aberto ou usar a função de membro attach, será necessário fechá-lo explicitamente.

Funções de processamento de erros

Use essas funções membro para testar se há erros ao gravar em um fluxo:

Função	Valor retornado
bad	Retornará true se houver um erro irrecuperável.
fail	Retornará true se houver um erro irrecuperável ou uma condição “esperada”, como um erro de conversão ou se o arquivo não for encontrado. O processamento geralmente pode retomar após uma chamada para clear com um argumento zero.
good	Retornará true se não houver nenhuma condição de erro (recuperável ou não) e o sinalizador de fim do arquivo não estiver definido.
eof	Retornará true na condição de fim do arquivo.
clear	Define o estado de erro interno. Se chamado com os argumentos padrão, limpa todos os bits de erro.
[rdstate](basic-ios-class.md#rdstate	Retorna o estado de erro atual.

O operador ! está sobrecarregado para executar a mesma função que a função fail. Portanto, a expressão:

if(!cout)...

é equivalente a:

if(cout.fail())...

O operador void*() está sobrecarregado para ser o oposto do operador !. Assim, a expressão:

if(cout)...

é igual a:

if(!cout.fail())...

O operador void*() não é equivalente a good, pois ele não testa o fim do arquivo.

Confira também

Fluxos de saída