KVP: Key-Value Pairs
[Query Object Framework]

Data Structures
struct	GHashTableKVPair
Files
file	kvp-util-p.h
	misc odd-job kvp utils engine-private routines
file	kvp-util.h
	QOF KVP utility functions.
file	kvp_frame.h
	A key-value frame system.
Defines
#define	QOF_MOD_KVP   "qof.kvp"
#define	kvp_frame   KvpFrame
#define	kvp_value   KvpValue
#define	kvp_value_t   KvpValueType
Typedefs
typedef struct _KvpFrame	KvpFrame
typedef struct _KvpValue	KvpValue
Enumerations
enum	KvpValueType {   KVP_TYPE_GINT64 = 1, KVP_TYPE_DOUBLE, KVP_TYPE_NUMERIC, KVP_TYPE_STRING,   KVP_TYPE_GUID, KVP_TYPE_TIMESPEC, KVP_TYPE_BINARY, KVP_TYPE_GLIST,   KVP_TYPE_FRAME }
	possible types in the union KvpValue More...
Functions
gchar *	kvp_value_to_bare_string (const KvpValue *val)
	General purpose function to convert any KvpValue to a string.
gchar *	kvp_value_to_string (const KvpValue *val)
	Debug version of kvp_value_to_string.
gboolean	kvp_value_binary_append (KvpValue *v, void *data, guint64 size)
gchar *	kvp_frame_to_string (const KvpFrame *frame)
gchar *	binary_to_string (const void *data, guint32 size)
gchar *	kvp_value_glist_to_string (const GList *list)
GHashTable *	kvp_frame_get_hash (const KvpFrame *frame)

---

Detailed Description

A KvpFrame is a set of associations between character strings (keys) and KvpValue structures. A KvpValue is a union with possible types enumerated in the KvpValueType enum, and includes, among other things, ints, doubles, strings, guid's, lists, time and numeric values. KvpValues may also be other frames, so KVP is inherently hierarchical.

Values are stored in a 'slot' associated with a key. Pointers passed as arguments into set_slot and get_slot are the responsibility of the caller. Pointers returned by get_slot are owned by the kvp_frame. Make copies as needed.

A 'path' is a sequence of keys that can be followed to a value. Paths may be specified as varargs (variable number of arguments to a subrutine, NULL-terminated), as a GSList, or as a standard URL-like path name. The later is parsed and treated in the same way as file paths would be: / separates keys, /./ is treated as / and /../ means backup one level. Repeated slashes are treated as one slash.

Note that although, in principle, keys may contain the / and . and .. characters, doing so may lead to confusion, and will make path-string parsing routines fail. In other words, don't use a key such as 'some/key' or 'some/./other/../key' because you may get unexpected results.

To set a value into a frame, you will want to use one of the kvp_frame_set_xxx() routines. Most of the other routines provide only low-level access that you probably shouldn't use.

---

Define Documentation

#define kvp_frame   KvpFrame

Deprecated:

Deprecated backwards compat token

do not use these in new code.

Definition at line 104 of file kvp_frame.h.

#define kvp_frame_add_gnc_numeric   kvp_frame_add_numeric

Deprecated:

Use kvp_frame_add_numeric instead of kvp_frame_add_gnc_numeric

Definition at line 270 of file kvp_frame.h.

#define kvp_frame_add_str   kvp_frame_add_string

Deprecated:

Use kvp_frame_add_string instead of kvp_frame_add_str

Definition at line 279 of file kvp_frame.h.

#define kvp_frame_set_gnc_numeric   kvp_frame_set_numeric

Deprecated:

Use kvp_frame_set_numeric instead of kvp_frame_set_gnc_numeric

Definition at line 154 of file kvp_frame.h.

#define kvp_frame_set_str   kvp_frame_set_string

Deprecated:

Use kvp_frame_set_string instead of kvp_frame_set_str

Definition at line 172 of file kvp_frame.h.

#define kvp_value   KvpValue

Deprecated:

Deprecated backwards compat token

Definition at line 106 of file kvp_frame.h.

#define kvp_value_new_gnc_numeric   kvp_value_new_numeric

Deprecated:

Use kvp_value_new_numeric instead of kvp_value_new_gnc_numeric

Definition at line 558 of file kvp_frame.h.

#define kvp_value_t   KvpValueType

Deprecated:

Deprecated backwards compat token

Definition at line 108 of file kvp_frame.h.

---

Typedef Documentation

typedef struct _KvpFrame KvpFrame

Opaque frame structure

Definition at line 71 of file kvp_frame.h.

typedef struct _KvpValue KvpValue

A KvpValue is a union with possible types enumerated in the KvpValueType enum.

Definition at line 75 of file kvp_frame.h.

---

Enumeration Type Documentation

enum KvpValueType

possible types in the union KvpValue

Todo:

: People have asked for boolean values, e.g. in xaccAccountSetAutoInterestXfer

Todo:

In the long run, this should be synchronized with the core QOF types, which in turn should be synced to the g_types in GLib. Unfortunately, this requires writing a pile of code to handle all of the different cases. An alternative might be to make kvp values inherit from the core g_types (i.e. add new core g_types) ??

Enumerator:

