Add value and percentage parsing helpers

2 files changed, 76 insertions, 1 deletions

diff --git a/include/math_utils.h b/include/math_utils.h
index 849921cde..40e8f399d 100644
--- a/include/math_utils.h
+++ b/include/math_utils.h
@@ -137,6 +137,20 @@ inline double gain_to_decibel(const double gain)
 	return 20.0 * log(gain) / log(10.0);
 }
 
+// A wrapper to convert a scalar gain to a percentage.
+// This avoids having a bunch of magic *100.0 throughout the code.
+constexpr float gain_to_percentage(const float gain)
+{
+	return gain * 100.0f;
+}
+
+// A wrapper to convert a percentage into a scalar gain.
+// This avoids having a bunch of magic /100.0 throughout the code.
+constexpr float percentage_to_gain(const float percentage)
+{
+	return percentage / 100.0f;
+}
+
 template <typename T>
 constexpr T lerp(const T a, const T b, const T t)
 {
@@ -171,5 +185,5 @@ template float remap<float>(const float in_min, const float in_max,
 template double remap<double>(const double in_min, const double in_max,
                               const double out_min, const double out_max,
                               const double v);
-
+							
 #endif
diff --git a/include/string_utils.h b/include/string_utils.h
index 6f52c5698..7b6ea9a63 100644
--- a/include/string_utils.h
+++ b/include/string_utils.h
@@ -26,6 +26,7 @@
 #include <cassert>
 #include <cstdarg>
 #include <cstring>
+#include <optional>
 #include <string>
 #include <vector>
 
@@ -212,4 +213,64 @@ bool UTF8_RenderForDos(const std::string &str_in,
                        std::string &str_out,
                        const uint16_t code_page = 0);
 
+// Parse a value from the string, clamp the result within the given min and max
+// values, and return it as a float. This API should give us enough numerical
+// range and accuracy for any text-based inputs.
+//
+// For example:
+//  - parse_value("101", 0, 100) return 100.0f.
+//  - parse_value("x10", 0, 100) return empty.
+//  - parse_value("txt", 0, 100) return empty.
+//  - parse_value("", 0, 100) return empty.
+//
+// To use it, check if the result then access it:
+//   const auto val = parse_value(s, ...);
+//   if (val)
+//       do_something(*val)
+//   else
+//       log_warning("%s was invalid", s.c_str());
+//
+// Alternatively, scope the value inside the if/else
+//   if (const auto v = parse_value(s, ...); v)
+//       do_something(*v)
+//   else
+//       log_warning("%s was invalid", s.c_str());
+//
+std::optional<float> parse_value(const std::string &s, const float min_value,
+                                 const float max_value);
+
+// parse_value clamped between 0 and 100
+std::optional<float> parse_percentage(const std::string &s);
+
+// Parse a value from a character-prefixed string, clamp the result within the
+// given min and max values, and return it as a float. This API should give us
+// enough numerical range and accuracy for any text-based inputs.
+//
+// For example:
+//  - parse_prefixed_value('x', "x101", 0, 100) return 100.0f.
+//  - parse_prefixed_value('X', "x101", 0, 100) return 100.0f.
+//  - parse_prefixed_value('y', "x101", 0, 100) return empty.
+//  - parse_prefixed_value('y', "1000", 0, 100) return empty.
+//  - parse_prefixed_value('y', "text", 0, 100) return empty.
+//
+// To use it, check if the result then access it:
+//   const auto val = parse_prefixed_value(...);
+//   if (val)
+//       do_something(*val);
+//   else
+//       log_warning("%s was invalid", s.c_str());
+//
+// Alternatively, scope the value inside the if/else
+//   if (const auto v = parse_prefixed_value(...); v)
+//       do_something(*v)
+//   else
+//       log_warning("%s was invalid", s.c_str());
+//
+std::optional<float> parse_prefixed_value(const char prefix, const std::string &s,
+                                          const float min_value,
+                                          const float max_value);
+
+// parse_prefixed_value clamped between 0 and 100
+std::optional<float> parse_prefixed_percentage(const char prefix, const std::string &s);
+
 #endif