Macro rust_icu_umsg::message_format

macro_rules! message_format {
    ($dest:expr $(,)?) => { ... };
    ($dest:expr, $( {$arg:expr => $t:ident} ),+ $(,)?) => { ... };
}

Given a formatter, formats the passed arguments into the formatter’s message.

The general usage pattern for the formatter is as follows, assuming that formatter is an appropriately initialized UMessageFormat:

use rust_icu_umsg as umsg;
// let result = umsg::message_format!(
//     formatter, [{ value => <type_assertion> }, ...]);
let result = umsg::message_format!(formatter, { 31337 => Double });

Each fragment { value => <type_assertion> } represents a single positional parameter binding for the pattern in formatter. The first fragment corresponds to the positional parameter 0 (which, if an integer, would be referred to as {0,number,integer} in a MessageFormat pattern). Since the original C API that this rust library is generated for uses variadic functions for parameter passing, it is very important that the programmer matches the actual parameter types to the types that are expected in the pattern.

Note: If the types of parameter bindings do not match the expectations in the pattern, memory corruption may occur, so tread lightly here.

In general this is very brittle, and an API in a more modern lanugage, or a contemporary C++ flavor would probably take a different route were the library to be written today. The rust binding tries to make the API use a bit more palatable by requiring that the programmer explicitly specifies a type for each of the parameters to be passed into the formatter.

The supported types are not those of a full rust system, but rather a very restricted subset of types that MessageFormat supports:

Type	Rust Type	Notes
Double	f64	Any numeric parameter not specifically designated as different type, is always a double. See section below on Doubles.
String	rust_icu_ustring::UChar
Integer	i32
Date	rust_icu_sys::UDate (alias for f64)	Is used to format dates. Depending on the date format requested in the pattern used in UMessageFormat, the end result of date formatting could be one of a wide variety of date formats.

Double as numeric parameter

According to the ICU documentation for umsg_format:

for all numeric arguments double is assumed unless the type is explicitly integer (long). All choice format arguments must be of type double.

Strings

We determined by code inspection that the string format must be rust_icu_ustring::UChar.

Example use

use rust_icu_sys as sys;
use rust_icu_common as common;
use rust_icu_ustring as ustring;
use rust_icu_uloc as uloc;
use rust_icu_umsg::{self as umsg, message_format};

fn testfn() -> Result<(), common::Error> {
  let loc = uloc::ULoc::try_from("en-US")?;
  let msg = ustring::UChar::try_from(
    r"Formatted double: {0,number,##.#},
      Formatted integer: {1,number,integer},
      Formatted string: {2},
      Date: {3,date,full}",
  )?;

  let fmt = umsg::UMessageFormat::try_from(&msg, &loc)?;
  let hello = ustring::UChar::try_from("Hello! Добар дан!")?;
  let result = umsg::message_format!(
    fmt,
    { 43.4 => Double },
    { 31337 => Integer },
    { hello => String },
    { 0.0 => Date },
  )?;

  assert_eq!(
    r"Formatted double: 43.4,
      Formatted integer: 31,337,
      Formatted string: Hello! Добар дан!,
      Date: Thursday, January 1, 1970",
    result
  );
Ok(())
}

Implements umsg_format. Implements umsg_vformat.