QOF  0.7.5
KVP: Key-Value Pairs

Files

file  kvpframe.h
 A key-value frame system.
 
file  kvputil-p.h
 misc odd-job kvp utils engine-private routines
 
file  kvputil.h
 QOF KVP utility functions.
 

Data Structures

struct  GHashTableKVPair
 

Macros

#define QOF_MOD_KVP   "qof-kvp"
 

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_TIME, KVP_TYPE_BINARY,
  KVP_TYPE_GLIST, KVP_TYPE_FRAME, KVP_TYPE_BOOLEAN
}
 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. More...
 
gchar * kvp_value_to_string (const KvpValue *val)
 Debug version. More...
 
gboolean kvp_value_binary_append (KvpValue *v, gpointer data, guint64 size)
 
gint kvp_frame_compare (const KvpFrame *fa, const KvpFrame *fb)
 
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)
 

KvpFrame Constructors

KvpFramekvp_frame_new (void)
 
void kvp_frame_delete (KvpFrame *frame)
 
KvpFramekvp_frame_copy (const KvpFrame *frame)
 
gboolean kvp_frame_is_empty (KvpFrame *frame)
 

KvpFrame Basic Value Storing

void kvp_frame_set_gint64 (KvpFrame *frame, const gchar *path, gint64 ival)
 store the value of the gint64 at the indicated path. More...
 
void kvp_frame_set_double (KvpFrame *frame, const gchar *path, gdouble dval)
 store the value of the double at the indicated path. More...
 
void kvp_frame_set_numeric (KvpFrame *frame, const gchar *path, QofNumeric nval)
 store the value of the QofNumeric at the indicated path. More...
 
void kvp_frame_set_string (KvpFrame *frame, const gchar *path, const gchar *str)
 Store a copy of the string at the indicated path. More...
 
void kvp_frame_set_guid (KvpFrame *frame, const gchar *path, const GUID *guid)
 Store a copy of the GUID at the indicated path. More...
 
void kvp_frame_set_time (KvpFrame *frame, const gchar *path, QofTime *qt)
 Store a copy of the QofTime at the indicated path. More...
 
void kvp_frame_set_boolean (KvpFrame *frame, const gchar *path, gboolean val)
 Store the value of the boolean at the indicated path. More...
 
void kvp_frame_set_frame (KvpFrame *frame, const gchar *path, KvpFrame *chld)
 Store a copy of the KvpFrame at the indicated path. More...
 
void kvp_frame_set_frame_nc (KvpFrame *frame, const gchar *path, KvpFrame *chld)
 Store a KvpFrame at the indicated path without copying. More...
 
KvpFramekvp_frame_set_value (KvpFrame *frame, const gchar *path, const KvpValue *value)
 Copy the KvpValue into the frame. More...
 
KvpFramekvp_frame_set_value_nc (KvpFrame *frame, const gchar *path, KvpValue *value)
 Store the KvpValue in the frame without copying. More...
 
KvpValuekvp_frame_replace_value_nc (KvpFrame *frame, const gchar *slot, KvpValue *new_value)
 

KvpFrame Glist Bag Storing

void kvp_frame_add_gint64 (KvpFrame *frame, const gchar *path, gint64 ival)
 add the value of the gint64 to the glist bag More...
 
void kvp_frame_add_double (KvpFrame *frame, const gchar *path, gdouble dval)
 Add the value of the double to the glist bag. More...
 
void kvp_frame_add_numeric (KvpFrame *frame, const gchar *path, QofNumeric nval)
 Add the value of the QofNumeric to the glist bag. More...
 
void kvp_frame_add_time (KvpFrame *frame, const gchar *path, QofTime *qt)
 Add the value of the QofTime to the glist bag. More...
 
void kvp_frame_add_string (KvpFrame *frame, const gchar *path, const gchar *str)
 Copy the string to the glist bag at the indicated path. More...
 
void kvp_frame_add_boolean (KvpFrame *frame, const gchar *path, gboolean val)
 
void kvp_frame_add_guid (KvpFrame *frame, const gchar *path, const GUID *guid)
 Copy the GUID to the glist bag at the indicated path. More...
 
void kvp_frame_add_frame (KvpFrame *frame, const gchar *path, KvpFrame *chld)
 Copy the frame to the glist bag at the indicated path. More...
 
void kvp_frame_add_frame_nc (KvpFrame *frame, const gchar *path, KvpFrame *chld)
 Add the frame to the glist bag without copying. More...
 
KvpFramekvp_frame_add_value (KvpFrame *frame, const gchar *path, KvpValue *value)
 Add a copy of the value to the glist bag. More...
 
KvpFramekvp_frame_add_value_nc (KvpFrame *frame, const gchar *path, KvpValue *value)
 

KvpFrame Value Fetching

Value accessors. These all take a unix-style slash-separated path as an argument, and return the value stored at that location. If the object at the end of that path is not of the type that was asked for, then a NULL or a zero is returned. So, for example, asking for a string when the path stored an int will return a NULL. In some future date, this may be changed to a looser type system, such as perl's automatic re-typing (e.g. an integer value might be converted to a printed string representing that value).

If any part of the path does not exist, then NULL or zero will be returned.

The values returned for GUID, binary, GList, KvpFrame and string are "non-copying" – the returned item is the actual item stored. Do not delete this item unless you take the required care to avoid possible bad pointer derefrences (i.e. core dumps). Also, be careful hanging on to those references if you are also storing at the same path names: the referenced item will be freed during the store.

That is, if you get a string value (or guid, binary or frame), and then store something else at that path, the string that you've gotten will be freed during the store (internally, by the set_*() routines), and you will be left hanging onto an invalid pointer.

gint64 kvp_frame_get_gint64 (const KvpFrame *frame, const gchar *path)
 
gdouble kvp_frame_get_double (const KvpFrame *frame, const gchar *path)
 
QofNumeric kvp_frame_get_numeric (const KvpFrame *frame, const gchar *path)
 
gchar * kvp_frame_get_string (const KvpFrame *frame, const gchar *path)
 
GUIDkvp_frame_get_guid (const KvpFrame *frame, const gchar *path)
 
gpointer kvp_frame_get_binary (const KvpFrame *frame, const gchar *path, guint64 *size_return)
 
gboolean kvp_frame_get_boolean (const KvpFrame *frame, const gchar *path)
 
QofTimekvp_frame_get_time (const KvpFrame *frame, const gchar *path)
 
KvpValuekvp_frame_get_value (const KvpFrame *frame, const gchar *path)
 
KvpFramekvp_frame_get_frame (const KvpFrame *frame, const gchar *path)
 
KvpFramekvp_frame_get_frame_path (KvpFrame *frame, const gchar *,...)
 
KvpFramekvp_frame_get_frame_gslist (KvpFrame *frame, GSList *key_path)
 
KvpFramekvp_frame_get_frame_slash (KvpFrame *frame, const gchar *path)
 

KvpFrame KvpValue low-level storing routines.

You probably shouldn't be using these low-level routines

All of the kvp_frame_set_slot_*() routines set the slot values
"destructively", in that if there was an old value there, that
old value is destroyed (and the memory freed).  Thus, one 
should not hang on to value pointers, as these will get 
trashed if set_slot is called on the corresponding key.

