PengZheng commented on code in PR #470:
URL: https://github.com/apache/celix/pull/470#discussion_r1382398863
##########
libs/utils/include/celix_properties.h:
##########
@@ -17,86 +17,474 @@
* under the License.
*/
-#ifndef CELIX_PROPERTIES_H_
-#define CELIX_PROPERTIES_H_
+/**
+ * @file celix_properties.h
+ * @brief Header file for the Celix Properties API.
+ *
+ * The Celix Properties API provides a means for storing and manipulating
key-value pairs, called properties,
+ * which can be used to store configuration data or metadata for a service,
component, or framework configuration.
+ * Functions are provided for creating and destroying property sets, loading
and storing properties from/to a file
+ * or stream, and setting, getting, and unsetting individual properties. There
are also functions for converting
+ * property values to various types (e.g. long, bool, double) and for
iterating over the properties in a set.
+ *
+ * Supported property value types include:
+ * - string (char*)
+ * - long
+ * - double
+ * - bool
+ * - celix_version_t*
+ */
#include <stdio.h>
-#include <stdbool.h>
#include "celix_cleanup.h"
#include "celix_compiler.h"
#include "celix_errno.h"
#include "celix_utils_export.h"
+#include "celix_version.h"
+
+#ifndef CELIX_PROPERTIES_H_
+#define CELIX_PROPERTIES_H_
#ifdef __cplusplus
extern "C" {
#endif
-typedef struct hashMap celix_properties_t; //opaque struct, TODO try to make
this a celix_properties struct
+/**
+ * @brief celix_properties_t is a type that represents a set of key-value
pairs called properties.
+ *
+ * @note Not thread safe.
+ */
+typedef struct celix_properties celix_properties_t;
+
+/**
+ * @brief Enum representing the possible types of a property value.
+ */
+typedef enum celix_properties_value_type {
+ CELIX_PROPERTIES_VALUE_TYPE_UNSET = 0, /**< Property value is not set. */
+ CELIX_PROPERTIES_VALUE_TYPE_STRING = 1, /**< Property value is a string. */
+ CELIX_PROPERTIES_VALUE_TYPE_LONG = 2, /**< Property value is a long
integer. */
+ CELIX_PROPERTIES_VALUE_TYPE_DOUBLE = 3, /**< Property value is a double. */
+ CELIX_PROPERTIES_VALUE_TYPE_BOOL = 4, /**< Property value is a boolean.
*/
+ CELIX_PROPERTIES_VALUE_TYPE_VERSION = 5 /**< Property value is a Celix
version. */
+} celix_properties_value_type_e;
+
+/**
+ * @brief A structure representing a single value entry in a property set.
+ */
+typedef struct celix_properties_entry {
+ const char* value; /**< The string value or string
representation of a non-string
+ typed value.*/
+ celix_properties_value_type_e valueType; /**< The type of the value of the
entry */
+ union {
+ const char* strValue; /**< The string value of the
entry. */
+ long longValue; /**< The long integer value of
the entry. */
+ double doubleValue; /**< The double-precision
floating point value of the entry. */
+ bool boolValue; /**< The boolean value of the
entry. */
+ const celix_version_t* versionValue; /**< The Celix version value of
the entry. */
+ } typed; /**< The typed values of the
entry. Only valid if valueType
+ is not
CELIX_PROPERTIES_VALUE_TYPE_UNSET and only the matching
+ value types should be used.
E.g typed.boolValue if valueType is
+
CELIX_PROPERTIES_VALUE_TYPE_BOOL. */
+} celix_properties_entry_t;
+
+/**
+ * @brief Represents an iterator for iterating over the entries in a
celix_properties_t object.
+ */
typedef struct celix_properties_iterator {
- //private data
- void* _data1;
- void* _data2;
- void* _data3;
- int _data4;
- int _data5;
-} celix_properties_iterator_t;
+ /**
+ * @brief The index of the current iterator.
+ */
+ size_t index;
+ /**
+ * @brief Te current key.
+ */
+ const char* key;
-/**********************************************************************************************************************
-
**********************************************************************************************************************
- * Updated API
-
**********************************************************************************************************************
-
**********************************************************************************************************************/
+ /**
+ * @brief The current value entry.
+ */
+ celix_properties_entry_t entry;
-CELIX_UTILS_EXPORT celix_properties_t* celix_properties_create(void);
+ /**
+ * @brief Private data used to implement the iterator.
+ */
+ char _data[56];
+} celix_properties_iterator_t;
-CELIX_UTILS_EXPORT void celix_properties_destroy(celix_properties_t
*properties);
+/**
+ * @brief Create a new empty property set.
+ *
+ * @return A new empty property set.
+ */
+CELIX_UTILS_EXPORT celix_properties_t* celix_properties_create();
+
+/**
+ * @brief Destroy a property set, freeing all associated resources.
+ *
+ * @param[in] properties The property set to destroy. If properties is NULL,
this function will do nothing.
+ */
+CELIX_UTILS_EXPORT void celix_properties_destroy(celix_properties_t*
properties);
CELIX_DEFINE_AUTOPTR_CLEANUP_FUNC(celix_properties_t, celix_properties_destroy)
-CELIX_UTILS_EXPORT celix_properties_t* celix_properties_load(const char
*filename);
+/**
+ * @brief Load properties from a file.
+ *
+ * @param[in] filename The name of the file to load properties from.
+ * @return A property set containing the properties from the file.
+ * @retval NULL If an error occurred (e.g. file not found).
+ */
+CELIX_UTILS_EXPORT celix_properties_t* celix_properties_load(const char*
filename);
-CELIX_UTILS_EXPORT celix_properties_t* celix_properties_loadWithStream(FILE
*stream);
+/**
+ * @brief Load properties from a stream.
+ *
+ * @param[in,out] stream The stream to load properties from.
+ * @return A property set containing the properties from the stream.
+ * @retval NULL If an error occurred (e.g. invalid format).
+ */
+CELIX_UTILS_EXPORT celix_properties_t* celix_properties_loadWithStream(FILE*
stream);
-CELIX_UTILS_EXPORT celix_properties_t* celix_properties_loadFromString(const
char *input);
+/**
+ * @brief Load properties from a string.
+ *
+ * @param[in] input The string to load properties from.
+ * @return A property set containing the properties from the string.
+ * @retval NULL If an error occurred (e.g. invalid format).
+ */
+CELIX_UTILS_EXPORT celix_properties_t* celix_properties_loadFromString(const
char* input);
-CELIX_UTILS_EXPORT void celix_properties_store(celix_properties_t *properties,
const char *file, const char *header);
+/**
+ * @brief Store properties to a file.
+ *
+ * @note Properties values are always stored as string values, regardless of
their actual underlining types.
+ *
+ * @param[in] properties The property set to store.
+ * @param[in] file The name of the file to store the properties to.
+ * @param[in] header An optional - single line - header to write to the file
before the properties.
+ * Will be prefix with a '#' character.
+ * @return CELIX_SUCCESS if the operation was successful,
CELIX_FILE_IO_EXCEPTION if there was an error writing to the
+ * file.
+ */
+CELIX_UTILS_EXPORT celix_status_t celix_properties_store(celix_properties_t*
properties,
+ const char* file,
+ const char* header);
-CELIX_UTILS_EXPORT const char* celix_properties_get(const celix_properties_t
*properties, const char *key, const char *defaultValue);
+/**
+ * @brief Get the entry for a given key in a property set.
+ *
+ * @param[in] properties The property set to search.
+ * @param[in] key The key to search for.
+ * @return The entry for the given key, or a NULL if the key is not found.
+ */
+CELIX_UTILS_EXPORT celix_properties_entry_t* celix_properties_getEntry(const
celix_properties_t* properties,
+ const
char* key);
-CELIX_UTILS_EXPORT void celix_properties_set(celix_properties_t *properties,
const char *key, const char *value);
+/**
+ * @brief Get the value of a property.
+ *
+ * @param[in] properties The property set to search.
+ * @param[in] key The key of the property to get.
+ * @param[in] defaultValue The value to return if the property is not set.
+ * @return The value of the property, or the default value if the property is
not set.
+ */
+CELIX_UTILS_EXPORT const char*
+celix_properties_get(const celix_properties_t* properties, const char* key,
const char* defaultValue);
-CELIX_UTILS_EXPORT void celix_properties_setWithoutCopy(celix_properties_t
*properties, char *key, char *value);
+/**
+ * @brief Get the type of a property value.
+ *
+ * @param[in] properties The property set to search.
+ * @param[in] key The key of the property to get the type of.
+ * @return The type of the property value, or
CELIX_PROPERTIES_VALUE_TYPE_UNSET if the property is not set.
+ */
+CELIX_UTILS_EXPORT celix_properties_value_type_e
celix_properties_getType(const celix_properties_t* properties,
+
const char* key);
-CELIX_UTILS_EXPORT void celix_properties_unset(celix_properties_t *properties,
const char *key);
+/**
+ * @brief Set the value of a property.
+ *
+ * @param[in] properties The property set to modify.
+ * @param[in] key The key of the property to set.
+ * @param[in] value The value to set the property to.
+ * @return CELIX_SUCCESS if the operation was successful, CELIX_ENOMEM if
there was not enough memory to set the entry.
+ */
+CELIX_UTILS_EXPORT celix_status_t celix_properties_set(celix_properties_t*
properties,
+ const char* key,
+ const char* value);
-CELIX_UTILS_EXPORT celix_properties_t* celix_properties_copy(const
celix_properties_t *properties);
+/**
+ * @brief Set the value of a property without copying the value string.
+ *
Review Comment:
We need to document ERR's usage.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscr...@celix.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
