X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=src%2Finclude%2Fcore%2Fdata.h;h=879af9087db92d7346fee2109326df55eaf25dfc;hb=e48ff35c0684d772d4ba8bdc9f75dafcc0df6a36;hp=4a4dd2d3385e5f2fbf9e17fbd39cf0e2161772b4;hpb=8d86f8d17b71234e55633fbbdbcaee6f3d365d36;p=sysdb.git

diff --git a/src/include/core/data.h b/src/include/core/data.h
index 4a4dd2d..879af90 100644
--- a/src/include/core/data.h
+++ b/src/include/core/data.h
@@ -1,6 +1,6 @@
 /*
  * SysDB - src/include/core/data.h
- * Copyright (C) 2012 Sebastian 'tokkee' Harl <sh@tokkee.org>
+ * Copyright (C) 2012-2014 Sebastian 'tokkee' Harl <sh@tokkee.org>
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -45,28 +45,106 @@ enum {
 	SDB_TYPE_BINARY,
 };
 
+#define SDB_TYPE_TO_STRING(t) \
+	(((t) == SDB_TYPE_INTEGER) \
+		? "INTEGER" \
+		: ((t) == SDB_TYPE_DECIMAL) \
+			? "DECIMAL" \
+			: ((t) == SDB_TYPE_STRING) \
+				? "STRING" \
+				: ((t) == SDB_TYPE_DATETIME) \
+					? "DATETIME" \
+					: ((t) == SDB_TYPE_BINARY) \
+						? "BINARY" \
+						: "UNKNOWN")
+
 /*
  * sdb_data_t:
  * A datum retrieved from an arbitrary data source.
- *
- * The string and binary objects are managed by whoever creates the data
- * object, thus, they must not be freed or modified. If you want to keep them,
- * make sure to make a copy.
  */
 typedef struct {
 	int type;
 	union {
 		int64_t     integer;  /* SDB_TYPE_INTEGER */
 		double      decimal;  /* SDB_TYPE_DECIMAL */
-		const char *string;   /* SDB_TYPE_STRING  */
+		char       *string;   /* SDB_TYPE_STRING  */
 		sdb_time_t  datetime; /* SDB_TYPE_DATETIME */
 		struct {
 			size_t length;
-			const unsigned char *datum;
+			unsigned char *datum;
 		} binary;             /* SDB_TYPE_BINARY */
 	} data;
 } sdb_data_t;
 
+/*
+ * sdb_data_copy:
+ * Copy the datum stored in 'src' to the memory location pointed to by 'dst'.
+ * Any dynamic data (strings, binary data) is copied to newly allocated
+ * memory. Use, for example, sdb_data_free_datum() to free any dynamic memory
+ * stored in a datum.
+ *
+ * Returns:
+ *  - 0 on success
+ *  - a negative value else
+ */
+int
+sdb_data_copy(sdb_data_t *dst, const sdb_data_t *src);
+
+/*
+ * sdb_data_free_datum:
+ * Free any dynamic memory referenced by the specified datum. Does not free
+ * the memory allocated by the sdb_data_t object itself. This function must
+ * not be used if any static or stack memory is referenced from the data
+ * object.
+ */
+void
+sdb_data_free_datum(sdb_data_t *datum);
+
+/*
+ * sdb_data_cmp:
+ * Compare two data points. A NULL datum is considered less than any non-NULL
+ * datum. On data-type mismatch, the function always returns a negative value.
+ *
+ * Returns:
+ *  - a value less than zero if d1 compares less than d2
+ *  - zero if d1 compares equal to d2
+ *  - a value greater than zero if d1 compares greater than d2
+ */
+int
+sdb_data_cmp(sdb_data_t *d1, sdb_data_t *d2);
+
+/*
+ * sdb_data_strlen:
+ * Returns a (worst-case) estimate for the number of bytes required to format
+ * the datum as a string. Does not take the terminating null byte into
+ * account.
+ */
+size_t
+sdb_data_strlen(const sdb_data_t *datum);
+
+enum {
+	SDB_UNQUOTED = 0,
+	SDB_SINGLE_QUOTED,
+	SDB_DOUBLE_QUOTED,
+};
+
+/*
+ * sdb_data_format:
+ * Output the specified datum to the specified string using a default format.
+ * The value of 'quoted' determines whether and how non-integer and
+ * non-decimal values are quoted. If the buffer size is less than the return
+ * value of sdb_data_strlen, the datum may be truncated. The buffer will
+ * always be nul-terminated after calling this function.
+ *
+ * Returns:
+ *  - the number of characters written to the buffer (excluding the terminated
+ *    null byte) or the number of characters which would have been written in
+ *    case the output was truncated
+ *  - a negative value else
+ */
+int
+sdb_data_format(const sdb_data_t *datum, char *buf, size_t buflen, int quoted);
+
 #ifdef __cplusplus
 } /* extern "C" */
 #endif