If you want the old value, use kvp_frame_replace_slot().
KvpValuekvp_frame_replace_slot_nc (KvpFrame *frame, const gchar *slot, KvpValue *new_value)
 
void kvp_frame_set_slot (KvpFrame *frame, const gchar *key, const KvpValue *value)
 
void kvp_frame_set_slot_nc (KvpFrame *frame, const gchar *key, KvpValue *value)
 
void kvp_frame_set_slot_path (KvpFrame *frame, const KvpValue *value, const gchar *first_key,...)
 
void kvp_frame_set_slot_path_gslist (KvpFrame *frame, const KvpValue *value, GSList *key_path)
 

KvpFrame KvpValue Low-Level Retrieval Routines

You probably shouldn't be using these low-level routines

Returns the KvpValue in the given KvpFrame 'frame' that is associated with 'key'. If there is no key in the frame, NULL is returned. If the value associated with the key is NULL, NULL is returned.

Pointers passed as arguments into get_slot are the responsibility of the caller. Pointers returned by get_slot are owned by the kvp_frame. Make copies as needed.

KvpValuekvp_frame_get_slot (const KvpFrame *frame, const gchar *key)
 
KvpValuekvp_frame_get_slot_path (KvpFrame *frame, const gchar *first_key,...)
 
KvpValuekvp_frame_get_slot_path_gslist (KvpFrame *frame, GSList *key_path)
 
gint kvp_glist_compare (const GList *list1, const GList *list2)
 
GList * kvp_glist_copy (const GList *list)
 
void kvp_glist_delete (GList *list)
 

KvpValue Constructors

The following routines are constructors for kvp_value. Those with pointer arguments copy in the value. The *_nc() versions do not copy in their values, but use them directly.

KvpValuekvp_value_new_gint64 (gint64 value)
 
KvpValuekvp_value_new_double (double value)
 
KvpValuekvp_value_new_numeric (QofNumeric value)
 
KvpValuekvp_value_new_string (const gchar *value)
 
KvpValuekvp_value_new_guid (const GUID *guid)
 
KvpValuekvp_value_new_time (QofTime *value)
 
KvpValuekvp_value_new_boolean (gboolean value)
 
KvpValuekvp_value_new_binary (const void *data, guint64 datasize)
 
KvpValuekvp_value_new_frame (const KvpFrame *value)
 
KvpValuekvp_value_new_glist (const GList *value)
 
KvpValuekvp_value_new_binary_nc (void *data, guint64 datasize)
 
KvpValuekvp_value_new_glist_nc (GList *lst)
 
KvpValuekvp_value_new_frame_nc (KvpFrame *value)
 
void kvp_value_delete (KvpValue *value)
 
KvpValuekvp_value_copy (const KvpValue *value)
 
KvpFramekvp_value_replace_frame_nc (KvpValue *value, KvpFrame *newframe)
 
GList * kvp_value_replace_glist_nc (KvpValue *value, GList *newlist)
 

KvpValue Value access

KvpValueType kvp_value_get_type (const KvpValue *value)
 
gint64 kvp_value_get_gint64 (const KvpValue *value)
 
gdouble kvp_value_get_double (const KvpValue *value)
 
QofNumeric kvp_value_get_numeric (const KvpValue *value)
 
gchar * kvp_value_get_string (const KvpValue *value)
 
GUIDkvp_value_get_guid (const KvpValue *value)
 
gpointer kvp_value_get_binary (const KvpValue *value, guint64 *size_return)
 
GList * kvp_value_get_glist (const KvpValue *value)
 
KvpFramekvp_value_get_frame (const KvpValue *value)
 
gboolean kvp_value_get_boolean (const KvpValue *value)
 
QofTimekvp_value_get_time (const KvpValue *value)
 
gint kvp_value_compare (const KvpValue *va, const KvpValue *vb)
 

Iterators

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

KvpBag Bags of GUID Pointers

KvpFrameqof_kvp_bag_add (KvpFrame *kvp_root, const gchar *path, QofTime *qt, const gchar *first_name,...)
 
void qof_kvp_bag_merge (KvpFrame *kvp_into, const gchar *intopath, KvpFrame *kvp_from, const gchar *frompath)
 
KvpFrameqof_kvp_bag_find_by_guid (KvpFrame *root, const gchar *path, const gchar *guid_name, GUID *desired_guid)
 
void qof_kvp_bag_remove_frame (KvpFrame *root, const gchar *path, KvpFrame *fr)
 

Hash Utilities

GSList * g_hash_table_key_value_pairs (GHashTable *table)
 
void g_hash_table_kv_pair_free_gfunc (gpointer data, gpointer user_data)
 

KvpFrame URL handling

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

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.

Typedef Documentation

typedef struct _KvpFrame KvpFrame

Opaque frame structure

Definition at line 74 of file kvpframe.h.

typedef struct _KvpValue KvpValue

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

Definition at line 78 of file kvpframe.h.

typedef void(* KvpValueForeachCB)(const gchar *key, KvpValue *value, gpointer data)
Since
0.7.2

Definition at line 770 of file kvpframe.h.

Enumeration Type Documentation

possible types in the union KvpValue

Todo:
In the long run, this could be synchronised with the core QOF types, which in turn may or may not be synced to the GValue types in GLib. The QOF types currently unsupported are KVP_TYPE_GLIST and KVP_TYPE_BINARY.
Enumerator
KVP_TYPE_GINT64 

64bit integer

  • QofType : QOF_TYPE_INT64
  • GType : G_TYPE_INT64
  • GLib type : gint64
KVP_TYPE_DOUBLE 

standard C double type

  • QofType : QOF_TYPE_DOUBLE
  • GType : G_TYPE_DOUBLE
  • GLib type : gdouble
KVP_TYPE_NUMERIC 

128bit denominator/numerator maths.

  • QofType : QOF_TYPE_NUMERIC
  • GType : no direct equivalent, consider QOF_TYPE_DOUBLE
  • GLib type : no direct equivalent, consider QOF_TYPE_DOUBLE
KVP_TYPE_STRING 

standard C string

  • QofType : QOF_TYPE_STRING
  • GType : G_TYPE_STRING
  • GLib type : gchar*
KVP_TYPE_GUID 

Unique identifier.

  • QofType : QOF_TYPE_GUID
  • GType : no direct equivalent, can be stored as QOF_TYPE_STRING
  • GLib : no direct equivalent, can be stored as QOF_TYPE_STRING
KVP_TYPE_TIMESPEC 
Deprecated:
QOF_TYPE_DATE
KVP_TYPE_TIME 

64bit time/date handling.

  • QofType : QOF_TYPE_TIME
  • GType : No equivalent.
  • GLib type : GDate (not fully equivalent, see QofTime)
KVP_TYPE_BINARY 

no QofType/GType/GLib equivalent.

KVP_TYPE_GLIST 

no QofType/GType equivalent.

KVP_TYPE_FRAME 

no QofType/GType/GLib equivalent.

KVP_TYPE_BOOLEAN 

Simple boolean type.

  • QofType : QOF_TYPE_BOOLEAN
  • GType : G_TYPE_BOOLEAN
  • GLib type : gboolean

Definition at line 87 of file kvpframe.h.

88 {
94  KVP_TYPE_GINT64 = 1,
119 #ifndef QOF_DISABLE_DEPRECATED
120 
122 #endif
123 
141 } 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 212 of file kvputil.c.

