Module datetime::format

Date and Time Formatting

There are various competing standards for how a date-time formatting string should look: Unix-style strftime with % symbols and flags, Joda-style formatters that use the number of letters as their widths, and many others, each with their own idiosyncrasies and subtle differences. Thus, it should come as no surprise that this library invents another style of formatting string, designed to mimic the syntax of the format! and println! macros.

In order to format a date, you must first create a formatter object, passing in a formatting string. This string is checked for correctness, after which it's guaranteed to always work. For example:

use datetime::format::DateFormat;
let formatter = match DateFormat::parse("{_:M} {:D}, {:Y}") {
    Ok(f) => f,
    Err(e) => panic!("Error in format string: {}", e),
};

If there's a syntax error in the formatting string, the Err(e) path will be followed, terminating the program and printing out an error. (It's usually considered better style to handle your errors more gracefully than this.) For this reason, it's preferable to use the date_format! macro whenever your formatting string is fixed, as this will check its syntax at compile-time, reporting an error if it is invalid, and removing the need for the match construct entirely:

use datetime::format::DateFormat;
let formatter = date_format!("{_:M} {:D}, {:Y}");

Locales

The second thing you need to be aware of before actually being able to format a date into a string is the concept of locales. A Locale object specifies how the months and days should be named. "January" isn't universally understood: in some places it's "janvier"; in others, "Janeiro", or "Ιανουαρίου", or "января", or "一月".

To govern which language a formatter should use, a Locale object can be passed in. For more information on how Locale objects work, see the documentation on the Locale crate.

If you're in a hurry and just want to format a date right now then the simplest way to get around this is to just use the English locale:

use locale;
let my_locale = locale::Time::english();

Actually Formatting a Date

Structs

Arguments
DateFormat
NumArguments
TextArguments

Enums

Field
FormatError

Type Definitions

Pos
Width