Enum ReportingPeriod 

#[non_exhaustive]
pub enum ReportingPeriod {
    Quarter {
        year: PeriodYear,
        quarter: QuarterOfYear,
    },
    Year {
        year: PeriodYear,
    },
    Date(PeriodDate),
    Other(OtherPeriod),
}

Reporting or fiscal period label with structured variants and extensible fallback.

ReportingPeriod models labels reported by issuers, analysts, or providers: 2023Q4, FY2023, 2023-12-31, and provider-specific ranges are labels, not calendar boundary claims. A fiscal 2023Q4 may not overlap calendar Q4. Use CalendarPeriod when you need date boundary helpers.

Canonical/serde rules:

• Emission uses a single canonical form per variant (UPPERCASE ASCII where applicable)
• Parser accepts a superset of tokens (aliases, case-insensitive where appropriate)
• Other(s) serializes to its canonical code() string (no escape prefix)
• Display output matches the canonical form for structured variants and the raw s for Other(s)
• Serde round-trips preserve identity for canonical variants; unknown tokens normalize to Other(UPPERCASE)

Canonical outputs:

• Quarters: YYYYQ# (e.g., 2023Q4)
• Years: YYYY (e.g., 2023)
• Dates: YYYY-MM-DD (ISO 8601)
• Other stores and emits canonicalize-style tokens

Display and serde always emit the canonical forms listed above. The parser accepts common provider variants (e.g., FY2023, 2023-Q4, 12/31/2023) and normalizes to the single canonical emission for round-trip stability.

ReportingPeriod intentionally does not implement Ord or date-boundary helpers: cross-granularity ordering needs caller-chosen semantics (fiscal calendar, exact date, provider-specific Other, etc.).

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Quarter

Quarterly period with year and quarter number

Fields

year: PeriodYear

The year of the quarter

quarter: QuarterOfYear

The quarter number (1-4)

Year

Annual period with year

Fields

year: PeriodYear

The year of the annual period

Date(PeriodDate)

Specific date

Tuple Fields

0: PeriodDate

Validated calendar date

Other(OtherPeriod)

Unknown or provider-specific period format

Implementations

impl ReportingPeriod

pub fn quarterly(year: i32, quarter: u8) -> Result<ReportingPeriod, DomainError>

Builds a validated quarterly period.

Errors

Returns DomainError::InvalidPeriodYear or DomainError::InvalidPeriodQuarter when either component is outside its accepted range.

pub fn annual(year: i32) -> Result<ReportingPeriod, DomainError>

Builds a validated annual period.

Errors

Returns DomainError::InvalidPeriodYear when year is outside 0..=9999.

pub fn date(date: NaiveDate) -> Result<ReportingPeriod, DomainError>

Builds a validated date period.

Errors

Returns DomainError::InvalidPeriodYear when date.year() is outside 0..=9999.

pub fn other(input: &str) -> Result<ReportingPeriod, DomainError>

Builds an unknown period token, rejecting tokens modeled by ReportingPeriod.

Errors

Returns an error if input is empty, cannot be canonicalized, parses to a modeled ReportingPeriod variant, or matches a supported structured period shape with invalid components.

Partial modeled-looking provider labels that do not match a supported structured parser, such as FY, may still be accepted as ReportingPeriod::Other.

pub fn code(&self) -> Cow<'_, str>

Returns the canonical display/serde code for this period.

pub const fn year(&self) -> Option<i32>

Returns the year for this period, if applicable

pub const fn period_year(&self) -> Option<PeriodYear>

Returns the validated year component for this period, if applicable.

pub const fn quarter(&self) -> Option<u8>

Returns the quarter number for quarterly periods

pub const fn quarter_of_year(&self) -> Option<QuarterOfYear>

Returns the validated quarter component for quarterly periods.

pub const fn is_quarterly(&self) -> bool

Returns true if this is a quarterly period

pub const fn is_annual(&self) -> bool

Returns true if this is an annual period

pub const fn is_date(&self) -> bool

Returns true if this is a specific date period

Trait Implementations

impl Clone for ReportingPeriod

fn clone(&self) -> ReportingPeriod

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ReportingPeriod

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for ReportingPeriod

fn deserialize<D>( deserializer: D, ) -> Result<ReportingPeriod, <D as Deserializer<'de>>::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for ReportingPeriod

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

Formats the value using the given formatter.

impl Eq for ReportingPeriod

impl From<CalendarPeriod> for ReportingPeriod

fn from(period: CalendarPeriod) -> ReportingPeriod

Converts to this type from the input type.

impl FromStr for ReportingPeriod

fn from_str( s: &str, ) -> Result<ReportingPeriod, <ReportingPeriod as FromStr>::Err>

Invariant: the canonical form of a ReportingPeriod::Other produced here is guaranteed not to parse as any structured variant on a subsequent deserialize. Without this, inputs like "-2023Q4" (rejected by the structured parsers because of the leading -) would canonicalize to "2023Q4" and serialize back to a string that re-parses as ReportingPeriod::Quarter, breaking round-trip identity.

To maintain the invariant without accepting malformed aliases, we re-run the structured parsers on the canonicalized form before returning Other. If any parser recognizes the canonical form, we return InvalidPeriodFormat; otherwise a malformed input such as "-2023Q4" would silently become ReportingPeriod::Quarter.

type Err = DomainError

The associated error which can be returned from parsing.

impl Hash for ReportingPeriod

fn hash<__H>(&self, state: &mut __H)

where __H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for ReportingPeriod

fn eq(&self, other: &ReportingPeriod) -> bool

Equality operator ==.

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

Inequality operator !=.

impl Serialize for ReportingPeriod

fn serialize<S>( &self, serializer: S, ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for ReportingPeriod

impl TryFrom<String> for ReportingPeriod

type Error = DomainError

The type returned in the event of a conversion error.

fn try_from( s: String, ) -> Result<ReportingPeriod, <ReportingPeriod as TryFrom<String>>::Error>

Performs the conversion.