offbrand
A collection of generic, reference counted datastructures in C for C
 All Classes Files Functions Variables Typedefs Macros Groups
Typedefs | Functions
obvector.h File Reference

obvector Public Interface More...

#include "offbrand.h"

Go to the source code of this file.

Typedefs

typedef struct obvector_struct obvector
 

Functions

obvectorobvector_new (uint32_t initial_capacity)
 Constructor, creates a new instance of obvector with a given initial capacity. More...
 
obvectorobvector_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_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. More...
 
objobvector_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...
 

Detailed Description

obvector Public Interface

Author
theck

Typedef Documentation

typedef struct obvector_struct obvector

Class type declaration

Function Documentation

void obvector_clear ( obvector v)

Removes all objects from an obvector, leaving it empty.

Parameters
vA pointer to an instance of obvector
void obvector_concat ( obvector destination,
obvector to_append 
)

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

Parameters
destinationobvector that will be extended with the contents of to_append
to_appendobvector 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_copyThe obvector instance to be copied
Returns
A new instance of obvector that is a shallow copy of to_copy
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
vA pointer to an instance of obvector
to_findA pointer to an instance of any Offbrand compatible class
Return values
0to_find was not found in the obvector
1to_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_length ( const obvector v)

Number of elements encompassed within the obvector.

Parameters
vA 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_capacityInteger 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
vA pointer to an instance of obvector
indexAn 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
NULLWhen 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)]
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
vA pointer to an instance of obvector
orderAccepts 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
vA pointer to an instance of obvector
orderAccepts OB_LEAST_TO_GREATEST or OB_GREATEST_TO_LEAST as valid sorting orders
functA 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
vA pointer to an instance of obvector
to_addA pointer to any Offbrand compativle class instance
indexAn 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)]