diff --git a/src/api/format-description.md b/src/api/format-description.md index 08fb5af..a9f4068 100644 --- a/src/api/format-description.md +++ b/src/api/format-description.md @@ -15,16 +15,7 @@ # Format description A format description is the manner in which the time crate knows how a value should be formatted and -parsed. However, a format description is not a single type; it is instead represented by two -internal traits (one for formatting and one for parsing) that are implemented by a number of types. -Currently, all types that implement one trait also implement the other, but this is not guaranteed. - -The following types currently implement both the `Formattable` and `Parsable` traits: - -- `FormatItem<'_>` -- `[FormatItem<'_>]` -- `T where ::Target: Formattable` (or `Parsable`) -- All [well known formats](./well-known-format-descriptions.md) +parsed. While it is possible to construct a format description manually, this is generally not recommended, as it is more tedious and less readable than the alternative. Unless you are doing this, you will @@ -47,6 +38,27 @@ to have both consecutive literals and consecutive components. Components must be between brackets with optional whitespace. Escaping behavior varies by version, and is described below. +## Modifiers + +Many of the components have optional modifiers to change how it is formatted or parsed. + +The `padding` modifier, such as used on the `hour` and `month` components can be padded +with `space`, `zero` or `none`. In the case of `none` leading zeros are still accepted during +parsing. + +## Traits + +A format description is not a single type; it is instead represented by two +internal traits (one for formatting and one for parsing) that are implemented by a number of types. +Currently, all types that implement one trait also implement the other, but this is not guaranteed. + +The following types currently implement both the `Formattable` and `Parsable` traits: + +- `FormatItem<'_>` +- `[FormatItem<'_>]` +- `T where ::Target: Formattable` (or `Parsable`) +- All [well known formats](./well-known-format-descriptions.md) + ## Versioning There are multiple versions of the format description syntax in `time`. Similar to Rust editions,