Skip to content

Commit

Permalink
Improve some header doc for string hash map / properties
Browse files Browse the repository at this point in the history 
Also add a missing celix_status_t return for celix_properties_setVersionWithoutCopy
  • Loading branch information
@pnoltes
pnoltes committed Nov 10, 2023
1 parent cb0a8ba commit be9f0a9
Show file tree
Hide file tree
Showing 4 changed files with 78 additions and 69 deletions.
10 changes: 5 additions & 5 deletions libs/utils/gtest/src/PropertiesTestSuite.cc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -311,15 +311,15 @@ TEST_F(PropertiesTestSuite, GetSetOverwrite) {
free(key);
}
EXPECT_STREQ("str1", celix_properties_get(props, "key", ""));
celix_properties_set(props, "key", "str2");
EXPECT_EQ(CELIX_SUCCESS, celix_properties_set(props, "key", "str2"));
EXPECT_STREQ("str2", celix_properties_get(props, "key", ""));
celix_properties_setLong(props, "key", 1);
EXPECT_EQ(CELIX_SUCCESS, celix_properties_setLong(props, "key", 1));
EXPECT_EQ(1, celix_properties_getAsLong(props, "key", -1L));
celix_properties_setDouble(props, "key", 2.0);
EXPECT_EQ(CELIX_SUCCESS, celix_properties_setDouble(props, "key", 2.0));
EXPECT_EQ(2.0, celix_properties_getAsLong(props, "key", -2.0));
celix_properties_setBool(props, "key", false);
EXPECT_EQ(CELIX_SUCCESS, celix_properties_setBool(props, "key", false));
EXPECT_EQ(false, celix_properties_getAsBool(props, "key", true));
celix_properties_setVersionWithoutCopy(props, "key", version);
EXPECT_EQ(CELIX_SUCCESS, celix_properties_setVersionWithoutCopy(props, "key", version));
EXPECT_EQ(version, celix_properties_getVersion(props, "key", nullptr));
celix_properties_set(props, "key", "last");

