Bzip2Ifstream Class Reference

Streaming decompressor for bzip2 (.bz2) files. More...

#include <OpenMS/FORMAT/Bzip2Ifstream.h>

Collaboration diagram for Bzip2Ifstream:

Public Member Functions
	Bzip2Ifstream ()
	Default constructor; leaves the instance in a closed state (isOpen returns false, streamEnd returns true).
	Bzip2Ifstream (const char *filename)
	Construct and open filename for reading in one step.
virtual	~Bzip2Ifstream ()
	Destructor; closes the bzip2 reader and the underlying file handle.
size_t	read (char *s, size_t n)
	Read up to n decompressed bytes into s.
bool	streamEnd () const
	Whether the stream has been closed (end of file reached or no file opened).
bool	isOpen () const
	Whether a file is currently open for reading.
void	open (const char *filename)
	Open filename for reading; closes the currently open file first.
void	close ()
	Close the currently open file (no-op if none is open). After the call, isOpen returns false and streamEnd returns true.

Protected Member Functions
	Bzip2Ifstream (const Bzip2Ifstream &bzip2)
Bzip2Ifstream &	operator= (const Bzip2Ifstream &bzip2)

Protected Attributes
FILE *	file_
	Underlying FILE handle used to feed the bzip2 reader; nullptr when no file is open.
BZFILE *	bzip2file_
	bzip2 read handle attached to file_; nullptr when no file is open.
size_t	n_buffer_
	Number of bytes produced by the most recent read call.
int	bzerror_
	Most recent bzip2 status code returned to the read API.
bool	stream_at_end_
	true once the stream has been closed (either explicitly via close or implicitly because the end of the compressed file was reached).

Detailed Description

Streaming decompressor for bzip2 (.bz2) files.

Reads raw bytes out of a bzip2-compressed file on demand. The class owns one underlying FILE handle and one bzip2 read handle; both are released by close (also called from the destructor). Copy and assignment are deliberately suppressed.

Typical lifecycle: construct (or call open) with the path of a .bz2 file, repeatedly call read until it returns fewer bytes than requested (at which point the stream is closed automatically, isOpen returns false and streamEnd returns true).

Constructor & Destructor Documentation

Bzip2Ifstream() [1/3]

Bzip2Ifstream

(

)

Default constructor; leaves the instance in a closed state (isOpen returns false, streamEnd returns true).

Bzip2Ifstream() [2/3]

Bzip2Ifstream ( const char *  filename )

explicit

Construct and open filename for reading in one step.

Parameters

[in]

filename

Path of the bzip2-compressed file to open (binary mode is used so the contents are not translated on Windows).

Exceptions

Exception::FileNotFound	when filename does not exist.
Exception::FileNotReadable	when filename exists but cannot be read.
Exception::IOException	when opening the file fails for any other reason.
Exception::ConversionError	when initialising the bzip2 reader on the opened file fails.

~Bzip2Ifstream()

virtual ~Bzip2Ifstream ( )

virtual

Destructor; closes the bzip2 reader and the underlying file handle.

Bzip2Ifstream() [3/3]

Bzip2Ifstream ( const Bzip2Ifstream &  bzip2 )

protected

Member Function Documentation

close()

void close

(

)

Close the currently open file (no-op if none is open). After the call, isOpen returns false and streamEnd returns true.

isOpen()

bool isOpen ( ) const

inline

Whether a file is currently open for reading.

Returns

true if a file is open, false otherwise.

References Bzip2Ifstream::file_.

Referenced by Bzip2InputStream::getIsOpen().

open()

void open

(

const char *

filename

)

Open filename for reading; closes the currently open file first.

Parameters

[in]

filename

Path of the bzip2-compressed file to open.

Exceptions

Exception::FileNotFound	when filename does not exist.
Exception::FileNotReadable	when filename exists but cannot be read.
Exception::IOException	when opening the file fails for any other reason.
Exception::ConversionError	when initialising the bzip2 reader on the opened file fails.

operator=()

Bzip2Ifstream & operator= ( const Bzip2Ifstream &  bzip2 )

protected

read()

size_t read	(	char *	s,
		size_t	n
	)

Read up to n decompressed bytes into s.

Returns the actual number of bytes written into s. A return value smaller than n indicates that the end of the compressed stream was reached during this call; the stream is then closed automatically (isOpen becomes false and streamEnd becomes true).

Parameters

[out]	s	Buffer that receives the decompressed bytes; must be at least n bytes long.
[in]	n	Number of bytes to attempt to read.

Returns

Number of decompressed bytes actually written into s.

Note

The output is a raw byte stream and is not null-terminated.

When the return value is less than n the stream has been closed; check isOpen before issuing further reads.

Exceptions

Exception::ParseError	when bzip2 reports a decompression failure mid-stream.
Exception::IllegalArgument	when called on an instance that has no open file (default-constructed, or already closed – including after the previous call read to end of file).

streamEnd()

bool streamEnd ( ) const

inline

Whether the stream has been closed (end of file reached or no file opened).

Returns

true if no further read calls should be issued, false otherwise.

References Bzip2Ifstream::stream_at_end_.

Member Data Documentation

bzerror_

int bzerror_

protected

Most recent bzip2 status code returned to the read API.

bzip2file_

BZFILE* bzip2file_

protected

bzip2 read handle attached to file_; nullptr when no file is open.

file_

FILE* file_

protected

Underlying FILE handle used to feed the bzip2 reader; nullptr when no file is open.

Referenced by Bzip2Ifstream::isOpen().

n_buffer_

size_t n_buffer_

protected

Number of bytes produced by the most recent read call.

stream_at_end_

bool stream_at_end_

protected

true once the stream has been closed (either explicitly via close or implicitly because the end of the compressed file was reached).

Referenced by Bzip2Ifstream::streamEnd().