# 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.

## Functions

- 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.0`will 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.