Module nih_plug::formatters

Convenience functions for formatting and parsing parameter values in various common formats.

Functions prefixed with v2s_ are meant to be used with the .value_to_string() parameter functions, while the s2v_ functions are meant to be used wit the .string_to_value(). functions. Most of these formatters come as a pair. Check each formatter’s documentation for any additional usage information.

Functions

• s2v_bool_bypass
  Parse a string in the same format as `v2s_bool_bypass().
• s2v_compression_ratio
  Parse a x:y compression ratio back to a floating point number. Used in conjunction with v2s_compression_ratio(). Plain numbers are parsed directly for UX’s sake.
• s2v_f32_gain_to_db
  Parse a decibel value to a linear voltage gain ratio. Handles the dB or dBFS units for you. Used in conjunction with v2s_f32_gain_to_db(). -inf dB will be parsed to 0.0.
• s2v_f32_hz_then_khz
  Convert an input in the same format at that of [v2s_f32_hz_then_khz()] to a Hertz value. This additionally also accepts note names in the same format as [s2v_i32_note_formatter()], and optionally also with cents in the form of D#5, -23 ct.`.
• s2v_f32_panning
  Parse a pan value in the format of [v2s_f32_panning()] to a linear value in the range [-1, 1]`.
• s2v_f32_percentage
  Parse a [0, 100] percentage to a [0, 1] number. Handles the percentage unit for you. Used in conjunction with v2s_f32_percentage().
• s2v_i32_note_formatter
  Parse a note name to a MIDI number using the inverse mapping from `v2s_i32_note_formatter().
• s2v_i32_power_of_two
  Parse a parameter input string to a power of two. Useful in conjunction with v2s_i32_power_of_two() to limit integer parameter ranges to be only powers of two.
• v2s_bool_bypass
  Display ‘Bypassed’ or ‘Not Bypassed’ depending on whether the parameter is true or false. ‘Enabled’ would have also been a possibility here, but that could be a bit confusing.
• v2s_compression_ratio
  Format a positive number as a compression ratio. A value of 4 will be formatted as 4.0:1 while 0.25 is formatted as 1:4.0.
• v2s_f32_gain_to_db
  Turn an f32 value from voltage gain to decibels using the semantics described in [util::gain_to_db()]. You should use either “ dB“or“ dBFS“for the parameter's unit.0.0will be formatted as-inf`.
• v2s_f32_hz_then_khz
  Format a f32 Hertz value as a rounded Hz below 1000 Hz, and as a rounded kHz value above 1000 Hz. This already includes the unit.
• v2s_f32_hz_then_khz_with_note_name
  v2s_f32_hz_then_khz(), but also includes the note name. Can be used with s2v_f32_hz_then_khz().
• v2s_f32_panning
  Turn an f32 [-1, 1] value to a panning value where negative values are represented by [100L, 1L], 0 gets turned into C, and positive values become [1R, 100R] values.
• v2s_f32_percentage
  Format a [0, 1] number as a percentage. Does not include the percent sign, you should specify this as the parameter’s unit.
• v2s_f32_rounded
  Round an f32 value to always have a specific number of decimal digits. Avoids returning negative zero values to make sure string->value->string roundtrips work correctly. Otherwise -0.001 rounded to two digits would result in -0.00.
• v2s_i32_note_formatter
  Turns an integer MIDI note number (usually in the range [0, 127]) into a note name, where 60 is C4 and 69 is A4 (nice).
• v2s_i32_power_of_two
  Format an order/power of two. Useful in conjunction with s2v_i32_power_of_two() to limit integer parameter ranges to be only powers of two.