GnuCash
2.6.99
|
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. | |
Data Structures | |
struct | GHashTableKVPair |
struct | KvpItem |
Transfer of KVP to and from GValue, with the key. More... | |
Macros | |
#define | QOF_MOD_KVP "qof.kvp" |
#define | kvp_value_t KvpValueType |
#define | GNC_TYPE_VALUE_LIST (gnc_value_list_get_type ()) |
Typedefs | |
typedef struct KvpFrameImpl | KvpFrame |
typedef struct KvpValueImpl | KvpValue |
Enumerations | |
enum | KvpValueType { KVP_TYPE_INVALID = -1, KVP_TYPE_GINT64 = 1, KVP_TYPE_DOUBLE, KVP_TYPE_NUMERIC, KVP_TYPE_STRING, KVP_TYPE_GUID, KVP_TYPE_TIMESPEC, KVP_TYPE_PLACEHOLDER_DONT_USE, KVP_TYPE_GLIST, KVP_TYPE_FRAME, KVP_TYPE_GDATE } |
possible types in the union KvpValue More... | |
Functions | |
gchar * | kvp_value_to_string (const KvpValue *val) |
Debug version of kvp_value_to_string. More... | |
gchar * | kvp_frame_to_string (const KvpFrame *frame) |
GValue * | kvp_frame_get_gvalue (KvpFrame *frame, const gchar *key) |
void | kvp_frame_set_gvalue (KvpFrame *frame, const gchar *key, const GValue *value) |
void | gnc_gvalue_free (GValue *value) |
Convenience function to release the value in a GValue acquired by kvp_frame_get_gvalue and to free the GValue. More... | |
GType | gnc_value_list_get_type (void) |
KvpBag Bags of GncGUID Pointers | |
KvpFrame * | gnc_kvp_bag_add (KvpFrame *kvp_root, const char *path, time64 secs, const char *first_name,...) |
void | gnc_kvp_bag_merge (KvpFrame *kvp_into, const char *intopath, KvpFrame *kvp_from, const char *frompath) |
KvpFrame * | gnc_kvp_bag_find_by_guid (KvpFrame *root, const char *path, const char *guid_name, const GncGUID *desired_guid) |
void | gnc_kvp_bag_remove_frame (KvpFrame *root, const char *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 Constructors | |
KvpFrame * | kvp_frame_new (void) |
void | kvp_frame_delete (KvpFrame *frame) |
KvpFrame * | kvp_frame_copy (const KvpFrame *frame) |
gboolean | kvp_frame_is_empty (const KvpFrame *frame) |
KvpFrame Basic Value Storing | |
const char ** | kvp_frame_get_keys (const KvpFrame *frame) |
void | kvp_frame_set_gint64 (KvpFrame *frame, const gchar *path, gint64 ival) |
void | kvp_frame_set_double (KvpFrame *frame, const gchar *path, double dval) |
void | kvp_frame_set_numeric (KvpFrame *frame, const gchar *path, gnc_numeric nval) |
void | kvp_frame_set_timespec (KvpFrame *frame, const gchar *path, Timespec ts) |
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 GncGUID *guid) |
void | kvp_frame_set_frame (KvpFrame *frame, const gchar *path, KvpFrame *chld) |
void | kvp_frame_set_frame_nc (KvpFrame *frame, const gchar *path, KvpFrame *chld) |
KvpFrame * | kvp_frame_set_value (KvpFrame *frame, const gchar *path, const KvpValue *value) |
KvpFrame * | kvp_frame_set_value_nc (KvpFrame *frame, const gchar *path, KvpValue *value) |
KvpValue * | kvp_frame_replace_value_nc (KvpFrame *frame, const gchar *slot, KvpValue *new_value) |
#define | kvp_frame_set_gnc_numeric kvp_frame_set_numeric |
KvpFrame Glist Bag Storing | |
void | kvp_frame_add_frame_nc (KvpFrame *frame, const gchar *path, KvpFrame *chld) |
Store the given kvp_frame to the glist bag at the indicated path (non-copying) More... | |
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 GncGUID, 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 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) |
double | kvp_frame_get_double (const KvpFrame *frame, const gchar *path) |
gnc_numeric | kvp_frame_get_numeric (const KvpFrame *frame, const gchar *path) |
const gchar * | kvp_frame_get_string (const KvpFrame *frame, const gchar *path) |
GncGUID * | kvp_frame_get_guid (const KvpFrame *frame, const gchar *path) |
Timespec | kvp_frame_get_timespec (const KvpFrame *frame, const gchar *path) |
KvpValue * | kvp_frame_get_value (const KvpFrame *frame, const gchar *path) |
KvpFrame * | kvp_frame_get_frame (const KvpFrame *frame, const gchar *path) |
KvpFrame * | kvp_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(). | |
void | kvp_frame_set_slot (KvpFrame *frame, const gchar *key, KvpValue *value) |
void | kvp_frame_set_slot_nc (KvpFrame *frame, const gchar *key, KvpValue *value) |
void | kvp_frame_set_slot_path (KvpFrame *frame, KvpValue *value, const gchar *first_key,...) |
void | kvp_frame_set_slot_path_gslist (KvpFrame *frame, 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. | |
KvpValue * | kvp_frame_get_slot (const KvpFrame *frame, const gchar *key) |
KvpValue * | kvp_frame_get_slot_path (KvpFrame *frame, const gchar *first_key,...) |
KvpValue * | kvp_frame_get_slot_path_gslist (KvpFrame *frame, const GSList *key_path) |
gint | kvp_frame_compare (const KvpFrame *fa, const KvpFrame *fb) |
gint | double_compare (double v1, double v2) |
KvpValue List Convenience Functions | |
You probably shouldn't be using these low-level routines kvp_glist_compare() compares GLists of kvp_values (not to be confused with GLists of something else): it iterates over the list elements, performing a kvp_value_compare on each. | |
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 | |
You probably shouldn't be using these low-level routines The following routines are constructors for kvp_value. Those with pointer arguments copy in the value. The *_nc() versions do not copy in thier values, but use them directly. | |
KvpValue * | kvp_value_new_gint64 (gint64 value) |
KvpValue * | kvp_value_new_double (double value) |
KvpValue * | kvp_value_new_numeric (gnc_numeric value) |
KvpValue * | kvp_value_new_string (const gchar *value) |
KvpValue * | kvp_value_new_guid (const GncGUID *guid) |
KvpValue * | kvp_value_new_timespec (Timespec timespec) |
KvpValue * | kvp_value_new_frame (const KvpFrame *value) |
KvpValue * | kvp_value_new_gdate (GDate date) |
KvpValue * | kvp_value_new_glist (const GList *value) |
KvpValue * | kvp_value_new_glist_nc (GList *lst) |
KvpValue * | kvp_value_new_frame_nc (KvpFrame *value) |
void | kvp_value_delete (KvpValue *value) |
KvpValue * | kvp_value_copy (const KvpValue *value) |
KvpFrame * | kvp_value_replace_frame_nc (KvpValue *value, KvpFrame *newframe) |
GList * | kvp_value_replace_glist_nc (KvpValue *value, GList *newlist) |
#define | kvp_value_new_gnc_numeric kvp_value_new_numeric |
KvpValue Value access | |
KvpValueType | kvp_value_get_type (const KvpValue *value) |
gint64 | kvp_value_get_gint64 (const KvpValue *value) |
double | kvp_value_get_double (const KvpValue *value) |
gnc_numeric | kvp_value_get_numeric (const KvpValue *value) |
char * | kvp_value_get_string (const KvpValue *value) |
GncGUID * | kvp_value_get_guid (const KvpValue *value) |
GList * | kvp_value_get_glist (const KvpValue *value) |
KvpFrame * | kvp_value_get_frame (const KvpValue *value) |
Timespec | kvp_value_get_timespec (const KvpValue *value) |
GDate | kvp_value_get_gdate (const KvpValue *value) |
gint | kvp_value_compare (const KvpValue *va, const KvpValue *vb) |
Iterators | |
void | kvp_frame_for_each_slot (KvpFrame *f, void(*proc)(const gchar *key, KvpValue *value, gpointer data), gpointer data) |
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 kvp_frame_set_gnc_numeric kvp_frame_set_numeric |
Use kvp_frame_set_numeric instead of kvp_frame_set_gnc_numeric
Definition at line 170 of file kvp_frame.h.
#define kvp_value_new_gnc_numeric kvp_value_new_numeric |
Use kvp_value_new_numeric instead of kvp_value_new_gnc_numeric
Definition at line 466 of file kvp_frame.h.
#define kvp_value_t KvpValueType |
do not use these in new code.
Definition at line 113 of file kvp_frame.h.
typedef struct KvpFrameImpl KvpFrame |
Opaque frame structure
Definition at line 76 of file kvp_frame.h.
typedef struct KvpValueImpl KvpValue |
A KvpValue is a union with possible types enumerated in the KvpValueType enum.
Definition at line 80 of file kvp_frame.h.
enum KvpValueType |
possible types in the union KvpValue
Definition at line 93 of file kvp_frame.h.
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);
void gnc_gvalue_free | ( | GValue * | value | ) |
Convenience function to release the value in a GValue acquired by kvp_frame_get_gvalue and to free the GValue.
value | A GValue* created by kvp_frame_get_gvalue |
KvpFrame* gnc_kvp_bag_add | ( | KvpFrame * | kvp_root, |
const char * | path, | ||
time64 | 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 GncGUID. 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 GncGUID pointer (const GncGUID *). 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.
KvpFrame* gnc_kvp_bag_find_by_guid | ( | KvpFrame * | root, |
const char * | path, | ||
const char * | guid_name, | ||
const GncGUID * | 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.
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.
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.
Store the given kvp_frame to the glist bag at the indicated path (non-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.
This method does NOT copy the frame.
Perform a deep (recursive) value copy, copying the fraame, subframes, and the values as well.
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.
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.
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.
GValue* kvp_frame_get_gvalue | ( | KvpFrame * | frame, |
const gchar * | key | ||
) |
Return a KvpItem containing the value of a KvpFrame
Structure types (gnc_numeric, Timespec) are converted to pointers and must be extracted with g_value_get_boxed. A KVP_TYPE_GLIST will have all of its contents converted from KvpValues to GValues, so the return type will be a GValue containing a GList of GValue*, not GValue. Use gnc_value_list_free() to free such a list if you take it out of the GValue.
frame | (transfer-none) The KvpFrame retrieved with kvp_get_frame_foo() |
key | (transfer-none) A slash-delimited string with the path to the stored value. Must not be NULL or empty. |
const char** kvp_frame_get_keys | ( | const KvpFrame * | frame | ) |
Retrieve the keys for the frame.
Returns a null-terminated array of the keys which can be used to look up values and determine the pairs in this frame.
The caller should free the array using g_free, but should not free the keys.
This routine return the value at the end of the path, or NULL if any portion of the path doesn't exist.
This routine return the value at the end of the path, or NULL if any portion of the path doesn't exist.
gboolean kvp_frame_is_empty | ( | const KvpFrame * | frame | ) |
Return TRUE if the KvpFrame is empty
KvpFrame* kvp_frame_new | ( | void | ) |
Return a new empty instance of KvpFrame
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_gvalue | ( | KvpFrame * | frame, |
const gchar * | key, | ||
const GValue * | value | ||
) |
Replace or create a Kvp slot from a KvpItem
Structure types (gnc_numeric, Timespec) should be stored as boxed-type pointers in the GValue with the appropriate type from qof.h. Lists should be stored as a GValue containing a GList of GValues of type convertable to KvpValues. Unsupported types will emit a warning message and will be skipped.
frame | (transfer none) The KvpFrame into which the value will be added. |
key | (transfer none) The subkey of the frame at which to store the value |
value | GValue containing the paramter to store. |
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.
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.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.
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.
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.
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.
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.
store the value of the Timespec at the indicated path. If not all frame components of the path exist, they are created.
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.
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.
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.
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.
void kvp_value_delete | ( | KvpValue * | value | ) |
This is a deep (recursive) delete.
Value accessor. This one is non-copying – the caller can modify the value directly.
GDate kvp_value_get_gdate | ( | const KvpValue * | value | ) |
Value accessor for GDate
gint64 kvp_value_get_gint64 | ( | const KvpValue * | value | ) |
Value accessors. Those for GncGUID, 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.
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.
Value accessor. This one is non-copying – the caller can modify the value directly.
char* kvp_value_get_string | ( | const KvpValue * | value | ) |
Value accessor. This one is non-copying – the caller can modify the value directly.
value constructors (non-copying - KvpValue takes pointer ownership) values must have been allocated via glib allocators! (gnew, etc.)
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!)
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.)
Replace old frame value with new, return old frame
GList* kvp_value_replace_glist_nc | ( | KvpValue * | value, |
GList * | newlist | ||
) |
Replace old glist value with new, return old glist
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.