KVP_TYPE_GINT64	QOF_TYPE_INT64 gint64
KVP_TYPE_DOUBLE	QOF_TYPE_DOUBLE gdouble
KVP_TYPE_NUMERIC	QOF_TYPE_NUMERIC
KVP_TYPE_STRING	QOF_TYPE_STRING gchar*
KVP_TYPE_GUID	QOF_TYPE_GUID
KVP_TYPE_TIMESPEC	QOF_TYPE_DATE
KVP_TYPE_BINARY	no QOF equivalent.
KVP_TYPE_GLIST	no QOF equivalent.
KVP_TYPE_FRAME	no QOF equivalent.

Definition at line 88 of file kvp_frame.h.

             {
  KVP_TYPE_GINT64=1,   
  KVP_TYPE_DOUBLE,     
  KVP_TYPE_NUMERIC,    
  KVP_TYPE_STRING,     
  KVP_TYPE_GUID,       
  KVP_TYPE_TIMESPEC,   
  KVP_TYPE_BINARY,     
  KVP_TYPE_GLIST,      
  KVP_TYPE_FRAME       
} KvpValueType;

---

Function Documentation

GSList* g_hash_table_key_value_pairs

(

GHashTable *

table

)

Returns a GSList* of all the keys and values in a given hash table. Data elements of lists are actual hash elements, so be careful, and deallocation of the GHashTableKVPairs in the result list are the caller's responsibility. A typical sequence might look like this:

GSList *kvps = g_hash_table_key_value_pairs(hash); ... use kvps->data->key and kvps->data->val, etc. here ... g_slist_foreach(kvps, g_hash_table_kv_pair_free_gfunc, NULL); g_slist_free(kvps);

Definition at line 221 of file kvp-util.c.

{
  GSList *result_list = NULL;
  g_hash_table_foreach(table, kv_pair_helper, &result_list);
  return result_list;
}

KvpFrame* gnc_kvp_bag_add	(	KvpFrame *	kvp_root,
		const char *	path,
		time_t	secs,
		const char *	first_name,
			...
	)

The gnc_kvp_bag_add() routine is used to maintain a collection of pointers in a kvp tree.

The thing being pointed at is uniquely identified by its GUID. This routine is typically used to create a linked list, and/or a collection of pointers to objects that are 'related' to each other in some way.

The var-args should be pairs of strings (const char *) followed by the corresponding GUID pointer (const GUID *). Terminate the varargs with a NULL as the last string argument.

The actual 'pointer' is stored in a subdirectory in a bag located at the node directory 'path'. A 'bag' is merely a collection of (unamed) values. The name of our bag is 'path'. A bag can contain any kind of values, including frames. This routine will create a frame, and put it in the bag. The frame will contain named data from the subroutine arguments. Thus, for example:

gnc_kvp_array (kvp, "foo", secs, "acct_guid", aguid, "book_guid", bguid, NULL);

will create a frame containing "/acct_guid" and "/book_guid", whose values are aguid and bguid respecitvely. The frame will also contain "/date", whose value will be secs. This frame will be placed into the bag located at "foo".

This routine returns a pointer to the frame that was created, or NULL if an error occured.

Definition at line 74 of file kvp-util.c.

{
   KvpFrame *cwd;
   va_list ap;
   va_start (ap, first_name);
   cwd = gnc_kvp_array_va (pwd, path, secs, first_name, ap);
   va_end (ap);
   return cwd;
}

KvpFrame* gnc_kvp_bag_find_by_guid	(	KvpFrame *	root,
		const char *	path,
		const char *	guid_name,
		const GUID *	desired_guid
	)

The gnc_kvp_bag_find_by_guid() routine examines the bag pointed located at root. It looks for a frame in that bag that has the guid value of "desired_guid" filed under the key name "guid_name". If it finds that matching guid, then it returns a pointer to the KVP frame that contains it. If it is not found, or if there is any other error, NULL is returned.

Definition at line 96 of file kvp-util.c.

{
  KvpValue *arr;
  KvpValueType valtype;
  GList *node;

  arr = kvp_frame_get_value (root, path);
  valtype = kvp_value_get_type (arr);
  if (KVP_TYPE_FRAME == valtype)
  {
    MATCH_GUID (arr);
    return NULL;
  }

  /* Its gotta be a single isolated frame, or a list of them. */
  if (KVP_TYPE_GLIST != valtype) return NULL;

  for (node = kvp_value_get_glist(arr); node; node=node->next)
  {
    KvpValue *va = node->data;
    MATCH_GUID (va);
  }
  return NULL;
}

void gnc_kvp_bag_merge	(	KvpFrame *	kvp_into,
		const char *	intopath,
		KvpFrame *	kvp_from,
		const char *	frompath
	)

The gnc_kvp_bag_merge() routine will move the bag contents from the 'kvp_from', to the 'into' bag. It will then delete the 'from' bag from the kvp tree.

Definition at line 190 of file kvp-util.c.

{
  KvpFrame *fr;

  fr = gnc_kvp_bag_get_first (kvp_from, frompath);
  while (fr) 
  {
    gnc_kvp_bag_remove_frame (kvp_from, frompath, fr);
    kvp_frame_add_frame_nc (kvp_into, intopath, fr);
    fr = gnc_kvp_bag_get_first (kvp_from, frompath);
  }
}

void gnc_kvp_bag_remove_frame	(	KvpFrame *	root,
		const char *	path,
		KvpFrame *	fr
	)

Remove the given frame from the bag. The frame is removed, however, it is not deleted. Note that the frame pointer must be a pointer to the actual frame (for example, as returned by gnc_kvp_bag_find_by_guid() for by gnc_kvp_bag_add()), and not some copy of the frame.

Definition at line 125 of file kvp-util.c.

