[][src]Crate time

Simple time handling.

rustc 1.32.0

Feature flags in Cargo

std

Currently, all structs except Instant can be used with #![no_std]. As support for the standard library is enabled by default, you must use default_features = false in your Cargo.toml to enable this.

[dependencies]
time = { version = "0.2", default-features = false }

Of the structs that are usable, some methods may only be enabled due a reliance on Instant. These will be indicated in the documentation.

serde

Serde support is behind a feature flag. To enable it, use the serde feature. This is not enabled by default. It is compatible with #![no_std], so long as an allocator is present.

With the standard library:

[dependencies]
time = { version = "0.2", features = ["serde"] }

With #![no_std] support:

[dependencies]
time = { version = "0.2", default-features = false, features = ["serde"] }

rand

Rand support is behind a feature flag. To enable it, use the rand feature. This is not enabled by default. Usage is compatible with #![no_std].

With the standard library:

[dependencies]
time = { version = "0.2", features = ["rand"] }

With #![no_std] support:

[dependencies]
time = { version = "0.2", default-features = false, features = ["rand"] }

deprecated

Using the deprecated feature allows using deprecated v0.1 methods. Enabled by default.

With the standard library, the normal time = 0.2 will work as expected.

With #![no_std] support:

[dependencies]
time = { version = "0.2", default-features = false, features = ["deprecated"] }

panicking-api

Non-panicking APIs are provided, and should generally be preferred. However, there are some situations where avoiding .unwrap() may be desired. To enable these APIs, you need to use the panicking-api feature in your Cargo.toml, which is not enabled by default.

Library authors should avoid using this feature.

This feature will be removed in a future release, as there are provided macros to perform the equivalent calculations at compile-time.

[dependencies]
time = { version = "0.2", features = ["panicking-api"] }

Formatting

Time's formatting behavior is based on strftime in C, though it is explicitly not compatible. Specifiers may be missing, added, or have different behavior than in C. As such, you should use the table below, which is an up-to-date reference on what each specifier does.

SpecifierReplaced byExample
%aAbbreviated weekday nameThu
%AFull weekday nameThursday
%bAbbreviated month nameAug
%BFull month nameAugust
%cDate and time representation, equivalent to %a %b %-d %-H:%M:%S %-YThu Aug 23 14:55:02 2001
%CYear divided by 100 and truncated to integer (00-99)20
%dDay of the month, zero-padded (01-31)23
%DShort MM/DD/YY date, equivalent to %-m/%d/%y8/23/01
%FShort YYYY-MM-DD date, equivalent to %-Y-%m-%d2001-08-23
%gWeek-based year, last two digits (00-99)01
%GWeek-based year2001
%HHour in 24h format (00-23)14
%IHour in 12h format (01-12)02
%jDay of the year (001-366)235
%mMonth as a decimal number (01-12)08
%MMinute (00-59)55
%NSubsecond nanoseconds. Always 9 digits012345678
%pam or pm designationpm
%PAM or PM designationPM
%r12-hour clock time, equivalent to %-I:%M:%S %p2:55:02 pm
%R24-hour HH:MM time, equivalent to %-H:%M14:55
%SSecond (00-59)02
%T24-hour clock time with seconds, equivalent to %-H:%M:%S14:55:02
%uISO 8601 weekday as number with Monday as 1 (1-7)4
%UWeek number with the first Sunday as the start of week one (00-53)33
%VISO 8601 week number (01-53)34
%wWeekday as a decimal number with Sunday as 0 (0-6)4
%WWeek number with the first Monday as the start of week one (00-53)34
%yYear, last two digits (00-99)01
%YFull year, including + if ≥10,0002001
%zISO 8601 offset from UTC in timezone (+HHMM)+0100
%%Literal %%

Modifiers

All specifiers that are strictly numerical have modifiers for formatting. Adding a modifier to a non-supporting specifier is a no-op.

ModifierBehaviorExample
- (dash)No padding%-d => 5
_ (underscore)Pad with spaces%_d => 5
0Pad with zeros%0d => 05

Modules

prelude

A collection of imports that are widely useful.

Macros

date

Construct a Date with a statically known value.

offset

Construct a UtcOffset with a statically known value.

time

Construct a Time with a statically known value.

Structs

ComponentRangeError

An error type indicating that a component provided to a method was out of range, causing a failure.

ConversionRangeError

An error type indicating that a conversion failed because the target type could not store the initial value.

Date

Calendar date.

Duration

A span of time with nanosecond precision.

IndeterminateOffsetError

The system's UTC offset could not be determined at the given datetime.

Instantfeature="std"

A measurement of a monotonically non-decreasing clock. Opaque and useful only with Duration.

OffsetDateTime

A PrimitiveDateTime with a UtcOffset.

PrimitiveDateTime

Combined date and time.

Time

The clock time within a given date. Nanosecond precision.

UtcOffset

An offset from UTC.

Enums

Error

A unified error type for anything returned by a method in the time crate.

Format

Various well-known formats, along with the possibility for a custom format (provided either at compile-time or runtime).

ParseError

An error occurred while parsing.

SignDeprecated

Contains the sign of a value: positive, negative, or zero.

Weekday

Days of the week.

Traits

NumericalDuration

Create Durations from primitive and core numeric types.

NumericalStdDuration

Create std::time::Durations from primitive and core numeric types.

NumericalStdDurationShort

Create std::time::Durations from primitive and core numeric types. Unless you are always expecting a std::time::Duration, you should prefer to use NumericalStdDuration for clarity.

Functions

days_in_year

Get the number of calendar days in a given year.

is_leap_year

Returns if the provided year is a leap year in the proleptic Gregorian calendar. Uses astronomical year numbering.

parse

Parse any parsable type from the time crate.

precise_time_nsDeprecated
precise_time_sDeprecated
validate_format_string

Checks if a user-provided formatting string is valid. If it isn't, a description of the error is returned.

weeks_in_year

Get the number of weeks in the ISO year.

Type Definitions

PreciseTimeDeprecated
Result

An alias for Result with a generic error from the time crate.

SteadyTimeDeprecated