Function format_float_str 

pub fn format_float_str(x: &Float, fmt: &str) -> Option<String>

Formats a Float according to an MPFR-style printf format string, for strict compatibility with MPFR’s mpfr_printf family.

The format string should contain a single conversion consuming the Float, written %[flags][width][.precision]R[rounding]conv, with any surrounding literal text (a literal % is written %%). The pieces are:

• flags: any of - (left-justify within the field), + (always show a sign), space (show a space before a nonnegative value), # (alternate form: always print a radix point, and keep trailing zeros for g/G), 0 (pad the field with leading zeros), and ' (group the integer part into thousands separated by ,).
• width: the minimum field width, as a decimal integer.
• precision: following a ., the number of digits after the radix point (for e/f and their hexadecimal/binary analogues) or the number of significant digits (for g); it defaults to 6.
• R: marks the argument as a Float (MPFR’s length modifier).
• rounding: an optional MPFR rounding character — N (to nearest, the default), D (toward $-\infty$), U (toward $+\infty$), Y (away from zero), or Z (toward zero).
• conv: the conversion — e/E (scientific), f/F (fixed-point), g/G (general), a/A (hexadecimal significand with a binary exponent), or b (binary significand with a binary exponent).

Returns None when the format string is not a single well-formed Float conversion: for instance if it uses * for the width or precision (which would need an integer argument that this single-value entry point does not supply), contains no %R conversion or more than one, requests a width or precision that overflows, or would produce an over-long result.

Worst-case complexity

$T(n) = O(n (\log n)^2 \log\log n)$

$M(n) = O(n \log n)$

where $T$ is time, $M$ is additional memory, and $n$ is max(x.complexity(), p, w), with p and w the precision and field width requested by the format string.

Examples

use malachite_float::float::conversion::string::format_float::format_float_str;
use malachite_float::Float;

// fixed-point, scientific, and hexadecimal conversions
assert_eq!(
    format_float_str(&Float::from(1.5), "%.3Rf"),
    Some("1.500".to_string())
);
assert_eq!(
    format_float_str(&Float::from(1.5), "%.5Re"),
    Some("1.50000e+00".to_string())
);
assert_eq!(
    format_float_str(&Float::from(255.0), "%Ra"),
    Some("0xf.fp+4".to_string())
);

// surrounding literal text is copied; a rounding character overrides the default of nearest
assert_eq!(
    format_float_str(&Float::from(1.5), "x = %Rg!"),
    Some("x = 1.5!".to_string())
);
assert_eq!(
    format_float_str(&Float::from(1.5), "%.0RUf"),
    Some("2".to_string())
);

// `*` needs an integer argument that this single-value entry point does not provide
assert_eq!(format_float_str(&Float::from(1.5), "%*Rf"), None);

A single-value entry point over the port of the %R path of mpfr_vasnprintf_aux (vasprintf.c, MPFR 4.2.2): format_float_str(x, fmt) is format(fmt, &[PrintfArg::Float(x)]). The output is valid UTF-8 because every literal run of fmt (% is ASCII, so it never splits a multi-byte character) and every conversion’s output is.