Detailed Description

Linked-list Data Structure API.

[Code sample - String]
// init a linked-list.
qentry_t *entry = qEntry();
// insert a string element
entry->putstr(entry, "str", "hello world", true);
// get the string.
char *str = entry->getstr(entry, "str", false);
if(str != NULL) {
  printf("str = %s\n", str);
  free(str);
}
// print out all elements in the list.
entry->print(entry, stdout, false);
// free the list.
entry->free(entry);
[Result]

Functions
qentry_t *	qEntry (void)
	Create new qentry_t linked-list object. More...

static bool	_put (qentry_t entry, const char name, const void *data, size_t size, bool replace)
	qentry_t->put(): Store object into linked-list structure. More...

static bool	_putstr (qentry_t entry, const char name, const char *str, bool replace)
	qentry_t->putstr(): Add string object into linked-list structure. More...

static bool	_putstrf (qentry_t entry, bool replace, const char name, const char *format,...)
	qentry_t->putstrf(): Add formatted string object into linked-list structure. More...

static bool	_putint (qentry_t entry, const char name, int num, bool replace)
	qentry_t->putint(): Add integer object into linked-list structure. More...

static void *	_get (qentry_t entry, const char name, size_t *size, bool newmem)
	qentry_t->get(): Find object with given name More...

static void *	_getlast (qentry_t entry, const char name, size_t *size, bool newmem)
	qentry_t->getlast(): Find lastest matched object with given name. More...

static char *	_getstr (qentry_t entry, const char name, bool newmem)
	qentry_t->getstr(): Find string object with given name. More...

static char *	_getstrf (qentry_t entry, bool newmem, const char namefmt,...)
	qentry_t->_getstrf(): Find string object with given formatted name. More...

static char *	_getstrlast (qentry_t entry, const char name, bool newmem)
	qentry_t->getstrlast(): Find lastest matched string object with given name. More...

static int	_getint (qentry_t entry, const char name)
	qentry_t->getint(): Find integer object with given name. More...

static int	_getintlast (qentry_t entry, const char name)
	qentry_t->getintlast(): Find lastest matched integer object with given name. More...

static void *	_caseget (qentry_t entry, const char name, size_t *size, bool newmem)
	qentry_t->caseget(): Find object with given name. More...

static char *	_casegetstr (qentry_t entry, const char name, bool newmem)
	qentry_t->casegetstr(): Find string object with given name in case-insensitive way. More...

static int	_casegetint (qentry_t entry, const char name)
	qentry_t->casegetint(): Find integer object with given name in case-insensitive way. More...

static bool	_getnext (qentry_t entry, qentobj_t obj, const char *name, bool newmem)
	qentry_t->getnext(): Get next object structure. More...

static int	_size (qentry_t *entry)
	qentry_t->size(): Get total number of stored objects More...

static int	_remove (qentry_t entry, const char name)
	qentry_t->remove(): Remove matched objects as given name. More...

static bool	_truncate (qentry_t *entry)
	qentry_t->truncate(): Truncate qentry_t More...

static bool	_reverse (qentry_t *entry)
	qentry_t->reverse(): Reverse-sort internal stored object. More...

static bool	_save (qentry_t entry, const char filepath)
	qentry_t->save(): Save qentry_t as plain text format More...

static int	_load (qentry_t entry, const char filepath)
	qentry_t->load(): Load and append entries from given filepath More...

static bool	_print (qentry_t entry, FILE out, bool print_data)
	qentry_t->print(): Print out stored objects for debugging purpose. More...

static bool	_free (qentry_t *entry)
	qentry_t->free(): Free qentry_t More...

Function Documentation

qentry_t* qEntry ( void )

Create new qentry_t linked-list object.

Returns: a pointer of malloced qentry_t structure in case of successful, otherwise returns NULL.

qentry_t *entry = qEntry();

static bool _put	(	qentry_t *	entry,
		const char *	name,
		const void *	data,
		size_t	size,
		bool	replace
	)

static

qentry_t->put(): Store object into linked-list structure.

Parameters

entry	qentry_t pointer
name	key name.
object	object pointer
size	size of the object
replace	in case of false, just insert. in case of true, remove all same key then insert object if found.