213 {
214  GSList *result_list = NULL;
215  g_hash_table_foreach (table, kv_pair_helper, &result_list);
216  return result_list;
217 }
void kvp_frame_add_double ( KvpFrame frame,
const gchar *  path,
gdouble  dval 
)

Add the value of the double to the glist bag.

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.

Definition at line 601 of file kvpframe.c.

602 {
603  KvpValue *value;
604  value = kvp_value_new_double (dval);
605  frame = kvp_frame_add_value_nc (frame, path, value);
606  if (!frame)
607  kvp_value_delete (value);
608 }
void kvp_frame_add_frame ( KvpFrame frame,
const gchar *  path,
KvpFrame chld 
)

Copy the frame 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.

Definition at line 662 of file kvpframe.c.

663 {
664  KvpValue *value;
665  value = kvp_value_new_frame (fr);
666  frame = kvp_frame_add_value_nc (frame, path, value);
667  if (!frame)
668  kvp_value_delete (value);
669 }
void kvp_frame_add_frame_nc ( KvpFrame frame,
const gchar *  path,
KvpFrame chld 
)

Add the frame to the glist bag without copying.

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.

Definition at line 672 of file kvpframe.c.

673 {
674  KvpValue *value;
675  value = kvp_value_new_frame_nc (fr);
676  frame = kvp_frame_add_value_nc (frame, path, value);
677  if (!frame)
678  kvp_value_delete (value);
679 }
void kvp_frame_add_gint64 ( KvpFrame frame,
const gchar *  path,
gint64  ival 
)

add the value of the gint64 to the glist bag

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.

Definition at line 591 of file kvpframe.c.

592 {
593  KvpValue *value;
594  value = kvp_value_new_gint64 (ival);
595  frame = kvp_frame_add_value_nc (frame, path, value);
596  if (!frame)
597  kvp_value_delete (value);
598 }
void kvp_frame_add_guid ( KvpFrame frame,
const gchar *  path,
const GUID guid 
)

Copy the GUID 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.

Definition at line 652 of file kvpframe.c.

653 {
654  KvpValue *value;
655  value = kvp_value_new_guid (guid);
656  frame = kvp_frame_add_value_nc (frame, path, value);
657  if (!frame)
658  kvp_value_delete (value);
659 }
void kvp_frame_add_numeric ( KvpFrame frame,
const gchar *  path,
QofNumeric  nval 
)

Add the value of the QofNumeric to the glist bag.

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.

Definition at line 611 of file kvpframe.c.

613 {
614  KvpValue *value;
615  value = kvp_value_new_numeric (nval);
616  frame = kvp_frame_add_value_nc (frame, path, value);
617  if (!frame)
618  kvp_value_delete (value);
619 }
void kvp_frame_add_string ( KvpFrame frame,
const gchar *  path,
const gchar *  str 
)

Copy 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.

Definition at line 642 of file kvpframe.c.

643 {
644  KvpValue *value;
645  value = kvp_value_new_string (str);
646  frame = kvp_frame_add_value_nc (frame, path, value);
647  if (!frame)
648  kvp_value_delete (value);
649 }
void kvp_frame_add_time ( KvpFrame frame,
const gchar *  path,
QofTime qt 
)

Add the value of the QofTime to the glist bag.

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.

Definition at line 622 of file kvpframe.c.

623 {
624  KvpValue *value;
625  value = kvp_value_new_time (qt);
626  frame = kvp_frame_add_value_nc (frame, path, value);
627  if (!frame)
628  kvp_value_delete (value);
629 }
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.

Definition at line 880 of file kvpframe.c.

881 {
882  gchar *buff, *p;
883  if (!frame || !enc)
884  return;
885 
886  /* Loop over all key-value pairs in the encoded string */
887  buff = g_strdup (enc);
888  p = buff;
889  while (*p)
890  {
891  gchar *n, *v;
892  n = strchr (p, '&'); /* n = next key-value */
893  if (n)
894  *n = 0x0;
895 
896  v = strchr (p, '='); /* v = pointer to value */
897  if (!v)
898  break;
899  *v = 0x0;
900  v++;
901 
902  decode (p);
903  decode (v);
904  kvp_frame_set_slot_nc (frame, p, kvp_value_new_string (v));
905 
906  if (!n)
907  break; /* no next key, we are done */
908  p = ++n;
909  }
910 
911  g_free (buff);
912 }
KvpFrame* kvp_frame_add_value ( KvpFrame frame,
const gchar *  path,
KvpValue value 
)

Add a copy of the value to the glist bag.

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. This routine returns the pointer to the last frame (the actual frame to which the value was added), or NULL if there was an error of any sort (typically, a parse error in the path).

Definition at line 581 of file kvpframe.c.

582 {
583  value = kvp_value_copy (value);
584  frame = kvp_frame_add_value_nc (frame, path, value);
585  if (!frame)
586  kvp_value_delete (value);
587  return frame;
588 }
gint kvp_frame_compare ( const KvpFrame fa,
const KvpFrame fb 
)

Similar returns as strcmp.

Definition at line 1757 of file kvpframe.c.

1758 {
1759  KvpFrameCompare status;
1760 
1761  if (fa == fb)
1762  return 0;
1763  /* nothing is always less than something */
1764  if (!fa && fb)
1765  return -1;
1766  if (fa && !fb)
1767  return 1;
1768 
1769  /* nothing is always less than something */
1770  if (!fa->hash && fb->hash)
1771  return -1;
1772  if (fa->hash && !fb->hash)
1773  return 1;
1774 
1775  status.compare = 0;
1776  status.other_frame = (KvpFrame *) fb;
1777 
1778  kvp_frame_for_each_slot ((KvpFrame *) fa, kvp_frame_compare_helper,
1779  &status);
1780 
1781  if (status.compare != 0)
1782  return status.compare;
1783 
1784  status.other_frame = (KvpFrame *) fa;
1785 
1786  kvp_frame_for_each_slot ((KvpFrame *) fb, kvp_frame_compare_helper,
1787  &status);
1788 
1789  return (-status.compare);
1790 }
KvpFrame* kvp_frame_copy ( const KvpFrame frame)

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

Definition at line 156 of file kvpframe.c.

157 {
158  KvpFrame *retval = kvp_frame_new ();
159 
160  if (!frame)
161  return retval;
162 
163  if (frame->hash)
164  {
165  if (!init_frame_body_if_needed (retval))
166  return (NULL);
167  g_hash_table_foreach (frame->hash,
168  &kvp_frame_copy_worker, (gpointer) retval);
169  }
170  return retval;
171 }
void kvp_frame_delete ( KvpFrame frame)

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

Definition at line 118 of file kvpframe.c.