Expand Down
120 changes: 64 additions & 56 deletions libs/utils/include/celix_properties.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -117,7 +117,7 @@ typedef struct celix_properties_iterator {
/**
* @brief Create a new empty property set.
*
* This function will push a error msg to celix_err if the return value is NULL.
* If the return status is an error, a error message is logged to celix_err.
*
* @return A new empty property set.
*/
Expand All @@ -135,7 +135,7 @@ CELIX_DEFINE_AUTOPTR_CLEANUP_FUNC(celix_properties_t, celix_properties_destroy)
/**
* @brief Load properties from a file.
*
* This function will push a error msg to celix_err if the return value is NULL.
* If the return status is an error, a error message is logged to celix_err.
*
* @param[in] filename The name of the file to load properties from.
* @return A property set containing the properties from the file.
Expand All @@ -146,7 +146,7 @@ CELIX_UTILS_EXPORT celix_properties_t* celix_properties_load(const char* filenam
/**
* @brief Load properties from a stream.
*
* This function will push a error msg to celix_err if the return value is NULL.
* If the return status is an error, a error message is logged to celix_err.
*
* @param[in,out] stream The stream to load properties from.
* @return A property set containing the properties from the stream.
Expand All @@ -157,7 +157,7 @@ CELIX_UTILS_EXPORT celix_properties_t* celix_properties_loadWithStream(FILE* str
/**
* @brief Load properties from a string.
*
* This function will push a error msg to celix_err if the return value is NULL.
* If the return status is an error, a error message is logged to celix_err.
*
* @param[in] input The string to load properties from.
* @return A property set containing the properties from the string.
Expand All @@ -170,7 +170,7 @@ CELIX_UTILS_EXPORT celix_properties_t* celix_properties_loadFromString(const cha
*
* @note Properties values are always stored as string values, regardless of their actual underlining types.
*
* This function will push a error msg to celix_err if the return code is not CELIX_SUCCESS.
* If the return status is an error, a error message is logged to celix_err.
*
* @param[in] properties The property set to store.
* @param[in] file The name of the file to store the properties to.
Expand Down Expand Up @@ -217,12 +217,13 @@ CELIX_UTILS_EXPORT celix_properties_value_type_e celix_properties_getType(const
/**
* @brief Set the value of a property.
*
* This function will push a error msg to celix_err if the return code is not CELIX_SUCCESS.
* If the return status is an error, a error 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] 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.
* @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.
*/
CELIX_UTILS_EXPORT celix_status_t celix_properties_set(celix_properties_t* properties,
const char* key,
Expand All @@ -231,53 +232,21 @@ 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.
*
* This function will push a error msg to celix_err if the return code is not CELIX_SUCCESS.
* If the return status is an error, a error message is logged to celix_err.
*
* @param[in] properties The property set to modify.
* @param[in] key The key of the property to set. This string will be used directly, so it must not be freed or
* modified after calling this function.
* @param[in] value The value to set the property to. This string will be used directly, so it must not be freed or
* modified after calling this function.
* @return CELIX_SUCCESS if the operation was successful, CELIX_ENOMEM if there was not enough memory to set the entry.
* @param[in] key The key of the property to set. This callee will take ownership of the key, so the key must not be
* used after calling this function. The key should be deallocated with free.
* @param[in] value The value to set the property to. This callee will take ownership of the value, so the value must
* not be used after calling this function. The value should be deallocated with free.
* @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 value is NULL.
* When CELIX_ENOMEM is returned, the key and value strings are not used and freed by this function.
*/
CELIX_UTILS_EXPORT celix_status_t celix_properties_setWithoutCopy(celix_properties_t* properties,
char* key,
char* value);

/**
* @brief Set the value of a property based on the provided property entry, maintaining underlying type.
*
* This function will push a error msg to celix_err if the return code is not CELIX_SUCCESS.
*
* @param[in] properties The property set to modify.
* @param[in] key The key of the property to set.
* @param[in] entry The entry to set the property to. The entry will be copied, so it can be freed after calling
* this function.
* @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_setEntry(celix_properties_t* properties,
const char* key,
const celix_properties_entry_t* entry);

/**
* @brief Unset a property, removing it from the property set.
*
* @param[in] properties The property set to modify.
* @param[in] key The key of the property to unset.
*/
CELIX_UTILS_EXPORT void celix_properties_unset(celix_properties_t* properties, const char* key);

/**
* @brief Make a copy of a properties set.
*
* This function will push a error msg to celix_err if the return value is NULL.
*
* @param[in] properties The property set to copy.
* @return A copy of the given property set.
*/
CELIX_UTILS_EXPORT celix_properties_t* celix_properties_copy(const celix_properties_t* properties);

/**
* @brief Get the value of a property as a long integer.
*
Expand All @@ -295,12 +264,13 @@ celix_properties_getAsLong(const celix_properties_t* properties, const char* key
/**
* @brief Set the value of a property to a long integer.
*
* This function will push a error msg to celix_err if the return code is not CELIX_SUCCESS.
* If the return status is an error, a error 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] value The long 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.
* @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.
*/
CELIX_UTILS_EXPORT celix_status_t celix_properties_setLong(celix_properties_t* properties, const char* key, long value);

Expand All @@ -321,24 +291,26 @@ celix_properties_getAsBool(const celix_properties_t* properties, const char* key
/**
* @brief Set the value of a property to a boolean.
*
* This function will push a error msg to celix_err if the return code is not CELIX_SUCCESS.
* If the return status is an error, a error 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] val The boolean 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.
* @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.
*/
CELIX_UTILS_EXPORT celix_status_t celix_properties_setBool(celix_properties_t* properties, const char* key, bool val);

/**
* @brief Set the value of a property to a double.
*
* This function will push a error msg to celix_err if the return code is not CELIX_SUCCESS.
* If the return status is an error, a error 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] val The double 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.
* @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.
*/
CELIX_UTILS_EXPORT celix_status_t celix_properties_setDouble(celix_properties_t* properties,
const char* key,
Expand All @@ -362,12 +334,13 @@ celix_properties_getAsDouble(const celix_properties_t* properties, const char* k
* @brief Set the value of a property as a Celix version.
*
* This function will make a copy of the provided celix_version_t object and store it in the property set.
* This function will push a error msg to celix_err if the return code is not CELIX_SUCCESS.
* If the return status is an error, a error 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] version The value to set. The function will make a copy of this object and store it in the property set.
* @return CELIX_SUCCESS if the operation was successful, CELIX_ENOMEM if there was not enough memory to set the entry.
* @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.
*/
CELIX_UTILS_EXPORT celix_status_t celix_properties_setVersion(celix_properties_t* properties,
const char* key,
Expand All @@ -378,14 +351,15 @@ CELIX_UTILS_EXPORT celix_status_t celix_properties_setVersion(celix_properties_t
*
* This function will store a reference to the provided celix_version_t object in the property set and takes
* ownership of the provided version.
* This function will push a error msg to celix_err if the return code is not CELIX_SUCCESS.
* If the return status is an error, a error 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] version The value to set. The function will store a reference to this object in the property set and
* takes ownership of the provided version.
*
*/
CELIX_UTILS_EXPORT void
CELIX_UTILS_EXPORT celix_status_t
celix_properties_setVersionWithoutCopy(celix_properties_t* properties, const char* key, celix_version_t* version);

/**
Expand Down Expand Up @@ -423,6 +397,40 @@ CELIX_UTILS_EXPORT celix_version_t* celix_properties_getAsVersion(const celix_pr
const char* key,
const celix_version_t* defaultValue);

/**
* @brief Set the value of a property based on the provided property entry, maintaining underlying type.
*
* If the return status is an error, a error 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] entry The entry to set the property to. The entry will be copied, so it can be freed after calling
* this function.
* @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.
*/
CELIX_UTILS_EXPORT celix_status_t celix_properties_setEntry(celix_properties_t* properties,
const char* key,
const celix_properties_entry_t* entry);

/**
* @brief Unset a property, removing it from the property set.
*
* @param[in] properties The property set to modify.
* @param[in] key The key of the property to unset.
*/
CELIX_UTILS_EXPORT void celix_properties_unset(celix_properties_t* properties, const char* key);

/**
* @brief Make a copy of a properties set.
*
* If the return status is an error, a error message is logged to celix_err.
*
* @param[in] properties The property set to copy.
* @return A copy of the given property set.
*/
CELIX_UTILS_EXPORT celix_properties_t* celix_properties_copy(const celix_properties_t* properties);

/**
* @brief Get the number of properties in a property set.
*
Expand Down
13 changes: 7 additions & 6 deletions libs/utils/include/celix_string_hash_map.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -117,12 +117,13 @@ typedef struct celix_string_hash_map_create_options {
* @brief If set to true, the string hash map will not make of copy of the keys and assumes
* that the keys are in scope/memory for the complete lifecycle of the string hash map.
*
* When keys are stored weakly it is the caller responsibility to check the return value of
* celix_stringHashMap_put* function calls.
* If a celix_stringHashMap_put* function call returns true, the key is used in the hash map and the key
* should never be freed or freed in a configured removedKeyCallback.
* If a celix_stringHashMap_put* function call returns false, a value is replaced and the already existing
* key is reused. If the needed the caller should free the provided key.
* When keys are stored weakly it is the caller responsibility to check if a key is already in use
* (celix_stringHashMap_hasKey).
*
* If the key is already in use, the celix_stringHashMap_put* will not store the provided key and will
* instead keep the already existing key. If needed, the caller should free the provided key.
* If the key is not already in use, the celix_stringHashMap_put* will store the provided key and the caller
* should not free the provided key.
*
* @note This changes the default behaviour of the celix_stringHashMap_put* functions.
*
Expand Down
4 changes: 2 additions & 2 deletions libs/utils/src/properties.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -831,8 +831,8 @@ celix_properties_setVersion(celix_properties_t* properties, const char* key, con
return celix_properties_createAndSetEntry(properties, key, NULL, NULL, NULL, NULL, celix_version_copy(version));
}

void celix_properties_setVersionWithoutCopy(celix_properties_t* properties, const char* key, celix_version_t* version) {
celix_properties_createAndSetEntry(properties, key, NULL, NULL, NULL, NULL, version);
celix_status_t celix_properties_setVersionWithoutCopy(celix_properties_t* properties, const char* key, celix_version_t* version) {
return celix_properties_createAndSetEntry(properties, key, NULL, NULL, NULL, NULL, version);
}

int celix_properties_size(const celix_properties_t* properties) {
Expand Down

0 comments on commit be9f0a9

Please sign in to comment.