Module nih_plug::formatters

source ·
Expand description

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.


  • Parse a string in the same format as `v2s_bool_bypass().
  • 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.
  • 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.
  • 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.`.
  • Parse a pan value in the format of [v2s_f32_panning()] to a linear value in the range [-1, 1]`.
  • Parse a [0, 100] percentage to a [0, 1] number. Handles the percentage unit for you. Used in conjunction with v2s_f32_percentage().
  • Parse a note name to a MIDI number using the inverse mapping from `v2s_i32_note_formatter().
  • 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.
  • 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.
  • 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.
  • 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`.
  • 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(), but also includes the note name. Can be used with s2v_f32_hz_then_khz().
  • 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.
  • Format a [0, 1] number as a percentage. Does not include the percent sign, you should specify this as the parameter’s unit.
  • 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.
  • 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).
  • 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.