{
  KvpValue *arr;
  KvpValueType valtype;
  GList *node, *listhead;

  arr = kvp_frame_get_value (root, path);
  valtype = kvp_value_get_type (arr);
  if (KVP_TYPE_FRAME == valtype)
  {
    if (fr == kvp_value_get_frame (arr))
    {
      KvpValue *old_val = kvp_frame_replace_value_nc (root, path, NULL); 
      kvp_value_replace_frame_nc (old_val, NULL);
      kvp_value_delete (old_val);
    }
    return;
  }

  /* Its gotta be a single isolated frame, or a list of them. */
  if (KVP_TYPE_GLIST != valtype) return;

  listhead = kvp_value_get_glist(arr);
  for (node = listhead; node; node=node->next)
  {
    KvpValue *va = node->data;
    if (fr == kvp_value_get_frame (va))
    {
      listhead = g_list_remove_link (listhead, node);
      g_list_free_1 (node);
      kvp_value_replace_glist_nc (arr, listhead);
      kvp_value_replace_frame_nc (va, NULL);
      kvp_value_delete (va);
      return;
    }
  }
}

void kvp_frame_add_gint64	(	KvpFrame *	frame,
		const gchar *	path,
		gint64	ival
	)

The kvp_frame_add_gint64() routine will add the value of the gint64 to the glist bag of values at the indicated path. If not all frame components of the path exist, they are created. If the value previously stored at this path was not a glist bag, then a bag will be formed there, the old value placed in the bag, and the new value added to the bag.

Similarly, the add_double, add_numeric, and add_timespec routines perform the same function, for each of the respective types.

void kvp_frame_add_string	(	KvpFrame *	frame,
		const gchar *	path,
		const gchar *	str
	)

Copy of the string to the glist bag at the indicated path.

If not all frame components of the path exist, they are created. If there was another item previously stored at that path, then the path is converted to a bag, and the old value, along with the new value, is added to the bag.

Similarly, the add_guid and add_frame will make copies and add those.

The kvp_frame_add_frame_nc() routine works as above, but does *NOT* copy the frame.

void kvp_frame_add_url_encoding	(	KvpFrame *	frame,
		const gchar *	enc
	)

The kvp_frame_add_url_encoding() routine will parse the value string, assuming it to be URL-encoded in the standard way, turning it into a set of key-value pairs, and adding those to the indicated frame. URL-encoded strings are the things that are returned by web browsers when a form is filled out. For example, 'start-date=June&end-date=November' consists of two keys, 'start-date' and 'end-date', which have the values 'June' and 'November', respectively. This routine also handles % encoding.

This routine treats all values as strings; it does *not* attempt to perform any type-conversion.

gint kvp_frame_compare	(	const KvpFrame *	fa,
		const KvpFrame *	fb
	)

Similar returns as strcmp.

Definition at line 1562 of file kvp_frame.c.

{
  kvp_frame_cmp_status status;

  if(fa == fb) return 0;
  /* nothing is always less than something */
  if(!fa && fb) return -1;
  if(fa && !fb) return 1;

  /* nothing is always less than something */
  if(!fa->hash && fb->hash) return -1;
  if(fa->hash && !fb->hash) return 1;

  status.compare = 0;
  status.other_frame = (KvpFrame *) fb;

  kvp_frame_for_each_slot((KvpFrame *) fa, kvp_frame_compare_helper, &status);

  if (status.compare != 0)
    return status.compare;

  status.other_frame = (KvpFrame *) fa;

  kvp_frame_for_each_slot((KvpFrame *) fb, kvp_frame_compare_helper, &status);

  return(-status.compare);
}

KvpFrame* kvp_frame_copy

(

const KvpFrame *

frame

)

Perform a deep (recursive) value copy, copying the fraame, subframes, and the values as well.

Definition at line 149 of file kvp_frame.c.

{
  KvpFrame * retval = kvp_frame_new();

  if (!frame) return retval;

  if(frame->hash) 
  {
    if(!init_frame_body_if_needed(retval)) return(NULL);
    g_hash_table_foreach(frame->hash,
                         & kvp_frame_copy_worker, 
                         (gpointer)retval);
  }
  return retval;
}

void kvp_frame_delete

(

KvpFrame *

frame

)

Perform a deep (recursive) delete of the frame and any subframes.

kvp_frame_delete and kvp_value_delete are deep (recursive) deletes. kvp_frame_copy and kvp_value_copy are deep value copies.

Definition at line 114 of file kvp_frame.c.

{
  if (!frame) return;

  if(frame->hash) 
  {
    /* free any allocated resource for frame or its children */
    g_hash_table_foreach(frame->hash, & kvp_frame_delete_worker, 
                         (gpointer)frame);
    
    /* delete the hash table */
    g_hash_table_destroy(frame->hash);
    frame->hash = NULL;
  }
  g_free(frame);
}

void kvp_frame_for_each_slot	(	KvpFrame *	f,
		void(*)(const gchar *key, KvpValue *value, gpointer data)	proc,
		gpointer	data
	)

Traverse all of the slots in the given kvp_frame. This function does not descend recursively to traverse any kvp_frames stored as slot values. You must handle that in proc, with a suitable recursive call if desired.

KvpFrame* kvp_frame_get_frame	(	const KvpFrame *	frame,
		const gchar *	path
	)

Value accessor. Takes a unix-style slash-separated path as an argument, and return the KvpFrame stored at that location. If the KvpFrame does not exist, then a NULL is returned.

