C++ bindings for cgul_crlf_file More...

#include <cgul_crlf_file_cxx.h>

Collaboration diagram for cgul_crlf_file_cxx:

Public Member Functions
	cgul_crlf_file_cxx ()

	cgul_crlf_file_cxx (const char *fname, bool is_block_buffered=true)

	cgul_crlf_file_cxx (FILE *f, bool is_block_buffered=true)

	cgul_crlf_file_cxx (const char *buf, size_t buf_size)

virtual	~cgul_crlf_file_cxx ()

virtual void	open_fname (const char *fname, bool is_block_buffered=true)

virtual void	open_file (FILE *f, bool is_block_buffered=true)

virtual void	open_memory (const char *buf, size_t buf_size)

virtual void	close ()

virtual const char *	get_file_name () const

virtual const void *	get_file () const

virtual int	get_strip_utf8_bom () const

virtual void	set_strip_utf8_bom (int strip_utf8_bom)

void	get_lines (char **lines, unsigned long int line_count)

virtual const char *	get_line ()

virtual unsigned long	get_line_count () const

virtual unsigned long	get_line_offset () const

virtual void	fseek (unsigned long offset, int whence)

virtual void	rewind ()

virtual unsigned long	get_buffer_size () const

virtual void	set_buffer_size (unsigned long bsize)

virtual cgul_crlf_file_t	get_obj () const

virtual cgul_crlf_file_t	take_obj ()

virtual void	set_obj (cgul_crlf_file_t rhs)

Detailed Description

This class provides the C++ bindings for C cgul_crlf_file objects. The main purpose of this class is to convert the C-style function calls and exception handling in cgul_crlf_file into C++-style function calls and exception handling.

Constructor & Destructor Documentation

§ cgul_crlf_file_cxx() [1/4]

cgul_crlf_file_cxx::cgul_crlf_file_cxx ( )

inline

This method creates a new cgul_crlf_file_cxx instance. After this method returns, open_fname, open_file(), or open_memory() should be called before calling any other method. If an error occurs, an exception is thrown.

References cgul_crlf_file__new().

Referenced by set_obj().

§ cgul_crlf_file_cxx() [2/4]

cgul_crlf_file_cxx::cgul_crlf_file_cxx	(	const char *	fname,
		bool	is_block_buffered = `true`
	)

inline

This method creates a new cgul_crlf_file_cxx instance and calls open() passing it fname. The file will be closed when this instance is deleted. If an error occurs, an exception is thrown.

If is_block_buffered is true, this method results in a very fast cgul_crlf_file_cxx instance, but the underlying file should be a regular file or any other file that is capable of block buffering. If the file is not capable of block buffering, is_block_buffered should be false which results in a much slower cgul_crlf_file_cxx instance, but one that should be able to read from any type of file. As a general rule, if you are reading from a regular file or are working in batch mode, is_block_buffered should be true to get the best performance. If you are reading from a line-oriented or character-oriented device like a terminal or from a named pipe across which small messages are being passed, is_block_buffered should be false.

Parameters

[in]	fname	file name
[in]	is_block_buffered	whether the file is block buffered

References cgul_crlf_file__new_from_fname().

§ cgul_crlf_file_cxx() [3/4]

cgul_crlf_file_cxx::cgul_crlf_file_cxx	(	FILE *	f,
		bool	is_block_buffered = `true`
	)

inline

This method creates a new cgul_crlf_file_cxx instance. This class does not take ownership of f. Thus, the client is still responsible for calling fclose() on f. If an error occurs, an exception is thrown.

If is_block_buffered is true, this method results in a very fast cgul_crlf_file_cxx instance, but the underlying file should be a regular file or any other file that is capable of block buffering. If the file is not capable of block buffering, is_block_buffered should be false which results in a much slower cgul_crlf_file_cxx instance, but one that should be able to read from any type of file. As a general rule, if you are reading from a regular file or are working in batch mode, is_block_buffered should be true to get the best performance. If you are reading from a line-oriented or character-oriented device like a terminal or from a named pipe across which small messages are being passed, is_block_buffered should be false.

Parameters

[in]	f	underlying file
[in]	is_block_buffered	whether the file is block buffered

References cgul_crlf_file__new_from_file().

§ cgul_crlf_file_cxx() [4/4]

cgul_crlf_file_cxx::cgul_crlf_file_cxx	(	const char *	buf,
		size_t	buf_size
	)

inline

This method creates a new cgul_crlf_file_cxx instance and calls open() passing it buf and buf_size. This class does not take ownership of buf so the client is still responsible for freeing buf if necessary. If an error occurs, an exception is thrown.

Parameters

[in]	buf	memory buffer
[in]	buf_size	size of `buf` in bytes

References cgul_crlf_file__new_from_memory().

§ ~cgul_crlf_file_cxx()

virtual cgul_crlf_file_cxx::~cgul_crlf_file_cxx ( )

inlinevirtual

This method deletes the instance freeing all internally allocated resources. This does not include closing the underlying file if it was obtained from the client by a call to cgul_crlf_file_cxx(FILE*).

References cgul_crlf_file__delete().

Member Function Documentation

§ open_fname()

virtual void cgul_crlf_file_cxx::open_fname	(	const char *	fname,
		bool	is_block_buffered = `true`
	)

inlinevirtual

Open the file with name fname and use it when getting lines. If a file is already open, it will be closed before this method attempts to open the new file. The new file will be closed when this instance is deleted. If an error occurs, an exception is thrown.

If is_block_buffered is true, this method results in a very fast cgul_crlf_file_cxx instance, but the underlying file should be a regular file or any other file that is capable of block buffering. If the file is not capable of block buffering, is_block_buffered should be false which results in a much slower cgul_crlf_file_cxx instance, but one that should be able to read from any type of file. As a general rule, if you are reading from a regular file or are working in batch mode, is_block_buffered should be true to get the best performance. If you are reading from a line-oriented or character-oriented device like a terminal or from a named pipe across which small messages are being passed, is_block_buffered should be false.

Parameters

[in]	fname	file name
[in]	is_block_buffered	whether the file is block buffered

References cgul_crlf_file__open_fname().

§ open_file()

virtual void cgul_crlf_file_cxx::open_file	(	FILE *	f,
		bool	is_block_buffered = `true`
	)

inlinevirtual

Use the file f when getting lines. If a file is already open, it will be closed before this method attempts to open the new file. This class does not take ownership of f. Thus, the client is still responsible for calling fclose() on f. If an error occurs, an exception is thrown.

If is_block_buffered is true, this method results in a very fast cgul_crlf_file_cxx instance, but the underlying file should be a regular file or any other file that is capable of block buffering. If the file is not capable of block buffering, is_block_buffered should be false which results in a much slower cgul_crlf_file_cxx instance, but one that should be able to read from any type of file. As a general rule, if you are reading from a regular file or are working in batch mode, is_block_buffered should be true to get the best performance. If you are reading from a line-oriented or character-oriented device like a terminal or from a named pipe across which small messages are being passed, is_block_buffered should be false.

Parameters

[in]	f	file
[in]	is_block_buffered	whether the file is block buffered

References cgul_crlf_file__open_file().

§ open_memory()

virtual void cgul_crlf_file_cxx::open_memory	(	const char *	buf,
		size_t	buf_size
	)

inlinevirtual

Use the memory buffer buf when getting lines. If a data source is already open, it will be closed before this method attempts to open the new data source. This class does not take ownership of buf. Thus, the client is still responsible for freeing buf if necessary. If an error occurs, an exception is thrown.

Parameters

[in]	buf	memory buffer
[in]	buf_size	size of `buf` in bytes

References cgul_crlf_file__open_memory().

§ close()

virtual void cgul_crlf_file_cxx::close ( )

inlinevirtual

Close the file. After this method returns, open() should be called before calling any other method.

References cgul_crlf_file__close().

§ get_file_name()

virtual const char* cgul_crlf_file_cxx::get_file_name ( ) const

inlinevirtual

