pub struct DateTime<Tz: TimeZone> { /* private fields */ }
Expand description

ISO 8601 combined date and time with time zone.

There are some constructors implemented here (the from_* methods), but the general-purpose constructors are all via the methods on the TimeZone implementations.

Implementations

Makes a new DateTime with given UTC datetime and offset. The local datetime should be constructed via the TimeZone trait.

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

let dt = DateTime::<Utc>::from_utc(NaiveDateTime::from_timestamp(61, 0), Utc);
assert_eq!(Utc.timestamp(61, 0), dt);

Makes a new DateTime with given local datetime and offset that presents local timezone.

Example
use chrono::DateTime;
use chrono::naive::NaiveDate;
use chrono::offset::{Utc, FixedOffset};

let naivedatetime_utc = NaiveDate::from_ymd(2000, 1, 12).and_hms(2, 0, 0);
let datetime_utc = DateTime::<Utc>::from_utc(naivedatetime_utc, Utc);

let timezone_east = FixedOffset::east(8 * 60 * 60);
let naivedatetime_east = NaiveDate::from_ymd(2000, 1, 12).and_hms(10, 0, 0);
let datetime_east = DateTime::<FixedOffset>::from_local(naivedatetime_east, timezone_east);

let timezone_west = FixedOffset::west(7 * 60 * 60);
let naivedatetime_west = NaiveDate::from_ymd(2000, 1, 11).and_hms(19, 0, 0);
let datetime_west = DateTime::<FixedOffset>::from_local(naivedatetime_west, timezone_west);
assert_eq!(datetime_east, datetime_utc.with_timezone(&timezone_east));
assert_eq!(datetime_west, datetime_utc.with_timezone(&timezone_west));

Retrieves a date component

Unless you are immediately planning on turning this into a DateTime with the same Timezone you should use the date_naive method.

use chrono::prelude::*;

let date: Date<Utc> = Utc.ymd(2020, 1, 1);
let dt: DateTime<Utc> = date.and_hms(0, 0, 0);

assert_eq!(dt.date(), date);

assert_eq!(dt.date().and_hms(1, 1, 1), date.and_hms(1, 1, 1));

Retrieves the Date without an associated timezone

NaiveDate is a more well-defined type, and has more traits implemented on it, so should be preferred to Date any time you truly want to operate on Dates.

use chrono::prelude::*;

let date: DateTime<Utc> = Utc.ymd(2020, 1, 1).and_hms(0, 0, 0);
let other: DateTime<FixedOffset> = FixedOffset::east(23).ymd(2020, 1, 1).and_hms(0, 0, 0);
assert_eq!(date.date_naive(), other.date_naive());

Retrieves a time component. Unlike date, this is not associated to the time zone.

Returns the number of non-leap seconds since January 1, 1970 0:00:00 UTC (aka “UNIX timestamp”).

Returns the number of non-leap-milliseconds since January 1, 1970 UTC

Note that this does reduce the number of years that can be represented from ~584 Billion to ~584 Million. (If this is a problem, please file an issue to let me know what domain needs millisecond precision over billions of years, I’m curious.)

Example
use chrono::Utc;
use chrono::TimeZone;

let dt = Utc.ymd(1970, 1, 1).and_hms_milli(0, 0, 1, 444);
assert_eq!(dt.timestamp_millis(), 1_444);

let dt = Utc.ymd(2001, 9, 9).and_hms_milli(1, 46, 40, 555);
assert_eq!(dt.timestamp_millis(), 1_000_000_000_555);

Returns the number of non-leap-microseconds since January 1, 1970 UTC

Note that this does reduce the number of years that can be represented from ~584 Billion to ~584 Thousand. (If this is a problem, please file an issue to let me know what domain needs microsecond precision over millennia, I’m curious.)

Example
use chrono::Utc;
use chrono::TimeZone;

let dt = Utc.ymd(1970, 1, 1).and_hms_micro(0, 0, 1, 444);
assert_eq!(dt.timestamp_micros(), 1_000_444);

let dt = Utc.ymd(2001, 9, 9).and_hms_micro(1, 46, 40, 555);
assert_eq!(dt.timestamp_micros(), 1_000_000_000_000_555);

Returns the number of non-leap-nanoseconds since January 1, 1970 UTC

