Change API for typed-get functions

1 files changed, 38 insertions, 51 deletions

diff --git a/pom.h b/pom.h
index 9adb156..9307508 100644
--- a/pom.h
+++ b/pom.h
@@ -22,6 +22,11 @@
 ///  likely never be an issue on any real machine.)
 /// Even if you are extremely paranoid, you can still use
 /// distinct configurations in different threads without worry.
+///
+/// ## Notes
+///
+/// Every libpom function may change the value of `errno` arbitrarily
+/// (its value after any libpom call should be ignored).
 
 /// \mainpage libpom doxygen documentation
 ///
@@ -206,10 +211,8 @@ pom_error_print(pom_error *error);
 /// Convert error to string. Return value is valid until `error` is `free()`’d.
 ///
 /// Includes every error in an error list (see \ref pom_error_next).
-POM__MUST_USE_L
 const char *
-pom_error_to_string(pom_error *error)
-POM__MUST_USE_R;
+pom_error_to_string(pom_error *error);
 
 /// Returns `true` if `key` is present in `conf`, `false` otherwise.
 bool
@@ -236,99 +239,83 @@ pom_conf_get_or_default(const pom_conf *conf, const char *key, const char *dflt)
 
 /// Get signed integer value of `key`.
 ///
-/// Returns `NULL` on success, putting the integer value in `*value`.
+/// Returns true on success, putting the integer value in `*value`.
 ///
 /// If `key` is not set or `key` is set but not a valid integer,
-/// returns an error which must be `free()`d.
+/// returns false.
 /// `*value` is set to 0 in this case.
-POM__MUST_USE_L
-pom_error *
-pom_conf_get_int(const pom_conf *conf, const char *key, int64_t *value)
-POM__MUST_USE_R;
+bool
+pom_conf_get_int(const pom_conf *conf, const char *key, int64_t *value);
 
 /// Get signed integer value of `key`, or `dflt` if not present.
 ///
-/// Returns `NULL` on success, putting the integer value in `*value`.
+/// Returns true on success, putting the integer value in `*value`.
 ///
 /// If `key` is set but not a valid integer,
-/// returns an error which must be `free()`d.
+/// returns false.
 /// `*value` is still set to `dflt` in this case.
-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;
+bool
+pom_conf_get_int_or_default(const pom_conf *conf, const char *key, int64_t *value, int64_t dflt);
 
 /// Get unsigned integer value of `key`.
 ///
-/// Returns `NULL` on success, putting the unsigned integer value in `*value`.
+/// Returns true on success, putting the unsigned integer value in `*value`.
 ///
 /// If `key` is not set or `key` is set but not a valid unsigned integer,
-/// returns an error which must be `free()`d.
+/// returns false.
 /// `*value` is set to 0 in this case.
-POM__MUST_USE_L
-pom_error *
-pom_conf_get_uint(const pom_conf *conf, const char *key, uint64_t *value)
-POM__MUST_USE_R;
+bool
+pom_conf_get_uint(const pom_conf *conf, const char *key, uint64_t *value);
 
 /// Get unsigned integer value of `key`, or `dflt` if not present.
 ///
-/// Returns `NULL` on success, putting the unsigned integer value in `*value`.
+/// Returns true on success, putting the unsigned integer value in `*value`.
 ///
 /// If `key` is set but not a valid unsigned integer,
-/// returns an error which must be `free()`d.
+/// returns false.
 /// `*value` is set to 0 in this case.
-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;
+bool
+pom_conf_get_uint_or_default(const pom_conf *conf, const char *key, uint64_t *value, uint64_t dflt);
 
 /// Get floating-point value of `key`.
 ///
-/// Returns `NULL` on success, putting the floating-point value in `*value`.
+/// Returns true on success, putting the floating-point value in `*value`.
 ///
 /// If `key` is not set or `key` is set but not a valid floating-point number,
-/// returns an error which must be `free()`d.
+/// returns false.
 /// `*value` is set to 0.0 in this case.
-POM__MUST_USE_L
-pom_error *
-pom_conf_get_float(const pom_conf *conf, const char *key, double *value)
-POM__MUST_USE_R;
+bool
+pom_conf_get_float(const pom_conf *conf, const char *key, double *value);
 
 /// Get floating-point value of `key`, or `dflt` if not present.
 ///
-/// Returns `NULL` on success, putting the floating-point value in `*value`.
+/// Returns true on success, putting the floating-point value in `*value`.
 ///
 /// If `key` is set but not a valid floating-point number,
-/// returns an error which must be `free()`d.
+/// returns false.
 /// `*value` is still set to `dflt` in this case.
-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;
+bool
+pom_conf_get_float_or_default(const pom_conf *conf, const char *key, double *value, double dflt);
 
 /// Get boolean value of `key`.
 ///
-/// Returns `NULL` on success, putting the boolean value in `*value`.
+/// Returns true on success], putting the boolean value in `*value`.
 ///
 /// If `key` is not set or `key` is set but not a valid boolean,
-/// returns an error which must be `free()`d.
+/// returns false.
 /// `*value` is set to `false` in this case.
-POM__MUST_USE_L
-pom_error *
-pom_conf_get_bool(const pom_conf *conf, const char *key, bool *value)
-POM__MUST_USE_R;
+bool
+pom_conf_get_bool(const pom_conf *conf, const char *key, bool *value);
 
 /// Get boolean value of `key`, or `dflt` if not present.
 ///
-/// Returns `NULL` on success, putting the boolean value in `*value`.
+/// Returns true on success, putting the boolean value in `*value`.
 ///
 /// If `key` is set but not a valid boolean,
-/// returns an error which must be `free()`d.
+/// returns false.
 /// `*value` is still set to `dflt` in this case.
-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;
+bool
+pom_conf_get_bool_or_default(const pom_conf *conf, const char *key, bool *value, bool dflt);
 
 /// Get comma-separated list value of `key`, or `NULL` if not present. The return value must be freed with `free`.
 ///