diff options
Diffstat (limited to 'pom.h')
| -rw-r--r-- | pom.h | 89 |
1 files changed, 52 insertions, 37 deletions
@@ -268,15 +268,16 @@ pom_conf_get_or_default(const pom_conf *conf, const char *key, const char *dflt) /// /// Returns `NULL` on success, putting the integer value in `*value`. /// -/// If `key` is not set, returns `""`. -/// If `key` is set but not a valid integer +/// If `key` is not set or is not a valid integer /// (decimal or `0x`/`0X`-prefixed hexadecimal, absolute value less than 2<sup>53</sup>), -/// returns the value of `key`. +/// returns an error. /// `*value` is set to 0 in these cases. /// -/// The returned pointer is valid until \ref pom_conf_free is called. -const char * -pom_conf_get_int(const pom_conf *conf, const char *key, int64_t *value); +/// The returned error must be `free()`d. +POM__MUST_USE_L +pom_error * +pom_conf_get_int(const pom_conf *conf, const char *key, int64_t *value) +POM__MUST_USE_R; /// Get signed integer value of `key`, or `dflt` if not present. /// @@ -284,25 +285,29 @@ pom_conf_get_int(const pom_conf *conf, const char *key, int64_t *value); /// /// If `key` is set but not a valid integer /// (decimal or `0x`/`0X`-prefixed hexadecimal, absolute value less than 2<sup>53</sup>), -/// returns the value of `key`. +/// returns an error. /// `*value` is still set to `dflt` in this case. /// -/// The returned pointer is valid until \ref pom_conf_free is called. -const char * -pom_conf_get_int_or_default(const pom_conf *conf, const char *key, int64_t *value, int64_t dflt); +/// The returned error must be `free()`d. +POM__MUST_USE_L +pom_error * +pom_conf_get_int_or_default(const pom_conf *conf, const char *key, int64_t *value, int64_t dflt) +POM__MUST_USE_R; /// Get unsigned integer value of `key`. /// /// Returns `NULL` on success, putting the unsigned integer value in `*value`. /// -/// If `key` is not set, returns `""`. If `key` is set but not a valid unsigned integer +/// If `key` is not set or is not a valid unsigned integer /// (decimal or `0x`/`0X`-prefixed hexadecimal, less than 2<sup>53</sup>), -/// returns the value of `key`. +/// returns an error. /// `*value` is set to 0 in these case cases. /// -/// The returned pointer is valid until \ref pom_conf_free is called. -const char * -pom_conf_get_uint(const pom_conf *conf, const char *key, uint64_t *value); +/// The returned error must be `free()`d. +POM__MUST_USE_L +pom_error * +pom_conf_get_uint(const pom_conf *conf, const char *key, uint64_t *value) +POM__MUST_USE_R; /// Get unsigned integer value of `key`, or `dflt` if not present. /// @@ -310,49 +315,57 @@ pom_conf_get_uint(const pom_conf *conf, const char *key, uint64_t *value); /// /// If `key` is set but not a valid unsigned integer /// (decimal or `0x`/`0X`-prefixed hexadecimal, less than 2<sup>53</sup>), -/// returns the value of `key`. +/// returns an error. /// `*value` is set to 0 in this case. /// -/// The returned pointer is valid until \ref pom_conf_free is called. -const char * -pom_conf_get_uint_or_default(const pom_conf *conf, const char *key, uint64_t *value, uint64_t dflt); +/// The returned error must be `free()`d. +POM__MUST_USE_L +pom_error * +pom_conf_get_uint_or_default(const pom_conf *conf, const char *key, uint64_t *value, uint64_t dflt) +POM__MUST_USE_R; /// Get floating-point value of `key`. /// /// Returns `NULL` on success, putting the floating-point value in `*value`. /// -/// If `key` is not set, returns `""`. If `key` is set but not a valid floating-point number, -/// returns the value of `key`. +/// If `key` is not set or is set but not a valid floating-point number, +/// returns an error. /// `*value` is set to 0.0 in this case. /// -/// The returned pointer is valid until \ref pom_conf_free is called. -const char * -pom_conf_get_float(const pom_conf *conf, const char *key, double *value); +/// The returned error must be `free()`d. +POM__MUST_USE_L +pom_error * +pom_conf_get_float(const pom_conf *conf, const char *key, double *value) +POM__MUST_USE_R; /// Get floating-point value of `key`, or `dflt` if not present. /// /// Returns `NULL` on success, putting the floating-point value in `*value`. /// /// If `key` is set but not a valid floating-point number, -/// returns the value of `key`. +/// returns an error. /// `*value` is still set to `dflt` in this case. /// -/// The returned pointer is valid until \ref pom_conf_free is called. -const char * -pom_conf_get_float_or_default(const pom_conf *conf, const char *key, double *value, double dflt); +/// The returned error must be `free()`d. +POM__MUST_USE_L +pom_error * +pom_conf_get_float_or_default(const pom_conf *conf, const char *key, double *value, double dflt) +POM__MUST_USE_R; /// Get boolean value of `key`. /// /// Returns `NULL` on success, putting the boolean value in `*value`. /// -/// If `key` is not set, returns `""`. If `key` is set but not a valid boolean +/// If `key` is not set or is set but not a valid boolean /// (`off`/`false`/`no`/`on`/`true`/`yes`), -/// returns the value of `key`. +/// returns an error. /// `*value` is set to `false` in this case. /// -/// The returned pointer is valid until \ref pom_conf_free is called. -const char * -pom_conf_get_bool(const pom_conf *conf, const char *key, bool *value); +/// The returned error must be `free()`d. +POM__MUST_USE_L +pom_error * +pom_conf_get_bool(const pom_conf *conf, const char *key, bool *value) +POM__MUST_USE_R; /// Get boolean value of `key`, or `dflt` if not present. /// @@ -360,12 +373,14 @@ pom_conf_get_bool(const pom_conf *conf, const char *key, bool *value); /// /// If `key` is set but not a valid boolean /// (`off`/`false`/`no`/`on`/`true`/`yes`), -/// returns the value of `key`. +/// returns an error. /// `*value` is still set to `dflt` in this case. /// -/// The returned pointer is valid until \ref pom_conf_free is called. -const char * -pom_conf_get_bool_or_default(const pom_conf *conf, const char *key, bool *value, bool dflt); +/// The returned error must be `free()`d. +POM__MUST_USE_L +pom_error * +pom_conf_get_bool_or_default(const pom_conf *conf, const char *key, bool *value, bool dflt) +POM__MUST_USE_R; /// Get comma-separated list value of `key`, or `NULL` if not present. The return value must be freed with `free`. /// |