Note that this does reduce the number of years that can be represented from ~584 Billion to ~584. (If this is a problem, please file an issue to let me know what domain needs nanosecond precision over millennia, I’m curious.)

Example
use chrono::Utc;
use chrono::TimeZone;

let dt = Utc.ymd(1970, 1, 1).and_hms_nano(0, 0, 1, 444);
assert_eq!(dt.timestamp_nanos(), 1_000_000_444);

let dt = Utc.ymd(2001, 9, 9).and_hms_nano(1, 46, 40, 555);
assert_eq!(dt.timestamp_nanos(), 1_000_000_000_000_000_555);

Returns the number of milliseconds since the last second boundary

warning: in event of a leap second, this may exceed 999

note: this is not the number of milliseconds since January 1, 1970 0:00:00 UTC

Returns the number of microseconds since the last second boundary

warning: in event of a leap second, this may exceed 999_999

note: this is not the number of microseconds since January 1, 1970 0:00:00 UTC

Returns the number of nanoseconds since the last second boundary

warning: in event of a leap second, this may exceed 999_999_999

note: this is not the number of nanoseconds since January 1, 1970 0:00:00 UTC

Retrieves an associated offset from UTC.

Retrieves an associated time zone.

Changes the associated time zone. The returned DateTime references the same instant of time from the perspective of the provided time zone.

Adds given Duration to the current date and time.

Returns None when it will result in overflow.

Subtracts given Duration from the current date and time.

Returns None when it will result in overflow.

Subtracts another DateTime from the current date and time. This does not overflow or underflow at all.

Returns a view to the naive UTC datetime.

Returns a view to the naive local datetime.

Retrieve the elapsed years from now to the given DateTime.

The minimum possible DateTime<Utc>.

The maximum possible DateTime<Utc>.

Parses an RFC 2822 date and time string such as Tue, 1 Jul 2003 10:52:37 +0200, then returns a new DateTime with a parsed FixedOffset.

RFC 2822 is the internet message standard that specifies the representation of times in HTTP and email headers.

assert_eq!(
    DateTime::parse_from_rfc2822("Wed, 18 Feb 2015 23:16:09 GMT").unwrap(),
    FixedOffset::east(0).ymd(2015, 2, 18).and_hms(23, 16, 9)
);

Parses an RFC 3339 and ISO 8601 date and time string such as 1996-12-19T16:39:57-08:00, then returns a new DateTime with a parsed FixedOffset.

Why isn’t this named parse_from_iso8601? That’s because ISO 8601 allows some freedom over the syntax and RFC 3339 exercises that freedom to rigidly define a fixed format.

Parses a string with the specified format string and returns a new DateTime with a parsed FixedOffset.

See the crate::format::strftime module on the supported escape sequences.

See also TimeZone::datetime_from_str which gives a local DateTime on specific time zone.

Note that this method requires a timezone in the string. See NaiveDateTime::parse_from_str for a version that does not require a timezone in the to-be-parsed str.

Example
use chrono::{DateTime, FixedOffset, TimeZone};

let dt = DateTime::parse_from_str(
    "1983 Apr 13 12:09:14.274 +0000", "%Y %b %d %H:%M:%S%.3f %z");
assert_eq!(dt, Ok(FixedOffset::east(0).ymd(1983, 4, 13).and_hms_milli(12, 9, 14, 274)));

Returns an RFC 2822 date and time string such as Tue, 1 Jul 2003 10:52:37 +0200.

Returns an RFC 3339 and ISO 8601 date and time string such as 1996-12-19T16:39:57-08:00.

Return an RFC 3339 and ISO 8601 date and time string with subseconds formatted as per a SecondsFormat.

If passed use_z true and the timezone is UTC (offset 0), use ‘Z’, as per Fixed::TimezoneOffsetColonZ If passed use_z false, use Fixed::TimezoneOffsetColon

Examples
let dt = Utc.ymd(2018, 1, 26).and_hms_micro(18, 30, 9, 453_829);
assert_eq!(dt.to_rfc3339_opts(SecondsFormat::Millis, false),
           "2018-01-26T18:30:09.453+00:00");
assert_eq!(dt.to_rfc3339_opts(SecondsFormat::Millis, true),
           "2018-01-26T18:30:09.453Z");
