C++ bindings for cgul_vector More...

#include <cgul_vector_cxx.h>

Collaboration diagram for cgul_vector_cxx:

Public Types
typedef cgul_vector__compare_t	compare_t

typedef cgul_vector__next_in_range_t	next_in_range_t

typedef int(*	fold_t) (void value, void data)

Public Member Functions
	cgul_vector_cxx ()

	cgul_vector_cxx (cgul_vector_t rhs)

virtual	~cgul_vector_cxx ()

virtual void	free_values ()

virtual int	is_empty () const

virtual void	assign (unsigned long int index, const void *ptr)

virtual void	insert (unsigned long int index, const void *ptr)

virtual void	erase (unsigned long int index)

virtual void	erase_unordered (unsigned long int index)

virtual void *	at (unsigned long int index)

virtual void *&	operator[] (unsigned long int index)

virtual void	push_back (const void *ptr)

virtual void *	get_back () const

virtual void *	pop_back ()

virtual void	sort (compare_t f)

virtual void	shuffle (next_in_range_t f, void *prng)

virtual void	clear ()

virtual void **	get_array () const

virtual void **	take_array ()

virtual unsigned long int	get_size () const

virtual void	trim ()

virtual size_t	get_minimum_capacity () const

virtual void	set_minimum_capacity (size_t minimum_capacity)

virtual void	swap (cgul_vector_cxx &rhs)

virtual void	foldl (fold_t f, void *data)

virtual void	foldr (fold_t f, void *data)

virtual cgul_vector_t	get_obj () const

virtual cgul_vector_t	take_obj ()

virtual void	set_obj (cgul_vector_t rhs)

Detailed Description

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

See also: cgul_vector_t

Member Typedef Documentation

§ compare_t

typedef cgul_vector__compare_t cgul_vector_cxx::compare_t

This typedef is the interface for the comparison function used by sort().

§ next_in_range_t

typedef cgul_vector__next_in_range_t cgul_vector_cxx::next_in_range_t

This type definition defines the interface to a pseudo-random number generator (PRNG) which shuffle() uses to generate pseudo-random numbers that are used to shuffle the elements of the vector. The quality of the shuffle depends entirely upon the quality of the pseudo-random numbers returned.

Functions that implement this interface will be passed the same PRNG prng that is passed into the shuffle function. The return value should be a pseudo-random integer in the half-open interval [0, range_max). If an error occurs when this function is called, the client should propagate the error via cex.

Note that this interface closely resembles the signature of the cgul_random_*__next_in_range() functions. So closely in fact, that it is usually not necessary to write a special callback to implement this function. Instead, this interface can be satisfied by casting cgul_random_*__next_in_range() to have next_in_range_t function type and pass in your PRNG object as prng.

§ fold_t

typedef int(* cgul_vector_cxx::fold_t) (void *value, void *data)

This typedef is the interface for the combining function used by the following methods:

    foldl()
    foldr()

Parameters

[in]	value	value
[in]	data	client data

Returns: whether to continue

Constructor & Destructor Documentation

§ cgul_vector_cxx() [1/2]

cgul_vector_cxx::cgul_vector_cxx ( )

inline

Create a new cgul_vector_cxx object. If memory cannot be allocated, an exception is thrown.

References cgul_vector__new().

Referenced by set_obj().

§ cgul_vector_cxx() [2/2]

cgul_vector_cxx::cgul_vector_cxx ( cgul_vector_t rhs )

inline

Create a new cgul_vector_cxx object by wrapping an existing cgul_vector object.

Parameters

[in] rhs right-hand side

§ ~cgul_vector_cxx()

virtual cgul_vector_cxx::~cgul_vector_cxx ( )

inlinevirtual

This method frees all internally allocated memory. This method does not free the elements stored in the vector. The caller allocated those elements so the caller is responsible for freeing them.

See also: free_values()

References cgul_vector__delete().

Member Function Documentation

§ free_values()

virtual void cgul_vector_cxx::free_values ( )

inlinevirtual

This method calls free() on all the values in the vector. Because this is such a common operation, it is an exception to the rule that cgul containers never free values. This method should only ever be called immediately before calling delete because it otherwise invalidates the vector.

References cgul_vector__free_values().

§ is_empty()

virtual int cgul_vector_cxx::is_empty ( ) const

inlinevirtual

Return true if the vector is empty.

Returns: whether the vector is empty

References cgul_vector__is_empty().

§ assign()

virtual void cgul_vector_cxx::assign	(	unsigned long int	index,
		const void *	ptr
	)

inlinevirtual

Assign ptr to the slot specified by index. If index is out of bounds, an exception is thrown. Indexing is zero-based.

Parameters

[in]	index	index into the vector
[in]	ptr	pointer to assign

References cgul_vector__assign().

§ insert()

virtual void cgul_vector_cxx::insert	(	unsigned long int	index,
		const void *	ptr
	)

inlinevirtual

Insert ptr at the slot specified by index shifting other pointers to the right as necessary. If index is out of bounds or if memory cannot be allocated, an exception is thrown. Indexing is zero-based.

It is legal to insert at the end of the vector such that index is one beyond the last element. Typically, you will use push_back() for inserting at the end however.

Parameters

[in]	index	index into the vector
[in]	ptr	pointer to insert

References cgul_vector__insert().

§ erase()

virtual void cgul_vector_cxx::erase ( unsigned long int index )

inlinevirtual

Erase the element at the slot specified by index shifting other pointers to the left as necessary. If index is out of bounds, an exception is thrown. Indexing is zero-based.

If it is not necessary to keep the elements in the underlying array in order, it is generally more efficient to call erase_unordered().

Parameters

[in] index index into the vector

References cgul_vector__erase().

§ erase_unordered()

virtual void cgul_vector_cxx::erase_unordered ( unsigned long int index )

inlinevirtual

Erase the element at the slot specified by index replacing it with the element at the back of the underlying array. If index is out of bounds, an exception is thrown. Indexing is zero-based.

If it is necessary to keep the elements in the underlying array in order, erase() should be used instead of this method.

Parameters

[in] index index into the vector

References cgul_vector__erase_unordered().

§ at()

virtual void* cgul_vector_cxx::at ( unsigned long int index )

inlinevirtual

This method returns the pointer at the slot specified by index. If index is out of bounds, an exception is thrown. Indexing is zero-based.

Unlike std::vector::at() this method does not return a reference to the pointer. It just returns the pointer. This is much safer because the caller does not have to worry about the reference that is returned being invalidated when the vector is resized because of an insert operation.

Furthermore, the underlying implementation of this method is written in C which cannot return references because they are not part of the language. Thus, to be consistent, this method returns the same value as the underlying C implementation.

Parameters

[in] index index into the vector

Returns: element at the slot for index

References cgul_vector__at().

Referenced by foldl(), and foldr().

§ operator[]()

virtual void*& cgul_vector_cxx::operator[] ( unsigned long int index )

inlinevirtual

This method returns a reference to the slot specified by index making it possible to assign directly to the return value. This behavior is similiar to how std::vector::operator[]() behaves.

The reference that is returned is only valid until the next insert operation so, if possible, use at() instead of this method to avoid having your pointers invalidated unexpectedly.

As with std::vector::operator[](), this method does not bounds check index. Thus, if index is out of bounds, behavior is undefined. If bounds checking is desired, use at() instead.

Indexing is zero-based.

Parameters

[in] index index into the vector

Returns: reference to the element at the slot for index

References cgul_vector__get_array().

§ push_back()

virtual void cgul_vector_cxx::push_back ( const void * ptr )

inlinevirtual

Append ptr to the end of the vector. If memory cannot be allocated, an exception will be thrown.

Parameters

[in] ptr pointer to add to the back of the vector

References cgul_vector__push_back().

§ get_back()

virtual void* cgul_vector_cxx::get_back ( ) const

inlinevirtual

Returns the pointer held in the last element of the vector without removing it from the vector. If there are no more elements, NULL is returned. If you want to remove the last element from the vector, see pop_back().

Returns: last element of the vector

References cgul_vector__get_back().

§ pop_back()

virtual void* cgul_vector_cxx::pop_back ( )

inlinevirtual

Return and remove the pointer held in the last element of the vector. If there are no more elements, NULL is returned. If you want to inspect the last element without removing it, see get_back().

Returns: last element of the vector

References cgul_vector__pop_back().

§ sort()

virtual void cgul_vector_cxx::sort ( compare_t f )

inlinevirtual

Sort the elements of the vector using the comparison function f.

Parameters

[in] f comparison function

References cgul_vector__sort().

§ shuffle()

virtual void cgul_vector_cxx::shuffle	(	next_in_range_t	f,
		void *	prng
	)

inlinevirtual

Shuffle the elements of the vector using the function f to generate the pseudo-random numbers that will be used to shuffle the vector. The PRNG prng will be passed through to the PRNG callback function f without modification. If an error occurs, an exception is thrown.

The following is an an example of how to use this method:

    cgul_vector_cxx v;
    cgul_random_lfg32_cxx prng;

    v.shuffle((cgul_vector_cxx::next_in_range_t)
                  cgul_random_lfg32__next_in_range,
              prng.get_obj());

Parameters

[in]	f	PRNG callback
[in]	prng	PRNG

References cgul_vector__shuffle().

§ clear()

virtual void cgul_vector_cxx::clear ( )

inlinevirtual

Remove all elements from the vector.

References cgul_vector__clear().

§ get_array()

virtual void** cgul_vector_cxx::get_array ( ) const

inlinevirtual

Get the internal array. The client must not free the pointer that is returned because it is still owned by the vector. The pointer returned is only valid until the next insert operation.

Returns: array of pointers

References cgul_vector__get_array().

§ take_array()

virtual void** cgul_vector_cxx::take_array ( )

inlinevirtual

Take ownership of the internal array. The client is responsible for calling free() on the pointer returned.

Just prior to taking ownership, the internal state of the vector is reset. If an error occurs when attempting to reset the vector, the vector is left unaltered, NULL is returned, and an exception is thrown.

Returns: array of pointers

References cgul_vector__take_array().

§ get_size()

virtual unsigned long int cgul_vector_cxx::get_size ( ) const

inlinevirtual

Return the size of the vector. This is a count of the total number of elements stored in the vector.

Returns: size of the vector

References cgul_vector__get_size().

Referenced by foldl(), and foldr().

§ trim()

virtual void cgul_vector_cxx::trim ( )

inlinevirtual

When you are through adding elements, you can trim any extra allocated space by calling this method.

References cgul_vector__trim().

§ get_minimum_capacity()

virtual size_t cgul_vector_cxx::get_minimum_capacity ( ) const

inlinevirtual

Get the minimum capacity. The default value is 128.

Returns: minimum capacity

References cgul_vector__get_minimum_capacity().

§ set_minimum_capacity()

virtual void cgul_vector_cxx::set_minimum_capacity ( size_t minimum_capacity )

inlinevirtual

Set the minimum capacity. The default value is 128. Decreasing the capacity will decrease the amount of space used and (typically) also decrease performance. If an error occurs, an exception is thrown.

Parameters

[in] minimum_capacity minimum capacity

References cgul_vector__set_minimum_capacity().

§ swap()

virtual void cgul_vector_cxx::swap ( cgul_vector_cxx & rhs )

inlinevirtual

Swap the underlying data for this object and rhs. For large vectors, this should be much faster than trying to do the same thing using push_back().

Parameters

[in] rhs right-hand side

References cgul_vector__swap().

§ foldl()

virtual void cgul_vector_cxx::foldl	(	fold_t	f,
		void *	data
	)

inlinevirtual

This method performs a left fold of the vector with the combining function f. f is called once for each value in the vector starting at the front of the vector and iterating forward to the end of the vector.

The first parameter passed into f is the current value. The second parameter passed into f is the client data which is where the result of the fold should be accumulated.

f must return true after each iteration in order for iteration to continue.

Parameters

[in]	f	combining function
[in]	data	client data passed to `f`

References at(), and get_size().

§ foldr()

virtual void cgul_vector_cxx::foldr	(	fold_t	f,
		void *	data
	)

inlinevirtual

This method performs a right fold of the vector with the combining function f. f is called once for each value in the vector starting at the back of the vector and iterating backward to the front of the vector.

The first parameter passed into f is the current value. The second parameter passed into f is the client data which is where the result of the fold should be accumulated.

f must return true after each iteration in order for iteration to continue.

Parameters

[in]	f	combining function
[in]	data	client data passed to `f`

References at(), and get_size().

§ get_obj()

virtual cgul_vector_t cgul_vector_cxx::get_obj ( ) const

inlinevirtual

Get the underlying cgul_vector object.

Returns: underlying object

§ take_obj()

virtual cgul_vector_t cgul_vector_cxx::take_obj ( )

inlinevirtual

Take the underlying cgul_vector 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_vector__delete().

Returns: underlying object

Referenced by cgul_heap_cxx::set_obj().

§ set_obj()

virtual void cgul_vector_cxx::set_obj ( cgul_vector_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_vector__delete(), and cgul_vector_cxx().

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

cgul_vector_cxx.h

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

§ compare_t

§ next_in_range_t

§ fold_t

Constructor & Destructor Documentation

§ cgul_vector_cxx() [1/2]

§ cgul_vector_cxx() [2/2]

§ ~cgul_vector_cxx()

Member Function Documentation

§ free_values()

§ is_empty()

§ assign()

§ insert()

§ erase()

§ erase_unordered()

§ at()

§ operator[]()

§ push_back()

§ get_back()

§ pop_back()

§ sort()

§ shuffle()

§ clear()

§ get_array()

§ take_array()

§ get_size()

§ trim()

§ get_minimum_capacity()

§ set_minimum_capacity()

§ swap()

§ foldl()

§ foldr()

§ get_obj()

§ take_obj()

§ set_obj()