Note:

The semantics here have changed: In gnucash-1.8, if the KvpFrame did not exist, this function automatically created one and returned it. However, now this function will return NULL in this case and the caller has to create a KvpFrame on his own. The old functionality is now implemented by kvp_frame_get_frame_path(). This happened on 2003-09-14, revision 1.31. FIXME: Is it really a good idea to change the semantics of an existing function and move the old semantics to a new function??! It would save us a lot of trouble if the new semantics would have been available in a new function!

Returns:

The KvpFrame at the specified path, or NULL if it doesn't exist.

KvpFrame* kvp_frame_get_frame_gslist	(	KvpFrame *	frame,
		const GSList *	key_path
	)

This routine returns the last frame of the path. If the frame path doesn't exist, it is created. Note that this is *VERY DIFFERENT FROM* kvp_frame_get_frame()

Definition at line 924 of file kvp_frame.c.

{
  if (!frame) return frame;

  while (key_path) 
  {
    const char *key = key_path->data;

    if (!key) return frame;  /* an unusual but valid exit for this routine. */

    frame = get_or_make (frame, key);
    if (!frame) return frame;  /* this should never happen */

    key_path = key_path->next;
  }
  return frame;  /* this is the normal exit for this func */
}

KvpFrame* kvp_frame_get_frame_path	(	KvpFrame *	frame,
		const gchar *	,
			...
	)

This routine returns the last frame of the path. If the frame path doesn't exist, it is created. Note that this is *VERY DIFFERENT FROM* like kvp_frame_get_frame()

Note:

The semantics of this function implemented the gnucash-1.8 behaviour of kvp_frame_get_frame: In gnucash-1.8, if the KvpFrame did not exist, kvp_frame_get_frame automatically created one and returned it. However, now that one will return NULL in this case and the caller has to create a KvpFrame on his own. The old functionality is implemented by this kvp_frame_get_frame_path(). This happened on 2003-09-14, revision 1.31.

KvpFrame* kvp_frame_get_frame_slash	(	KvpFrame *	frame,
		const gchar *	path
	)

This routine returns the last frame of the path. If the frame path doesn't exist, it is created. Note that this is *VERY DIFFERENT FROM* kvp_frame_get_frame()

The kvp_frame_get_frame_slash() routine takes a single string where the keys are separated by slashes; thus, for example: /this/is/a/valid/path and///so//is////this/ Multiple slashes are compresed. Leading slash is optional. The pointers . and .. are *not* currently followed/obeyed. (This is a bug that needs fixing).

KvpValue* kvp_frame_get_slot_path	(	KvpFrame *	frame,
		const gchar *	first_key,
			...
	)

This routine return the value at the end of the path, or NULL if any portion of the path doesn't exist.

KvpValue* kvp_frame_get_slot_path_gslist	(	KvpFrame *	frame,
		const GSList *	key_path
	)

This routine return the value at the end of the path, or NULL if any portion of the path doesn't exist.

Definition at line 1012 of file kvp_frame.c.

{
  if (!frame || !key_path) return NULL;

  while (TRUE) 
  {
    const char *key = key_path->data;
    KvpValue *value;

    if (!key) return NULL;

    value = kvp_frame_get_slot (frame, key);
    if (!value) return NULL;

    key_path = key_path->next;
    if (!key_path) return value;

    frame = kvp_value_get_frame (value);
    if (!frame) return NULL;
  }
}

gboolean kvp_frame_is_empty

(

const KvpFrame *

frame

)

Return TRUE if the KvpFrame is empty

Definition at line 132 of file kvp_frame.c.

{
  if (!frame) return TRUE;
  if (!frame->hash) return TRUE;
  return FALSE;
}

KvpFrame* kvp_frame_new

(

void

)

Return a new empty instance of KvpFrame

Definition at line 97 of file kvp_frame.c.

{
  KvpFrame * retval = g_new0(KvpFrame, 1);

  /* Save space until the frame is actually used */
  retval->hash = NULL;
  return retval;
}

KvpValue* kvp_frame_replace_slot_nc	(	KvpFrame *	frame,
		const gchar *	slot,
		KvpValue *	new_value
	)

The kvp_frame_replace_slot_nc() routine places the new value into the indicated frame, for the given key. It returns the old value, if any. It returns NULL if the slot doesn't exist, if there was some other an error, or if there was no old value. Passing in a NULL new_value has the effect of deleting that slot.

KvpValue* kvp_frame_replace_value_nc	(	KvpFrame *	frame,
		const gchar *	slot,
		KvpValue *	new_value
	)

The kvp_frame_replace_value_nc() routine places the new value at the indicated path. It returns the old value, if any. It returns NULL if there was an error, or if there was no old value. If the path doesn't exist, it is created, unless new_value is NULL. Passing in a NULL new_value has the effect of deleting the trailing slot (i.e. the trailing path element).

void kvp_frame_set_double	(	KvpFrame *	frame,
		const gchar *	path,
		double	dval
	)

store the value of the double at the indicated path. If not all frame components of the path exist, they are created.

void kvp_frame_set_gint64	(	KvpFrame *	frame,
		const gchar *	path,
		gint64	ival
	)

store the value of the gint64 at the indicated path. If not all frame components of the path exist, they are created.

void kvp_frame_set_numeric	(	KvpFrame *	frame,
		const gchar *	path,
		gnc_numeric	nval
	)

store the value of the gnc_numeric at the indicated path. If not all frame components of the path exist, they are created.

