datrie/sb-trie.h File Reference

---

Detailed Description

Trie data type and functions.

Typedefs
typedef _SBTrie	SBTrie
	Single-byte domain trie data type.
typedef unsigned char	SBChar
	Single-byte character type.
typedef Bool(*)	SBTrieEnumFunc (const SBChar *key, TrieData key_data, void *user_data)
	Single-byte domain trie enumeration function.
typedef _SBTrieState	SBTrieState
	Single-byte domain trie walking state.
Functions
SBTrie *	sb_trie_open (const char *path, const char *name, TrieIOMode mode)
	Open a single-byte domain trie.
int	sb_trie_close (SBTrie *sb_trie)
	Close a single-byte domain trie.
int	sb_trie_save (SBTrie *sb_trie)
	Save a single-byte domain trie.
Bool	sb_trie_retrieve (SBTrie *sb_trie, const SBChar *key, TrieData *o_data)
	Retrieve an entry from single-byte domain trie.
Bool	sb_trie_store (SBTrie *sb_trie, const SBChar *key, TrieData data)
	Store a value for an entry to single-byte domain trie.
Bool	sb_trie_delete (SBTrie *sb_trie, const SBChar *key)
	Delete an entry from single-byte domain trie.
Bool	sb_trie_enumerate (SBTrie *sb_trie, SBTrieEnumFunc enum_func, void *user_data)
	Enumerate entries in single-byte domain trie.
SBTrieState *	sb_trie_root (SBTrie *sb_trie)
	Get root state of a single-byte domain trie.
SBTrieState *	sb_trie_state_clone (const SBTrieState *s)
	Clone a single-byte domain trie state.
void	sb_trie_state_free (SBTrieState *s)
	Free a single-byte trie state.
void	sb_trie_state_rewind (SBTrieState *s)
	Rewind a single-byte trie state.
Bool	sb_trie_state_walk (SBTrieState *s, SBChar c)
	Walk the single-byte domain trie from the state.
Bool	sb_trie_state_is_walkable (const SBTrieState *s, SBChar c)
	Test walkability of character from state.
Bool	sb_trie_state_is_terminal (const SBTrieState *s)
	Check for terminal state.
Bool	sb_trie_state_is_leaf (const SBTrieState *s)
	Check for leaf state.
TrieData	sb_trie_state_get_data (const SBTrieState *s)
	Get data from leaf state.

---

Typedef Documentation

typedef Bool(*) SBTrieEnumFunc(const SBChar *key, TrieData key_data, void *user_data)

Single-byte domain trie enumeration function.

Parameters:

	key	: the key of the entry
	data	: the data of the entry

Returns:

TRUE to continue enumeration, FALSE to stop

---

Function Documentation

int sb_trie_close

(

SBTrie *

sb_trie

)

Close a single-byte domain trie.

Parameters:

sb_trie,:

the single-byte domain trie

Returns:

0 on success, non-zero on failure

Close the given trie. If trie was openned for writing, all pending changes will be saved to file.

Bool sb_trie_delete	(	SBTrie *	sb_trie,
		const SBChar *	key
	)

Delete an entry from single-byte domain trie.

Parameters:

	sb_trie	: the single-byte domain trie
	key	: the key for the entry to delete

Returns:

boolean value indicating whether the key exists and is removed

Delete an entry for the given key from trie.

Bool sb_trie_enumerate	(	SBTrie *	sb_trie,
		SBTrieEnumFunc	enum_func,
		void *	user_data
	)

Enumerate entries in single-byte domain trie.

Parameters:

	sb_trie	: the single-byte domain trie
	enum_func	: the callback function to be called on each key
	user_data	: user-supplied data to send as an argument to enum_func

Returns:

boolean value indicating whether all the keys are visited

Enumerate all entries in trie. For each entry, the user-supplied enum_func callback function is called, with the entry key and data. Returning FALSE from such callback will stop enumeration and return FALSE.

SBTrie* sb_trie_open	(	const char *	path,
		const char *	name,
		TrieIOMode	mode
	)