Returns: true if successful, otherwise returns false.

static bool _putstr	(	qentry_t *	entry,
		const char *	name,
		const char *	str,
		bool	replace
	)

static

qentry_t->putstr(): Add string object into linked-list structure.

Parameters

entry	qentry_t pointer
name	key name.
str	string value
replace	in case of false, just insert. in case of true, remove all same key then insert object if found.

Returns: true if successful, otherwise returns false.

static bool _putstrf	(	qentry_t *	entry,
		bool	replace,
		const char *	name,
		const char *	format,
			...
	)

static

qentry_t->putstrf(): Add formatted string object into linked-list structure.

Parameters

entry	qentry_t pointer
replace	in case of false, just insert. in case of true, remove all same key then insert object if found.
name	key name.
format	formatted value string

Returns: true if successful, otherwise returns false.

static bool _putint	(	qentry_t *	entry,
		const char *	name,
		int	num,
		bool	replace
	)

static

qentry_t->putint(): Add integer object into linked-list structure.

Parameters

entry	qentry_t pointer
name	key name.
num	number value
replace	in case of false, just insert. in case of true, remove all same key then insert object if found.

Returns: true if successful, otherwise returns false.

static void* _get	(	qentry_t *	entry,
		const char *	name,
		size_t *	size,
		bool	newmem
	)

static

qentry_t->get(): Find object with given name

Parameters

entry	qentry_t pointer
name	key name
size	if size is not NULL, object size will be stored.
newmem	whether or not to allocate memory for the data.

Returns: a pointer of data if key is found, otherwise returns NULL.

qentry_t *entry = qEntry();
(...codes...)
// with newmem flag unset
size_t size;
const char *data = entry->get(entry, "key_name", &size, false);
// with newmem flag set
size_t size;
char *data = entry->get(entry, "key_name", &size, true);
if(data != NULL) free(data);

Note: If newmem flag is set, returned data will be malloced and should be deallocated by user. Otherwise returned pointer will point internal buffer directly and should not be de-allocated by user. In thread-safe mode, newmem flag always should be true.

static void* _getlast	(	qentry_t *	entry,
		const char *	name,
		size_t *	size,
		bool	newmem
	)

static

qentry_t->getlast(): Find lastest matched object with given name.

Parameters

entry	qentry_t pointer
name	key name
size	if size is not NULL, object size will be stored.
newmem	whether or not to allocate memory for the data.

Returns: a pointer of malloced data if key is found, otherwise returns NULL.

Note: If you have multiple objects with same name. this method can be used to find out lastest matched object.

static char* _getstr	(	qentry_t *	entry,
		const char *	name,
		bool	newmem
	)

static

qentry_t->getstr(): Find string object with given name.

Parameters

entry	qentry_t pointer
name	key name
newmem	whether or not to allocate memory for the data.

Returns: a pointer of malloced data if key is found, otherwise returns NULL.

static char* _getstrf	(	qentry_t *	entry,
		bool	newmem,
		const char *	namefmt,
			...
	)

static

qentry_t->_getstrf(): Find string object with given formatted name.

Parameters

entry	qentry_t pointer
newmem	whether or not to allocate memory for the data.
namefmt	formatted name string

Returns: a pointer of malloced data if key is found, otherwise returns NULL.

static char* _getstrlast	(	qentry_t *	entry,
		const char *	name,
		bool	newmem
	)

static

qentry_t->getstrlast(): Find lastest matched string object with given name.

Parameters

entry	qentry_t pointer
name	key name
newmem	whether or not to allocate memory for the data.

Returns: a pointer of malloced data if key is found, otherwise returns NULL.

static int _getint	(	qentry_t *	entry,
		const char *	name
	)

static

qentry_t->getint(): Find integer object with given name.

Parameters

entry	qentry_t pointer
name	key name

Returns: a integer value of the integer object, otherwise returns 0.

static int _getintlast	(	qentry_t *	entry,
		const char *	name
	)

static

qentry_t->getintlast(): Find lastest matched integer object with given name.

Parameters

entry	qentry_t pointer
name	key name

Returns: a integer value of the object.

static void* _caseget	(	qentry_t *	entry,
		const char *	name,
		size_t *	size,
		bool	newmem
	)