void kvp_frame_set_slot	(	KvpFrame *	frame,
		const gchar *	key,
		const KvpValue *	value
	)

The kvp_frame_set_slot() routine copies the value into the frame, associating it with a copy of 'key'. Pointers passed as arguments into kvp_frame_set_slot are the responsibility of the caller; the pointers are *not* taken over or managed. The old value at this location, if any, is destroyed.

void kvp_frame_set_slot_nc	(	KvpFrame *	frame,
		const gchar *	key,
		KvpValue *	value
	)

The kvp_frame_set_slot_nc() routine puts the value (without copying it) into the frame, associating it with a copy of 'key'. This routine is handy for avoiding excess memory allocations & frees. Note that because the KvpValue was grabbed, you can't just delete unless you remove the key as well (or unless you replace the value). The old value at this location, if any, is destroyed.

void kvp_frame_set_slot_path	(	KvpFrame *	frame,
		const KvpValue *	value,
		const gchar *	first_key,
			...
	)

The kvp_frame_set_slot_path() routine walks the hierarchy, using the key values to pick each branch. When the terminal node is reached, the value is copied into it. The old value at this location, if any, is destroyed.

void kvp_frame_set_slot_path_gslist	(	KvpFrame *	frame,
		const KvpValue *	value,
		GSList *	key_path
	)

The kvp_frame_set_slot_path_gslist() routine walks the hierarchy, using the key values to pick each branch. When the terminal node is reached, the value is copied into it. The old value at this location, if any, is destroyed.

Definition at line 725 of file kvp_frame.c.

{
  if (!frame || !key_path) return;

  while (TRUE) 
  {
    const char *key = key_path->data;
    KvpValue *value;

    if (!key)
      return;

    g_return_if_fail (*key != '\0');

    key_path = key_path->next;
    if (!key_path) 
    {
      kvp_frame_set_slot (frame, key, new_value);
      return;
    }

    value = kvp_frame_get_slot (frame, key);
    if (!value) 
    {
      KvpFrame *new_frame = kvp_frame_new ();
      KvpValue *frame_value = kvp_value_new_frame (new_frame);

      kvp_frame_set_slot_nc (frame, key, frame_value);

      value = kvp_frame_get_slot (frame, key);
      if (!value)
        return;
    }

    frame = kvp_value_get_frame (value);
    if (!frame)
      return;
  }
}

void kvp_frame_set_string	(	KvpFrame *	frame,
		const gchar *	path,
		const gchar *	str
	)

Store a copy of the string at the indicated path.

If not all frame components of the path exist, they are created. If there was another string previously stored at that path, the old copy is deleted.

Similarly, the set_guid and set_frame will make copies and store those. Old copies, if any, are deleted.

The kvp_frame_set_frame_nc() routine works as above, but does *NOT* copy the frame.

void kvp_frame_set_timespec	(	KvpFrame *	frame,
		const gchar *	path,
		Timespec	ts
	)

store the value of the Timespec at the indicated path. If not all frame components of the path exist, they are created.

KvpFrame* kvp_frame_set_value	(	KvpFrame *	frame,
		const gchar *	path,
		const KvpValue *	value
	)

The kvp_frame_set_value() routine copies the value into the frame, at the location 'path'. If the path contains slashes '/', these are assumed to represent a sequence of keys. The returned value is a pointer to the actual frame into which the value was inserted; it is NULL if the frame couldn't be found (and thus the value wasn't inserted). The old value at this location, if any, is destroyed.

Pointers passed as arguments into this routine are the responsibility of the caller; the pointers are *not* taken over or managed.

KvpFrame* kvp_frame_set_value_nc	(	KvpFrame *	frame,
		const gchar *	path,
		KvpValue *	value
	)

The kvp_frame_set_value_nc() routine puts the value (without copying it) into the frame, putting it at the location 'path'. If the path contains slashes '/', these are assumed to represent a sequence of keys. The returned value is a pointer to the actual frame into which the value was inserted; it is NULL if the frame couldn't be found (and thus the value wasn't inserted). The old value at this location, if any, is destroyed.

This routine is handy for avoiding excess memory allocations & frees. Note that because the KvpValue was grabbed, you can't just delete unless you remove the key as well (or unless you replace the value).

gchar* kvp_frame_to_string

(

const KvpFrame *

frame

)

Internal helper routines, you probably shouldn't be using these.

Definition at line 1819 of file kvp_frame.c.

{
    gchar *tmp1;

    g_return_val_if_fail (frame != NULL, NULL);

    tmp1 = g_strdup_printf("{\n");

    if (frame->hash)
      g_hash_table_foreach(frame->hash, kvp_frame_to_string_helper, &tmp1);

    {
        gchar *tmp2;
        tmp2 = g_strdup_printf("%s}\n", tmp1);
        g_free(tmp1);
        tmp1 = tmp2;
    }

    return tmp1;
}

GList* kvp_glist_copy

(

const GList *

list

)

kvp_glist_copy() performs a deep copy of a GList of kvp_values (not to be confused with GLists of something else): same as mapping kvp_value_copy() over the elements and then copying the spine.

Definition at line 1057 of file kvp_frame.c.

{
  GList * retval = NULL;
  GList * lptr;

  if (!list) return retval;
  
  /* Duplicate the backbone of the list (this duplicates the POINTERS
   * to the values; we need to deep-copy the values separately) */
  retval = g_list_copy((GList *) list);
  
  /* This step deep-copies the values */
  for(lptr = retval; lptr; lptr = lptr->next) 
  {
    lptr->data = kvp_value_copy(lptr->data);
  }
  
  return retval;
}

