Struct Year

pub struct Year(/* private fields */);

SAC13 year. It roughly corresponds to the Gregorian Year + 10’000. Roughly, because the Gregorian Calendar starts its year with January and SAC13 with March.

The year can have any value from 0 to 25’999 (both inclusive).

Examples

use sac13::prelude::*;

// Preferred method for hard-coded / compile-time years:
let year = year!(M024);

// From &str (e.g. user input):
let year = Year::try_from_str("M024").unwrap();

// From an integer (via `TryFrom` trait):
let year = Year::new(12_024).unwrap();

// Year construction via const compile-time helper function:
// Prefer that method if you know the year at compile-time.

TODO: year construction only via TryFrom?

About the limits

Even though the SAC13 calendar system design could easily support negative years and years beyond 26’000 we intentionally chose not to for the following reasons:

• The 10’000 year offset compared to the Gregorian Calendar the year zero is so far in the past, there aren’t really any applications for exact dates around that time. Maybe astronomers, but they already use linear time-scales like JDN instead of civil calendars.

• The year 25’999 is so far in the future it’s highly unlikely, that this calendar would survive unaltered for that long anyway. I hope that humans (or our AI overlords) are no longer interested in Earth-based solar calendars at that point.

• SAC13 years are typically written with a millennium indicator letter (A=0, B=1, …, Z=25) to disambiguate between SAC13 and the Gregorian Calendar. So the year 12’020 is written as M020 and the year 25’999 would be Z999.

All SAC13 implementations have to respect those limits and handle edge cases accordingly. Having different limits than zero and 25’999 is considered a bug. Limits should be handled as graceful as possible.

For example:

• If you have a UI, prevent the user from switching to dates outside the limit.
• If you process data, or handle requests, return an error if the request contains invalid dates (dates outside the limits are invalid!).
• As a last resort you can also log, silently drop or abort the process in those cases.

The benefit of such strict rules is that everybody knows what to expect and what other systems consider valid or invalid. Unlike with the Gregorian Calender where everybody decides for themselves what the limits are. Because of that, every software out there handles the cases differently on arbitrary limits.

If you are implementing SAC13 according to the specification you know for a fact that using a 16 bit integer (signed or unsigned doesn’t matter) would be enough.

Implementations

impl Year

pub const MIN_INT: u16 = 0u16

Earliest representable date (in its native integer type).

pub const MAX_INT: u16 = 25_999u16

Latest representable value (in its native integer type).

pub const MIN: Self

Earliest representable date

pub const MAX: Self

Latest representable value

pub const fn new(value: u16) -> Option<Self>

Creates a new Year.

Returns None for invalid values. Valid values are between (and including) MIN_INT (A000-01-01) and MAX_INT (Z999-13-29).

pub const fn value(&self) -> u16

Returns the underlying integer value.

pub const fn next(&self) -> Option<Self>

Returns the next year. Returns None if the next year is outside the valid SAC13 range.

pub const fn previous(&self) -> Option<Self>

Returns the previous year. Returns None if the previous year is outside the valid SAC13 range.

impl Year

pub const fn try_from_str(year: &str) -> Option<Self>

Used internally for the year!() macro. TODO: details

pub const fn year_type(&self) -> YearType

Returns the type of the year (leap year or common year).

pub const fn is_leap(&self) -> bool

pub const fn is_common(&self) -> bool

pub const fn days(&self) -> u16

Returns the number of days the year has.

Can only be 365 or 366.

Trait Implementations

impl Clone for Year

fn clone(&self) -> Year

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Year

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

Formats the value using the given formatter.

impl Display for Year

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

Displays the year with prefixed millennium indicator.

use sac13::year;

let formatted_year = format!("{}", year!(M020));
assert_eq!(formatted_year, "M020");

impl Hash for Year

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

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 Ord for Year

fn cmp(&self, other: &Year) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Year

fn eq(&self, other: &Year) -> 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 PartialOrd for Year

fn partial_cmp(&self, other: &Year) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Copy for Year

impl Eq for Year

impl StructuralPartialEq for Year