index b657486b794b16cdb9bc00560cb0b2f4ab2090dc..230c1c9f887cd434b7c34bd74edf72ec12b88a5d 100644 (file)
--- a/src/include/core/data.h
+++ b/src/include/core/data.h
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;
} 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 for 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_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(sdb_data_t *datum);
+
+/*
+ * sdb_data_format:
+ * Output the specified datum to the specified string using a default format.
+ * 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(sdb_data_t *datum, char *buf, size_t buflen);
+
#ifdef __cplusplus
} /* extern "C" */
#endif