[−][src]Crate time

Simple time handling.

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.

Specifier	Replaced by	Example
`%a`	Abbreviated weekday name	`Thu`
`%A`	Full weekday name	`Thursday`
`%b`	Abbreviated month name	`Aug`
`%B`	Full month name	`August`
`%c`	Date and time representation, equivalent to `%a %b %-d %-H:%M:%S %-Y`	`Thu Aug 23 14:55:02 2001`
`%C`	Year divided by 100 and truncated to integer (`00`-`99`)	`20`
`%d`	Day of the month, zero-padded (`01`-`31`)	`23`
`%D`	Short MM/DD/YY date, equivalent to `%-m/%d/%y`	`8/23/01`
`%F`	Short YYYY-MM-DD date, equivalent to `%-Y-%m-%d`	`2001-08-23`
`%g`	Week-based year, last two digits (`00`-`99`)	`01`
`%G`	Week-based year	`2001`
`%H`	Hour in 24h format (`00`-`23`)	`14`
`%I`	Hour in 12h format (`01`-`12`)	`02`
`%j`	Day of the year (`001`-`366`)	`235`
`%m`	Month as a decimal number (`01`-`12`)	`08`
`%M`	Minute (`00`-`59`)	`55`
`%N`	Subsecond nanoseconds. Always 9 digits	`012345678`
`%p`	`am` or `pm` designation	`pm`
`%P`	`AM` or `PM` designation	`PM`
`%r`	12-hour clock time, equivalent to `%-I:%M:%S %p`	`2:55:02 pm`
`%R`	24-hour HH:MM time, equivalent to `%-H:%M`	`14:55`
`%S`	Second (`00`-`59`)	`02`
`%T`	24-hour clock time with seconds, equivalent to `%-H:%M:%S`	`14:55:02`
`%u`	ISO 8601 weekday as number with Monday as 1 (`1`-`7`)	`4`
`%U`	Week number with the first Sunday as the start of week one (`00`-`53`)	`33`
`%V`	ISO 8601 week number (`01`-`53`)	`34`
`%w`	Weekday as a decimal number with Sunday as 0 (`0`-`6`)	`4`
`%W`	Week number with the first Monday as the start of week one (`00`-`53`)	`34`
`%y`	Year, last two digits (`00`-`99`)	`01`
`%Y`	Full year, including `+` if ≥10,000	`2001`
`%z`	ISO 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.

Modifier	Behavior	Example
`-` (dash)	No padding	`%-d` => `5`
`_` (underscore)	Pad with spaces	`%_d` => `5`
`0`	Pad 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.
Instant	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.
Sign	Deprecated Contains the sign of a value: positive, negative, or zero.
Weekday	Days of the week.

Traits

NumericalDuration	Create `Duration`s from primitive and core numeric types.
NumericalStdDuration	Create `std::time::Duration`s from primitive and core numeric types.
NumericalStdDurationShort	Create `std::time::Duration`s 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_ns	Deprecated
precise_time_s	Deprecated
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

PreciseTime	Deprecated
Result	An alias for `Result` with a generic error from the time crate.
SteadyTime	Deprecated