phash.h File Reference

#include <stdint.h>

Include dependency graph for phash.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	PHASH_API_VERSION   1002000
#define	PHASH_API_VERSION_STR   "1.2.0"
#define	PHASH_NO_COPY_KEYS   1

Functions
phash *	phash_create (uint32_t options)
int	phash_destroy (phash *h)
int	phash_set (phash *h, const char *key, void *value)
void *	phash_get (phash *h, const char *key)
int	phash_remove (phash *h, const char *key)
int	phash_rewind (phash *h)
int	phash_next (phash *h, const char **key, void **value)
int	phash_size (phash *h)
const char *	phash_version ()

Detailed Description

A simple dictionary library for storing pointers.

A phash doesn't actually store any data for the key or the value, merely pointers to them. The in-memory data must persist until the phash is destroyed. If a memory location referred to by a phash is free'd, or non-malloc'd pointers simply go out of scope the phash will almost definitely try to access invalid memory locations during a call to any function except for phash_destroy. String literals, depending on the compiler, generally get put into some kind of read-only memory and persist through the program, so they might be safe.

Definition in file phash.h.

Macro Definition Documentation

PHASH_API_VERSION

#define PHASH_API_VERSION   1002000

Current API version. If already defined, use API defined first.

Definition at line 25 of file phash.h.

PHASH_API_VERSION_STR

#define PHASH_API_VERSION_STR   "1.2.0"

Current API version as a string. If already defined, use API defined first.

Definition at line 27 of file phash.h.

PHASH_NO_COPY_KEYS

#define PHASH_NO_COPY_KEYS   1

Definition at line 30 of file phash.h.

Function Documentation

phash_create()

phash* phash_create

(

uint32_t

options

)

Initialize a phash object.

Parameters

[in]

options

Bitwise OR'd option flags. Currently unused.

Returns

Pointer to malloc'd phash.

Definition at line 107 of file phash.c.

phash_destroy()

int phash_destroy

(

phash *

h

)

Destroy a phash object, free'ing the memory used.

Parameters

[in]

h

Pointer to phash to be destroyed.

Returns

0 on success.

Definition at line 136 of file phash.c.

phash_get()

void* phash_get	(	phash *	h,
		const char *	key
	)

Find a pointer associated with the given string.

Parameters

[in]	h	Pointer to phash to be searched.
[in]	key	Key for which to search.

Returns

Pointer to value, or NULL if key is not found.

Definition at line 205 of file phash.c.

phash_next()

int phash_next	(	phash *	h,
		const char **	key,
		void **	value
	)

Retrieves the next key-value pair in the phash. The order in which the pointers are returned shall be consistent but may be arbitrary.

Consistent refers only to running identical code and rewinding and traversing the data. Adding or removing pointers may modify the order in which keys are returned.

On end-of-hash, the hash is rewind()'d and the state of the key and value inputs are set to NULL.

Parameters

[in]	h	Pointer to phash to be traversed.
[out]	key	Pointer to fill with the next key, NULL to ignore.
[out]	value	Pointer to fill with the next value, NULL to ignore.

Returns

-1 on error, positive 1 on end-of-hash, and 0 on success.

Definition at line 275 of file phash.c.

phash_remove()

int phash_remove	(	phash *	h,
		const char *	key
	)

Remove a pointer associated with the given string.

Parameters

[in]	h	Pointer to phash to be modified.
[in]	key	Key for which to remove.

Returns

0 on success.

Definition at line 146 of file phash.c.

phash_rewind()

int phash_rewind

(

phash *

h

)

Rewind iterator for traversing all the keys and values.

Parameters

[in]

h

Pointer to phash to be reset.

Returns

number of items currently in the phash.

Definition at line 269 of file phash.c.

phash_set()

int phash_set	(	phash *	h,
		const char *	key,
		void *	value
	)

Add or overwrite a pointer, associating it with the given key.

Parameters

[in]	h	Pointer to phash to be modified.
[in]	key	Null-terminated string with which to associate the new pointer.
[in]	value	New pointer to store..

Returns

0 on add, 1 on overwrite, and -1 on error.

Definition at line 224 of file phash.c.

phash_size()

int phash_size

(

phash *

h

)

Retrieves the number of key-value pairs in the hash object.

Parameters

[in]

h

Pointer to shash to be analyzed.

Definition at line 312 of file phash.c.

phash_version()

const char* phash_version

(

)

Returns the source code version and the implemented API version.

No assumptions are made about the format of the return value.

Definition at line 316 of file phash.c.