static

qentry_t->caseget(): Find object with given name.

(case-insensitive)

Parameters

entry	qentry_t pointer
name	key name
size	if size is not NULL, object size will be stored.
newmem	whether or not to allocate memory for the data.

Returns: a pointer of malloced data if key is found, otherwise returns NULL.

static char* _casegetstr	(	qentry_t *	entry,
		const char *	name,
		bool	newmem
	)

static

qentry_t->casegetstr(): Find string object with given name in case-insensitive way.

Parameters

entry	qentry_t pointer
name	key name
newmem	whether or not to allocate memory for the data.

Returns: a pointer of malloced data if key is found, otherwise returns NULL.

static int _casegetint	(	qentry_t *	entry,
		const char *	name
	)

static

qentry_t->casegetint(): Find integer object with given name in case-insensitive way.

Parameters

entry	qentry_t pointer
name	key name

Returns: a integer value of the object.

static bool _getnext	(	qentry_t *	entry,
		qentobj_t *	obj,
		const char *	name,
		bool	newmem
	)

static

qentry_t->getnext(): Get next object structure.

Parameters

entry	qentry_t pointer
obj	found data will be stored in this object
name	key name, if key name is NULL search every key in the list.
newmem	whether or not to allocate memory for the data.

Returns: true if found otherwise returns false

Note: obj should be filled with 0 by using memset() before first call. If newmem flag is true, user should de-allocate obj.name and obj.data resources.

qentry_t *entry = qEntry();
entry->putstr(entry, "key1", "hello world 1", false);
entry->putstr(entry, "key2", "hello world 2", false);
entry->putstr(entry, "key3", "hello world 3", false);
qentobj_t obj;
memset((void*)&obj, 0, sizeof(obj)); // must be cleared before call
while(entry->getnext(entry, &obj, NULL, false) == true) {
  printf("NAME=%s, DATA=%s", SIZE=%zu", obj.name, obj.data, obj.size);
}
// with newmem flag
qentobj_t obj;
memset((void*)&obj, 0, sizeof(obj)); // must be cleared before call
while(entry->getnext(entry, &obj, NULL, true) == true) {
  printf("NAME=%s, DATA=%s", SIZE=%zu", obj.name, obj.data, obj.size);
  free(obj.name);
  free(obj.data);
}

static int _size ( qentry_t * entry )

static

qentry_t->size(): Get total number of stored objects

Parameters

entry qentry_t pointer

Returns: total number of stored objects.

static int _remove	(	qentry_t *	entry,
		const char *	name
	)

static

qentry_t->remove(): Remove matched objects as given name.

Parameters

entry	qentry_t pointer
name	key name

Returns: a number of removed objects.

static bool _truncate ( qentry_t * entry )

static

qentry_t->truncate(): Truncate qentry_t

Parameters

entry qentry_t pointer

Returns: always returns true.

static bool _reverse ( qentry_t * entry )

static

qentry_t->reverse(): Reverse-sort internal stored object.

Parameters

entry qentry_t pointer

Returns: true if successful otherwise returns false.

Note: This method can be used to improve look up performance. if your application offen looking for last stored object.

static bool _save	(	qentry_t *	entry,
		const char *	filepath
	)

static

qentry_t->save(): Save qentry_t as plain text format

Parameters

entry	qentry_t pointer
filepath	save file path

Returns: true if successful, otherwise returns false.

static int _load	(	qentry_t *	entry,
		const char *	filepath
	)

static

qentry_t->load(): Load and append entries from given filepath

Parameters

entry	qentry_t pointer
filepath	save file path

Returns: a number of loaded entries.

static bool _print	(	qentry_t *	entry,
		FILE *	out,
		bool	print_data
	)

static

qentry_t->print(): Print out stored objects for debugging purpose.

Parameters

entry	qentry_t pointer
out	output stream FILE descriptor such like stdout, stderr.
print_data	true for printing out object value, false for disable printing out object value.

static bool _free ( qentry_t * entry )

static

qentry_t->free(): Free qentry_t

Parameters

entry qentry_t pointer

Returns: always returns true.

qDecoder API Reference

Detailed Description

Functions

Function Documentation