Rosetta Utilities  2014.35
Public Member Functions | Static Public Member Functions | Private Types | Private Member Functions | Private Attributes | Static Private Attributes | Friends | List of all members
utility::io::ozstream Class Reference

ozstream: Output file stream wrapper for uncompressed and compressed files More...

#include <ozstream.hh>

Public Member Functions

 ozstream ()
 Default constructor. More...
 
 ozstream (std::string const &filename_a, std::ios_base::openmode open_mode=std::ios_base::out, std::streamsize buf_size=OZSTREAM_DEFAULT_BUFFER_SIZE)
 Filename constructor. More...
 
virtual ~ozstream ()
 Destructor. More...
 
 operator bool () const
 bool conversion More...
 
 operator std::ostream const & () const
 Stream conversion. More...
 
 operator std::ostream & ()
 Stream conversion. More...
 
template<typename T >
ozstreamoperator<< (T const &t)
 Stream output: override to preserve type of return value. More...
 
ozstreamoperator<< (manipulator m)
 Stream output overload to replace std::endl with
to avoid flushing. More...
 
void open (std::string const &filename_a, std::ios_base::openmode open_mode=std::ios_base::out)
 Open a file. More...
 
void open_append (std::string const &filename_a)
 Open a text file for appending. More...
 
void open_append_if_existed (std::string const &filename_a, std::stringstream &preprinted_header)
 open file as append if it exists, return true if file existed before, false if it is new. More...
 
ozstreamput (char const c)
 Write a char. More...
 
ozstreamwrite (char const *str, std::streamsize const count)
 Write a string. More...
 
ozstreamwrite (std::string const &str, std::streamsize const count)
 Write a string. More...
 
ozstreamflush ()
 Flush the stream – currently alias to flush_finalize() More...
 
ozstreamflush_finalize ()
 Flush the streams and finalize the zip stream. More...
 
void zflush ()
 Flush the zip_ostream. More...
 
void zflush_finalize ()
 Flush and finalize the zip_stream. More...
 
void clear ()
 Clear the stream. More...
 
void close ()
 Close the ofstream and reset the state. More...
 
std::ostream const & operator() () const
 Stream access. More...
 
std::ostream & operator() ()
 Stream access. More...
 
std::ostream const & stream () const
 Stream access. More...
 
std::ostream & stream ()
 Stream access. More...
 
std::streambuf * rdbuf () const
 Pointer to the stream buffer. More...
 
std::string const & filename () const
 File name. More...
 
bool good () const
 Good? More...
 
bool eof () const
 End of file? More...
 
bool fail () const
 Fail? More...
 
bool bad () const
 Bad? More...
 
bool compressed () const
 Compressed? More...
 
bool uncompressed () const
 Uncompressed? More...
 
bool gzipped () const
 gzipped? More...
 
std::streamsize buffer_size () const
 get buffer size (bytes) More...
 
void buffer_size (std::streamsize const &buf_size)
 set buffer size (bytes) More...
 
- Public Member Functions inherited from utility::io::orstream
virtual ~orstream ()
 Destructor. More...
 
template<typename T >
orstreamoperator<< (T const &t)
 Stream output. More...
 

Static Public Member Functions

static void enable_MPI_reroute (int min_client_rank, int master_rank)
 
static int MPI_reroute_rank ()
 

Private Types

enum  Compression { NONE, UNCOMPRESSED, GZIP }
 

Private Member Functions

bool is_gzip () const
 Is stream attached to a gzip file? More...
 
long get_crc () const
 CRC of the uncompressed data (see zipstream documentation) More...
 
long get_in_size () const
 Uncompressed data size. More...
 
long get_out_size () const
 Compressed data size. More...
 
bool allocate_assign_char_buffer ()
 if character buffer does not exist, create it and assign it to internal ofstream More...
 
bool destroy_char_buffer ()
 if character buffer exists, destroy it More...
 

Private Attributes

Compression compression_
 Compression state. More...
 
std::ofstream of_stream_
 File stream. More...
 
std::string filename_
 File name. More...
 
std::streamsize buffer_size_
 size of buffer (in bytes) More...
 
char * char_buffer_p_
 character buffer pointer (owning) More...
 
zlib_stream::zip_ostream * zip_stream_p_
 Zip file stream pointer (owning) More...
 
mpi_stream::mpi_ostreammpi_stream_p_
 

Static Private Attributes

static bool bMPI_reroute_stream_
 
static int mpi_FileBuf_master_rank_
 

Friends

long utility::file::gzip (std::string const &uncompressedfile, bool overwrite)
 
long utility::file::gunzip (std::string const &compressedfile, bool overwrite)
 

Additional Inherited Members

- Protected Types inherited from utility::io::orstream
typedef std::ostream &(* manipulator )(std::ostream &)
 
- Protected Member Functions inherited from utility::io::orstream
 orstream ()
 Default constructor. More...
 

Detailed Description

ozstream: Output file stream wrapper for uncompressed and compressed files

Member Enumeration Documentation

Enumerator
NONE 
UNCOMPRESSED 
GZIP 

Constructor & Destructor Documentation

utility::io::ozstream::ozstream ( )
inline

Default constructor.

utility::io::ozstream::ozstream ( std::string const &  filename_a,
std::ios_base::openmode  open_mode = std::ios_base::out,
std::streamsize  buf_size = OZSTREAM_DEFAULT_BUFFER_SIZE 
)
inlineexplicit

Filename constructor.

Parameters
[in]filename_afilename
[in]open_modeopening mode bitmask, use std::ios_base::out for gzip files
[in]buf_sizebuffer size (bytes), enforced lower bound of 4KB

References buffer_size(), and open().

virtual utility::io::ozstream::~ozstream ( )
inlinevirtual

Destructor.

References close().

Member Function Documentation

bool utility::io::ozstream::allocate_assign_char_buffer ( )
inlineprivate

if character buffer does not exist, create it and assign it to internal ofstream

File must be closed for this operation to be successful, otherwise we can run into implementation dependent behavior of std::basic_filebuf.

Returns
true if successful, false otherwise

References buffer_size_, char_buffer_p_, and of_stream_.

Referenced by open(), and open_append().

bool utility::io::ozstream::bad ( ) const
inlinevirtual

Bad?

Implements utility::io::orstream.

References stream().

std::streamsize utility::io::ozstream::buffer_size ( ) const
inline

get buffer size (bytes)

In uncompressed mode this is the size of the character buffer. In compressed mode this is the size of the zip buffer.

References buffer_size_.

Referenced by ozstream().

void utility::io::ozstream::buffer_size ( std::streamsize const &  buf_size)
inline

set buffer size (bytes)

In uncompressed mode this is the size of the character buffer. In compressed mode this is the size of the zip buffer. Lower bound of 4KB is enforced due to zipstream requirements. Operation is skipped if the file is currently open, as the buffer is considered locked.

References buffer_size_, max(), and of_stream_.

void utility::io::ozstream::clear ( )
inlinevirtual

Clear the stream.

Implements utility::io::orstream.

References mpi_stream_p_, of_stream_, and zip_stream_p_.

void utility::io::ozstream::close ( )
inline
bool utility::io::ozstream::compressed ( ) const
inlinevirtual

Compressed?

Implements utility::io::orstream.

References compression_, and GZIP.

bool utility::io::ozstream::destroy_char_buffer ( )
inlineprivate

if character buffer exists, destroy it

File must be closed for this operation to be successful, otherwise we are deleting a buffer that's still in use.

Returns
true if successful, false otherwise

References char_buffer_p_, and of_stream_.

Referenced by close().

void utility::io::ozstream::enable_MPI_reroute ( int  min_client_rank,
int  master_rank 
)
static
bool utility::io::ozstream::eof ( ) const
inlinevirtual

End of file?

Implements utility::io::orstream.

References stream().