119 {
120  if (!frame)
121  return;
122 
123  if (frame->hash)
124  {
125  /* free any allocated resource for frame or its children */
126  g_hash_table_foreach (frame->hash, &kvp_frame_delete_worker,
127  (gpointer) frame);
128 
129  /* delete the hash table */
130  g_hash_table_destroy (frame->hash);
131  frame->hash = NULL;
132  }
133  g_free (frame);
134 }
void kvp_frame_for_each_slot ( KvpFrame f,
KvpValueForeachCB  ,
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.

Definition at line 1650 of file kvpframe.c.

1651 {
1652  if (!f)
1653  return;
1654  if (!proc)
1655  return;
1656  if (!(f->hash))
1657  return;
1658  g_hash_table_foreach (f->hash, (GHFunc) proc, data);
1659 }
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.

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

Definition at line 984 of file kvpframe.c.

985 {
986  gchar *key = NULL;
987  frame = get_trailer_or_null (frame, path, &key);
988  return kvp_value_get_frame (kvp_frame_get_slot (frame, key));
989 }
KvpFrame* kvp_frame_get_frame_gslist ( KvpFrame frame,
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 1002 of file kvpframe.c.

1003 {
1004  if (!frame)
1005  return frame;
1006 
1007  while (key_path)
1008  {
1009  const gchar *key = key_path->data;
1010 
1011  if (!key)
1012  return frame; /* an unusual but valid exit for this routine. */
1013 
1014  frame = get_or_make (frame, key);
1015  if (!frame)
1016  return frame; /* this should never happen */
1017 
1018  key_path = key_path->next;
1019  }
1020  return frame; /* this is the normal exit for this func */
1021 }
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 kvp_frame_get_frame()

Definition at line 1024 of file kvpframe.c.

1025 {
1026  va_list ap;
1027  if (!frame || !key)
1028  return frame;
1029 
1030  va_start (ap, key);
1031 
1032  while (key)
1033  {
1034  frame = get_or_make (frame, key);
1035  if (!frame)
1036  break; /* error, should never occur */
1037  key = va_arg (ap, const char *);
1038  }
1039 
1040  va_end (ap);
1041  return frame;
1042 }
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).

Definition at line 1045 of file kvpframe.c.

1046 {
1047  gchar *root;
1048  if (!frame || !key_path)
1049  return frame;
1050 
1051  root = g_strdup (key_path);
1052  frame = kvp_frame_get_frame_slash_trash (frame, root);
1053  g_free (root);
1054  return frame;
1055 }
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.

Definition at line 1060 of file kvpframe.c.

1061 {
1062  va_list ap;
1063  KvpValue *value;
1064  const gchar *key;
1065 
1066  if (!frame || !first_key)
1067  return NULL;
1068 
1069  va_start (ap, first_key);
1070 
1071  key = first_key;
1072  value = NULL;
1073 
1074  while (TRUE)
1075  {
1076  value = kvp_frame_get_slot (frame, key);
1077  if (!value)
1078  break;
1079 
1080  key = va_arg (ap, const gchar *);
1081  if (!key)
1082  break;
1083 
1084  frame = kvp_value_get_frame (value);
1085  if (!frame)
1086  {
1087  value = NULL;
1088  break;
1089  }
1090  }
1091 
1092  va_end (ap);
1093 
1094  return value;
1095 }
KvpValue* kvp_frame_get_slot_path_gslist ( KvpFrame frame,
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 1098 of file kvpframe.c.

1099 {
1100  if (!frame || !key_path)
1101  return NULL;
1102 
1103  while (TRUE)
1104  {
1105  const gchar *key = key_path->data;
1106  KvpValue *value;
1107 
1108  if (!key)
1109  return NULL;
1110 
1111  value = kvp_frame_get_slot (frame, key);
1112  if (!value)
1113  return NULL;
1114 
1115  key_path = key_path->next;
1116  if (!key_path)
1117  return value;
1118 
1119  frame = kvp_value_get_frame (value);
1120  if (!frame)
1121  return NULL;
1122  }
1123 }
gboolean kvp_frame_is_empty ( KvpFrame frame)

Return TRUE if the KvpFrame is empty

Definition at line 137 of file kvpframe.c.

138 {
139  if (!frame)
140  return TRUE;
141  if (!frame->hash)
142  return TRUE;
143  return FALSE;
144 }
KvpFrame* kvp_frame_new ( void  )

Return a new empty instance of KvpFrame

Definition at line 100 of file kvpframe.c.

101 {
102  KvpFrame *retval = g_new0 (KvpFrame, 1);
103 
104  /* Save space until the frame is actually used */
105  retval->hash = NULL;
106  return retval;
107 }
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.

Definition at line 178 of file kvpframe.c.

180 {
181  gpointer orig_key;
182  gpointer orig_value = NULL;
183  int key_exists;
184 
185  if (!frame || !slot)
186  return NULL;
187  if (!init_frame_body_if_needed (frame))
188  return NULL; /* Error ... */
189 
190  key_exists = g_hash_table_lookup_extended (frame->hash, slot,
191  &orig_key, &orig_value);
192  if (key_exists)
193  {
194  g_hash_table_remove (frame->hash, slot);
195  qof_util_string_cache_remove (orig_key);
196  }
197  else
198  orig_value = NULL;
199  if (new_value)
200  g_hash_table_insert (frame->hash,
201  qof_util_string_cache_insert ((gpointer) slot), new_value);
202  return (KvpValue *) orig_value;
203 }
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).

Definition at line 516 of file kvpframe.c.

518 {
519  KvpValue *old_value;
520  gchar *last_key;
521 
522  last_key = NULL;
523  if (new_value)
524  frame = get_trailer_make (frame, key_path, &last_key);
525  else
526  frame =
527  (KvpFrame *) get_trailer_or_null (frame, key_path, &last_key);
528  if (!frame)
529  return NULL;
530 
531  old_value = kvp_frame_replace_slot_nc (frame, last_key, new_value);
532  return old_value;
533 }
void kvp_frame_set_boolean ( KvpFrame frame,
const gchar *  path,
gboolean  val 
)

Store the value of the boolean at the indicated path.

If not all frame components of the path exist, they are created.

Definition at line 431 of file kvpframe.c.

433 {
434  KvpValue * value;
435  value = kvp_value_new_boolean (val);
436  frame = kvp_frame_set_value_nc (frame, path, value);
437  if (!frame)
438  kvp_value_delete (value);
439 }
void kvp_frame_set_double ( KvpFrame frame,
const gchar *  path,
gdouble  dval 
)

store the value of the double at the indicated path.

If not all frame components of the path exist, they are created.

Definition at line 400 of file kvpframe.c.

401 {
402  KvpValue *value;
403  value = kvp_value_new_double (dval);
404  frame = kvp_frame_set_value_nc (frame, path, value);
405  if (!frame)
406  kvp_value_delete (value);
407 }
void kvp_frame_set_frame ( KvpFrame frame,
const gchar *  path,
KvpFrame chld 
)

Store a copy of the KvpFrame at the indicated path.

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

Definition at line 464 of file kvpframe.c.

465 {
466  KvpValue *value;
467  value = kvp_value_new_frame (fr);
468  frame = kvp_frame_set_value_nc (frame, path, value);
469  if (!frame)
470  kvp_value_delete (value);
471 }
void kvp_frame_set_frame_nc ( KvpFrame frame,
const gchar *  path,
KvpFrame chld 
)

Store a KvpFrame at the indicated path without copying.

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

Definition at line 474 of file kvpframe.c.

475 {
476  KvpValue *value;
477  value = kvp_value_new_frame_nc (fr);
478  frame = kvp_frame_set_value_nc (frame, path, value);
479  if (!frame)
480  kvp_value_delete (value);
481 }
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.

Definition at line 390 of file kvpframe.c.

391 {
392  KvpValue *value;
393  value = kvp_value_new_gint64 (ival);
394  frame = kvp_frame_set_value_nc (frame, path, value);
395  if (!frame)
396  kvp_value_delete (value);
397 }
void kvp_frame_set_guid ( KvpFrame frame,
const gchar *  path,
const GUID guid 
)

Store a copy of the GUID at the indicated path.

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

Definition at line 453 of file kvpframe.c.

455 {
456  KvpValue *value;
457  value = kvp_value_new_guid (guid);
458  frame = kvp_frame_set_value_nc (frame, path, value);
459  if (!frame)
460  kvp_value_delete (value);
461 }
void kvp_frame_set_numeric ( KvpFrame frame,
const gchar *  path,
QofNumeric  nval 
)

store the value of the QofNumeric at the indicated path.

If not all frame components of the path exist, they are created.

Definition at line 420 of file kvpframe.c.

422 {
423  KvpValue *value;
424  value = kvp_value_new_numeric (nval);
425  frame = kvp_frame_set_value_nc (frame, path, value);
426  if (!frame)
427  kvp_value_delete (value);
428 }
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.

Definition at line 684 of file kvpframe.c.

686 {
687  KvpValue *new_value = NULL;
688 
689  if (!frame)
690  return;
691 
692  g_return_if_fail (slot && *slot != '\0');
693 
694  if (value)
695  new_value = kvp_value_copy (value);
696  kvp_frame_set_slot_destructively (frame, slot, new_value);
697 }
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.

Definition at line 700 of file kvpframe.c.

702 {
703  if (!frame)
704  return;
705 
706  g_return_if_fail (slot && *slot != '\0');
707 
708  kvp_frame_set_slot_destructively (frame, slot, value);
709 }
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.

Definition at line 726 of file kvpframe.c.

728 {
729  va_list ap;
730  const gchar *key;
731 
732  if (!frame)
733  return;
734 
735  g_return_if_fail (first_key && *first_key != '\0');
736 
737  va_start (ap, first_key);
738 
739  key = first_key;
740 
741  while (TRUE)
742  {
743  KvpValue *value;
744  const gchar *next_key;
745 
746  next_key = va_arg (ap, const gchar *);
747  if (!next_key)
748  {
749  kvp_frame_set_slot (frame, key, new_value);
750  break;
751  }
752 
753  g_return_if_fail (*next_key != '\0');
754 
755  value = kvp_frame_get_slot (frame, key);
756  if (!value)
757  {
758  KvpFrame *new_frame = kvp_frame_new ();
759  KvpValue *frame_value = kvp_value_new_frame (new_frame);
760 
761  kvp_frame_set_slot_nc (frame, key, frame_value);
762 
763  value = kvp_frame_get_slot (frame, key);
764  if (!value)
765  break;
766  }
767 
768  frame = kvp_value_get_frame (value);
769  if (!frame)
770  break;
771 
772  key = next_key;
773  }
774 
775  va_end (ap);
776 }
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 779 of file kvpframe.c.

781 {
782  if (!frame || !key_path)
783  return;
784 
785  while (TRUE)
786  {
787  const gchar *key = key_path->data;
788  KvpValue *value;
789 
790  if (!key)
791  return;
792 
793  g_return_if_fail (*key != '\0');
794 
795  key_path = key_path->next;
796  if (!key_path)
797  {
798  kvp_frame_set_slot (frame, key, new_value);
799  return;
800  }
801 
802  value = kvp_frame_get_slot (frame, key);
803  if (!value)
804  {
805  KvpFrame *new_frame = kvp_frame_new ();
806  KvpValue *frame_value = kvp_value_new_frame (new_frame);
807 
808  kvp_frame_set_slot_nc (frame, key, frame_value);
809 
810  value = kvp_frame_get_slot (frame, key);
811  if (!value)
812  return;
813  }
814 
815  frame = kvp_value_get_frame (value);
816  if (!frame)
817  return;
818  }
819 }
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.

Definition at line 442 of file kvpframe.c.

444 {
445  KvpValue *value;
446  value = kvp_value_new_string (str);
447  frame = kvp_frame_set_value_nc (frame, path, value);
448  if (!frame)
449  kvp_value_delete (value);
450 }
void kvp_frame_set_time ( KvpFrame frame,
const gchar *  path,
QofTime qt 
)

Store a copy of the QofTime at the indicated path.

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

Definition at line 410 of file kvpframe.c.

411 {
412  KvpValue *value;
413  value = kvp_value_new_time (qt);
414  frame = kvp_frame_set_value_nc (frame, path, value);
415  if (!frame)
416  kvp_value_delete (value);
417 }
KvpFrame* kvp_frame_set_value ( KvpFrame frame,
const gchar *  path,
const KvpValue value 
)

Copy the KvpValue into the frame.

If the path contains slashes '/', these are assumed to represent a sequence of keys. The old value at this location, if any, is destroyed.

Pointers passed as arguments into this routine remain the responsibility of the caller.

Parameters
frameThe frame to hold the copied value.
pathThe location of the value in the frame.
valueThe value to be copied.
Returns
a pointer to the actual frame into which the value was inserted or NULL if the frame could not be found.

Definition at line 499 of file kvpframe.c.

501 {
502  KvpValue *new_value = NULL;
503  gchar *last_key;
504 
505  frame = get_trailer_make (frame, key_path, &last_key);
506  if (!frame)
507  return NULL;
508 
509  if (value)
510  new_value = kvp_value_copy (value);
511  kvp_frame_set_slot_destructively (frame, last_key, new_value);
512  return frame;
513 }
KvpFrame* kvp_frame_set_value_nc ( KvpFrame frame,
const gchar *  path,
KvpValue value 
)

Store the KvpValue in the frame without copying.

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).

