qDecoder API Reference

Functions

qentry.c File Reference


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_tqEntry (void)
 Create new qentry_t linked-list object.
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.
static bool _putstr (qentry_t *entry, const char *name, const char *str, bool replace)
 qentry_t->putstr(): Add string object into linked-list structure.
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.
static bool _putint (qentry_t *entry, const char *name, int num, bool replace)
 qentry_t->putint(): Add integer object into linked-list structure.
static void * _get (qentry_t *entry, const char *name, size_t *size, bool newmem)
 qentry_t->get(): Find object with given name
static void * _getlast (qentry_t *entry, const char *name, size_t *size, bool newmem)
 qentry_t->getlast(): Find lastest matched object with given name.
static char * _getstr (qentry_t *entry, const char *name, bool newmem)
 qentry_t->getstr(): Find string object with given name.
static char * _getstrf (qentry_t *entry, bool newmem, const char *namefmt,...)
 qentry_t->_getstrf(): Find string object with given formatted name.
static char * _getstrlast (qentry_t *entry, const char *name, bool newmem)
 qentry_t->getstrlast(): Find lastest matched string object with given name.
static int _getint (qentry_t *entry, const char *name)
 qentry_t->getint(): Find integer object with given name.
static int _getintlast (qentry_t *entry, const char *name)
 qentry_t->getintlast(): Find lastest matched integer object with given name.
static void * _caseget (qentry_t *entry, const char *name, size_t *size, bool newmem)
 qentry_t->caseget(): Find object with given name.
static char * _casegetstr (qentry_t *entry, const char *name, bool newmem)
 qentry_t->casegetstr(): Find string object with given name in case-insensitive way.
static int _casegetint (qentry_t *entry, const char *name)
 qentry_t->casegetint(): Find integer object with given name in case-insensitive way.
static bool _getnext (qentry_t *entry, qentobj_t *obj, const char *name, bool newmem)
 qentry_t->getnext(): Get next object structure.
static int _size (qentry_t *entry)
 qentry_t->size(): Get total number of stored objects
static int _remove (qentry_t *entry, const char *name)
 qentry_t->remove(): Remove matched objects as given name.
static bool _truncate (qentry_t *entry)
 qentry_t->truncate(): Truncate qentry_t
static bool _reverse (qentry_t *entry)
 qentry_t->reverse(): Reverse-sort internal stored object.
static bool _save (qentry_t *entry, const char *filepath)
 qentry_t->save(): Save qentry_t as plain text format
static int _load (qentry_t *entry, const char *filepath)
 qentry_t->load(): Load and append entries from given filepath
static bool _print (qentry_t *entry, FILE *out, bool print_data)
 qentry_t->print(): Print out stored objects for debugging purpose.
static bool _free (qentry_t *entry)
 qentry_t->free(): Free qentry_t

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.