bool utility::io::ozstream::fail ( ) const
inlinevirtual

Fail?

Implements utility::io::orstream.

References stream().

std::string const& utility::io::ozstream::filename ( ) const
inline

File name.

References filename_.

ozstream& utility::io::ozstream::flush ( )
inlinevirtual

Flush the stream – currently alias to flush_finalize()

Instead doing a regular flush, we currently force a completion of the zip stream. We do this to pre-empt against several things: (1) the expensive operation of closing and re-opening a stream (2) confusion and inconvenience that may result from users calling flushes and ending upon with broken or corrupted files if a job is somehow interrupted (e.g. on a cluster). Please note that calling flush_finalize() too often can seriously degrade compression. zlib documentation appears to imply that every 1MB or so is a reasonable rule of thumb.

Implements utility::io::orstream.

References utility::io::mpi_stream::basic_mpi_ostream< Elem, Tr, ElemA, ByteT, ByteAT >::flush(), flush(), mpi_stream_p_, of_stream_, and zip_stream_p_.

Referenced by flush(), flush_finalize(), and operator<<().

ozstream& utility::io::ozstream::flush_finalize ( )
inline

Flush the streams and finalize the zip stream.

Calling this will complete the zip stream. Upon the next write, a new zip stream will be started. Please note that calling flush_finalize() too often can seriously degrade compression. zlib documentation appears to imply that every 1MB or so is a reasonable rule of thumb.

References utility::io::mpi_stream::basic_mpi_ostream< Elem, Tr, ElemA, ByteT, ByteAT >::flush(), flush(), mpi_stream_p_, of_stream_, and zip_stream_p_.

long utility::io::ozstream::get_crc ( ) const
inlineprivate

CRC of the uncompressed data (see zipstream documentation)

References zip_stream_p_.

long utility::io::ozstream::get_in_size ( ) const
inlineprivate

Uncompressed data size.

References zip_stream_p_.

long utility::io::ozstream::get_out_size ( ) const
inlineprivate

Compressed data size.

References zip_stream_p_.

bool utility::io::ozstream::good ( ) const
inlinevirtual

Good?

Implements utility::io::orstream.

References stream().

Referenced by open_append_if_existed().

bool utility::io::ozstream::gzipped ( ) const
inlinevirtual

gzipped?

Implements utility::io::orstream.

References compression_, and GZIP.

bool utility::io::ozstream::is_gzip ( ) const
inlineprivate

Is stream attached to a gzip file?

References zip_stream_p_.

static int utility::io::ozstream::MPI_reroute_rank ( )
inlinestatic
void utility::io::ozstream::open ( std::string const &  filename_a,
std::ios_base::openmode  open_mode = std::ios_base::out 
)
void utility::io::ozstream::open_append ( std::string const &  filename_a)
void utility::io::ozstream::open_append_if_existed ( std::string const &  filename_a,
std::stringstream &  preprinted_header 
)

open file as append if it exists, return true if file existed before, false if it is new.

special "atomic" method to open a stream and print a header if it is new. This is necessary to avoid process competition when checking for existance to decided whether or not to write a header.

References bMPI_reroute_stream_, close(), compression_, utility::file::file_exists(), filename_, good(), mpi_FileBuf_master_rank_, mpi_stream_p_, NONE, open(), open_append(), and UNCOMPRESSED.

utility::io::ozstream::operator bool ( ) const
inlinevirtual

bool conversion

Implements utility::io::orstream.

References mpi_stream_p_, of_stream_, and zip_stream_p_.

utility::io::ozstream::operator std::ostream & ( )
inlinevirtual

Stream conversion.

Implements utility::io::orstream.

References mpi_stream_p_, of_stream_, and zip_stream_p_.

utility::io::ozstream::operator std::ostream const & ( ) const
inlinevirtual

Stream conversion.

Implements utility::io::orstream.

References mpi_stream_p_, of_stream_, and zip_stream_p_.

std::ostream const& utility::io::ozstream::operator() ( ) const
inlinevirtual

