obdeque Method Implementation More...

#include "../../include/obdeque.h"
#include "../../include/private/obdeque_private.h"

Functions
obdeque *	obdeque_new (void)
	Constructor, creates a new instance of obdeque with no contents. More...

obdeque *	obdeque_copy (const obdeque *to_copy)
	Copy Constructor, creates a new obdeque that contains the same contents as an obdeque instance. More...

uint8_t	obdeque_is_empty (const obdeque *deque)
	The emptyness state of an obdeque, either empty or non-empty. More...

uint64_t	obdeque_length (const obdeque *deque)
	Number of elements stored within an obdeque. More...

obdeque_iterator *	obdeque_head_iterator (const obdeque *deque)
	Constructor for an iterator for an obdeque that is directed at the head of the obdeque. More...

obdeque_iterator *	obdeque_tail_iterator (const obdeque *deque)
	Constructor for an iterator for an obdeque that is directed at the tail of the obdeque. More...

obdeque_iterator *	obdeque_copy_iterator (const obdeque_iterator *it)
	Copy Constructor for an obdeque_iterator from another obdeque_iterator. More...

uint8_t	obdeque_iterate_next (const obdeque deque, obdeque_iterator it)
	Advance an obdeque_iterator bound to an obdeque to the next element within the obdeque closer to the tail of the obdeque. More...

uint8_t	obdeque_iterate_prev (const obdeque deque, obdeque_iterator it)
	Advance an obdeque_iterator bound to an obdeque to the previous element within the obdeque closer to the obdeque head. More...

void	obdeque_add_at_head (obdeque deque, obj to_add)
	Add an obj to the head of an obdeque. More...

void	obdeque_add_at_tail (obdeque deque, obj to_add)
	Add an obj to the tail of an obdeque. More...

void	obdeque_add_at_iterator (obdeque deque, obdeque_iterator it, obj *to_add)
	Add an obj to an obdeque at position before the element specified by an obdeque_iterator. More...

obdeque *	obdeque_join (const obdeque d1, const obdeque d2)
	creates a new obdeque that contains the ordered contents of two obdeques More...

uint8_t	obdeque_find_obj (const obdeque deque, const obj to_find)
	Searches an obdeque for an obj. More...

void	obdeque_sort (obdeque *deque, int8_t order)
	Sorts an obdeque from least-to-greatest or greatest-to-least using the standard compare function. More...

void	obdeque_sort_with_funct (obdeque *deque, int8_t order, ob_compare_fptr funct)
	Sorts an obdeque from least-to-greatest or greatest-to-least using a specified comparision function. More...

obj *	obdeque_obj_at_head (const obdeque *deque)
	Peek at the obj stored at the head of an obdeque. More...

obj *	obdeque_obj_at_tail (const obdeque *deque)
	Peek at the obj stored at the tail of an obdeque. More...

obj *	obdeque_obj_at_iterator (const obdeque deque, const obdeque_iterator it)
	Peek at the obj stored within a obdeque stored at the position denoted by an obdeque_iterator bound to that obdeque. More...

void	obdeque_remove_head (obdeque *deque)
	Remove the obj stored at the head of an obdeque, shrinking the obdeque by one element. More...

void	obdeque_remove_tail (obdeque *deque)
	Remove the obj stored at the tail of an obdeque, shrinking the obdeque by one element. More...

void	obdeque_remove_at_iterator (obdeque deque, obdeque_iterator it)
	Remove the obj stored within an obdeque at the position denoted by the obdeque_iterator bound to that obdeque, shrinking the obdeque by one element. More...

void	obdeque_clear (obdeque *deque)
	removes all obj's from the Deque, leaving the Deque empty More...

obdeque_node *	obdeque_new_node (obj *to_store)
	Constructor, creates a new obdeque_node containing an obj. More...

void	obdeque_destroy_node (obj *to_dealloc)
	Destructor for obdeque_node. More...

obdeque_iterator *	obdeque_new_iterator (const obdeque deque, obdeque_node node)
	Constructor, creates an instance of obdeque_iterator bound to an obdeque and an obdeque_node within that deque. More...

void	obdeque_destroy_iterator (obj *to_dealloc)
	Destructor for obdeque_iterator. More...

obdeque *	obdeque_create_default (void)
	Default constructor for obdeque. More...

obdeque	obdeque_recursive_sort (obdeque deque, int8_t order, ob_compare_fptr funct)
	Internal merge sort implementation for an obdeque. More...

ob_hash_t	obdeque_hash (const obj *to_hash)
	Hash function for obdeque. More...

int8_t	obdeque_compare (const obj a, const obj b)
	Compares two instances of obdeque. More...

void	obdeque_display (const obj *to_print)
	Displays information about an obdeque to stderr. More...

void	obdeque_destroy (obj *to_dealloc)
	Destructor for obdeque. More...

Detailed Description

obdeque Method Implementation

Author: theck

Function Documentation

void obdeque_add_at_head	(	obdeque *	deque,
		obj *	to_add
	)

Add an obj to the head of an obdeque.

Parameters

deque	An instance of obdeque
to_add	Any instance of an Offbrand compatible class to add to deque

void obdeque_add_at_iterator	(	obdeque *	deque,
		obdeque_iterator *	it,
		obj *	to_add
	)

Add an obj to an obdeque at position before the element specified by an obdeque_iterator.

Parameters

deque	An instance of obdeque
it	An instance of obdeque_iterator bound to deque
to_add	Any instance of an Offbrand compatible class to add to deque

void obdeque_add_at_tail	(	obdeque *	deque,
		obj *	to_add
	)

Add an obj to the tail of an obdeque.

Parameters

deque	An instance of obdeque
to_add	Any instance of an Offbrand compatible class to add to deque

void obdeque_clear ( obdeque * deque)

removes all obj's from the Deque, leaving the Deque empty

Parameters

deque An instance of obdeque

int8_t obdeque_compare	(	const obj *	a,
		const obj *	b
	)

Compares two instances of obdeque.

Parameters

a	A non-NULL obj pointer to type obdeque
b	A non-NULL obj pointer to type obdeque

Return values

OB_LESS_THAN	obj a is less than b
OB_GREATER_THAN	obj a is equivalent to b
OB_EQUAL_TO	obj a is greater than b

obdeque* obdeque_copy ( const obdeque * to_copy)

Copy Constructor, creates a new obdeque that contains the same contents as an obdeque instance.

Parameters

to_copy An instance of obdeque to copy

Returns: Pointer to a newly created and initialized instance of obdeque

obdeque_iterator* obdeque_copy_iterator ( const obdeque_iterator * it)

Copy Constructor for an obdeque_iterator from another obdeque_iterator.

Parameters

it	An instance of obdeque_iterator

Returns: An obdeque_iterator instance bound to the same obdeque as the provided obdeque_iterator and directect at the same location within that obdeque

Warning: The obdeque_iterator created by this method MUST be released by the user, else a memory leak will occur

obdeque* obdeque_create_default ( void )

Default constructor for obdeque.

Returns: An instance of class obdeque

Warning: All public constructors should call this constructor and initialize individual members as needed, so that all base data is initialized properly

void obdeque_destroy ( obj * to_dealloc)

Destructor for obdeque.

Parameters

to_dealloc An obj pointer to an instance of obdeque with reference count 0

Warning: Do not call manually, release will call automatically when the instances reference count drops to 0!

void obdeque_destroy_iterator ( obj * to_dealloc)

Destructor for obdeque_iterator.

Parameters

to_dealloc An obj pointer to an instance of obdeque_iterator with reference count 0

Warning: Do not call manually, release will call automatically when the instances reference count drops to 0!

void obdeque_destroy_node ( obj * to_dealloc)

Destructor for obdeque_node.

Parameters

to_dealloc An obj pointer to an instance of obdeque_node with reference count 0

Warning: Do not call manually, release will call automatically when the instances reference count drops to 0!

void obdeque_display ( const obj * to_print)

Displays information about an obdeque to stderr.

Parameters

to_print A non-NULL obj pointer to type obdeque

uint8_t obdeque_find_obj	(	const obdeque *	deque,
		const obj *	to_find
	)

Searches an obdeque for an obj.

Parameters

deque	An instance of obdeque
to_find	An instance of any Offbrand compatible class to search for within the deque

Return values

0	to_find not found within deque
1	to_find found within the deque

ob_hash_t obdeque_hash ( const obj * to_hash)

Hash function for obdeque.

Parameters

to_hash An obj pointer to an instance of obdeque

Returns: Key value (hash) for the given obj pointer to a obdeque

obdeque_iterator* obdeque_head_iterator ( const obdeque * deque)

Constructor for an iterator for an obdeque that is directed at the head of the obdeque.

Parameters

deque An instance of obdeque

Return values

NULL	The obdeque provided is empty and cannot be iterated
non-NULL	An obdeque_iterator instance bound to the provided instance of obdeque and directed at the head of that obdeque

Warning: The obdeque_iterator created by this method MUST be released by the user, else a memory leak will occur

uint8_t obdeque_is_empty ( const obdeque * deque)

The emptyness state of an obdeque, either empty or non-empty.

Parameters

deque An instance of obdeque

Return values

0	The deque is empty
non-zero	The deque contains elements

uint8_t obdeque_iterate_next	(	const obdeque *	deque,
		obdeque_iterator *	it
	)

Advance an obdeque_iterator bound to an obdeque to the next element within the obdeque closer to the tail of the obdeque.

Parameters

deque	An instance of obdeque
it	An intstance of obdeque_iterator that is bound to deque

Return values

non-zero	Advancement was successful.
0	Advancement failed because no more elements exist in the obdeque closer to the deque tail

uint8_t obdeque_iterate_prev	(	const obdeque *	deque,
		obdeque_iterator *	it
	)

Advance an obdeque_iterator bound to an obdeque to the previous element within the obdeque closer to the obdeque head.

Parameters

deque	An instance of obdeque
it	An intstance of obdeque_iterator that is bound to deque

Return values

non-zero	Advancement was successful.
0	Advancement failed because no more elements exist in the obdeque closer to the deque head

obdeque* obdeque_join	(	const obdeque *	d1,
		const obdeque *	d2
	)

creates a new obdeque that contains the ordered contents of two obdeques

Parameters

d1	First obdeque to copy into the resultant obdeque
d2	Second obdeque to copy onto the end of the resultant obdeque

Returns: An obdeque instance that contains the contents of d1 followed by d2

uint64_t obdeque_length ( const obdeque * deque)

Number of elements stored within an obdeque.

Parameters

deque An instance of obdeque

Returns: An integer corresponding the the number of objects in the deque

obdeque* obdeque_new ( void )

Constructor, creates a new instance of obdeque with no contents.

Returns: Pointer to a newly created and initialized instance of obdeque

obdeque_iterator* obdeque_new_iterator	(	const obdeque *	deque,
		obdeque_node *	node
	)

Constructor, creates an instance of obdeque_iterator bound to an obdeque and an obdeque_node within that deque.

Parameters

deque	An instance of obdeque
node	An instance of obdeque_node contained within deque

Returns: An instance of obdeque_iterator

obdeque_node* obdeque_new_node ( obj * to_store)

Constructor, creates a new obdeque_node containing an obj.

Parameters

to_store A non-NULL instance of any Offbrand compatible class

Returns: A new instance of obdeque node storing to_store and with NULL references to next and prev nodes

obj* obdeque_obj_at_head ( const obdeque * deque)

Peek at the obj stored at the head of an obdeque.

Parameters

deque An instance of obdeque

Return values

NULL	No elements exist within deque
non-NULL	The element stored at the head of deque

obj* obdeque_obj_at_iterator	(	const obdeque *	deque,
		const obdeque_iterator *	it
	)

Peek at the obj stored within a obdeque stored at the position denoted by an obdeque_iterator bound to that obdeque.

Parameters

deque	An instance of obdeque
it	An instance of obdeque_iterator bound to deque

Return values

NULL	No elements exist within deque
non-NULL	The element stored at the tail of deque

obj* obdeque_obj_at_tail ( const obdeque * deque)

Peek at the obj stored at the tail of an obdeque.

Parameters

deque An instance of obdeque

Return values

NULL	No elements exist within deque
non-NULL	The element stored at the tail of deque

obdeque obdeque_recursive_sort	(	obdeque	deque,
		int8_t	order,
		ob_compare_fptr	funct
	)

Internal merge sort implementation for an obdeque.

Parameters

deque	Static obdeque to be sorted
order	Accepts OB_LEAST_TO_GREATEST or OB_GREATEST_TO_LEAST as valid sorting orders
funct	A compare_fptr to a function that returns an int8_t when given two obj * arguments

Returns: A sorted static deque

Warning: There is little to no parameter checking in this function, all sorting should use the publicly accessable function which calls this method internally.

void obdeque_remove_at_iterator	(	obdeque *	deque,
		obdeque_iterator *	it
	)

Remove the obj stored within an obdeque at the position denoted by the obdeque_iterator bound to that obdeque, shrinking the obdeque by one element.

Parameters

deque	An instance of obdeque
it	An instance of obdeque_iterator bound to deque

The provided obdeque_iterator will be advanced toward the obdeque tail, unless removing the tail then it will be advanced to the element before the tail (NULL if no more elements exist)

void obdeque_remove_head ( obdeque * deque)

Remove the obj stored at the head of an obdeque, shrinking the obdeque by one element.

Parameters

deque An instance of obdeque

void obdeque_remove_tail ( obdeque * deque)

Remove the obj stored at the tail of an obdeque, shrinking the obdeque by one element.

Parameters

deque An instance of obdeque

void obdeque_sort	(	obdeque *	deque,
		int8_t	order
	)

Sorts an obdeque from least-to-greatest or greatest-to-least using the standard compare function.

Parameters

deque	An instance of obdeque
order	Accepts OB_LEAST_TO_GREATEST or OB_GREATEST_TO_LEAST as valid sorting orders

Warning: If called on an obdeque containing instances of multiple Offbrand compatible classes the call will likely not sort members in any expected order, but will reorder components

void obdeque_sort_with_funct	(	obdeque *	deque,
		int8_t	order,
		ob_compare_fptr	funct
	)

Sorts an obdeque from least-to-greatest or greatest-to-least using a specified comparision function.

Parameters

deque	An instance of obdeque
order	Accepts OB_LEAST_TO_GREATEST or OB_GREATEST_TO_LEAST as valid sorting orders
funct	A pointer to a comparision function that returns a int8_t when given two obj * arguments

obdeque_iterator* obdeque_tail_iterator ( const obdeque * deque)

Constructor for an iterator for an obdeque that is directed at the tail of the obdeque.

Parameters

deque An instance of obdeque

Return values

NULL	The obdeque provided is empty and cannot be iterated
non-NULL	An obdeque_iterator instance bound to the provided instance and directed at the tail of that obdeque

Warning: The obdeque_iterator created by this method MUST be released by the user, else a memory leak will occur

Functions

Detailed Description

Function Documentation