impl<'a> StrftimeItems<'a>

const fn new(s: &'a str) -> StrftimeItems<'a>

Creates a new parsing iterator from a strftime-like format string.

Errors

While iterating Item::Error will be returned if the format string contains an invalid or unrecognized formatting specifier.

Example

use chrono::format::*;

let strftime_parser = StrftimeItems::new("%F"); // %F: year-month-day (ISO 8601)

const ISO8601_YMD_ITEMS: &[Item<'static>] = &[
    Item::Numeric(Numeric::Year, Pad::Zero),
    Item::Literal("-"),
    Item::Numeric(Numeric::Month, Pad::Zero),
    Item::Literal("-"),
    Item::Numeric(Numeric::Day, Pad::Zero),
];
assert!(strftime_parser.eq(ISO8601_YMD_ITEMS.iter().cloned()));

const fn new_lenient(s: &'a str) -> StrftimeItems<'a>

The same as StrftimeItems::new, but returns Item::Literal instead of Item::Error.

Useful for formatting according to potentially invalid format strings.

Example

use chrono::format::*;

let strftime_parser = StrftimeItems::new_lenient("%Y-%Q"); // %Y: year, %Q: invalid

const ITEMS: &[Item<'static>] = &[
    Item::Numeric(Numeric::Year, Pad::Zero),
    Item::Literal("-"),
    Item::Literal("%Q"),
];
println!("{:?}", strftime_parser.clone().collect::<Vec<_>>());
assert!(strftime_parser.eq(ITEMS.iter().cloned()));

fn parse(self) -> Result<Vec<Item<'a>>, ParseError>

Parse format string into a Vec of formatting Item's.

If you need to format or parse multiple values with the same format string, it is more efficient to convert it to a Vec of formatting Item's than to re-parse the format string on every use.

The format_with_items methods on DateTime, NaiveDateTime, NaiveDate and NaiveTime accept the result for formatting. format::parse() can make use of it for parsing.

Errors

Returns an error if the format string contains an invalid or unrecognized formatting specifier and the StrftimeItems wasn't constructed with [new_lenient][Self::new_lenient].

Example

use chrono::format::{parse, Parsed, StrftimeItems};
use chrono::NaiveDate;

let fmt_items = StrftimeItems::new("%e %b %Y %k.%M").parse()?;
let datetime = NaiveDate::from_ymd_opt(2023, 7, 11).unwrap().and_hms_opt(9, 0, 0).unwrap();

// Formatting
assert_eq!(
    datetime.format_with_items(fmt_items.as_slice().iter()).to_string(),
    "11 Jul 2023  9.00"
);

// Parsing
let mut parsed = Parsed::new();
parse(&mut parsed, "11 Jul 2023  9.00", fmt_items.as_slice().iter())?;
let parsed_dt = parsed.to_naive_datetime_with_offset(0)?;
assert_eq!(parsed_dt, datetime);
# Ok::<(), chrono::ParseError>(())

fn parse_to_owned(self) -> Result<Vec<Item<'static>>, ParseError>

Parse format string into a Vec of Item's that contain no references to slices of the format string.

A Vec created with StrftimeItems::parse contains references to the format string, binding the lifetime of the Vec to that string. StrftimeItems::parse_to_owned will convert the references to owned types.

Errors

Returns an error if the format string contains an invalid or unrecognized formatting specifier and the StrftimeItems wasn't constructed with [new_lenient][Self::new_lenient].

Example

use chrono::format::{Item, ParseError, StrftimeItems};
use chrono::NaiveDate;

fn format_items(date_fmt: &str, time_fmt: &str) -> Result<Vec<Item<'static>>, ParseError> {
    // `fmt_string` is dropped at the end of this function.
    let fmt_string = format!("{} {}", date_fmt, time_fmt);
    StrftimeItems::new(&fmt_string).parse_to_owned()
}

let fmt_items = format_items("%e %b %Y", "%k.%M")?;
let datetime = NaiveDate::from_ymd_opt(2023, 7, 11).unwrap().and_hms_opt(9, 0, 0).unwrap();

assert_eq!(
    datetime.format_with_items(fmt_items.as_slice().iter()).to_string(),
    "11 Jul 2023  9.00"
);
# Ok::<(), ParseError>(())