assert_eq!(dt.to_rfc3339_opts(SecondsFormat::Secs, true),
           "2018-01-26T18:30:09Z");

let pst = FixedOffset::east(8 * 60 * 60);
let dt = pst.ymd(2018, 1, 26).and_hms_micro(10, 30, 9, 453_829);
assert_eq!(dt.to_rfc3339_opts(SecondsFormat::Secs, true),
           "2018-01-26T10:30:09+08:00");

Formats the combined date and time with the specified formatting items.

Formats the combined date and time with the specified format string. See the crate::format::strftime module on the supported escape sequences.

Example
use chrono::prelude::*;

let date_time: DateTime<Utc> = Utc.ymd(2017, 04, 02).and_hms(12, 50, 32);
let formatted = format!("{}", date_time.format("%d/%m/%Y %H:%M"));
assert_eq!(formatted, "02/04/2017 12:50");

Trait Implementations

The resulting type after applying the + operator.
Performs the + operation. Read more
The resulting type after applying the + operator.
Performs the + operation. Read more
Performs the += operation. Read more
Returns a copy of the value. Read more
Performs copy-assignment from source. Read more
Returns the year number in the calendar date.
Returns the month number starting from 1. Read more
Returns the month number starting from 0. Read more
Returns the day of month starting from 1. Read more
Returns the day of month starting from 0. Read more
Returns the day of year starting from 1. Read more
Returns the day of year starting from 0. Read more
Returns the day of week.
Returns the ISO week.
Makes a new value with the year number changed. Read more
Makes a new value with the month number (starting from 1) changed. Read more
Makes a new value with the month number (starting from 0) changed. Read more
Makes a new value with the day of month (starting from 1) changed. Read more
Makes a new value with the day of month (starting from 0) changed. Read more
Makes a new value with the day of year (starting from 1) changed. Read more
Makes a new value with the day of year (starting from 0) changed. Read more
Returns the absolute year number starting from 1 with a boolean flag, which is false when the year predates the epoch (BCE/BC) and true otherwise (CE/AD). Read more
Counts the days in the proleptic Gregorian calendar, with January 1, Year 1 (CE) as day 1. Read more
Formats the value using the given formatter. Read more
Returns the “default value” for a type. Read more
Returns the “default value” for a type. Read more
Returns the “default value” for a type. Read more

Deserialize a value that optionally includes a timezone offset in its string representation

The value to be deserialized must be an rfc3339 string.

See the serde module for alternate deserialization formats.

Deserialize this value from the given Serde deserializer. Read more

Deserialize a value that includes no timezone in its string representation

The value to be deserialized must be an rfc3339 string.

See the serde module for alternate serialization formats.

Deserialize this value from the given Serde deserializer. Read more

Deserialize into a UTC value

The value to be deserialized must be an rfc3339 string.

See the serde module for alternate deserialization formats.

Deserialize this value from the given Serde deserializer. Read more
Formats the value using the given formatter. Read more
Error that can occur in rounding or truncating
Return a copy rounded by Duration. Read more
Return a copy truncated by Duration. Read more

Convert a DateTime<FixedOffset> instance into a DateTime<Local> instance.

Convert this DateTime<FixedOffset> instance into a DateTime<Local> instance.

Conversion is performed via DateTime::with_timezone. Returns the equivalent value in local time.

Convert a DateTime<FixedOffset> instance into a DateTime<Utc> instance.

Convert this DateTime<FixedOffset> instance into a DateTime<Utc> instance.

Conversion is performed via DateTime::with_timezone, accounting for the timezone difference.

Convert a DateTime<Local> instance into a DateTime<FixedOffset> instance.

Convert this DateTime<Local> instance into a DateTime<FixedOffset> instance.

Conversion is performed via DateTime::with_timezone. Note that the converted value returned by this will be created with a fixed timezone offset of 0.

Convert a DateTime<Local> instance into a DateTime<Utc> instance.

Convert this DateTime<Local> instance into a DateTime<Utc> instance.

Conversion is performed via DateTime::with_timezone, accounting for the difference in timezones.

Converts to this type from the input type.

Convert a DateTime<Utc> instance into a DateTime<FixedOffset> instance.

Convert this DateTime<Utc> instance into a DateTime<FixedOffset> instance.

Conversion is done via DateTime::with_timezone. Note that the converted value returned by this will be created with a fixed timezone offset of 0.

Convert a DateTime<Utc> instance into a DateTime<Local> instance.

Convert this DateTime<Utc> instance into a DateTime<Local> instance.

Conversion is performed via DateTime::with_timezone, accounting for the difference in timezones.

Converts to this type from the input type.
Converts to this type from the input type.

Accepts a relaxed form of RFC3339. A space or a ‘T’ are acepted as the separator between the date and time parts. Additional spaces are allowed between each component.

All of these examples are equivalent:

"2012-12-12T12:12:12Z".parse::<DateTime<FixedOffset>>();
"2012-12-12 12:12:12Z".parse::<DateTime<FixedOffset>>();
"2012-  12-12T12:  12:12Z".parse::<DateTime<FixedOffset>>();
The associated error which can be returned from parsing.
Parses a string s to return a value of this type. Read more

Accepts a relaxed form of RFC3339. A space or a ‘T’ are acepted as the separator between the date and time parts. Additional spaces are allowed between each component.

All of these examples are equivalent:

"2012-12-12T12:12:12Z".parse::<DateTime<Local>>();
"2012-12-12 12:12:12Z".parse::<DateTime<Local>>();
"2012-  12-12T12:  12:12Z".parse::<DateTime<Local>>();
The associated error which can be returned from parsing.
Parses a string s to return a value of this type. Read more

Accepts a relaxed form of RFC3339. A space or a ‘T’ are acepted as the separator between the date and time parts. Additional spaces are allowed between each component.

All of these examples are equivalent:

"2012-12-12T12:12:12Z".parse::<DateTime<Utc>>();
"2012-12-12 12:12:12Z".parse::<DateTime<Utc>>();
"2012-  12-12T12:  12:12Z".parse::<DateTime<Utc>>();
The associated error which can be returned from parsing.
Parses a string s to return a value of this type. Read more
Feeds this value into the given Hasher. Read more
Feeds a slice of this type into the given Hasher. Read more
This method returns an Ordering between self and other. Read more
Compares and returns the maximum of two values. Read more
Compares and returns the minimum of two values. Read more
Restrict a value to a certain interval. Read more
This method tests for self and other values to be equal, and is used by ==. Read more
This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason. Read more

Compare two DateTimes based on their true time, ignoring time zones

Example
use chrono::prelude::*;

let earlier = Utc.ymd(2015, 5, 15).and_hms(2, 0, 0).with_timezone(&FixedOffset::west(1 * 3600));
let later   = Utc.ymd(2015, 5, 15).and_hms(3, 0, 0).with_timezone(&FixedOffset::west(5 * 3600));

assert_eq!(earlier.to_string(), "2015-05-15 01:00:00 -01:00");
assert_eq!(later.to_string(), "2015-05-14 22:00:00 -05:00");

assert!(later > earlier);
This method tests less than (for self and other) and is used by the < operator. Read more
This method tests less than or equal to (for self and other) and is used by the <= operator. Read more
This method tests greater than (for self and other) and is used by the > operator. Read more
This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more

Serialize into a rfc3339 time string

See the serde module for alternate serializations.

Serialize this value into the given Serde serializer. Read more
The resulting type after applying the - operator.
Performs the - operation. Read more
The resulting type after applying the - operator.
Performs the - operation. Read more
The resulting type after applying the - operator.
Performs the - operation. Read more
Performs the -= operation. Read more
Returns the hour number from 0 to 23.
Returns the minute number from 0 to 59.
Returns the second number from 0 to 59.
Returns the number of nanoseconds since the whole non-leap second. The range from 1,000,000,000 to 1,999,999,999 represents the leap second. Read more
Makes a new value with the hour number changed. Read more
Makes a new value with the minute number changed. Read more
Makes a new value with the second number changed. Read more
Makes a new value with nanoseconds since the whole non-leap second changed. Read more
Returns the hour number from 1 to 12 with a boolean flag, which is false for AM and true for PM. Read more
Returns the number of non-leap seconds past the last midnight.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The resulting type after obtaining ownership.
Creates owned data from borrowed data, usually by cloning. Read more
Uses borrowed data to replace owned data, usually by cloning. Read more
Converts the given value to a String. Read more
The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.