Struct DateFields 

#[non_exhaustive]
pub struct DateFields<'a> {
    pub era: Option<&'a [u8]>,
    pub era_year: Option<i32>,
    pub extended_year: Option<i32>,
    pub month_code: Option<&'a [u8]>,
    pub ordinal_month: Option<u8>,
    pub day: Option<u8>,
}

A bag of various ways of expressing the year, month, and/or day.

Pass this into Date::try_from_fields.

🚧 This code is considered unstable; it may change at any time, in breaking or non-breaking ways, including in SemVer minor releases. Do not use this type unless you are prepared for things to occasionally break.

Graduation tracking issue: issue #7161.

✨ Enabled with the unstable Cargo feature.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

era: Option<&'a [u8]>

The era code as a UTF-8 string.

The acceptable codes are defined by CLDR and documented on each calendar.

If set, Self::era_year must also be set.

Examples

To set the era field, use a byte string:

use icu::calendar::types::DateFields;

let mut fields = DateFields::default();

// As a byte string literal:
fields.era = Some(b"reiwa");

// Using str::as_bytes:
fields.era = Some("reiwa".as_bytes());

For a full example, see Self::extended_year.

era_year: Option<i32>

The numeric year in Self::era.

If set, Self::era must also be set.

For an example, see Self::extended_year.

extended_year: Option<i32>

See Date::extended_year().

If both this and Self::era/Self::era_year are set, they must refer to the same year.

Examples

Either extended_year or era + era_year can be used in DateFields:

use icu::calendar::cal::Japanese;
use icu::calendar::types::DateFields;
use icu::calendar::Date;

let mut fields1 = DateFields::default();
fields1.era = Some(b"reiwa");
fields1.era_year = Some(7);
fields1.ordinal_month = Some(1);
fields1.day = Some(1);

let date1 =
    Date::try_from_fields(fields1, Default::default(), Japanese::new())
        .expect("a well-defined Japanese date from era year");

let mut fields2 = DateFields::default();
fields2.extended_year = Some(2025);
fields2.ordinal_month = Some(1);
fields2.day = Some(1);

let date2 =
    Date::try_from_fields(fields2, Default::default(), Japanese::new())
        .expect("a well-defined Japanese date from extended year");

assert_eq!(date1, date2);

let year_info = date1.year().era().unwrap();
assert_eq!(year_info.year, 7);
assert_eq!(year_info.era.as_str(), "reiwa");
assert_eq!(year_info.extended_year, 2025);

month_code: Option<&'a [u8]>

The month code representing a valid month in this calendar year, as a UTF-8 string.

See MonthCode for information on the syntax.

Examples

To set the month code field, use a byte string:

use icu::calendar::types::DateFields;

let mut fields = DateFields::default();

// As a byte string literal:
fields.era = Some(b"M02L");

// Using str::as_bytes:
fields.era = Some("M02L".as_bytes());

For a full example, see Self::ordinal_month.

ordinal_month: Option<u8>

See MonthInfo::ordinal.

If both this and Self::month_code are set, they must refer to the same month.

Note: using Self::month_code is recommended, because the ordinal month numbers can vary from year to year, as illustrated in the following example.

Examples

Either month_code or ordinal_month can be used in DateFields, but they might not resolve to the same month number:

use icu::calendar::cal::ChineseTraditional;
use icu::calendar::types::DateFields;
use icu::calendar::Date;

// The 2023 Year of the Rabbit had a leap month after the 2nd month.
let mut fields1 = DateFields::default();
fields1.extended_year = Some(2023);
fields1.month_code = Some(b"M02L");
fields1.day = Some(1);

let date1 = Date::try_from_fields(
    fields1,
    Default::default(),
    ChineseTraditional::new(),
)
.expect("a well-defined Chinese date from month code");

let mut fields2 = DateFields::default();
fields2.extended_year = Some(2023);
fields2.ordinal_month = Some(3);
fields2.day = Some(1);

let date2 = Date::try_from_fields(
    fields2,
    Default::default(),
    ChineseTraditional::new(),
)
.expect("a well-defined Chinese date from ordinal month");

assert_eq!(date1, date2);

let month_info = date1.month();
assert_eq!(month_info.ordinal, 3);
assert_eq!(month_info.standard_code.0, "M02L");

day: Option<u8>

See DayOfMonth.

Trait Implementations

impl<'a> Clone for DateFields<'a>

fn clone(&self) -> DateFields<'a>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DateFields<'_>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> Default for DateFields<'a>

fn default() -> DateFields<'a>

Returns the “default value” for a type.

impl<'a> PartialEq for DateFields<'a>

fn eq(&self, other: &DateFields<'a>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a> Copy for DateFields<'a>

impl<'a> StructuralPartialEq for DateFields<'a>