Definition at line 486 of file kvpframe.c.

488 {
489  gchar *last_key;
490 
491  frame = get_trailer_make (frame, key_path, &last_key);
492  if (!frame)
493  return NULL;
494  kvp_frame_set_slot_destructively (frame, last_key, value);
495  return frame;
496 }
gint kvp_glist_compare ( const GList *  list1,
const GList *  list2 
)

kvp_glist_compare() compares GLists of KvpValue values (not to be confused with GLists of something else): it iterates over the list elements, performing a kvp_value_compare on each.

Definition at line 1170 of file kvpframe.c.

1171 {
1172  const GList *lp1;
1173  const GList *lp2;
1174 
1175  if (list1 == list2)
1176  return 0;
1177 
1178  /* Nothing is always less than something */
1179  if (!list1 && list2)
1180  return -1;
1181  if (list1 && !list2)
1182  return 1;
1183 
1184  lp1 = list1;
1185  lp2 = list2;
1186  while (lp1 && lp2)
1187  {
1188  KvpValue *v1 = (KvpValue *) lp1->data;
1189  KvpValue *v2 = (KvpValue *) lp2->data;
1190  gint vcmp = kvp_value_compare (v1, v2);
1191  if (vcmp != 0)
1192  return vcmp;
1193  lp1 = lp1->next;
1194  lp2 = lp2->next;
1195  }
1196  if (!lp1 && lp2)
1197  return -1;
1198  if (!lp2 && lp1)
1199  return 1;
1200  return 0;
1201 }
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 1148 of file kvpframe.c.

