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 >
ozstream &	operator<< (T const &t)
	Stream output: override to preserve type of return value. More...

ozstream &	operator<< (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...

ozstream &	put (char const c)
	Write a char. More...

ozstream &	write (char const *str, std::streamsize const count)
	Write a string. More...

ozstream &	write (std::string const &str, std::streamsize const count)
	Write a string. More...

ozstream &	flush ()
	Flush the stream – currently alias to flush_finalize() More...

ozstream &	flush_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 >
orstream &	operator<< (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_ostream *	mpi_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

enum utility::io::ozstream::Compression

private

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_a	filename
[in]	open_mode	opening mode bitmask, use std::ios_base::out for gzip files
[in]	buf_size	buffer 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

Close the ofstream and reset the state.

References utility::io::mpi_stream::basic_mpi_ostream< Elem, Tr, ElemA, ByteT, ByteAT >::close(), compression_, destroy_char_buffer(), filename_, mpi_stream_p_, NONE, of_stream_, and zip_stream_p_.

Referenced by open(), open_append(), open_append_if_existed(), and ~ozstream().

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

References utility_exit_with_message.

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

References bMPI_reroute_stream_, and mpi_FileBuf_master_rank_.

void utility::io::ozstream::open	(	std::string const &	filename_a,
		std::ios_base::openmode	open_mode = `std::ios_base::out`
	)

Open a file.

References allocate_assign_char_buffer(), bMPI_reroute_stream_, buffer_size_, close(), compression_, utility::file::file_extension(), filename_, GZIP, mpi_FileBuf_master_rank_, mpi_stream_p_, NONE, of_stream_, utility::file::trytry_ofstream_open(), UNCOMPRESSED, and zip_stream_p_.

Referenced by open_append_if_existed(), and ozstream().

void utility::io::ozstream::open_append ( std::string const & filename_a )

Open a text file for appending.

Open a text file or gzip'd file for appending.

References allocate_assign_char_buffer(), bMPI_reroute_stream_, buffer_size_, close(), compression_, utility::io::oc::cout, utility::options::OptionKeys::options::exit, utility::file::file_extension(), filename_, GZIP, mpi_FileBuf_master_rank_, mpi_stream_p_, NONE, of_stream_, utility::file::trytry_ofstream_open(), UNCOMPRESSED, and zip_stream_p_.

Referenced by open_append_if_existed().

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_, 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

Write a char.

Implements utility::io::orstream.

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

Referenced by put().

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

Write a string.

Implements utility::io::orstream.

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

Referenced by write().

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

Referenced by MPI_reroute_rank(), open(), open_append(), and open_append_if_existed().

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

Compression state.

Referenced by close(), compressed(), gzipped(), open(), open_append(), open_append_if_existed(), and uncompressed().