This is an automated email from the ASF dual-hosted git repository. pnoltes pushed a commit to branch feature/674-improve-properties in repository https://gitbox.apache.org/repos/asf/celix.git
commit 9a51102e504a86965c7d8a7399a927dea32e4019 Author: Pepijn Noltes <[email protected]> AuthorDate: Sat Jan 20 19:53:55 2024 +0100 Improve C/C++ properties code documentation --- libs/utils/include/celix/Properties.h | 231 ++++++++++++++++++++++++++++++---- libs/utils/include/celix_properties.h | 104 +++++++++++---- 2 files changed, 290 insertions(+), 45 deletions(-) diff --git a/libs/utils/include/celix/Properties.h b/libs/utils/include/celix/Properties.h index 47a3ffdc..96eb8b32 100644 --- a/libs/utils/include/celix/Properties.h +++ b/libs/utils/include/celix/Properties.h @@ -201,7 +201,7 @@ namespace celix { * @brief Wrap C properties and returns it as const in a shared_ptr, * but does not take ownership -> dtor will not destroy C properties. */ - static const Properties wrap(const celix_properties_t* wrapProps) { + static Properties wrap(const celix_properties_t* wrapProps) { auto* cp = const_cast<celix_properties_t*>(wrapProps); return Properties{cp, false}; } @@ -210,7 +210,7 @@ namespace celix { * @brief Wrap C properties and returns it as const in a shared_ptr, * but does not take ownership -> dtor will not destroy C properties. */ - static const Properties wrap(celix_properties_t* wrapProps) { + static Properties wrap(celix_properties_t* wrapProps) { return Properties{wrapProps, false}; } @@ -309,7 +309,13 @@ namespace celix { return celix_properties_getAsLong(cProps.get(), key.c_str(), defaultValue); } - // TODO doc + /** + * @Brief Get the value of a property, if the property is set and the underlying type is a long. + * @param[in] key The key of the property to get. + * @param[in] defaultValue The value to return if the property is not set or the value is not a long. + * @return The value of the property, or the default value if the property is not set or the value is not of the + * requested type. + */ long getLong(const std::string& key, long defaultValue) const { return celix_properties_getLong(cProps.get(), key.c_str(), defaultValue); } @@ -326,7 +332,14 @@ namespace celix { return celix_properties_getAsDouble(cProps.get(), key.c_str(), defaultValue); } - // TODO doc + /** + * @Brief Get the value of a property, if the property is set and the underlying type is a double. + * @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 the value is not a double. + * @return The value of the property, or the default value if the property is not set or the value is not of the + * requested type. + */ double getDouble(const std::string& key, double defaultValue) const { return celix_properties_getDouble(cProps.get(), key.c_str(), defaultValue); } @@ -343,7 +356,13 @@ namespace celix { return celix_properties_getAsBool(cProps.get(), key.c_str(), defaultValue); } - // TODO doc + /** + * @Brief Get the value of a property, if the property is set and the underlying type is a boolean. + * @param[in] key The key of the property to get. + * @param[in] defaultValue The value to return if the property is not set or the value is not a boolean. + * @return The value of the property, or the default value if the property is not set or the value is not of the + * requested type. + */ bool getBool(const std::string& key, bool defaultValue) const { return celix_properties_getBool(cProps.get(), key.c_str(), defaultValue); } @@ -373,7 +392,20 @@ namespace celix { return defaultValue; } - // TODO doc + /** + * @brief Get the Celix version value of a property without copying. + * + * This function provides a non-owning, read-only access to a Celix version contained in the properties. + * It returns a const pointer to the Celix version value associated with the specified key. + * This function does not perform any conversion from a string property value to a Celix version. + * + * @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 const pointer to the Celix version if it is present and valid, or the provided default value if the + * property is not set or the value is not a valid Celix version. The returned pointer should not be modified or + * freed. + */ celix::Version getVersion(const std::string& key, celix::Version defaultValue = {}) const { auto* v = celix_properties_getVersion(cProps.get(), key.c_str(), nullptr); if (v) { @@ -385,7 +417,22 @@ namespace celix { return defaultValue; } - // TODO doc + /** + * @brief Get a property value as a vector of longs. + * + * This function retrieves the value of a property, interpreting it as a vector of longs. If the underlying type + * of the property value is a long array, a new long vector with the longs of the found array is returned. If + * the underlying type is a string, the string is converted to a vector of longs if possible. If the property is + * not set, its value is not a vector of longs or its value cannot be converted to a long vector, the default + * value is returned as a copy. + * + * @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 a vector + * of longs. + * @return A new vector with long values or a copy of the default value if + * the property is not set, its value is not a array of longs or its value cannot be converted to a vector of + * longs. + */ std::vector<long> getAsLongVector(const std::string& key, const std::vector<long>& defaultValue = {}) const { celix_autoptr(celix_array_list_t) list; celix_status_t status = celix_properties_getAsLongArrayList(cProps.get(), key.c_str(), nullptr, &list); @@ -393,13 +440,34 @@ namespace celix { return convertToVector<long>(list, defaultValue, celix_arrayList_getLong); } - // TODO doc + /** + * @brief Get vector of longs if the underlying property type is a array of longs. + * + * @param[in] key The key of the property to get. + * @param[in] defaultValue A new vector with long values or a copy of the default value if the property is not + * set or its value is not a array of longs. + */ std::vector<long> getLongVector(const std::string& key, const std::vector<long>& defaultValue = {}) const { const auto* list = celix_properties_getLongArrayList(cProps.get(), key.c_str(), nullptr); return convertToVector<long>(list, defaultValue, celix_arrayList_getLong); } - // TODO doc + /** + * @brief Get a property value as a vector of booleans. + * + * This function retrieves the value of a property, interpreting it as a vector of booleans. If the underlying + * type of the property value is a booleans array, a new boolean vector with the booleans of the found array is + * returned. If the underlying type is a string, the string is converted to a vector of booleans if possible. If + * the property is not set, its value is not a vector of booleans or its value cannot be converted to a boolean + * vector, the default value is returned as a copy. + * + * @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 a vector + * of booleans. + * @return A new vector with boolean values or a copy of the default value if + * the property is not set, its value is not a array of booleans or its value cannot be converted to a vector of + * booleans. + */ std::vector<bool> getAsBoolVector(const std::string& key, const std::vector<bool>& defaultValue = {}) const { celix_autoptr(celix_array_list_t) list; celix_status_t status = celix_properties_getAsBoolArrayList(cProps.get(), key.c_str(), nullptr, &list); @@ -407,13 +475,34 @@ namespace celix { return convertToVector<bool>(list, defaultValue, celix_arrayList_getBool); } - // TODO doc + /** + * @brief Get vector of booleans if the underlying property type is a array of booleans. + * + * @param[in] key The key of the property to get. + * @param[in] defaultValue A new vector with boolean values or a copy of the default value if the property is not + * set or its value is not a array of booleans. + */ std::vector<bool> getBoolVector(const std::string& key, const std::vector<bool>& defaultValue = {}) const { const auto* list = celix_properties_getBoolArrayList(cProps.get(), key.c_str(), nullptr); return convertToVector<bool>(list, defaultValue, celix_arrayList_getBool); } - // TODO doc + /** + * @brief Get a property value as a vector of doubles. + * + * This function retrieves the value of a property, interpreting it as a vector of doubles. If the underlying + * type of the property value is a double array, a new double vector with the doubles of the found array is + * returned. If the underlying type is a string, the string is converted to a vector of doubles if possible. If + * the property is not set, its value is not a vector of doubles or its value cannot be converted to a double + * vector, the default value is returned as a copy. + * + * @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 a vector + * of doubles. + * @return A new vector with double values or a copy of the default value if + * the property is not set, its value is not a array of doubles or its value cannot be converted to a vector of + * doubles. + */ std::vector<double> getAsDoubleVector(const std::string& key, const std::vector<double>& defaultValue = {}) const { celix_autoptr(celix_array_list_t) list; @@ -422,14 +511,36 @@ namespace celix { return convertToVector<double>(list, defaultValue, celix_arrayList_getDouble); } - // TODO doc + /** + * @brief Get vector of doubles if the underlying property type is a array of doubles. + * + * @param[in] key The key of the property to get. + * @param[in] defaultValue A new vector with double values or a copy of the default value if the property is not + * set or its value is not a array of doubles. + */ std::vector<double> getDoubleVector(const std::string& key, const std::vector<double>& defaultValue = {}) const { const auto* list = celix_properties_getDoubleArrayList(cProps.get(), key.c_str(), nullptr); return convertToVector<double>(list, defaultValue, celix_arrayList_getDouble); } - // TODO doc + /** + * @brief Get a property value as a vector of celix::Version. + * + * This function retrieves the value of a property, interpreting it as a vector of celix::Version. If the + * underlying type of the property value is a celix_version_t* array, a new celix::Version vector created using + * the celix_version_t of the found array is returned. If the underlying type is a string, the string is + * converted to a vector of celix::Version if possible. If the property is not set, its value is not a vector of + * celix_version_t* or its value cannot be converted to a celix::Version vector, the default value is returned + * as a copy. + * + * @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 a vector + * of celix::Version. + * @return A new vector with celix::Version values or a copy of the default value if + * the property is not set, its value is not a array of celix_version_t* or its value cannot be converted to a + * vector of celix::Version. + */ std::vector<celix::Version> getAsVersionVector(const std::string& key, const std::vector<celix::Version>& defaultValue = {}) const { celix_autoptr(celix_array_list_t) list; @@ -449,7 +560,13 @@ namespace celix { return defaultValue; } - // TODO doc + /** + * @brief Get vector of celix::Version if the underlying property type is a array of celix_version_t*. + * + * @param[in] key The key of the property to get. + * @param[in] defaultValue A new vector with celix::Version values or a copy of the default value if the + * property is not set or its value is not a array of celix_version_t*. + */ std::vector<celix::Version> getVersionVector(const std::string& key, const std::vector<celix::Version>& defaultValue = {}) const { const auto* list = celix_properties_getVersionArrayList(cProps.get(), key.c_str(), nullptr); @@ -467,7 +584,22 @@ namespace celix { return defaultValue; } - // TODO doc + /** + * @brief Get a property value as a vector of strings. + * + * This function retrieves the value of a property, interpreting it as a vector of strings. If the underlying + * type of the property value is a string array, a new string vector with the strings of the found array is + * returned. If the underlying type is a string, the string is converted to a vector of strings if possible. If + * the property is not set, its value is not a vector of strings or its value cannot be converted to a string + * vector, the default value is returned as a copy. + * + * @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 a vector + * of strings. + * @return A new vector with string values or a copy of the default value if + * the property is not set, its value is not a array of strings or its value cannot be converted to a vector of + * strings. + */ std::vector<std::string> getAsStringVector(const std::string& key, const std::vector<std::string>& defaultValue = {}) const { celix_autoptr(celix_array_list_t) list; @@ -484,7 +616,13 @@ namespace celix { return defaultValue; } - // TODO doc + /** + * @brief Get vector of strings if the underlying property type is a array of strings. + * + * @param[in] key The key of the property to get. + * @param[in] defaultValue A new vector with string values or a copy of the default value if the property is not + * set or its value is not a array of strings. + */ std::vector<std::string> getStringVector(const std::string& key, const std::vector<std::string>& defaultValue = {}) const { const auto* list = celix_properties_getStringArrayList(cProps.get(), key.c_str(), nullptr); @@ -502,6 +640,8 @@ namespace celix { /** * @brief Set the value of a property. * + * The property value will be set as a string. + * * @param[in] key The key of the property to set. * @param[in] value The value to set the property to. * @throws std::bad_alloc If a ENOMEM error occurs while setting the property. @@ -516,6 +656,8 @@ namespace celix { /** * @brief Set string property value for a given key. * + * The set property type will be ValueType::String. + * * @param[in] key The key of the property to set. * @param[in] value The value to set the property to. * @throws std::bad_alloc If a ENOMEM error occurs while setting the property. @@ -530,6 +672,8 @@ namespace celix { /** * @brief Set a property with a to_string value of type T. * + * The set property type will be ValueType::String. + * * This function will use the std::to_string function to convert the value of type T to a string, * which will be used as the value for the property. * @@ -549,6 +693,8 @@ namespace celix { /** * @brief Sets a celix::Version property value for a given key. * + * The set property type will be ValueType::Version. + * * @param[in] key The key of the property to set. * @param[in] value The value to set for the property. * @throws std::bad_alloc If a ENOMEM error occurs while setting the property. @@ -563,6 +709,8 @@ namespace celix { /** * @brief Sets a bool property value for a given key. * + * The set property type will be ValueType::Bool. + * * @param[in] key The key of the property to set. * @param[in] value The value to set for the property. * @throws std::bad_alloc If a ENOMEM error occurs while setting the property. @@ -577,6 +725,8 @@ namespace celix { /** * @brief Sets a long property value for a given key. * + * The set property type will be ValueType::Long. + * * @param[in] key The key of the property to set. * @param[in] value The value to set for the property. * @throws std::bad_alloc If a ENOMEM error occurs while setting the property. @@ -591,6 +741,8 @@ namespace celix { /** * @brief Sets a double property value for a given key. * + * The set property type will be ValueType::Double. + * * @param[in] key The key of the property to set. * @param[in] value The value to set for the property. * @throws std::bad_alloc If a ENOMEM error occurs while setting the property. @@ -605,6 +757,8 @@ namespace celix { /** * @brief Sets a celix_version_t* property value for a given key. * + * The set property type will be ValueType::Version. + * * @param[in] key The key of the property to set. * @param[in] value The value to set for the property. * @throws std::bad_alloc If a ENOMEM error occurs while setting the property. @@ -614,7 +768,14 @@ namespace celix { throwIfEnomem(status); } - // TODO doc + /** + * @brief Set a string array value for a property. + * + * The set property type will be ValueType::StringArray. + * + * @param[in] key The key of the property to set. + * @param[in] values An vector of string values to set for the property. + */ void setStrings(const std::string& key, const std::vector<std::string>& values) { celix_array_list_create_options_t opts{}; opts.simpleRemovedCallback = free; @@ -630,7 +791,14 @@ namespace celix { throwIfEnomem(status); } - // TODO doc + /** + * @brief Set a celix::Version array value for a property. + * + * The set property type will be ValueType::VersionArray. + * + * @param[in] key The key of the property to set. + * @param[in] values An vector of celix::Version values to set for the property. + */ void setVersions(const std::string& key, const std::vector<celix::Version>& values) { celix_array_list_create_options_t opts{}; opts.simpleRemovedCallback = (void (*)(void*))celix_version_destroy; @@ -646,7 +814,14 @@ namespace celix { throwIfEnomem(status); } - // TODO doc + /** + * @brief Set a boolean array value for a property. + * + * The set property type will be ValueType::BooleanArray. + * + * @param[in] key The key of the property to set. + * @param[in] values An vector of boolean values to set for the property. + */ void setBooleans(const std::string& key, const std::vector<bool>& values) { celix_autoptr(celix_array_list_t) list = celix_arrayList_create(); throwIfNull(list); @@ -658,13 +833,27 @@ namespace celix { throwIfEnomem(status); } - // TODO doc + /** + * @brief Set a long array value for a property. + * + * The set property type will be ValueType::LongArray. + * + * @param[in] key The key of the property to set. + * @param[in] values An vector of long values to set for the property. + */ void setLongs(const std::string& key, const std::vector<long>& values) { auto status = celix_properties_setLongs(cProps.get(), key.data(), values.data(), values.size()); throwIfEnomem(status); } - // TODO doc + /** + * @brief Set a double array value for a property. + * + * The set property type will be ValueType::DoubleArray. + * + * @param[in] key The key of the property to set. + * @param[in] values An vector of double values to set for the property. + */ void setDoubles(const std::string& key, const std::vector<double>& values) { auto status = celix_properties_setDoubles(cProps.get(), key.data(), values.data(), values.size()); throwIfEnomem(status); diff --git a/libs/utils/include/celix_properties.h b/libs/utils/include/celix_properties.h index 66114728..875aad04 100644 --- a/libs/utils/include/celix_properties.h +++ b/libs/utils/include/celix_properties.h @@ -226,7 +226,9 @@ CELIX_UTILS_EXPORT celix_properties_value_type_e celix_properties_getType(const CELIX_UTILS_EXPORT bool celix_properties_hasKey(const celix_properties_t* properties, const char* key); /** - * @brief Set the value of a property. + * @brief Set the string value of a property. + * + * The set property type will be CELIX_PROPERTIES_VALUE_TYPE_STRING. * * If the return status is an error, an error message is logged to celix_err. * @@ -243,6 +245,8 @@ CELIX_UTILS_EXPORT celix_status_t celix_properties_set(celix_properties_t* prope /** * @brief Set the value of a property without copying the value string. * + * The set property type will be CELIX_PROPERTIES_VALUE_TYPE_STRING. + * * If the return status is an error, an error message is logged to celix_err. * * @param[in] properties The property set to modify. @@ -286,6 +290,8 @@ celix_properties_getAsLong(const celix_properties_t* properties, const char* key /** * @brief Set the value of a property to a long integer. * + * The set property type will be CELIX_PROPERTIES_VALUE_TYPE_LONG. + * * If the return status is an error, an error message is logged to celix_err. * * @param[in] properties The property set to modify. @@ -324,6 +330,8 @@ celix_properties_getAsBool(const celix_properties_t* properties, const char* key /** * @brief Set the value of a property to a boolean. * + * The set property type will be CELIX_PROPERTIES_VALUE_TYPE_BOOL. + * * If the return status is an error, an error message is logged to celix_err. * * @param[in] properties The property set to modify. @@ -337,6 +345,8 @@ CELIX_UTILS_EXPORT celix_status_t celix_properties_setBool(celix_properties_t* p /** * @brief Set the value of a property to a double. * + * The set property type will be CELIX_PROPERTIES_VALUE_TYPE_DOUBLE. + * * If the return status is an error, an error message is logged to celix_err. * * @param[in] properties The property set to modify. @@ -377,6 +387,8 @@ celix_properties_getAsDouble(const celix_properties_t* properties, const char* k /** * @brief Set the value of a property as a Celix version. * + * The set property type will be CELIX_PROPERTIES_VALUE_TYPE_VERSION. + * * This function will make a copy of the provided celix_version_t object and store it in the property set. * If the return status is an error, an error message is logged to celix_err. * @@ -394,6 +406,8 @@ CELIX_UTILS_EXPORT celix_status_t celix_properties_setVersion(celix_properties_t /** * @brief Assign the value of a property with the provided Celix version pointer. * + * The set property type will be CELIX_PROPERTIES_VALUE_TYPE_VERSION. + * * This function will store a reference to the provided celix_version_t object in the property set and takes * ownership of the provided version. * If the return status is an error, an error message is logged to celix_err. @@ -451,6 +465,8 @@ CELIX_UTILS_EXPORT celix_status_t celix_properties_getAsVersion(const celix_prop /** * @brief Set a long array value for a property. * + * The set property type will be CELIX_PROPERTIES_VALUE_TYPE_LONG_ARRAY. + * * This function will make a copy of the provided celix_array_list_t object, assuming it contains long values, * and store it in the property set. * If an error occurs, the error status is returned and a message is logged to @@ -469,6 +485,8 @@ CELIX_UTILS_EXPORT celix_status_t celix_properties_setLongArrayList(celix_proper /** * @brief Assign a long array value to a property, taking ownership of the array. * + * The set property type will be CELIX_PROPERTIES_VALUE_TYPE_LONG_ARRAY. + * * 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 @@ -488,6 +506,8 @@ CELIX_UTILS_EXPORT celix_status_t celix_properties_assignLongArrayList(celix_pro /** * @brief Set multiple long values for a property using an array of longs. * + * The set property type will be CELIX_PROPERTIES_VALUE_TYPE_LONG_ARRAY. + * * This function allows setting multiple long values for a given property key. The values are passed as an array * of long integers. The number of values in the array should be specified by nrOfValues. * @@ -507,10 +527,13 @@ CELIX_UTILS_EXPORT celix_status_t celix_properties_setLongs(celix_properties_t* size_t nrOfValues); /** - * @brief Get a property value as an array of longs, making a copy of the array. + * @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. It returns a new copy of the - * array. If the property is not set or its value is not an array of longs, the default value is returned as a copy. + * 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. @@ -546,6 +569,8 @@ CELIX_UTILS_EXPORT const celix_array_list_t* celix_properties_getLongArrayList(c /** * @brief Set a double array value for a property. * + * The set property type will be CELIX_PROPERTIES_VALUE_TYPE_DOUBLE_ARRAY. + * * This function will make a copy of the provided celix_array_list_t object, assuming it contains double values, * and store it in the property set. * If an error occurs, the error status is returned and a message is logged to @@ -564,6 +589,8 @@ CELIX_UTILS_EXPORT celix_status_t celix_properties_setDoubleArrayList(celix_prop /** * @brief Assign a double array value to a property, taking ownership of the array. * + * The set property type will be CELIX_PROPERTIES_VALUE_TYPE_DOUBLE_ARRAY. + * * 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 @@ -583,6 +610,8 @@ CELIX_UTILS_EXPORT celix_status_t celix_properties_assignDoubleArrayList(celix_p /** * @brief Set multiple double values for a property using an array of longs. * + * The set property type will be CELIX_PROPERTIES_VALUE_TYPE_DOUBLE_ARRAY. + * * This function allows setting multiple double values for a given property key. The values are passed as an array * of double integers. The number of values in the array should be specified by nrOfValues. * @@ -604,8 +633,10 @@ CELIX_UTILS_EXPORT celix_status_t celix_properties_setDoubles(celix_properties_t /** * @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. It returns a new copy of the - * array. If the property is not set or its value is not an array of doubles, the default value is returned as a copy. + * 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. @@ -618,9 +649,9 @@ CELIX_UTILS_EXPORT celix_status_t celix_properties_setDoubles(celix_properties_t * 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); + 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. @@ -641,6 +672,8 @@ CELIX_UTILS_EXPORT const celix_array_list_t* celix_properties_getDoubleArrayList /** * @brief Set a boolean array value for a property. * + * The set property type will be CELIX_PROPERTIES_VALUE_TYPE_BOOLEAN_ARRAY. + * * This function will make a copy of the provided celix_array_list_t object, assuming it contains boolean values, * and store it in the property set. * If an error occurs, the error status is returned and a message is logged to @@ -659,6 +692,8 @@ CELIX_UTILS_EXPORT celix_status_t celix_properties_setBoolArrayList(celix_proper /** * @brief Assign a boolean array value to a property, taking ownership of the array. * + * The set property type will be CELIX_PROPERTIES_VALUE_TYPE_BOOLEAN_ARRAY. + * * 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 @@ -678,6 +713,8 @@ CELIX_UTILS_EXPORT celix_status_t celix_properties_assignBoolArrayList(celix_pro /** * @brief Set multiple boolean values for a property using an array of longs. * + * The set property type will be CELIX_PROPERTIES_VALUE_TYPE_BOOLEAN_ARRAY. + * * This function allows setting multiple boolean values for a given property key. The values are passed as an array * of booleans. The number of values in the array should be specified by nrOfValues. * @@ -699,8 +736,10 @@ CELIX_UTILS_EXPORT celix_status_t celix_properties_setBooleans(celix_properties_ /** * @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. It returns a new copy of the - * array. If the property is not set or its value is not an array of booleans, the default value is returned as a copy. + * 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. @@ -713,9 +752,9 @@ CELIX_UTILS_EXPORT celix_status_t celix_properties_setBooleans(celix_properties_ * 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); + 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. @@ -736,6 +775,8 @@ CELIX_UTILS_EXPORT const celix_array_list_t* celix_properties_getBoolArrayList( /** * @brief Set a string array value for a property. * + * The set property type will be CELIX_PROPERTIES_VALUE_TYPE_STRING_ARRAY. + * * This function will make a copy of the provided celix_array_list_t object, assuming it contains string values, * and store it in the property set. * If an error occurs, the error status is returned and a message is logged to @@ -754,6 +795,8 @@ CELIX_UTILS_EXPORT celix_status_t celix_properties_setStringArrayList(celix_prop /** * @brief Assign a string array value to a property, taking ownership of the array. * + * The set property type will be CELIX_PROPERTIES_VALUE_TYPE_STRING_ARRAY. + * * The provided array list should be created with a remove callback so that the destruction of the array list * will also free the strings in the array list. If this is not done, this property set will leak memory. * @@ -774,7 +817,9 @@ CELIX_UTILS_EXPORT celix_status_t celix_properties_assignStringArrayList(celix_p celix_array_list_t* values); /** - * @brief Set multiple string values for a property using an array of longs. + * @brief Set multiple string values for a property using an array of strings. + * + * The set property type will be CELIX_PROPERTIES_VALUE_TYPE_STRING_ARRAY. * * This function allows setting multiple string values for a given property key. The values are passed as an array * of strings. The number of values in the array should be specified by nrOfValues. @@ -797,8 +842,10 @@ CELIX_UTILS_EXPORT celix_status_t celix_properties_setStrings(celix_properties_t /** * @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. It returns a new copy of the - * array. If the property is not set or its value is not an array of strings, the default value is returned as a copy. + * 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. @@ -814,9 +861,9 @@ CELIX_UTILS_EXPORT celix_status_t celix_properties_setStrings(celix_properties_t * 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); + 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. @@ -837,6 +884,8 @@ CELIX_UTILS_EXPORT const celix_array_list_t* celix_properties_getStringArrayList /** * @brief Set a celix_version_t array value for a property. * + * The set property type will be CELIX_PROPERTIES_VALUE_TYPE_VERSION_ARRAY. + * * This function will make a copy of the provided celix_array_list_t object, assuming it contains celix_version_t * values, and store it in the property set. If an error occurs, the error status is returned and a message is logged to * celix_err. @@ -854,6 +903,8 @@ CELIX_UTILS_EXPORT celix_status_t celix_properties_setVersionArrayList(celix_pro /** * @brief Assign a celix_version_t array value to a property, taking ownership of the array. * + * The set property type will be CELIX_PROPERTIES_VALUE_TYPE_VERSION_ARRAY. + * * The provided array list should be created with a remove callback so that the destruction of the array list * will also free the celix_version_t entries in the array list. If this is not done, this property set will leak * memory. @@ -875,7 +926,9 @@ CELIX_UTILS_EXPORT celix_status_t celix_properties_assignVersionArrayList(celix_ celix_array_list_t* values); /** - * @brief Set multiple celix_version_t values for a property using an array of longs. + * @brief Set multiple celix_version_t values for a property using an array of celix_version_t*. + * + * The set property type will be CELIX_PROPERTIES_VALUE_TYPE_VERSION_ARRAY. * * This function allows setting multiple celix_version_t values for a given property key. The values are passed as an * array with celix_version_t entries. The number of values in the array should be specified by nrOfValues. @@ -898,9 +951,12 @@ CELIX_UTILS_EXPORT celix_status_t celix_properties_setVersions(celix_properties_ /** * @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. It returns a - * new copy of 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 as a copy. + * + * 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.