1149 {
1150  GList *retval = NULL;
1151  GList *lptr;
1152 
1153  if (!list)
1154  return retval;
1155 
1156  /* Duplicate the backbone of the list (this duplicates the POINTERS
1157  * to the values; we need to deep-copy the values separately) */
1158  retval = g_list_copy ((GList *) list);
1159 
1160  /* This step deep-copies the values */
1161  for (lptr = retval; lptr; lptr = lptr->next)
1162  {
1163  lptr->data = kvp_value_copy (lptr->data);
1164  }
1165 
1166  return retval;
1167 }
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 1130 of file kvpframe.c.

1131 {
1132  GList *node;
1133  if (!list)
1134  return;
1135 
1136  /* Delete the data in the list */
1137  for (node = list; node; node = node->next)
1138  {
1139  KvpValue *val = node->data;
1140  kvp_value_delete (val);
1141  }
1142 
1143  /* Free the backbone */
1144  g_list_free (list);
1145 }
gboolean kvp_value_binary_append ( KvpValue v,
gpointer  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 1662 of file kvpframe.c.

1663 {
1664  if (kva == kvb)
1665  return 0;
1666  /* nothing is always less than something */
1667  if (!kva && kvb)
1668  return -1;
1669  if (kva && !kvb)
1670  return 1;
1671 
1672  if (kva->type < kvb->type)
1673  return -1;
1674  if (kva->type > kvb->type)
1675  return 1;
1676 
1677  switch (kva->type)
1678  {
1679  case KVP_TYPE_GINT64:
1680  if (kva->value.int64 < kvb->value.int64)
1681  return -1;
1682  if (kva->value.int64 > kvb->value.int64)
1683  return 1;
1684  return 0;
1685  break;
1686  case KVP_TYPE_DOUBLE:
1687  return qof_util_double_compare (kva->value.dbl, kvb->value.dbl);
1688  break;
1689  case KVP_TYPE_NUMERIC:
1690  return qof_numeric_compare (kva->value.numeric,
1691  kvb->value.numeric);
1692  break;
1693  case KVP_TYPE_STRING:
1694  return strcmp (kva->value.str, kvb->value.str);
1695  break;
1696  case KVP_TYPE_GUID:
1697  return guid_compare (kva->value.guid, kvb->value.guid);
1698  break;
1699  case KVP_TYPE_BOOLEAN:
1700  {
1701  /* true > false */
1702  if (kva->value.gbool != kvb->value.gbool)
1703  return (kva->value.gbool) ? 1 : -1;
1704  return 0;
1705  break;
1706  }
1707  case KVP_TYPE_TIME :
1708  return qof_time_cmp (kva->value.qt, kvb->value.qt);
1709  break;
1710 #ifndef QOF_DISABLE_DEPRECATED
1711  case KVP_TYPE_TIMESPEC:
1712  return timespec_cmp (&(kva->value.timespec),
1713  &(kvb->value.timespec));
1714  break;
1715 #endif
1716  case KVP_TYPE_BINARY:
1717  if (kva->value.binary.datasize < kvb->value.binary.datasize)
1718  return -1;
1719  if (kva->value.binary.datasize > kvb->value.binary.datasize)
1720  return 1;
1721  return memcmp (kva->value.binary.data,
1722  kvb->value.binary.data, kva->value.binary.datasize);
1723  break;
1724  case KVP_TYPE_GLIST:
1725  return kvp_glist_compare (kva->value.list, kvb->value.list);
1726  break;
1727  case KVP_TYPE_FRAME:
1728  return kvp_frame_compare (kva->value.frame, kvb->value.frame);
1729  break;
1730  }
1731  return 0;
1732 }
KvpValue* kvp_value_copy ( const KvpValue value)

This is a deep value copy.

Definition at line 1601 of file kvpframe.c.

1602 {
1603  if (!value)
1604  return NULL;
1605 
1606  switch (value->type)
1607  {
1608  case KVP_TYPE_GINT64:
1609  return kvp_value_new_gint64 (value->value.int64);
1610  break;
1611  case KVP_TYPE_DOUBLE:
1612  return kvp_value_new_double (value->value.dbl);
1613  break;
1614  case KVP_TYPE_NUMERIC:
1615  return kvp_value_new_numeric (value->value.numeric);
1616  break;
1617  case KVP_TYPE_STRING:
1618  return kvp_value_new_string (value->value.str);
1619  break;
1620  case KVP_TYPE_GUID:
1621  return kvp_value_new_guid (value->value.guid);
1622  break;
1623  case KVP_TYPE_BOOLEAN:
1624  return NULL;
1625  return kvp_value_new_boolean (value->value.gbool);
1626  break;
1627  case KVP_TYPE_TIME :
1628  return kvp_value_new_time (value->value.qt);
1629  break;
1630 #ifndef QOF_DISABLE_DEPRECATED
1631  case KVP_TYPE_TIMESPEC:
1632  return kvp_value_new_timespec (value->value.timespec);
1633  break;
1634 #endif
1635  case KVP_TYPE_BINARY:
1636  return kvp_value_new_binary (value->value.binary.data,
1637  value->value.binary.datasize);
1638  break;
1639  case KVP_TYPE_GLIST:
1640  return kvp_value_new_glist (value->value.list);
1641  break;
1642  case KVP_TYPE_FRAME:
1643  return kvp_value_new_frame (value->value.frame);
1644  break;
1645  }
1646  return NULL;
1647 }
void kvp_value_delete ( KvpValue value)

This is a deep (recursive) delete.

Definition at line 1361 of file kvpframe.c.

1362 {
1363  if (!value)
1364  return;
1365 
1366  switch (value->type)
1367  {
1368  case KVP_TYPE_STRING:
1369  g_free (value->value.str);
1370  break;
1371  case KVP_TYPE_GUID:
1372  g_free (value->value.guid);
1373  break;
1374  case KVP_TYPE_BINARY:
1375  g_free (value->value.binary.data);
1376  break;
1377  case KVP_TYPE_GLIST:
1378  kvp_glist_delete (value->value.list);
1379  break;
1380  case KVP_TYPE_FRAME:
1381  kvp_frame_delete (value->value.frame);
1382  break;
1383  case KVP_TYPE_BOOLEAN:
1384  case KVP_TYPE_GINT64:
1385  case KVP_TYPE_DOUBLE:
1386  case KVP_TYPE_NUMERIC:
1387  default:
1388  break;
1389  }
1390  g_free (value);
1391 }
gpointer 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 1507 of file kvpframe.c.

1508 {
1509  if (!value)
1510  {
1511  if (size_return)
1512  *size_return = 0;
1513  PERR (" no size specified");
1514  return NULL;
1515  }
1516 
1517  if (value->type == KVP_TYPE_BINARY)
1518  {
1519  if (size_return)
1520  *size_return = value->value.binary.datasize;
1521  return value->value.binary.data;
1522  }
1523  else
1524  {
1525  if (size_return)
1526  *size_return = 0;
1527  PERR (" value type %d does not match KVP_TYPE_BINARY",
1528  value->type);
1529  return NULL;
1530  }
1531 }
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 1549 of file kvpframe.c.

1550 {
1551  if (!value)
1552  return NULL;
1553  if (value->type == KVP_TYPE_FRAME)
1554  return value->value.frame;
1555  else
1556  {
1557  PERR (" value type %d does not match KVP_TYPE_FRAME",
1558  value->type);
1559  return NULL;
1560  }
1561 }
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.

Todo:
kvp_value_get_ functions need to set QofError so that users can check that a NULL or zero value is actually a real value and not an error result.

Definition at line 1402 of file kvpframe.c.

1403 {
1404  if (!value)
1405  return 0;
1406  if (value->type == KVP_TYPE_GINT64)
1407  return value->value.int64;
1408  else
1409  {
1410  PERR (" value type %d does not match KVP_TYPE_GINT64",
1411  value->type);
1412  return 0;
1413  }
1414 }
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 1534 of file kvpframe.c.

1535 {
1536  if (!value)
1537  return NULL;
1538  if (value->type == KVP_TYPE_GLIST)
1539  return value->value.list;
1540  else
1541  {
1542  PERR (" value type %d does not match KVP_TYPE_GLIST",
1543  value->type);
1544  return NULL;
1545  }
1546 }
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 1477 of file kvpframe.c.

1478 {
1479  if (!value)
1480  return NULL;
1481  if (value->type == KVP_TYPE_GUID)
1482  return value->value.guid;
1483  else
1484  {
1485  PERR (" value type %d does not match KVP_TYPE_GUID",
1486  value->type);
1487  return NULL;
1488  }
1489 }
gchar* kvp_value_get_string ( const KvpValue value)

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

Definition at line 1447 of file kvpframe.c.

1448 {
1449  if (!value)
1450  return NULL;
1451  if (value->type == KVP_TYPE_STRING)
1452  return value->value.str;
1453  else
1454  {
1455  PERR (" value type %d does not match KVP_TYPE_STRING",
1456  value->type);
1457  return NULL;
1458  }
1459 }
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.)

KvpValue* kvp_value_new_boolean ( gboolean  value)
Since
0.7.2

Definition at line 1226 of file kvpframe.c.

1227 {
1228  KvpValue * retval = g_new0 (KvpValue, 1);
1229  retval->type = KVP_TYPE_BOOLEAN;
1230  retval->value.gbool = value;
1231  return retval;
1232 }
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 1348 of file kvpframe.c.

1349 {
1350  KvpValue *retval;
1351  if (!value)
1352  return NULL;
1353 
1354  retval = g_new0 (KvpValue, 1);
1355  retval->type = KVP_TYPE_FRAME;
1356  retval->value.frame = value;
1357  return retval;
1358 }
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 1309 of file kvpframe.c.

1310 {
1311  KvpValue *retval;
1312  if (!value)
1313  return NULL;
1314 
1315  retval = g_new0 (KvpValue, 1);
1316  retval->type = KVP_TYPE_GLIST;
1317  retval->value.list = kvp_glist_copy (value);
1318  return retval;
1319 }
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 1322 of file kvpframe.c.

1323 {
1324  KvpValue *retval;
1325  if (!value)
1326  return NULL;
1327 
1328  retval = g_new0 (KvpValue, 1);
1329  retval->type = KVP_TYPE_GLIST;
1330  retval->value.list = value;
1331  return retval;
1332 }
KvpFrame* kvp_value_replace_frame_nc ( KvpValue value,
KvpFrame newframe 
)

Replace old frame value with new, return old frame

Definition at line 1564 of file kvpframe.c.

1565 {
1566  KvpFrame *oldframe;
1567  if (!value)
1568  return NULL;
1569  if (KVP_TYPE_FRAME != value->type)
1570  {
1571  PERR (" value type %d does not match KVP_TYPE_FRAME",
1572  value->type);
1573  return NULL;
1574  }
1575  oldframe = value->value.frame;
1576  value->value.frame = newframe;
1577  return oldframe;
1578 }
GList* kvp_value_replace_glist_nc ( KvpValue value,
GList *  newlist 
)

Replace old glist value with new, return old glist

Definition at line 1581 of file kvpframe.c.

1582 {
1583  GList *oldlist;
1584  if (!value)
1585  return NULL;
1586  if (KVP_TYPE_GLIST != value->type)
1587  {
1588  PERR (" value type %d does not match KVP_TYPE_GLIST",
1589  value->type);
1590  return NULL;
1591  }
1592 
1593  oldlist = value->value.list;
1594  value->value.list = newlist;
1595  return oldlist;
1596 }
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 1848 of file kvpframe.c.

1849 {
1850  gchar *tmp1;
1851  gchar *tmp2;
1852  const gchar *ctmp;
1853 
1854  g_return_val_if_fail (val, NULL);
1855  tmp1 = g_strdup ("");
1856  switch (kvp_value_get_type (val))
1857  {
1858  case KVP_TYPE_GINT64:
1859  {
1860  return g_strdup_printf ("%" G_GINT64_FORMAT,
1861  kvp_value_get_gint64 (val));
1862  break;
1863  }
1864  case KVP_TYPE_DOUBLE:
1865  {
1866  return g_strdup_printf ("(%g)", kvp_value_get_double (val));
1867  break;
1868  }
1869  case KVP_TYPE_NUMERIC:
1870  {
1871  tmp1 = qof_numeric_to_string (kvp_value_get_numeric (val));
1872  tmp2 = g_strdup_printf ("%s", tmp1 ? tmp1 : "");
1873  g_free (tmp1);
1874  return tmp2;
1875  break;
1876  }
1877  case KVP_TYPE_STRING:
1878  {
1879  tmp1 = kvp_value_get_string (val);
1880  return g_strdup_printf ("%s", tmp1 ? tmp1 : "");
1881  break;
1882  }
1883  case KVP_TYPE_GUID:
1884  {
1885  ctmp = guid_to_string (kvp_value_get_guid (val));
1886  tmp2 = g_strdup_printf ("%s", ctmp ? ctmp : "");
1887  return tmp2;
1888  break;
1889  }
1890 #ifndef QOF_DISABLE_DEPRECATED
1891  case KVP_TYPE_TIMESPEC:
1892  {
1893  time_t t;
1894  t = timespecToTime_t (kvp_value_get_timespec (val));
1895  qof_date_format_set (QOF_DATE_FORMAT_UTC);
1896  return qof_print_date (t);
1897  break;
1898  }
1899 #endif
1900  case KVP_TYPE_BOOLEAN :
1901  return (kvp_value_get_boolean (val)) ? "TRUE" : "FALSE";
1902  case KVP_TYPE_BINARY:
1903  {
1904  guint64 len;
1905  gpointer data;
1906  data = kvp_value_get_binary (val, &len);
1907  tmp1 = binary_to_string (data, len);
1908  return g_strdup_printf ("%s", tmp1 ? tmp1 : "");
1909  break;
1910  }
1911  case KVP_TYPE_GLIST:
1912  /* borked. kvp_value_glist_to_string is a debug fcn */
1913  {
1914  tmp1 = kvp_value_glist_to_string (kvp_value_get_glist (val));
1915  tmp2 = g_strdup_printf ("%s", tmp1 ? tmp1 : "");
1916  g_free (tmp1);
1917  return tmp2;
1918  break;
1919  }
1920  case KVP_TYPE_FRAME:
1921  {
1922  KvpFrame *frame;
1923 
1924  frame = kvp_value_get_frame (val);
1925  if (frame->hash)
1926  {
1927  tmp1 = g_strdup ("");
1928  g_hash_table_foreach (frame->hash,
1929  kvp_frame_to_bare_string_helper, &tmp1);
1930  }
1931  return tmp1;
1932  break;
1933  }
1934  default:
1935  return g_strdup_printf (" ");
1936  break;
1937  }
1938 }
gchar* kvp_value_to_string ( const KvpValue val)

