chrono

Chrono provides functionality for correct operations on dates and times using the proleptic Gregorian calendar. Key features include:

• Timezone Awareness: The DateTime type is timezone-aware by default, while separate timezone-naive types are also available.
• Safety: Operations that might result in invalid or ambiguous dates/times return Option or MappedLocalTime.
• Formatting: Supports configurable parsing and formatting using an strftime-inspired syntax.
• OS Integration: The Local timezone type integrates with the current timezone of the operating system.
• Efficiency: Types and operations are designed for reasonable efficiency.

Note on Timezone Data: To keep binary sizes small, timezone data is not included by default. For full timezone support, use the companion crates chrono-tz or tzfile.

To execute the Chrono fuzzer, navigate to the root directory of the chrono repository and run the fuzz_reader target using cargo-fuzz.

cargo-fuzz run fuzz_reader

To perform fuzz testing on the Chrono crate, you must first install the cargo-fuzz tool using cargo.

cargo install cargo-fuzz

For convenience, you can use the prelude module to import the most commonly used types and traits. This is recommended for most use cases.

Included in the prelude:

• Timezone types: Utc, Local, FixedOffset (via TimeZone trait)
• Date/Time types: DateTime, NaiveDate, NaiveDateTime, NaiveTime
• Traits: Datelike, Timelike
• Enums: Month, Weekday, SecondsFormat
• Others: Locale (if unstable-locales is enabled), SubsecRound

use chrono::prelude::*;

Chrono has several features that can be enabled or disabled via Cargo.

Default features:

• alloc: Enables features depending on allocation (e.g., string formatting).
• std: Enables standard library functionality (superset of alloc).
• clock: Enables reading the local timezone (Local).
• now: Enables reading the system time (now).
• wasmbind: Interface with the JS Date API for wasm32 targets.

Optional features:

• serde: Enable serialization/deserialization via serde.
• rkyv-16, rkyv-32, rkyv-64: Enable zero-copy serialization via rkyv (these are mutually exclusive).
• rkyv-validation: Enable rkyv validation support using bytecheck.
• arbitrary: Construct arbitrary instances with the Arbitrary crate.
• unstable-locales: Enable localization (adds _localized methods). Requires alloc feature.
• unstable-locales requires alloc.

When using Chrono, be aware of the following technical constraints:

• Calendar: Only the proleptic Gregorian calendar is supported.
• Range: Date types are limited to approximately +/- 262,000 years from the common epoch.
• Precision: Time types are limited to nanosecond accuracy.
• Leap Seconds: While leap seconds can be represented, Chrono does not provide full support for them. Refer to the NaiveTime documentation for specific leap second handling details.

The DurationRound trait provides methods to round or truncate a DateTime or NaiveDateTime using a specific TimeDelta (duration) as the rounding interval.

• duration_round(duration): Returns a copy rounded to the nearest duration interval. Halfway values are rounded to the nearest interval based on the implementation logic.
• duration_trunc(duration): Returns a copy truncated to the nearest duration interval.
• duration_round_up(duration): Returns a copy rounded up to the next duration interval.

Limitations & Errors: These operations are performed via nanosecond timestamps. They will fail if:

• The TimeDelta or the DateTime cannot be represented as nanoseconds.
• The TimeDelta is larger than the timestamp, negative, or zero.

Errors returned are of type RoundingError.

The default value for NaiveDateTime is the 1st of January 1970 at 00:00:00.

Note: This is the timezone-naive version of the UNIX epoch. To get the actual timezone-aware UNIX epoch, use DateTime::UNIX_EPOCH.

You can create a new NaiveDateTime with modified components using with_* methods. These methods return an Option<NaiveDateTime>, returning None if the resulting date is invalid (e.g., February 29 in a non-leap year or an invalid month number).

Date modification:

• with_year(year: i32)
• with_month(month: u32)
• with_month0(month0: u32)
• with_day(day: u32)
• with_day0(day0: u32)
• with_ordinal(ordinal: u32)
• with_ordinal0(ordinal0: u32)

Time modification:

• with_hour(hour: u32)
• with_minute(min: u32)
• with_second(sec: u32)
• with_nanosecond(nano: u32)

If any rkyv feature is enabled, you can use the chrono::rkyv module to access archived versions of Chrono types for zero-copy deserialization.

Supported archived types include:

• ArchivedDateTime
• ArchivedMonth
• ArchivedNaiveDate
• ArchivedNaiveDateTime
• ArchivedIsoWeek
• ArchivedNaiveTime
• ArchivedFixedOffset
• ArchivedLocal (if clock is enabled)
• ArchivedUtc
• ArchivedTimeDelta
• ArchivedWeekday