C++ bindings for cgul_csv More...

#include <cgul_csv_cxx.h>

Collaboration diagram for cgul_csv_cxx:

Public Member Functions
	cgul_csv_cxx ()

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

	cgul_csv_cxx (FILE *f, bool is_block_buffered=true)

	cgul_csv_cxx (const char *buf, size_t buf_size)

	cgul_csv_cxx (cgul_crlf_file_cxx &crlf_file)

	cgul_csv_cxx (cgul_crlf_file_cxx *crlf_file)

	cgul_csv_cxx (cgul_csv_t rhs)

virtual	~cgul_csv_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	open_crlf_file (cgul_crlf_file_cxx &crlf_file)

virtual void	open_crlf_file (cgul_crlf_file_cxx *crlf_file)

virtual void	close ()

virtual char	get_separator () const

virtual void	set_separator (char separator)

virtual int	load_next ()

virtual unsigned long int	get_number_of_fields () const

virtual const char *	lookup (unsigned long int field)

virtual const char *	lookup_by_header (const char *header)

virtual char *	take_value (unsigned long int field)

virtual char *	take_value_by_header (const char *header)

virtual cgul_csv_t	get_obj () const

virtual cgul_csv_t	take_obj ()

virtual void	set_obj (cgul_csv_t rhs)

Static Public Member Functions
static void	quote (const char *bare_field, cgul_string_cxx &quoted_field)

Detailed Description

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

Constructor & Destructor Documentation

§ cgul_csv_cxx() [1/7]

cgul_csv_cxx::cgul_csv_cxx ( )

inline

This method creates a new cgul_csv_cxx instance. After calling this method, an input source should be opened before calling any other method. Use set_separator() to change the default separator which is a comma. If an error occurs, an exception is thrown.

References cgul_csv__new().

Referenced by set_obj().

§ cgul_csv_cxx() [2/7]

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

inline

Create a new cgul_csv_cxx object and call open_fname() passing it fname. This method opens fname so that input can be read from it. For regular files, is_block_buffered should be set to true; for character-oriented or line-oriented files, is_block_buffered should be set to false. Use set_separator() to change the default separator which is a comma. If an error occurs, an exception is thrown.

Parameters

[in]	fname	file name of stanza file
[in]	is_block_buffered	whether `fname` is block buffered

References cgul_csv__new_from_fname().

§ cgul_csv_cxx() [3/7]

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

inline

Create a new cgul_csv_cxx object and call open_file() passing it f. This method uses f when reading input. This class does not take ownership of f. Thus, the client is still responsible for calling fclose() on f. For regular files, is_block_buffered should be set to true; for character-oriented or line-oriented files, is_block_buffered should be set to false. Use set_separator() to change the default separator which is a comma. If an error occurs, an exception is thrown.

Parameters

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

References cgul_csv__new_from_file().

§ cgul_csv_cxx() [4/7]

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

inline

Create a new cgul_csv_cxx object and call open_memory() passing it buf and buf_size. This method uses buf when reading input. This class does not take ownership of buf. Thus, the client is still responsible for calling free() on buf if necessary. Use set_separator() to change the default separator which is a comma. The client is responsible for freeing the object by calling delete 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_csv__new_from_memory().

§ cgul_csv_cxx() [5/7]

cgul_csv_cxx::cgul_csv_cxx ( cgul_crlf_file_cxx & crlf_file )

inline

Create a new cgul_csv_cxx object and call open_crlf_file() passing it crlf_file. This makes it possible to read from any file type supported by cgul_crlf_file_cxx like memory for example. Use set_separator() to change the default separator which is a comma. If an error occurs, an exception is thrown.

The crlf_file object is used as the interface for reading lines of text from a data source. It should already be initialized before calling this method. This class does not take ownership of crlf_file so the client is still responsible for calling delete on it if necessary.

Parameters

[in] crlf_file interface used for reading lines of text

References cgul_csv__new_from_crlf_file(), and cgul_crlf_file_cxx::get_obj().

§ cgul_csv_cxx() [6/7]

cgul_csv_cxx::cgul_csv_cxx ( cgul_crlf_file_cxx * crlf_file )

inline

Create a new cgul_csv_cxx object and call open_crlf_file() passing it crlf_file. This makes it possible to read from any file type supported by cgul_crlf_file_cxx like memory for example. Use set_separator() to change the default separator which is a comma. If an error occurs, an exception is thrown.

The crlf_file object is used as the interface for reading lines of text from a data source. It should already be initialized before calling this method. This class does not take ownership of crlf_file so the client is still responsible for calling delete on it if necessary.

Parameters

[in] crlf_file interface used for reading lines of text

References cgul_csv__new_from_crlf_file(), and cgul_crlf_file_cxx::get_obj().

§ cgul_csv_cxx() [7/7]

cgul_csv_cxx::cgul_csv_cxx ( cgul_csv_t rhs )

inline

Create a new cgul_csv_cxx object by wrapping an existing cgul_csv object.

Parameters

[in] rhs right-hand side

§ ~cgul_csv_cxx()

virtual cgul_csv_cxx::~cgul_csv_cxx ( )

inlinevirtual

This method deletes objects of this class releasing all internally allocated resources.

References cgul_csv__delete().

Member Function Documentation

§ open_fname()

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

inlinevirtual

Open the file with name fname so that load_next() can be called. If an input source is already open, it will be closed before this method attempts to open the new source. The new file will be closed when this instance is deleted. For regular files, is_block_buffered should be set to true; for character-oriented or line-oriented files, is_block_buffered should be set to false. If an error occurs, an exception is thrown.

Parameters

[in]	fname	file name
[in]	is_block_buffered	whether `f` is block buffered

References cgul_csv__open_fname().

§ open_file()

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

inlinevirtual

Open f so that load_next() can be called. If an input source is already open, it will be closed before this method attempts to open the new source. This class does not take ownership of f. Thus, the client is still responsible for calling fclose() on f. For regular files, is_block_buffered should be set to true; for character-oriented or line-oriented files, is_block_buffered should be set to false. If an error occurs, an exception is thrown.

Parameters

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

References cgul_csv__open_file().

§ open_memory()

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

inlinevirtual

Open buf so that load_next() can be called. If an input source is already open, it will be closed before this method attempts to open the new source. This class does not take ownership of buf. Thus, the client is still responsible for calling free() on 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_csv__open_memory().

§ open_crlf_file() [1/2]

virtual void cgul_csv_cxx::open_crlf_file ( cgul_crlf_file_cxx & crlf_file )

inlinevirtual

Open crlf_file so that input can be read from it. This makes it possible to read from any file type supported by cgul_crlf_file_cxx like memory for example. If an input source is already open, it will be closed before this method attempts to open the new source. If an error occurs, an exception is thrown.

The crlf_file object is used as the interface for reading lines of text from a data source. It should already be initialized before calling this method. This class does not take ownership of crlf_file so the client is still responsible for calling delete on it if necessary.

Parameters

[in] crlf_file interface used for reading lines of text

References cgul_csv__open_crlf_file(), and cgul_crlf_file_cxx::get_obj().

§ open_crlf_file() [2/2]

virtual void cgul_csv_cxx::open_crlf_file ( cgul_crlf_file_cxx * crlf_file )

inlinevirtual

Open crlf_file so that input can be read from it. This makes it possible to read from any file type supported by cgul_crlf_file_cxx like memory for example. If an input source is already open, it will be closed before this method attempts to open the new source. If an error occurs, an exception is thrown.

The crlf_file object is used as the interface for reading lines of text from a data source. It should already be initialized before calling this method. This class does not take ownership of crlf_file so the client is still responsible for calling delete on it if necessary.

Parameters

[in] crlf_file interface used for reading lines of text

References cgul_csv__open_crlf_file(), and cgul_crlf_file_cxx::get_obj().

§ close()

virtual void cgul_csv_cxx::close ( )

inlinevirtual

This method closes the object. After calling this method, an input source should be opened before calling any other method.

References cgul_csv__close().

§ get_separator()

virtual char cgul_csv_cxx::get_separator ( ) const

inlinevirtual

Get the character that is currently being used as the separator. By default, the separator is a comma.

Returns: separator

References cgul_csv__get_separator().

§ set_separator()

virtual void cgul_csv_cxx::set_separator ( char separator )

inlinevirtual

Set the character that will be used as the separator. By default, the separator is a comma.

Parameters

[in] separator separator

References cgul_csv__set_separator().

§ load_next()

virtual int cgul_csv_cxx::load_next ( )

inlinevirtual

This method loads the next csv record. The client can use lookup() or take_value() to lookup the value for a particular field or get_vector() to iterate over all the fields.

The client can also use lookup_by_header() or take_value_by_header() to lookup the value associated with a particular header.

On success, 1 is returned. On EOF, 0 is returned. If an error occurs, an exception is thrown.

Returns: whether EOF was not reached

References cgul_csv__load_next().

§ get_number_of_fields()

virtual unsigned long int cgul_csv_cxx::get_number_of_fields ( ) const

inlinevirtual

This method returns the number of fields that are present in the current record. This method throws an exception only if an input source has not been opened yet.

Returns: number of fields in the current record

References cgul_csv__get_number_of_fields().

§ lookup()

virtual const char* cgul_csv_cxx::lookup ( unsigned long int field )

inlinevirtual

This method returns the value in the field for the current record. The pointer returned is owned by this class and will be invalidated the next time load_next() is called. If field is out of bounds, an exception is thrown.

If the caller is going to make a copy of the value returned, it should probably use take_value() instead which functions the same as this method except ownership is transfered to the caller thus avoiding a copy.

If you need more functionality than what is provided by this method, you can use get_vector() and iterate over each field instead.

Parameters

[in] field field

Returns: value present in the field

References cgul_csv__lookup().

§ lookup_by_header()

virtual const char* cgul_csv_cxx::lookup_by_header ( const char * header )

inlinevirtual

This method returns the value in the field associated with header for the current record. The pointer returned is owned by this class and will be invalidated the next time load_next() is called. If header does not exist, NULL is returned.

The basic idea is that many CSV files use the first row to store the headers for each column. The first time load_next() is called, it remembers the position of each header allowing this method to retrieve subsequent values by using the string for the header instead of the integer for the position.

If two columns have the same header, the value in the first column will be returned.

If the caller is going to make a copy of the value returned, it should probably use take_value_by_header() instead which functions the same as this method except ownership is transfered to the caller thus avoiding a copy.

If headers are manually added to the CSV file, remember that space is significant. So for this method to work, usually the headers in the CSV file will only be separated by commas (or tabs), not spaces.

This method throws an exception only if an input source has not been opened yet.

Parameters

[in] header header

Returns: value present in the field associated with header

References cgul_csv__lookup_by_header().

§ take_value()

virtual char* cgul_csv_cxx::take_value ( unsigned long int field )

inlinevirtual

This method returns the value in the field for the current record. Ownership of the pointer returned is transfered to the caller. Thus, the caller must arrange for free() to be called on the pointer. If field is out of bounds, an exception is thrown.

Note that once the value for a particular field has been taken, subsequent lookups on that field return NULL for the value. In order to do otherwise would require making a copy of the value which would defeat the purpose of this method.

If the caller only needs to inspect the value, it should probably use lookup() instead allowing the the object to retain ownership thereby guaranteeing that the pointer will be freed.

If you need more functionality than what is provided by this method, you can use get_vector() and iterate over each field instead.

Parameters

[in] field field

Returns: value present in the field

References cgul_csv__take_value().

§ take_value_by_header()

virtual char* cgul_csv_cxx::take_value_by_header ( const char * header )

inlinevirtual

This method returns the value in the field associated with header for the current record. Ownership of the pointer returned is transfered to the caller. Thus, the caller must arrange for free() to be called on the pointer. If header does not exist, NULL is returned.

Note that once the value for a particular header has been taken, subsequent lookups on that field return NULL for the value. In order to do otherwise would require making a copy of the value which would defeat the purpose of this method.

If the caller only needs to inspect the value, it should probably use lookup_by_header() instead allowing this instance to retain ownership thereby guaranteeing that the pointer will be freed.

If headers are manually added to the CSV file, remember that space is significant. So for this method to work, usually the headers in the CSV file will only be separated by commas (or tabs), not spaces.

This method throws an exception only if an input source has not been opened yet.

Parameters

[in] header header

Returns: value present in the field associated with header

References cgul_csv__take_value_by_header().

§ quote()

static void cgul_csv_cxx::quote	(	const char *	bare_field,
		cgul_string_cxx &	quoted_field
	)

inlinestatic

This static method is used to quote bare_field when writing a CSV file. It appends the result to the quoted_field string. This method only properly quotes bare_field. It does not append the commas (or tabs) that need to appear between fields. If an error occurs, an exception is thrown.

To write a CSV file, simply use fopen() to open a text file for writing. Use this method to quote each field before writing it to the CSV file, and do not forget to manual insert commas (or tabs) between fields as needed.

The tests/main_csv_sort.c program demonstrates the process. It reorders a CSV file by sorting the columns alphabetically based on the headers for each column.

Parameters

[in]	bare_field	bare field
[out]	quoted_field	quoted field

References cgul_csv__quote(), and cgul_string_cxx::get_obj().

§ get_obj()

virtual cgul_csv_t cgul_csv_cxx::get_obj ( ) const

inlinevirtual

Get the underlying cgul_csv object.

Returns: underlying object

§ take_obj()

virtual cgul_csv_t cgul_csv_cxx::take_obj ( )

inlinevirtual

Take the underlying cgul_csv 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_csv__delete().

Returns: underlying object

§ set_obj()

virtual void cgul_csv_cxx::set_obj ( cgul_csv_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_csv__delete(), and cgul_csv_cxx().

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

cgul_csv_cxx.h

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

§ cgul_csv_cxx() [1/7]

§ cgul_csv_cxx() [2/7]

§ cgul_csv_cxx() [3/7]

§ cgul_csv_cxx() [4/7]

§ cgul_csv_cxx() [5/7]

§ cgul_csv_cxx() [6/7]

§ cgul_csv_cxx() [7/7]

§ ~cgul_csv_cxx()

Member Function Documentation

§ open_fname()

§ open_file()

§ open_memory()

§ open_crlf_file() [1/2]

§ open_crlf_file() [2/2]

§ close()

§ get_separator()

§ set_separator()

§ load_next()

§ get_number_of_fields()

§ lookup()

§ lookup_by_header()

§ take_value()

§ take_value_by_header()

§ quote()

§ get_obj()

§ take_obj()

§ set_obj()