Debug version.

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

Definition at line 1941 of file kvpframe.c.

1942 {
1943  gchar *tmp1;
1944  gchar *tmp2;
1945  const gchar *ctmp;
1946 
1947  g_return_val_if_fail (val, NULL);
1948 
1949  switch (kvp_value_get_type (val))
1950  {
1951  case KVP_TYPE_GINT64:
1952  {
1953  return g_strdup_printf ("KVP_VALUE_GINT64(%" G_GINT64_FORMAT ")",
1954  kvp_value_get_gint64 (val));
1955  break;
1956  }
1957  case KVP_TYPE_DOUBLE:
1958  {
1959  return g_strdup_printf ("KVP_VALUE_DOUBLE(%g)",
1960  kvp_value_get_double (val));
1961  break;
1962  }
1963  case KVP_TYPE_NUMERIC:
1964  {
1965  tmp1 = qof_numeric_to_string (kvp_value_get_numeric (val));
1966  tmp2 = g_strdup_printf ("KVP_VALUE_NUMERIC(%s)", tmp1 ? tmp1 : "");
1967  g_free (tmp1);
1968  return tmp2;
1969  break;
1970  }
1971  case KVP_TYPE_STRING:
1972  {
1973  tmp1 = kvp_value_get_string (val);
1974  return g_strdup_printf ("KVP_VALUE_STRING(%s)", tmp1 ? tmp1 : "");
1975  break;
1976  }
1977  case KVP_TYPE_GUID:
1978  {
1979  /* THREAD-UNSAFE */
1980  ctmp = guid_to_string (kvp_value_get_guid (val));
1981  tmp2 = g_strdup_printf ("KVP_VALUE_GUID(%s)", ctmp ? ctmp : "");
1982  return tmp2;
1983  break;
1984  }
1985 #ifndef QOF_DISABLE_DEPRECATED
1986  case KVP_TYPE_TIMESPEC:
1987  {
1988  tmp1 = g_new0 (gchar, 40);
1989  gnc_timespec_to_iso8601_buff (kvp_value_get_timespec (val), tmp1);
1990  tmp2 = g_strdup_printf ("KVP_VALUE_TIMESPEC(%s)", tmp1);
1991  g_free (tmp1);
1992  return tmp2;
1993  break;
1994  }
1995 #endif
1996  case KVP_TYPE_BINARY:
1997  {
1998  guint64 len;
1999  gpointer data;
2000  data = kvp_value_get_binary (val, &len);
2001  tmp1 = binary_to_string (data, len);
2002  return g_strdup_printf ("KVP_VALUE_BINARY(%s)",
2003  tmp1 ? tmp1 : "");
2004  break;
2005  }
2006  case KVP_TYPE_GLIST:
2007  {
2008  tmp1 = kvp_value_glist_to_string (kvp_value_get_glist (val));
2009  tmp2 = g_strdup_printf ("KVP_VALUE_GLIST(%s)", tmp1 ? tmp1 : "");
2010  g_free (tmp1);
2011  return tmp2;
2012  break;
2013  }
2014  case KVP_TYPE_FRAME:
2015  {
2016  tmp1 = kvp_frame_to_string (kvp_value_get_frame (val));
2017  tmp2 = g_strdup_printf ("KVP_VALUE_FRAME(%s)", tmp1 ? tmp1 : "");
2018  g_free (tmp1);
2019  return tmp2;
2020  break;
2021  }
2022  default:
2023  return g_strdup_printf (" ");
2024  break;
2025  }
2026 }
KvpFrame* qof_kvp_bag_add ( KvpFrame kvp_root,
const gchar *  path,
QofTime qt,
const gchar *  first_name,
  ... 
)

The qof_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:

qof_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 67 of file kvputil.c.

69 {
70  KvpFrame *cwd;
71  va_list ap;
72  va_start (ap, first_name);
73  cwd = qof_kvp_array_va (pwd, path, qt, first_name, ap);
74  va_end (ap);
75  return cwd;
76 }
KvpFrame* qof_kvp_bag_find_by_guid ( KvpFrame root,
const gchar *  path,
const gchar *  guid_name,
GUID desired_guid 
)

The qof_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 89 of file kvputil.c.

91 {
92  KvpValue *arr;
93  KvpValueType valtype;
94  GList *node;
95 
96  arr = kvp_frame_get_value (root, path);
97  valtype = kvp_value_get_type (arr);
98  if (KVP_TYPE_FRAME == valtype)
99  {
100  MATCH_GUID (arr);
101  return NULL;
102  }
103 
104  /* Its got to be a single isolated frame, or a list of them. */
105  if (KVP_TYPE_GLIST != valtype)
106  return NULL;
107 
108  for (node = kvp_value_get_glist (arr); node; node = node->next)
109  {
110  KvpValue *va = node->data;
111  MATCH_GUID (va);
112  }
113  return NULL;
114 }
void qof_kvp_bag_merge ( KvpFrame kvp_into,
const gchar *  intopath,
KvpFrame kvp_from,
const gchar *  frompath 
)

The qof_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 186 of file kvputil.c.

188 {
189  KvpFrame *fr;
190 
191  fr = qof_kvp_bag_get_first (kvp_from, frompath);
192  while (fr)
193  {
194  qof_kvp_bag_remove_frame (kvp_from, frompath, fr);
195  kvp_frame_add_frame_nc (kvp_into, intopath, fr);
196  fr = qof_kvp_bag_get_first (kvp_from, frompath);
197  }
198 }
void qof_kvp_bag_remove_frame ( KvpFrame root,
const gchar *  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 119 of file kvputil.c.

120 {
121  KvpValue *arr;
122  KvpValueType valtype;
123  GList *node, *listhead;
124 
125  arr = kvp_frame_get_value (root, path);
126  valtype = kvp_value_get_type (arr);
127  if (KVP_TYPE_FRAME == valtype)
128  {
129  if (fr == kvp_value_get_frame (arr))
130  {
131  KvpValue *old_val =
132  kvp_frame_replace_value_nc (root, path, NULL);
133  kvp_value_replace_frame_nc (old_val, NULL);
134  kvp_value_delete (old_val);
135  }
136  return;
137  }
138 
139  /* Its got to be a single isolated frame, or a list of them. */
140  if (KVP_TYPE_GLIST != valtype)
141  return;
142 
143  listhead = kvp_value_get_glist (arr);
144  for (node = listhead; node; node = node->next)
145  {
146  KvpValue *va = node->data;
147  if (fr == kvp_value_get_frame (va))
148  {
149  listhead = g_list_remove_link (listhead, node);
150  g_list_free_1 (node);
151  kvp_value_replace_glist_nc (arr, listhead);
152  kvp_value_replace_frame_nc (va, NULL);
153  kvp_value_delete (va);
154  return;
155  }
156  }
157 }