void kvp_glist_delete

(

GList *

list

)

kvp_glist_delete() performs a deep delete of a GList of kvp_values (not to be confused with GLists of something else): same as mapping * kvp_value_delete() over the elements and then deleting the GList.

Definition at line 1040 of file kvp_frame.c.

{
  GList *node;
  if(!list) return;
  
  /* Delete the data in the list */
  for (node=list; node; node=node->next)
  {
    KvpValue *val = node->data;
    kvp_value_delete(val);
  }
  
  /* Free the backbone */
  g_list_free(list);
}

gboolean kvp_value_binary_append	(	KvpValue *	v,
		void *	data,
		guint64	size
	)

Manipulator:

copying - but more efficient than creating a new KvpValue manually.

gint kvp_value_compare	(	const KvpValue *	va,
		const KvpValue *	vb
	)

Similar returns as strcmp.

Definition at line 1489 of file kvp_frame.c.

{
  if(kva == kvb) return 0;
  /* nothing is always less than something */
  if(!kva && kvb) return -1;
  if(kva && !kvb) return 1;

  if(kva->type < kvb->type) return -1;
  if(kva->type > kvb->type) return 1;

  switch(kva->type) {
  case KVP_TYPE_GINT64:
    if(kva->value.int64 < kvb->value.int64) return -1;
    if(kva->value.int64 > kvb->value.int64) return 1;
    return 0;
    break;
  case KVP_TYPE_DOUBLE:
    return double_compare(kva->value.dbl, kvb->value.dbl);
    break;
  case KVP_TYPE_NUMERIC:
    return gnc_numeric_compare (kva->value.numeric, kvb->value.numeric);
    break;
  case KVP_TYPE_STRING:
    return strcmp(kva->value.str, kvb->value.str);
    break;
  case KVP_TYPE_GUID:
    return guid_compare(kva->value.guid, kvb->value.guid);
    break;
  case KVP_TYPE_TIMESPEC:
    return timespec_cmp(&(kva->value.timespec), &(kvb->value.timespec));
    break;
  case KVP_TYPE_BINARY:
    /* I don't know that this is a good compare. Ab is bigger than Acef.
       But I'm not sure that actually matters here. */
    if(kva->value.binary.datasize < kvb->value.binary.datasize) return -1;
    if(kva->value.binary.datasize > kvb->value.binary.datasize) return 1;
    return memcmp(kva->value.binary.data,
                  kvb->value.binary.data,
                  kva->value.binary.datasize);
    break;
  case KVP_TYPE_GLIST:
    return kvp_glist_compare(kva->value.list, kvb->value.list);
    break;
  case KVP_TYPE_FRAME:
    return kvp_frame_compare(kva->value.frame, kvb->value.frame);
    break;
  }
  PERR ("reached unreachable code.");
  return FALSE;
}

KvpValue* kvp_value_copy

(

const KvpValue *

value

)

This is a deep value copy.

Definition at line 1428 of file kvp_frame.c.

{
  if(!value) return NULL;

  switch(value->type) {
  case KVP_TYPE_GINT64:
    return kvp_value_new_gint64(value->value.int64);
    break;
  case KVP_TYPE_DOUBLE:
    return kvp_value_new_double(value->value.dbl);
    break;
  case KVP_TYPE_NUMERIC:
    return kvp_value_new_gnc_numeric(value->value.numeric);
    break;
  case KVP_TYPE_STRING:
    return kvp_value_new_string(value->value.str);
    break;
  case KVP_TYPE_GUID:
    return kvp_value_new_guid(value->value.guid);
    break;
  case KVP_TYPE_TIMESPEC:
    return kvp_value_new_timespec(value->value.timespec);
    break;
  case KVP_TYPE_BINARY:
    return kvp_value_new_binary(value->value.binary.data,
                                value->value.binary.datasize);
    break;
  case KVP_TYPE_GLIST:
    return kvp_value_new_glist(value->value.list);
    break;
  case KVP_TYPE_FRAME:
    return kvp_value_new_frame(value->value.frame);
    break;
  }  
  return NULL;
}

void kvp_value_delete

(

KvpValue *

value

)

This is a deep (recursive) delete.

Definition at line 1246 of file kvp_frame.c.

{
  if(!value) return;

  switch(value->type) 
  {
  case KVP_TYPE_STRING:
    g_free(value->value.str);
    break;
  case KVP_TYPE_GUID:
    g_free(value->value.guid);
    break;
  case KVP_TYPE_BINARY:
    g_free(value->value.binary.data);
    break;
  case KVP_TYPE_GLIST:
    kvp_glist_delete(value->value.list);
    break;
  case KVP_TYPE_FRAME:
    kvp_frame_delete(value->value.frame);
    break;
    
  case KVP_TYPE_GINT64:    
  case KVP_TYPE_DOUBLE:
  case KVP_TYPE_NUMERIC:
  default:
    break;
  }
  g_free(value);
}

void* kvp_value_get_binary	(	const KvpValue *	value,
		guint64 *	size_return
	)

Value accessor. This one is non-copying -- the caller can modify the value directly.

Definition at line 1356 of file kvp_frame.c.

{
  if (!value)
  {
    if (size_return)
      *size_return = 0;
    return NULL;
  }

  if(value->type == KVP_TYPE_BINARY) {
    if (size_return)
      *size_return = value->value.binary.datasize;
    return value->value.binary.data;
  }
  else {
    if (size_return)
      *size_return = 0;
    return NULL;
  }
}

