Collaboration diagram for The Pointer-Vector component interface:

Files
file	ptr_vector.c
file	ptr_vector.h
Typedefs
typedef ptrdiff_t	locator_t
typedef struct ptr_vector *	ptr_vector_h
typedef struct ptr_vector const *	ptr_vector_const_h
typedef void(*	dtor_t )(void *)
typedef void (	cloner_t )(void const *)
typedef int(*	comparator_t )(void const obj, void const key, locator_t keylen)
Functions
ptr_vector_h	ptr_vector_new (dtor_t dtor, cloner_t cloner)
void	ptr_vector_dispose (ptr_vector_h pv)
void	ptr_vector_drop (ptr_vector_h pv)
ptr_vector_h	ptr_vector_copy (ptr_vector_const_h src)
void	ptr_vector_swap (ptr_vector_h lhs, ptr_vector_h rhs)
void	ptr_vector_assign (ptr_vector_h dest, ptr_vector_const_h src)
void	ptr_vector_insert (ptr_vector_h pv, size_t pos, void const *ptr)
bool	ptr_vector_delete (ptr_vector_h pv, size_t pos)
bool	ptr_vector_equal (ptr_vector_const_h lhs, ptr_vector_const_h rhs, comparator_t compare)
dtor_t	ptr_vector_dtor (ptr_vector_const_h pv)
cloner_t	ptr_vector_cloner (ptr_vector_const_h pv)
void	ptr_vector_append (ptr_vector_h pv, void *ptr)
size_t	ptr_vector_count (ptr_vector_const_h pv)
void **	ptr_vector_begin (ptr_vector_h pv)
void const **	ptr_vector_begin_const (ptr_vector_const_h pv)
void **	ptr_vector_end (ptr_vector_h pv)
void const **	ptr_vector_end_const (ptr_vector_const_h pv)
void *	ptr_vector_at (ptr_vector_h pv, size_t pos)
void const *	ptr_vector_at_const (ptr_vector_const_h pv, size_t pos)
locator_t	ptr_vector_search (ptr_vector_const_h pv, void const *key, locator_t keylen, comparator_t compare, bool ordered)

Detailed Description

interface.

Typedef Documentation

typedef void*(* cloner_t)(void const *)

Abstact type of function for cloning heap objects

Definition at line 66 of file ptr_vector.h.

typedef int(* comparator_t)(void const *obj, void const *key, locator_t keylen)

Abstract type of function for comparing an object with a key value.

Parameters:

obj	Address of the object to be compared with the key.
key	Address of the key value.
keylen	If positive, this is the length of the key. If 0 or negative then the function shall assume that key is in fact the address of a second object of the same type as obj and shall compare thse two objects by key.

Returns:: < 0 of obj compares less than key; 0 if obj compares equal with key; > 0 if obj compares greater than key.

Definition at line 78 of file ptr_vector.h.

typedef void(* dtor_t)(void *)

Abstact type of function for disposing of heap objects

Definition at line 63 of file ptr_vector.h.

typedef ptrdiff_t locator_t

Abstract signed type of a memory location or array offset

Definition at line 54 of file ptr_vector.h.

typedef struct ptr_vector const* ptr_vector_const_h

Abstract type of const pointer-vector object

Definition at line 60 of file ptr_vector.h.

typedef struct ptr_vector* ptr_vector_h

Abstract type of pointer-vector object

Definition at line 57 of file ptr_vector.h.

Function Documentation

void ptr_vector_append	(	ptr_vector_h	pv,
		void *	ptr
	)

Append a pointer to a pointer-vector.

Parameters:

pv	The pointer-vector to which the pointer is to be appended.
ptr	The pointer to be appended. The vector is extended if necessary to append `ptr`.

Note:: Pointers that the caller is holding to pointers within the vector must be assumed invalidated after an insertion.

Definition at line 273 of file ptr_vector.c.

References ptr_vector_insert().

Referenced by directive_text_lookup(), link_in(), parse_args_file(), ptr_set_insert(), ptr_vector_copy_init(), and symbol_resolve().

Here is the call graph for this function:

void ptr_vector_assign	(	ptr_vector_h	dest,
		ptr_vector_const_h	src
	)

Assign one pointer vector to another.

Parameters:

dest	The pointer vector to be assigned
src	The pointrer vector to be assigned to dest.

Definition at line 190 of file ptr_vector.c.

References ptr_vector_copy(), ptr_vector_dispose(), and ptr_vector_swap().

Here is the call graph for this function:

void * ptr_vector_at	(	ptr_vector_h	pv,
		size_t	pos
	)

Get a pointer to the element at a given position in a pointer-vector.

Parameters:

pv	The pointer-vector from which an element is wanted.
pos	The position in the vector from which the element is wanted.

