Module chrono

Expand description

Date and time library.

chrono provides comprehensive date and time functionality for Rust. It supports timezone-aware and timezone-naive date and time types, parsing and formatting with standard formats like RFC 3339 and ISO 8601, and arithmetic operations on dates and times.

Note that while widely used in the Rust ecosystem its API is unwieldy. Most users that just need to work with dates should prefer jiff.

The library centers around several core types: NaiveDate for dates without timezones, NaiveTime for times without timezones, NaiveDateTime for combined date-time without timezones, and DateTime<Tz> for timezone-aware date-times.

Chrono uses the TimeZone trait to handle timezone conversions, with built-in support for UTC and local time, plus optional support for the IANA timezone database through the chrono-tz crate.

The design emphasizes correctness and type safety, making invalid states unrepresentable where possible. All types are designed to be space-efficient and performant.

§Examples

Working with dates and times:

use chrono::{DateTime, Utc, Local, NaiveDate, Duration};

// Current time in UTC
let now_utc: DateTime<Utc> = Utc::now();
println!("UTC now: {}", now_utc);

// Current local time
let now_local: DateTime<Local> = Local::now();
println!("Local now: {}", now_local);

// Create a specific date
let date = NaiveDate::from_ymd_opt(2024, 3, 15).unwrap();
let datetime = date.and_hms_opt(14, 30, 0).unwrap();
println!("Specific datetime: {}", datetime);

// Add duration
let future = now_utc + Duration::days(7);
println!("One week from now: {}", future);

Parsing and formatting dates:

use chrono::{DateTime, Utc, NaiveDateTime};

// Parse RFC 3339 / ISO 8601
let parsed = "2024-03-15T14:30:00Z".parse::<DateTime<Utc>>().unwrap();
println!("Parsed: {}", parsed);

// Custom formatting
let formatted = parsed.format("%Y-%m-%d %H:%M:%S");
println!("Formatted: {}", formatted);

// Parse custom format
let naive = NaiveDateTime::parse_from_str(
    "2024-03-15 14:30:00",
    "%Y-%m-%d %H:%M:%S"
).unwrap();
println!("Parsed naive: {}", naive);

Modules§

format: Formatting (and parsing) utilities for date and time.
naive: Date and time types unconcerned with timezones.
offset: The time zone, which calculates offsets from the local time to UTC.
prelude: A convenience module appropriate for glob imports (use chrono::prelude::*;).
round: Functionality for rounding or truncating a DateTime by a TimeDelta.

Structs§

DateDeprecated: ISO 8601 calendar date with time zone.
DateTime: ISO 8601 combined date and time with time zone.
Days: A duration in calendar days.
FixedOffset: The time zone with fixed offset, from UTC-23:59:59 to UTC+23:59:59.
IsoWeek: ISO 8601 week.
Local: The local timescale.
Months: A duration in calendar months
NaiveDate: ISO 8601 calendar date without timezone. Allows for every proleptic Gregorian date from Jan 1, 262145 BCE to Dec 31, 262143 CE. Also supports the conversion from ISO 8601 ordinal and week date.
NaiveDateTime: ISO 8601 combined date and time without timezone.
NaiveTime: ISO 8601 time without timezone. Allows for the nanosecond precision and optional leap second representation.
NaiveWeek: A week represented by a NaiveDate and a Weekday which is the first day of the week.
OutOfRange: Out of range error type used in various converting APIs
OutOfRangeError: Represents error when converting TimeDelta to/from a standard library implementation
ParseError: An error from the parse function.
ParseMonthError: An error resulting from reading <Month> value with FromStr.
ParseWeekdayError: An error resulting from reading Weekday value with FromStr.
TimeDelta: Time duration with nanosecond precision.
Utc: The UTC time zone. This is the most efficient time zone when you don’t need the local time. It is also used as an offset (which is also a dummy type).

Enums§

LocalResult: Old name of MappedLocalTime. See that type for more documentation.
Month: The month of the year.
RoundingError: An error from rounding by TimeDelta
SecondsFormat: Specific formatting options for seconds. This may be extended in the future, so exhaustive matching in external code is not recommended.
Weekday: The day of week.

Constants§

MAX_DATEDeprecated: The maximum possible Date.
MAX_DATETIMEDeprecated: The maximum possible DateTime<Utc>.
MIN_DATEDeprecated: The minimum possible Date.
MIN_DATETIMEDeprecated: The minimum possible DateTime<Utc>.

Traits§

Datelike: The common set of methods for date component.
DurationRound: Extension trait for rounding or truncating a DateTime by a TimeDelta.
Offset: The offset from the local time to UTC.
SubsecRound: Extension trait for subsecond rounding or truncation to a maximum number of digits. Rounding can be used to decrease the error variance when serializing/persisting to lower precision. Truncation is the default behavior in Chrono display formatting. Either can be used to guarantee equality (e.g. for testing) when round-tripping through a lower precision format.
TimeZone: The time zone.
Timelike: The common set of methods for time component.

Type Aliases§

Duration: Alias of TimeDelta.
MappedLocalTime: The result of mapping a local time to a concrete instant in a given time zone.
ParseResult: Same as Result<T, ParseError>.

Module chronoCopy item path