KvpFrame* kvp_value_get_frame

(

const KvpValue *

value

)

Value accessor. This one is non-copying -- the caller can modify the value directly.

Definition at line 1390 of file kvp_frame.c.

{
  if (!value) return NULL;
  if(value->type == KVP_TYPE_FRAME) {
    return value->value.frame;
  }
  else {
    return NULL;
  }
}

gint64 kvp_value_get_gint64

(

const KvpValue *

value

)

Value accessors. Those for GUID, binary, GList, KvpFrame and string are non-copying -- the caller can modify the value directly. Just don't free it, or you screw up everything. Note that if another value is stored at the key location that this value came from, then this value will be uncermoniously deleted, and you will be left pointing to garbage. So don't store values at the same time you are examining their contents.

Definition at line 1285 of file kvp_frame.c.

{
  if (!value) return 0;
  if(value->type == KVP_TYPE_GINT64) {
    return value->value.int64;
  }
  else {
    return 0;
  }
}

GList* kvp_value_get_glist

(

const KvpValue *

value

)

Returns the GList of kvp_frame's (not to be confused with GList's of something else!) from the given kvp_frame. This one is non-copying -- the caller can modify the value directly.

Definition at line 1378 of file kvp_frame.c.

{
  if (!value) return NULL;
  if(value->type == KVP_TYPE_GLIST) {
    return value->value.list;
  }
  else {
    return NULL;
  }
}

GUID* kvp_value_get_guid

(

const KvpValue *

value

)

Value accessor. This one is non-copying -- the caller can modify the value directly.

Definition at line 1333 of file kvp_frame.c.

{
  if (!value) return NULL;
  if(value->type == KVP_TYPE_GUID) {
    return value->value.guid;
  }
  else {
    return NULL;
  }
}

char* kvp_value_get_string

(

const KvpValue *

value

)

Value accessor. This one is non-copying -- the caller can modify the value directly.

Definition at line 1321 of file kvp_frame.c.

{
  if (!value) return NULL;
  if(value->type == KVP_TYPE_STRING) {
    return value->value.str;
  }
  else { 
    return NULL; 
  }
}

KvpValue* kvp_value_new_binary_nc	(	void *	data,
		guint64	datasize
	)

value constructors (non-copying - KvpValue takes pointer ownership) values *must* have been allocated via glib allocators! (gnew, etc.)

Definition at line 1185 of file kvp_frame.c.

{
  KvpValue * retval;
  if (!value) return NULL;

  retval = g_new0(KvpValue, 1);
  retval->type = KVP_TYPE_BINARY;
  retval->value.binary.data = value;
  retval->value.binary.datasize = datasize;
  return retval;
}

KvpValue* kvp_value_new_frame_nc

(

KvpFrame *

value

)

value constructors (non-copying - KvpValue takes pointer ownership) values *must* have been allocated via glib allocators! (gnew, etc.)

Definition at line 1234 of file kvp_frame.c.

{
  KvpValue * retval;
  if (!value) return NULL;

  retval  = g_new0(KvpValue, 1);
  retval->type        = KVP_TYPE_FRAME;
  retval->value.frame = value;
  return retval;  
}

KvpValue* kvp_value_new_glist

(

const GList *

value

)

Creates a KvpValue from a GList of kvp_value's! (Not to be confused with GList's of something else!)

Definition at line 1198 of file kvp_frame.c.

{
  KvpValue * retval;
  if (!value) return NULL;

  retval = g_new0(KvpValue, 1);
  retval->type       = KVP_TYPE_GLIST;
  retval->value.list = kvp_glist_copy(value);
  return retval;
}  

KvpValue* kvp_value_new_glist_nc

(

GList *

lst

)

Creates a KvpValue from a GList of kvp_value's! (Not to be confused with GList's of something else!)

This value constructor is non-copying (KvpValue takes pointer ownership). The values *must* have been allocated via glib allocators! (gnew, etc.)

Definition at line 1210 of file kvp_frame.c.

{
  KvpValue * retval;
  if (!value) return NULL;

  retval = g_new0(KvpValue, 1);
  retval->type       = KVP_TYPE_GLIST;
  retval->value.list = value;
  return retval;
}  

KvpFrame* kvp_value_replace_frame_nc	(	KvpValue *	value,
		KvpFrame *	newframe
	)

Replace old frame value with new, return old frame

Definition at line 1402 of file kvp_frame.c.

{
  KvpFrame *oldframe;
  if (!value) return NULL;
  if (KVP_TYPE_FRAME != value->type) return NULL;

  oldframe = value->value.frame;
  value->value.frame = newframe;
  return oldframe;  
}

GList* kvp_value_replace_glist_nc	(	KvpValue *	value,
		GList *	newlist
	)

Replace old glist value with new, return old glist

Definition at line 1414 of file kvp_frame.c.

{
  GList *oldlist;
  if (!value) return NULL;
  if (KVP_TYPE_GLIST != value->type) return NULL;

  oldlist = value->value.list;
  value->value.list = newlist;
  return oldlist;
}

gchar* kvp_value_to_bare_string

(

const KvpValue *

val

)

General purpose function to convert any KvpValue to a string.

Only the bare string is returned, there is no debugging information.

Definition at line 1641 of file kvp_frame.c.