Return the name of the currently opened file. If a FILE* was opened instead of a file name, "FILE" will be used. If memory was opened instead of a file name, "MEMORY" will be used. The client must not attempt to free the pointer returned. This method throws an exception only if a file is not currently open.

Returns: name of the currently opened file

References cgul_crlf_file__get_fname().

§ get_file()

virtual const void* cgul_crlf_file_cxx::get_file ( ) const

inlinevirtual

Return the currently opened file. If a file name or FILE* was opened, a FILE* is returned. If memory was opened, a char* is returned. The client must not do anything that would invalidate the pointer or corrupt the associated data stream. This method throws an exception only if a file is not currently open.

Returns: currently opened file or memory

References cgul_crlf_file__get_file().

§ get_strip_utf8_bom()

virtual int cgul_crlf_file_cxx::get_strip_utf8_bom ( ) const

inlinevirtual

This method returns whether the leading UTF-8 byte-order mark (BOM) should be removed from the first line if it is present.

Returns: whether to strip a leading UTF-8 byte-order mark

References cgul_crlf_file__get_strip_utf8_bom().

§ set_strip_utf8_bom()

virtual void cgul_crlf_file_cxx::set_strip_utf8_bom ( int strip_utf8_bom )

inlinevirtual

By default, this class detects the leading UTF-8 byte-order mark (BOM) and strips it from the first line returned by get_line() if it is present. It then clears its internal flag so that BOMs internal to the text file will be returned. This is generally what you want because the leading BOM is not significant but the internal BOMs are.

You can alter the way this class handles the leading BOM by calling this method with strip_utf8_bom set to 0. This will cause the leading BOM to be returned as part of the first line. This can be useful, for example, if you just want to convert the text file and are not interested in its contents.

It should be noted that most operating systems do not save UTF-8 text files with a leading BOM because UTF-8 is a character stream and, as such, does not have byte-order problems; however, Microsoft Windows adds the BOM to its UTF-8 text files presumably to help distinguish UTF-8 text files from text files with different encodings.

Parameters

[in] strip_utf8_bom whether to strip leading UTF-8 byte-order mark

References cgul_crlf_file__set_strip_utf8_bom().

§ get_lines()

void cgul_crlf_file_cxx::get_lines	(	char ***	lines,
		unsigned long int *	line_count
	)

inline

Return the array of lines from the text file fname in *lines and the number of lines in *line_count. Each line is stored in the array as a C-style string. The client is responsible for calling free() on each line. If an error occurs, an exception is thrown.

To use this function, do something like the following:

    char** lines = NULL;
    unsigned long int line_count = 0;
    crlf.get_lines(&lines, &line_count);

Parameters

[out]	lines	ordered list of lines from the file
[out]	line_count	number of lines

Returns: list of lines from the file

References cgul_crlf_file__get_lines().

§ get_line()

virtual const char* cgul_crlf_file_cxx::get_line ( )

inlinevirtual

This method returns the next line of text from the underlying DOS, Mac, or Unix text file. The caller must not call free() on the pointer returned as it typically points into a larger block owned by this class. If EOF is reached, NULL is returned. If an error occurs, an exception is thrown.

Returns: next line of text

References cgul_crlf_file__get_line().

§ get_line_count()

virtual unsigned long cgul_crlf_file_cxx::get_line_count ( ) const

inlinevirtual

Get the line count for the last line returned by get_line. The line count is one-based. No attempt is made to prevent the return value from overflowing. So, the caller is responsible for verifying the return value.

Returns: line count

References cgul_crlf_file__get_line_count().

§ get_line_offset()

virtual unsigned long cgul_crlf_file_cxx::get_line_offset ( ) const

inlinevirtual

Get the line offset for the last line returned by cgul_crlf_file__get_line. The offset is zero-based. If the underlying file is binary and random access, you can use the return value to directly seek to the line as follows:

    f.fseek(offset, SEEK_SET);

Because the prototype for fseek() requires a long for the offset parameter, no attempt is made to prevent the return value from overflowing. So, the caller is responsible for verifying the return value.

Note that the offset returned is basically the number of bytes from the start of the file to the current line. This is not necessarily the same as the number of characters which depends on how the file is encoded.

Returns: file offset

References cgul_crlf_file__get_line_offset().

§ fseek()

virtual void cgul_crlf_file_cxx::fseek	(	unsigned long	offset,
		int	whence
	)

inlinevirtual

This method calls cgul_libc__fseek() on the underlying FILE* object and resets the underlying cgul_crlf object so that reading new lines can continue at offset which is relative to whence. If an error occurs, an exception is thrown.

You can call get_line_offset() immediately after calling get_line() to determine the offset for the beginning of the last line returned.

Parameters

[in]	offset	offset
[in]	whence	position to which offset is relative

References cgul_crlf_file__fseek().

§ rewind()

virtual void cgul_crlf_file_cxx::rewind ( )

inlinevirtual

This method calls cgul_libc__rewind() on the underlying FILE* object and resets the underlying cgul_crlf object so that reading new lines can continue at the beginning of the file. This method throws an exception if either open or open_file() has not been called. This method also throws an exception if the underlying file is not seekable.

References cgul_crlf_file__rewind().

§ get_buffer_size()

virtual unsigned long cgul_crlf_file_cxx::get_buffer_size ( ) const

inlinevirtual

This method returns the size of the buffer used to read blocks out of the underlying file.

Returns: buffer size

References cgul_crlf_file__get_buffer_size().

§ set_buffer_size()

virtual void cgul_crlf_file_cxx::set_buffer_size ( unsigned long bsize )

inlinevirtual

This method sets the size of the buffer used to read blocks out of the underlying file. By default, the buffer size is 16K which is efficient for processing large files en masse but may not be efficient when randomly accessing small parts of the same file. If an error occurs allocating the new buffer, an exception is thrown, and the original buffer will continue to be used.

Parameters

[in] bsize new buffer size

References cgul_crlf_file__set_buffer_size().

§ get_obj()

virtual cgul_crlf_file_t cgul_crlf_file_cxx::get_obj ( ) const

inlinevirtual

Get the underlying cgul_crlf_file object.

Returns: underlying object

Referenced by cgul_csv_cxx::cgul_csv_cxx(), cgul_stanza_cxx::cgul_stanza_cxx(), cgul_csv_cxx::open_crlf_file(), and cgul_stanza_cxx::open_crlf_file().

§ take_obj()

virtual cgul_crlf_file_t cgul_crlf_file_cxx::take_obj ( )

inlinevirtual

Take the underlying cgul_crlf_file object. This means the underlying object will not be deleted when the wrapper goes out of scope. Also, because you have taken the underlying object, no other methods should be called on this wrapper's instance. Lastly, after taking the underlying object, it is the caller's responsibility to delete the underlying object by calling cgul_crlf_file__delete().

Returns: underlying object

§ set_obj()

virtual void cgul_crlf_file_cxx::set_obj ( cgul_crlf_file_t rhs )

inlinevirtual

Set the new underlying object to rhs. This causes the old underlying object to be deleted which invalidates any outstanding pointers to or iterators for the old underlying object.

This instance takes ownership of rhs which means rhs will be automatically deleted when the C++ wrapper is deleted. To prevent automatic deletion of rhs, call take_obj() when the C++ wrapper is no longer needed.

Parameters

[in] rhs right-hand side

References cgul_crlf_file__delete(), and cgul_crlf_file_cxx().

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

cgul_crlf_file_cxx.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

§ cgul_crlf_file_cxx() [1/4]

§ cgul_crlf_file_cxx() [2/4]

§ cgul_crlf_file_cxx() [3/4]

§ cgul_crlf_file_cxx() [4/4]

§ ~cgul_crlf_file_cxx()

Member Function Documentation

§ open_fname()

§ open_file()

§ open_memory()

§ close()

§ get_file_name()

§ get_file()

§ get_strip_utf8_bom()

§ set_strip_utf8_bom()

§ get_lines()

§ get_line()

§ get_line_count()

§ get_line_offset()

§ fseek()

§ rewind()

§ get_buffer_size()

§ set_buffer_size()

§ get_obj()

§ take_obj()

§ set_obj()