Open a single-byte domain trie.

Parameters:

	path	: the path that stores the trie files
	name	: the name of the trie (not actual file name)
	mode	: openning mode, read or write

Returns:

a pointer to the openned trie, NULL on failure

Open a trie of given name. Note that name here does not mean the actual file name. Rather, the file name will be inferred by the name.

Bool sb_trie_retrieve	(	SBTrie *	sb_trie,
		const SBChar *	key,
		TrieData *	o_data
	)

Retrieve an entry from single-byte domain trie.

Parameters:

	sb_trie	: the single-byte domain trie
	key	: the key for the entry to retrieve
	o_data	: the storage for storing the entry data on return

Returns:

boolean value indicating the existence of the entry.

Retrieve an entry for the given key from trie. On return, if key is found and o_val is not NULL, *o_val is set to the data associated to key.

SBTrieState* sb_trie_root

(

SBTrie *

sb_trie

)

Get root state of a single-byte domain trie.

Parameters:

sb_trie

: the single-byte domain trie

Returns:

the root state of the trie

Get root state of trie, for stepwise walking.

The returned state is allocated and must be freed with trie_state_free()

int sb_trie_save

(

SBTrie *

sb_trie

)

Save a single-byte domain trie.

Parameters:

sb_trie,:

the single-byte domain trie

Returns:

0 on success, non-zero on failure

If trie was openned for writing, save all pending data to file.

SBTrieState* sb_trie_state_clone

(

const SBTrieState *

s

)

Clone a single-byte domain trie state.

Parameters:

s

: the state to clone

Returns:

an duplicated instance of s

Make a copy of trie state.

The returned state is allocated and must be freed with trie_state_free()

void sb_trie_state_free

(

SBTrieState *

s

)

Free a single-byte trie state.

Parameters:

s

: the state to free

Free the trie state.

TrieData sb_trie_state_get_data

(

const SBTrieState *

s

)

Get data from leaf state.

Parameters:

s

: the leaf state

Returns:

the data associated with the leaf state s, or TRIE_DATA_ERROR if s is not a leaf state

Get value from a leaf state of trie. Getting the value from leaf state will result in TRIE_DATA_ERROR.

Bool sb_trie_state_is_leaf

(

const SBTrieState *

s

)

Check for leaf state.

Parameters:

s

: the state to check

Returns:

boolean value indicating whether it is a leaf state

Check if the given state is a leaf state. A leaf state is a terminal state that has no other branch.

Bool sb_trie_state_is_terminal

(

const SBTrieState *

s

)

Check for terminal state.

Parameters:

s

: the state to check

Returns:

boolean value indicating whether it is a terminal state

Check if the given state is a terminal state. A leaf state is a trie state that terminates a key, and stores a value associated with the key.

Bool sb_trie_state_is_walkable	(	const SBTrieState *	s,
		SBChar	c
	)

Test walkability of character from state.

Parameters:

	s	: the state to check
	c	: the input character

Returns:

boolean indicating walkability

Test if there is a transition from state s with input character c.

void sb_trie_state_rewind

(

SBTrieState *

s

)

Rewind a single-byte trie state.

Parameters:

s

: the state to rewind

Put the state at root.

Bool sb_trie_state_walk	(	SBTrieState *	s,
		SBChar	c
	)

Walk the single-byte domain trie from the state.

Parameters:

	s	: current state
	c	: key character for walking

Returns:

boolean value indicating the success of the walk

Walk the trie stepwise, using a given character c. On return, the state s is updated to the new state if successfully walked.

Bool sb_trie_store	(	SBTrie *	sb_trie,
		const SBChar *	key,
		TrieData	data
	)

Store a value for an entry to single-byte domain trie.

Parameters:

	sb_trie	: the single-byte domain trie
	key	: the key for the entry to retrieve
	data	: the data associated to the entry

Returns:

boolean value indicating the success of the process

Store a data data for the given key in trie. If key does not exist in trie, it will be appended.

---