pnoltes commented on code in PR #721:
URL: https://github.com/apache/celix/pull/721#discussion_r1538075149
##########
libs/utils/include/celix_properties.h:
##########
@@ -385,14 +512,264 @@ celix_properties_getVersion(const celix_properties_t*
properties, const char* ke
* @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 or
if the value is not a Celix version.
- * @return A copy of the property value if it is a Celix version, or a new
Celix version created from the property
- * value string if it can be converted, or a copy of the default value
if the property is not set or the value
- * is not a valid Celix version.
- * @retval NULL if version cannot be found/converted and the defaultValue is
NULL.
+ * @param[out] version A copy of the found version, a new parsed version, or a
copy of the default value if the
+ * property is not set, its value is not an version or its
value cannot be converted to an version.
+ * @return CELIX_SUCCESS if the operation was successful, CELIX_ENOMEM if
there was not enough memory to create the
+ * version. Note if the key is not found, the return status is still
CELIX_SUCCESS.
+ */
+CELIX_UTILS_EXPORT celix_status_t celix_properties_getAsVersion(const
celix_properties_t* properties,
+ const char*
key,
+ const
celix_version_t* defaultValue,
+
celix_version_t** version);
+
+/**
+ * @brief Set a pointer, long, double, bool, string or version array list
array for a property value.
+ *
+ * The set property type cannot be CELIX_ARRAY_LIST_ELEMENT_TYPE_UNDEFINED or
CELIX_ARRAY_LIST_ELEMENT_TYPE_POINTER
+ *
+ * This function will make a copy of the provided celix_array_list_t object,
using the celix_arrayList_copy function.
+ *
+ * If an error occurs, the error status is returned and a message is logged to
+ * celix_err.
+ *
+ * @param[in] properties The property set to modify.
+ * @param[in] key The key of the property to set.
+ * @param[in] values An array list of types values to set for the property.
Cannot be NULL.
+ * @return CELIX_SUCCESS if the operation was successful, CELIX_ENOMEM if
there was not enough memory to set the entry,
+ * and CELIX_ILLEGAL_ARGUMENT if the provided key or values is NULL or
if the array list type is
+ * valid.
*/
-CELIX_UTILS_EXPORT celix_version_t* celix_properties_getAsVersion(const
celix_properties_t* properties,
+CELIX_UTILS_EXPORT celix_status_t
celix_properties_setArrayList(celix_properties_t* properties,
+ const char*
key,
+ const
celix_array_list_t* values);
+
+/**
+ * @brief Assign a pointer, long, double, bool, string or version array list
array for a property value.
+ *
+ * The set property type cannot be CELIX_ARRAY_LIST_ELEMENT_TYPE_UNDEFINED or
CELIX_ARRAY_LIST_ELEMENT_TYPE_POINTER
+ *
+ * This function stores a reference to the provided celix_array_list_t object
in the property set and takes
+ * ownership of the array.
+ * If an error occurs, the error status is returned, the provided array is
destroyed and a
+ * message is logged to celix_err.
+ *
+ * @param[in] properties The property set to modify.
+ * @param[in] key The key of the property to set.
+ * @param[in] values An array list of long values to assign to the property.
Ownership of the array is transferred
+ * to the properties set. Cannot be NULL.
+ * @return CELIX_SUCCESS if the operation was successful, CELIX_ENOMEM if
there was not enough memory to set the entry,
+ * and CELIX_ILLEGAL_ARGUMENT if the provided key is NULL, values is
NULL or the array list type is
+ * valid. On error, the provided array list is destroyed.
+ */
+CELIX_UTILS_EXPORT celix_status_t
celix_properties_assignArrayList(celix_properties_t* properties,
+ const char*
key,
+
celix_array_list_t* values);
+
+/**
+ * @brief Get a property value as an array of longs.
+ *
+ * This function retrieves the value of a property, interpreting it as an
array of longs. If the underlying type of the
+ * property value is a long array, a copy of the array is returned. If the
underlying type is a string, the string is
+ * converted to an array of longs if possible.
+ * If the property is not set, its value is not an array of longs or its value
cannot be converted to a long array,
+ * the default value is returned as a copy.
+ *
+ * @param[in] properties The property set to search.
+ * @param[in] key The key of the property to get.
+ * @param[in] defaultValue The default value to return if the property is not
set or its value is not an array of longs.
+ * @param[out] list A copy of the found list, a new array list with long
values or a copy of the default value if the
+ * property is not set, its value is not an array of longs or
its value cannot be converted to an array
+ * of longs.
+ * @return CELIX_SUCCESS if the operation was successful, CELIX_ENOMEM if
there was not enough memory to create the
+ * array list. Note if the key is not found, the return status is still
CELIX_SUCCESS.
+ */
+CELIX_UTILS_EXPORT celix_status_t celix_properties_getAsLongArrayList(const
celix_properties_t* properties,
const char*
key,
- const
celix_version_t* defaultValue);
+ const
celix_array_list_t* defaultValue,
+
celix_array_list_t** list);
+
+/**
+ * @brief Get the property value as an array of longs without copying.
+ *
+ * This function provides a non-owning, read-only access to a property value
interpreted as an array of longs.
+ * It returns a const pointer to the array. If the property is not set or its
value is not an array of longs,
+ * the default value is returned.
+ *
+ * @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 or
its value is not an array of longs.
+ * @return A const pointer to the property value interpreted as an array of
longs, or the default value if the property
+ * is not set or its value is not an array of longs. The returned
pointer should not be modified or freed.
+ */
+CELIX_UTILS_EXPORT const celix_array_list_t*
celix_properties_getLongArrayList(const celix_properties_t* properties,
+
const char* key,
+
const celix_array_list_t* defaultValue);
+
+/**
+ * @brief Get a property value as an array of doubles, making a copy of the
array.
+ *
+ * This function retrieves the value of a property, interpreting it as an
array of doubles. If the underlying type of
+ * the property value is a double array, a copy of the array is returned. If
the underlying type is a string, the string
+ * is converted to an array of doubles if possible. If the property is not
set, its value is not an array of doubles or
+ * its value cannot be converted to a double array, the default value is
returned as a copy.
+ *
+ * @param[in] properties The property set to search.
+ * @param[in] key The key of the property to get.
+ * @param[in] defaultValue The default value to return if the property is not
set or its value is not an array of
+ * doubles.
+ * @param[out] list A copy of the found list, a new array list with double
values or a copy of the default value if the
+ * property is not set, its value is not an array doubles
longs or its value cannot be converted to an
+ * array of doubles.
+ * @return CELIX_SUCCESS if the operation was successful, CELIX_ENOMEM if
there was not enough memory to create the
+ * array list. Note if the key is not found, the return status is still
CELIX_SUCCESS.
+ */
+CELIX_UTILS_EXPORT celix_status_t celix_properties_getAsDoubleArrayList(const
celix_properties_t* properties,
+ const
char* key,
+ const
celix_array_list_t* defaultValue,
+
celix_array_list_t** list);
+
+/**
+ * @brief Get the property value as an array of doubles without copying.
+ *
+ * This function provides a non-owning, read-only access to a property value
interpreted as an array of doubles.
+ * It returns a const pointer to the array. If the property is not set or its
value is not an array of doubles,
+ * the default value is returned.
+ *
+ * @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 or
its value is not an array of doubles.
+ * @return A const pointer to the property value interpreted as an array of
doubles, or the default value if the
+ * property is not set or its value is not an array of doubles. The returned
pointer should not be modified or freed.
+ */
+CELIX_UTILS_EXPORT const celix_array_list_t*
celix_properties_getDoubleArrayList(
+ const celix_properties_t* properties, const char* key, const
celix_array_list_t* defaultValue);
+
+/**
+ * @brief Get a property value as an array of booleans, making a copy of the
array.
+ *
+ * This function retrieves the value of a property, interpreting it as an
array of booleans. If the underlying type of
+ * the property value is a boolean array, a copy of the array is returned. If
the underlying type is a string, the
+ * string is converted to an array of booleans if possible. If the property is
not set, its value is not an array of
+ * booleans or its value cannot be converted to a boolean array, the default
value is returned as a copy.
+ *
+ * @param[in] properties The property set to search.
+ * @param[in] key The key of the property to get.
+ * @param[in] defaultValue The default value to return if the property is not
set or its value is not an array of
+ * booleans.
+ * @param[out] list A copy of the found list, a new array list with boolean
values or a copy of the default value if the
+ * property is not set, its value is not an array of booleans
or its value cannot be converted to an
+ * array of booleans.
+ * @return CELIX_SUCCESS if the operation was successful, CELIX_ENOMEM if
there was not enough memory to create the
+ * array list. Note if the key is not found, the return status is still
CELIX_SUCCESS.
+ */
+CELIX_UTILS_EXPORT celix_status_t celix_properties_getAsBoolArrayList(const
celix_properties_t* properties,
+ const
char* key,
+ const
celix_array_list_t* defaultValue,
+
celix_array_list_t** list);
+
+/**
+ * @brief Get the property value as an array of booleans without copying.
+ *
+ * This function provides a non-owning, read-only access to a property value
interpreted as an array of booleans.
+ * It returns a const pointer to the array. If the property is not set or its
value is not an array of booleans,
+ * the default value is returned.
+ *
+ * @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 or
its value is not an array of booleans.
+ * @return A const pointer to the property value interpreted as an array of
booleans, or the default value if the
+ * property is not set or its value is not an array of booleans. The returned
pointer should not be modified or freed.
+ */
+CELIX_UTILS_EXPORT const celix_array_list_t* celix_properties_getBoolArrayList(
+ const celix_properties_t* properties, const char* key, const
celix_array_list_t* defaultValue);
+
+/**
+ * @brief Get a property value as an array of strings, making a copy of the
array.
+ *
+ * This function retrieves the value of a property, interpreting it as an
array of strings. If the underlying type of
+ * the property value is a string array, a copy of the array is returned. If
the underlying type is a string, the string
+ * is converted to an array of strings if possible. If the property is not
set, its value is not an array of strings or
+ * its value cannot be converted to a string array, the default value is
returned as a copy.
+ *
+ * The returned array list is configured with a remove callback so that the
destruction of the array list will also
+ * free the strings in the array list.
+ *
+ * @param[in] properties The property set to search.
+ * @param[in] key The key of the property to get.
+ * @param[in] defaultValue The default value to return if the property is not
set or its value is not an array of
+ * strings.
+ * @param[out] list A copy of the found list, a new array list with string
values or a copy of the default value if the
+ * property is not set, its value is not an array of strings
or its value cannot be converted to an
+ * array of strings.
+ * @return CELIX_SUCCESS if the operation was successful, CELIX_ENOMEM if
there was not enough memory to create the
+ * array list. Note if the key is not found, the return status is still
CELIX_SUCCESS.
+ */
+CELIX_UTILS_EXPORT celix_status_t celix_properties_getAsStringArrayList(const
celix_properties_t* properties,
+ const
char* key,
+ const
celix_array_list_t* defaultValue,
+
celix_array_list_t** list);
+
+/**
+ * @brief Get the property value as an array of strings without copying.
+ *
+ * This function provides a non-owning, read-only access to a property value
interpreted as an array of strings.
+ * It returns a const pointer to the array. If the property is not set or its
value is not an array of strings,
+ * the default value is returned.
+ *
+ * @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 or
its value is not an array of strings.
+ * @return A const pointer to the property value interpreted as an array of
strings, or the default value if the
+ * property is not set or its value is not an array of strings. The returned
pointer should not be modified or freed.
+ */
+CELIX_UTILS_EXPORT const celix_array_list_t*
celix_properties_getStringArrayList(
+ const celix_properties_t* properties, const char* key, const
celix_array_list_t* defaultValue);
+
+/**
+ * @brief Get a property value as an array of celix_version_t entries, making
a copy of the array.
+ *
+ *
+ * This function retrieves the value of a property, interpreting it as an
array of celix_version_t* entries. If the
+ * underlying type of the property value is a celix_version_t* array, a copy
of the array is returned. If the underlying
+ * type is a string, the string is converted to an array of celix_version_t*
if possible. If the property is not set,
+ * its value is not an array of celix_version_t* entries or its value cannot
be converted to a celix_version_t* array,
+ * the default value is returned as a copy.
+ *
+ * The returned array list is configured with a remove callback so that the
destruction of the array list will also
+ * free the celix_version_t entries in the array list.
+ *
+ * @param[in] properties The property set to search.
+ * @param[in] key The key of the property to get.
+ * @param[in] defaultValue The default value to return if the property is not
set or its value is not an array of
+ * celix_version_t entries.
+ * @param[out] list A copy of the found list, a new array list with
celix_version_t values or a copy of the default
+ * value if the property is not set, its value is not an array of
celix_version_t entries or its value cannot be
+ * converted to an array of celix_version_t entries.
+ * @return CELIX_SUCCESS if the operation was successful, CELIX_ENOMEM if
there was not enough memory to create the
+ * array list. Note if the key is not found, the return status is still
CELIX_SUCCESS.
+ */
+CELIX_UTILS_EXPORT celix_status_t celix_properties_getAsVersionArrayList(const
celix_properties_t* properties,
+ const
char* key,
+ const
celix_array_list_t* defaultValue,
+
celix_array_list_t** list);
+
+/**
+ * @brief Get the property value as an array of celix_version_t entries
without copying.
+ *
+ * This function provides a non-owning, read-only access to a property value
interpreted as an array of celix_version_t
+ * entries. It returns a const pointer to the array. If the property is not
set or its value is not an array of
+ * celix_version_t entries, the default value is returned.
+ *
+ * @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 or
its value is not an array of
+ * celix_version_t entries.
+ * @return A const pointer to the property value interpreted as an array of
celix_version_t entries, or the default
+ * value if the property is not set or its value is not an array of
celix_version_t entries. The returned pointer should
+ * not be modified or freed.
+ */
+CELIX_UTILS_EXPORT const celix_array_list_t*
celix_properties_getVersionArrayList(
Review Comment:
I think that would be more error prone. Because this way the user known the
returned array list is a array list with entry type version.
With exception of generic printing / serialization I do not see a use case
to retrieve all array list types. And for that use case we already have
`celix_properties_getEntry`
--
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