Returns:: The pointer at position pos in pv, unless pos is out of range; NULL if pos is out of range.

Definition at line 309 of file ptr_vector.c.

References ptr_vector::ptrs.

Referenced by directive_text_add(), directive_text_lookup(), file_tree_child(), ptr_set_insert(), ptr_set_search(), and ptr_vector_at_const().

void const * ptr_vector_at_const	(	ptr_vector_const_h	pv,
		size_t	pos
	)

Get a const pointer to the element at a given position in a pointer-vector.

Parameters:

pv	The pointer-vector from which an element is wanted.
pos	The position in the vector from which the element is wanted.

Returns:: The pointer at position pos in pv, unless pos is out of range; NULL if pos is out of range.

Definition at line 315 of file ptr_vector.c.

References ptr_vector_at().

Here is the call graph for this function:

void ** ptr_vector_begin ( ptr_vector_h pv )

Get a pointer to the start of a pointer-vector.

Parameters:

pv	The pointer-vector whose start is wanted.

Returns:: Pointer to the first element of pv, if pv is non-empty; otherwise NULL

Definition at line 285 of file ptr_vector.c.

References ptr_vector::ptrs.

Referenced by file_tree_count(), file_tree_traverse(), parse_args_file(), ptr_set_begin(), ptr_vector_begin_const(), seek(), seek_child(), and traverse().

void const ** ptr_vector_begin_const ( ptr_vector_const_h pv )

Get a const pointer to the start of a pointer-vector.

Parameters:

pv	The pointer-vector whose start is wanted.

Returns:: Pointer to the first element of pv, if pv is non-empty; otherwise NULL

Definition at line 291 of file ptr_vector.c.

References ptr_vector_begin().

Referenced by file_tree_copy_init(), file_tree_equal(), ptr_vector_copy_init(), ptr_vector_equal(), ptr_vector_search(), and symbol_resolve().

Here is the call graph for this function:

cloner_t ptr_vector_cloner ( ptr_vector_const_h pv )

Get the cloning function from a pointer vector.

Definition at line 265 of file ptr_vector.c.

Referenced by ptr_set_cloner().

ptr_vector_h ptr_vector_copy ( ptr_vector_const_h src )

Construct a copy of a ptr_vector.

Parameters:

src	The ptr_vector to copy

Returns:: A copy of src.

Definition at line 167 of file ptr_vector.c.

References ptr_vector_copy_init(), and zallocate().

Referenced by ptr_set_copy_init(), and ptr_vector_assign().

Here is the call graph for this function:

size_t ptr_vector_count ( ptr_vector_const_h pv )

Get the number of elements in a pointer-vector.

Parameters:

pv	The pointer-vector to count.

Returns:: The number of elements in pv.

Definition at line 279 of file ptr_vector.c.

Referenced by directive_text_lookup(), file_tree_child(), file_tree_equal(), file_tree_is_empty(), parse_args_file(), ptr_set_count(), ptr_set_insert(), and ptr_vector_equal().

bool ptr_vector_delete	(	ptr_vector_h	pv,
		size_t	pos
	)

Delete a pointer from a pointer-vector.

Parameters:

pv	The pointer-vector to be modified.
pos	The position in the vector at which to remove an element.

Returns:: True if an element is deleted, else false.

If pos lies within pv then the element at pos is removed by moving subsequent elements down 1 position and decrementing the vector's size. Otherwise nothing is done.

Definition at line 219 of file ptr_vector.c.

References ptr_vector::count, and ptr_vector::ptrs.

Referenced by ptr_set_delete().

void ptr_vector_dispose ( ptr_vector_h pv )

Dispose of a pointer-vector object

Parameters:

pv	The pointer-vector to be destroyed.

The vector's dtor member is called on each element and then remaining memory controlled by the pointer-vector is released.

The function is a no-op if pv is NULL.

Definition at line 150 of file ptr_vector.c.

References ptr_vector_finis().

Referenced by args_finis(), file_tree_finis(), ptr_set_dispose(), and ptr_vector_assign().

Here is the call graph for this function:

void ptr_vector_drop ( ptr_vector_h pv )

Dispose of a pointer-vector object without destroying its elements.

Parameters:

pv	The pointer-vector to be destroyed.

A pointer-vector formed from members of a prior pointer-vector should be destroyed with ptr_vector_drop() rather than ptr_vector_dispose(), leaving the elements to be destroyed with the prior pointer-vector.

The function is a no-op if pv is NULL.

Definition at line 159 of file ptr_vector.c.

Referenced by symbol_resolve().

dtor_t ptr_vector_dtor ( ptr_vector_const_h pv )

Get the destructor function from a pointer vector.

Definition at line 258 of file ptr_vector.c.