{
    gchar *tmp1;
    gchar *tmp2;
    const gchar *ctmp;
    
    g_return_val_if_fail(val, NULL);
    tmp1 = g_strdup("");
    switch(kvp_value_get_type(val))
    {
    case KVP_TYPE_GINT64:
        return g_strdup_printf("%" G_GINT64_FORMAT, kvp_value_get_gint64(val));
        break;

    case KVP_TYPE_DOUBLE:
        return g_strdup_printf("(%g)", kvp_value_get_double(val));
        break;

    case KVP_TYPE_NUMERIC:
        tmp1 = gnc_numeric_to_string(kvp_value_get_numeric(val));
        tmp2 = g_strdup_printf("%s", tmp1 ? tmp1 : "");
        g_free(tmp1);
        return tmp2;
        break;

    case KVP_TYPE_STRING:
        tmp1 = kvp_value_get_string (val);
        return g_strdup_printf("%s", tmp1 ? tmp1 : "");
        break;

    case KVP_TYPE_GUID:
        ctmp = guid_to_string(kvp_value_get_guid(val));
        tmp2 = g_strdup_printf("%s", ctmp ? ctmp : "");
        return tmp2;
        break;

    case KVP_TYPE_TIMESPEC:
        {
                time_t t;
                t = timespecToTime_t(kvp_value_get_timespec(val));
        qof_date_format_set(QOF_DATE_FORMAT_UTC);
        return qof_print_date(t);
        break;
        }
    case KVP_TYPE_BINARY:
    {
        guint64 len;
        void *data;
        data = kvp_value_get_binary(val, &len);
        tmp1 = binary_to_string(data, len);
        return g_strdup_printf("%s", tmp1 ? tmp1 : "");
    }
        break;
 
    case KVP_TYPE_GLIST:
                /* borked. kvp_value_glist_to_string is a debug fcn */
        {
        tmp1 = kvp_value_glist_to_string(kvp_value_get_glist(val));
        tmp2 = g_strdup_printf("%s", tmp1 ? tmp1 : "");
        g_free(tmp1);
        return tmp2;
        break;
        }
    case KVP_TYPE_FRAME:
        {
                KvpFrame *frame;

                frame = kvp_value_get_frame(val);
                if (frame->hash) {
                        tmp1 = g_strdup("");
                        g_hash_table_foreach(frame->hash, kvp_frame_to_bare_string_helper, &tmp1);
                }
        return tmp1;
        break;
        }
    default:
        return g_strdup_printf(" ");
        break;
    }
}

gchar* kvp_value_to_string

(

const KvpValue *

val

)

Debug version of kvp_value_to_string.

This version is used only by qof_query_printValueForParam, itself a debugging and development utility function.

Definition at line 1723 of file kvp_frame.c.

{
    gchar *tmp1;
    gchar *tmp2;
    const gchar *ctmp;
    
    g_return_val_if_fail(val, NULL);
    
    switch(kvp_value_get_type(val))
    {
    case KVP_TYPE_GINT64:
        return g_strdup_printf("KVP_VALUE_GINT64(%" G_GINT64_FORMAT ")",
                               kvp_value_get_gint64(val));
        break;

    case KVP_TYPE_DOUBLE:
        return g_strdup_printf("KVP_VALUE_DOUBLE(%g)",
                               kvp_value_get_double(val));
        break;

    case KVP_TYPE_NUMERIC:
        tmp1 = gnc_numeric_to_string(kvp_value_get_numeric(val));
        tmp2 = g_strdup_printf("KVP_VALUE_NUMERIC(%s)", tmp1 ? tmp1 : "");
        g_free(tmp1);
        return tmp2;
        break;

    case KVP_TYPE_STRING:
        tmp1 = kvp_value_get_string (val);
        return g_strdup_printf("KVP_VALUE_STRING(%s)", tmp1 ? tmp1 : "");
        break;

    case KVP_TYPE_GUID:
                /* THREAD-UNSAFE */
        ctmp = guid_to_string(kvp_value_get_guid(val));
        tmp2 = g_strdup_printf("KVP_VALUE_GUID(%s)", ctmp ? ctmp : "");
        return tmp2;
        break;

    case KVP_TYPE_TIMESPEC:
        tmp1 = g_new0 (char, 40);
        gnc_timespec_to_iso8601_buff (kvp_value_get_timespec (val), tmp1);
        tmp2 = g_strdup_printf("KVP_VALUE_TIMESPEC(%s)", tmp1);
        g_free(tmp1);
        return tmp2;
        break;

    case KVP_TYPE_BINARY:
    {
        guint64 len;
        void *data;
        data = kvp_value_get_binary(val, &len);
        tmp1 = binary_to_string(data, len);
        return g_strdup_printf("KVP_VALUE_BINARY(%s)", tmp1 ? tmp1 : "");
    }
        break;
 
    case KVP_TYPE_GLIST:
        tmp1 = kvp_value_glist_to_string(kvp_value_get_glist(val));
        tmp2 = g_strdup_printf("KVP_VALUE_GLIST(%s)", tmp1 ? tmp1 : "");
        g_free(tmp1);
        return tmp2;
        break;

    case KVP_TYPE_FRAME:
        tmp1 = kvp_frame_to_string(kvp_value_get_frame(val));
        tmp2 = g_strdup_printf("KVP_VALUE_FRAME(%s)", tmp1 ? tmp1 : "");
        g_free(tmp1);
        return tmp2;
        break;

    default:
        return g_strdup_printf(" ");
        break;
    }
}