Stream access.

Implements utility::io::orstream.

References mpi_stream_p_, of_stream_, and zip_stream_p_.

std::ostream& utility::io::ozstream::operator() ( )
inlinevirtual

Stream access.

Implements utility::io::orstream.

References mpi_stream_p_, of_stream_, and zip_stream_p_.

template<typename T >
ozstream& utility::io::ozstream::operator<< ( T const &  t)
inline

Stream output: override to preserve type of return value.

References mpi_stream_p_, of_stream_, basic::options::OptionKeys::in::file::t, and zip_stream_p_.

ozstream& utility::io::ozstream::operator<< ( manipulator  m)
inlinevirtual

Stream output overload to replace std::endl with
to avoid flushing.

and call ozstream::flush() when passed std::flush

Implements utility::io::orstream.

References flush(), mpi_stream_p_, of_stream_, and zip_stream_p_.

ozstream& utility::io::ozstream::put ( char const  c)
inlinevirtual
std::streambuf* utility::io::ozstream::rdbuf ( ) const
inlinevirtual

Pointer to the stream buffer.

Implements utility::io::orstream.

References stream().

std::ostream const& utility::io::ozstream::stream ( ) const
inlinevirtual

Stream access.

Implements utility::io::orstream.

References mpi_stream_p_, of_stream_, and zip_stream_p_.

Referenced by bad(), eof(), fail(), good(), rdbuf(), and write().

std::ostream& utility::io::ozstream::stream ( )
inlinevirtual

Stream access.

Implements utility::io::orstream.

References mpi_stream_p_, of_stream_, and zip_stream_p_.

bool utility::io::ozstream::uncompressed ( ) const
inlinevirtual

Uncompressed?

Implements utility::io::orstream.

References compression_, and UNCOMPRESSED.

ozstream& utility::io::ozstream::write ( char const *  str,
std::streamsize const  count 
)
inlinevirtual
ozstream& utility::io::ozstream::write ( std::string const &  str,
std::streamsize const  count 
)
inlinevirtual

Write a string.

Implements utility::io::orstream.

References stream().

void utility::io::ozstream::zflush ( )
inline

Flush the zip_ostream.

this will flush but not finalize the zip stream

References zip_stream_p_.

void utility::io::ozstream::zflush_finalize ( )
inline

Flush and finalize the zip_stream.

Calling this will complete the zip stream. Upon the next write, a new zip stream will be started Please note that calling zflush_finalize() too often can seriously degrade compression. zlib documentation appears to imply that every 1MB or so is a reasonable rule of thumb.

References zip_stream_p_.

Friends And Related Function Documentation

long utility::file::gunzip ( std::string const &  compressedfile,
bool  overwrite 
)
friend
long utility::file::gzip ( std::string const &  uncompressedfile,
bool  overwrite 
)
friend

Member Data Documentation

bool utility::io::ozstream::bMPI_reroute_stream_
staticprivate
std::streamsize utility::io::ozstream::buffer_size_
private

size of buffer (in bytes)

In uncompressed mode this is the size of the character buffer. In compressed mode this is the size of the zip buffer. Must be at least 4KB otherwise zipstream will break.

Referenced by allocate_assign_char_buffer(), buffer_size(), open(), and open_append().

char* utility::io::ozstream::char_buffer_p_
private

character buffer pointer (owning)

Referenced by allocate_assign_char_buffer(), and destroy_char_buffer().

Compression utility::io::ozstream::compression_
private
std::string utility::io::ozstream::filename_
private

File name.

Referenced by close(), filename(), open(), open_append(), and open_append_if_existed().

int utility::io::ozstream::mpi_FileBuf_master_rank_
staticprivate
mpi_stream::mpi_ostream* utility::io::ozstream::mpi_stream_p_
private
std::ofstream utility::io::ozstream::of_stream_
private
zlib_stream::zip_ostream* utility::io::ozstream::zip_stream_p_
private

The documentation for this class was generated from the following files: