obvector.c File Reference

obvector Method Implementation More...

#include "../../include/obvector.h"
#include "../../include/private/obvector_private.h"

Functions
obvector *	obvector_new (uint32_t initial_capacity)
	Constructor, creates a new instance of obvector with a given initial capacity. More...
obvector *	obvector_copy (const obvector *to_copy)
	Copy Constructor, creates a new obvector that is a copy of an instance of another obvector. More...
uint32_t	obvector_length (const obvector *v)
	Number of elements encompassed within the obvector. More...
void	obvector_store_at_index (obvector *v, obj *to_store, int64_t index)
	Stores the obj at the associated index in a vector, overwriting previous obj stored at that index and resizing the vector as needed. More...
obj *	obvector_obj_at_index (const obvector *v, int64_t index)
	Accesses the Offbrand compatile class instance stored an index in an obvector. More...
void	obvector_concat (obvector *destination, obvector *to_append)
	Adds the contents of on vector to the end of another, concatenating the two. More...
uint8_t	obvector_find_obj (const obvector *v, const obj *to_find)
	Searches for an instance of any Offbrand compatible class in an obvector using a comparision function. More...
void	obvector_sort (obvector *v, int8_t order)
	Sorts an obvector from least-to-greatest or greatest-to-least using the standard compare function. More...
void	obvector_sort_with_funct (obvector *v, int8_t order, ob_compare_fptr funct)
	Sorts an obvector from least-to-greatest or greatest-to-least using a specified comparision function. More...
void	obvector_clear (obvector *v)
	Removes all objects from an obvector, leaving it empty. More...
obvector *	obvector_create_default (uint32_t initial_capacity)
	Create the default obvector. More...
void	obvector_resize (obvector *v, uint32_t index)
	Resizes a vector if the number of objects it contains is equal to its capacity by doubling the potential capacity of the vector. More...
obj **	obvector_recursive_sort (obj **to_sort, uint32_t size, int8_t order, ob_compare_fptr funct)
	Internal merge sort implementation for an obvector. More...
ob_hash_t	obvector_hash (const obj *to_hash)
	Hash function for obvector. More...
int8_t	obvector_compare (const obj *a, const obj *b)
	Compares two instances of obvector. More...
void	obvector_display (const obj *to_print)
	Display function for an instance of OBString. More...
void	obvector_destroy (obj *to_dealloc)
	Destructor for obvector. More...
uint32_t	obvector_find_valid_precursor (obj **array, uint32_t index)
	Searches an array of obj for the first encountered non-NULL pointer, returning the index where this pointer is found. More...

Detailed Description

obvector Method Implementation

Author

theck

Function Documentation

void obvector_clear

(

obvector *

v)

Removes all objects from an obvector, leaving it empty.

Parameters

v	A pointer to an instance of obvector

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

Compares two instances of obvector.

Parameters

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

Return values

OB_NOT_EQUAL	a does not equal b
OB_EQUAL_TO	a equals b

void obvector_concat	(	obvector *	destination,
		obvector *	to_append
	)

Adds the contents of on vector to the end of another, concatenating the two.

Parameters

destination	obvector that will be extended with the contents of to_append
to_append	obvector whos contents will be added to the end of destination

obvector* obvector_copy

(

const obvector *

to_copy)

Copy Constructor, creates a new obvector that is a copy of an instance of another obvector.

The new copy is a shallow copy, it references the same obj pointers rather that creating unique copies of each contained obj

Parameters

to_copy

The obvector instance to be copied

Returns

A new instance of obvector that is a shallow copy of to_copy

obvector* obvector_create_default

(

uint32_t

initial_capacity)

Create the default obvector.

Parameters

initial_capacity

Capacity of the vector to be created

Returns

A new, partially initialized instance of obvector

void obvector_destroy

(

obj *

to_dealloc)

Destructor for obvector.

Parameters

to_dealloc

An obj pointer to an instance of obvector with reference count of 0

Warning

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

void obvector_display

(

const obj *

to_print)

Display function for an instance of OBString.

Parameters

to_print

A non-NULL obj pointer to type OBString

uint8_t obvector_find_obj	(	const obvector *	v,
		const obj *	to_find
	)

Searches for an instance of any Offbrand compatible class in an obvector using a comparision function.

Parameters

v	A pointer to an instance of obvector
to_find	A pointer to an instance of any Offbrand compatible class

Return values

0	to_find was not found in the obvector
1	to_find exists in the obvector

Warning

Specify NULL as the comparision function if the given obvector is known to contain instances of may different classes else the function will likely cause the program to be aborted

uint32_t obvector_find_valid_precursor	(	obj **	array,
		uint32_t	index
	)

Searches an array of obj for the first encountered non-NULL pointer, returning the index where this pointer is found.

Parameters

array	Array of pointers to instances of Offbrand compatible classes
index	Index from which to begin searching

Return values

<UINT32_MAX	Index where a non-NULL pointer was found
UINT32_MAX	No non-NULL pointer was found

ob_hash_t obvector_hash

(

const obj *

to_hash)

Hash function for obvector.

Parameters

to_hash

An obj pointer to an instance of obvector

Returns

Key value (hash) for the given obj pointer to an obvector

uint32_t obvector_length

(

const obvector *

v)

Number of elements encompassed within the obvector.

Parameters

v	A pointer to an instance of obvector

Returns

An integer corresponding to the length required to span all elements contained within the vector (including all NULL elements added by the user)

obvector* obvector_new

(

uint32_t

initial_capacity)

Constructor, creates a new instance of obvector with a given initial capacity.

Parameters

initial_capacity

Integer size for the vector capacity

Returns

Pointer to the newly created vector

obj* obvector_obj_at_index	(	const obvector *	v,
		int64_t	index
	)

Accesses the Offbrand compatile class instance stored an index in an obvector.

Parameters

v	A pointer to an instance of obvector
index	An integer index that may be positive to index from the beginning of the vector or negative to index from the end of the vector (where index = -x associates to element at [size of v] - x)

Return values

NULL	When index is out of range of obvector
obj*	When index is in obvector range

Warning

Do not call release on returned object unless the calling code already had a reference to the object before calling objAtVectorIndex that it wishes to relenquish

Positive indexing can occur past vector length, negative indexing is limited to the range [-1, -(length of v)]

obj** obvector_recursive_sort	(	obj **	to_sort,
		uint32_t	size,
		int8_t	order,
		ob_compare_fptr	funct
	)

Internal merge sort implementation for an obvector.

Parameters

to_sort	Primitive array of objects to be sorted
size	Size of to_sort
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

The sorted primitive array of objects (a new primitive array, not to_sort)

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 obvector_resize	(	obvector *	v,
		uint32_t	index
	)

Resizes a vector if the number of objects it contains is equal to its capacity by doubling the potential capacity of the vector.

Parameters

v	Pointer to an instance of obvector
index	Index that vector must be resized to contain

void obvector_sort	(	obvector *	v,
		int8_t	order
	)

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

Parameters

v	A pointer to an instance of obvector
order	Accepts OB_LEAST_TO_GREATEST or OB_GREATEST_TO_LEAST as valid sorting orders

Warning

If called on an obvector containing instances of multiple Offbrand classes the call will likely not sort members properly but will still likely reorder internal contents

Sorting may appear to shrink vector as NULL values interspersed with valid objects will be consolidated and removed

void obvector_sort_with_funct	(	obvector *	v,
		int8_t	order,
		ob_compare_fptr	funct
	)

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

Parameters

v	A pointer to an instance of obvector
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

Warning

Sorting may appear to shrink vector as NULL values interspersed with valid objects will be consolidated and removed

void obvector_store_at_index	(	obvector *	v,
		obj *	to_add,
		int64_t	index
	)

Stores the obj at the associated index in a vector, overwriting previous obj stored at that index and resizing the vector as needed.

Parameters

v	A pointer to an instance of obvector
to_add	A pointer to any Offbrand compativle class instance
index	An integer index that may be positive to index from the beginning of the vector or negative to index from the end of the vector (where index = -x associates to element at [length of v] - x)

Storing NULL at an index in the vector is equivalent to removing that object from the vector (if it only is found in that single vector positition). Storing NULL beyond vector length has no effect on vector length

Warning

Positive indexing can occur past vector length, negative indexing is limited to the range [-1, -(length of v)]