Referenced by ptr_set_dtor().

void ** ptr_vector_end ( ptr_vector_h pv )

Get a pointer to the end of a pointer-vector.

Parameters:

pv	The pointer-vector whose end is wanted.

Returns:: Pointer just past the last element of pv, if pv is non-empty; otherwise NULL

Definition at line 297 of file ptr_vector.c.

References ptr_vector::count, and ptr_vector::ptrs.

Referenced by file_tree_count(), file_tree_traverse(), ptr_set_end(), ptr_vector_end_const(), seek(), seek_child(), and traverse().

void const ** ptr_vector_end_const ( ptr_vector_const_h pv )

Get a const pointer to the end of a pointer-vector.

Parameters:

pv	The pointer-vector whose end is wanted.

Returns:: Pointer just past the last element of pv, if pv is non-empty; otherwise NULL

Definition at line 303 of file ptr_vector.c.

References ptr_vector_end().

Referenced by file_tree_copy_init(), file_tree_equal(), ptr_vector_copy_init(), ptr_vector_equal(), ptr_vector_search(), and symbol_resolve().

Here is the call graph for this function:

bool ptr_vector_equal	(	ptr_vector_const_h	lhs,
		ptr_vector_const_h	rhs,
		comparator_t	compare
	)

Say whether two pointer vectors compare equal.

Parameters:

lhs	The first pointer vector to compare.
rhs	The second pointer vector to compare.
compare	The comparator function to be used.

Returns:

True if both vectors are NULL or if they have:

the same destructor and cloner members
the same number of elements that are pairwise equal as evaluated by compare.

Definition at line 232 of file ptr_vector.c.

References ptr_vector_begin_const(), ptr_vector_count(), and ptr_vector_end_const().

Referenced by ptr_set_equal().

Here is the call graph for this function:

void ptr_vector_insert	(	ptr_vector_h	pv,
		size_t	pos,
		void const *	ptr
	)

Insert a pointer into a pointer-vector.

Parameters:

pv	The pointer-vector in which a pointer is to be inserted.
pos	The position in the vector at which to insert.
ptr	The pointer to be inserted. If `pos` is beyond the end of `pv` then `ptr` is appended to `pv` The vector is extended if necessary to insert or append `ptr`.

Note:: Pointers that the caller is holding to pointers within the vector must be assumed invalidated after an insertion.; Insertion is inefficient even when it does not provoke an extension of the vector, because it requires all elements from pos onward to be moved up 1 position.

Definition at line 200 of file ptr_vector.c.

References ptr_vector::cap, ptr_vector::count, ptr_vector::ptrs, reallocate(), and ptr_vector::tranch.

Referenced by ptr_set_insert(), and ptr_vector_append().

Here is the call graph for this function:

ptr_vector_h ptr_vector_new	(	dtor_t	dtor,
		cloner_t	cloner
	)

Create new pointer-vector object

Parameters:

dtor	The destructor to be applied to vector elements when the vector is destroyed, or NULL. If NULL then free() is assumed.
cloner	The cloning function for cloning elements of this vector, or NULL. If NULL then clone(ptr,0) is assumed.

Returns:: A new ptr_vector object

Definition at line 142 of file ptr_vector.c.

References ptr_vector_init(), and zallocate().

Referenced by args_init(), deepen(), link_in(), new_dir_node(), ptr_set_init(), and symbol_resolve().

Here is the call graph for this function:

locator_t ptr_vector_search	(	ptr_vector_const_h	pv,
		void const *	key,
		locator_t	keylen,
		comparator_t	compare,
		bool	ordered
	)

Search a pointer vector for an element matching a key value

Parameters:

pv	The pointer vector to search
key	The address of the key value.
keylen	The Length of the key value or 0.
compare	The comparator function to use for matching.
ordered	If true then elements of the pv are assumed to be ordered ascending by compare. In this case the search can be accelerated.

Returns:: If key is matched then the index of the matching element is returned, otherwise a negative value L. If ordered is true then ~L is index at which at element matching key should be inserted to preserve order.

Definition at line 321 of file ptr_vector.c.

References ptr_vector_begin_const(), and ptr_vector_end_const().

Referenced by ptr_set_insert(), and ptr_set_search().

Here is the call graph for this function:

void ptr_vector_swap	(	ptr_vector_h	lhs,
		ptr_vector_h	rhs
	)

Exchange two pointer vectors

Definition at line 177 of file ptr_vector.c.

References ptr_vector::cap, ptr_vector::cloner, ptr_vector::count, ptr_vector::dtor, PODSWAP, ptr_vector::ptrs, and ptr_vector::tranch.

Referenced by ptr_set_swap(), and ptr_vector_assign().

Files

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation