Struct TimeWith

pub struct TimeWith { /* private fields */ }

Available on crate features dep_jiff and alloc only.

A builder for setting the fields on a Time.

This builder is constructed via Time::with.

Example

Unlike Date, a Time is valid for all possible valid values of its fields. That is, there is no way for two valid field values to combine into an invalid Time. So, for Time, this builder does have as much of a benefit versus an API design with methods like Time::with_hour and Time::with_minute. Nevertheless, this builder permits settings multiple fields at the same time and performing only one validity check. Moreover, this provides a consistent API with other date and time types in this crate.

use jiff::civil::time;

let t1 = time(0, 0, 24, 0);
let t2 = t1.with().hour(15).minute(30).millisecond(10).build()?;
assert_eq!(t2, time(15, 30, 24, 10_000_000));

Implementations

impl TimeWith

pub fn build(self) -> Result<Time, Error>

Create a new Time from the fields set on this configuration.

An error occurs when the fields combine to an invalid time. This only occurs when at least one field has an invalid value, or if at least one of millisecond, microsecond or nanosecond is set and subsec_nanosecond is set. Otherwise, if all fields are valid, then the entire Time is guaranteed to be valid.

For any fields not set on this configuration, the values are taken from the Time that originally created this configuration. When no values are set, this routine is guaranteed to succeed and will always return the original time without modification.

Example

This creates a time but with its fractional nanosecond component stripped:

use jiff::civil::time;

let t = time(14, 27, 30, 123_456_789);
assert_eq!(t.with().subsec_nanosecond(0).build()?, time(14, 27, 30, 0));

Example: error for invalid time

use jiff::civil::time;

let t = time(14, 27, 30, 0);
assert!(t.with().hour(24).build().is_err());

Example: error for ambiguous sub-second value

use jiff::civil::time;

let t = time(14, 27, 30, 123_456_789);
// Setting both the individual sub-second fields and the entire
// fractional component could lead to a misleading configuration. So
// if it's done, it results in an error in all cases. Callers must
// choose one or the other.
assert!(t.with().microsecond(1).subsec_nanosecond(0).build().is_err());

pub fn hour(self, hour: i8) -> TimeWith

Set the hour field on a Time.

One can access this value via Time::hour.

This overrides any previous hour settings.

Errors

This returns an error when TimeWith::build is called if the given hour is outside the range 0..=23.

Example

use jiff::civil::time;

let t1 = time(15, 21, 59, 0);
assert_eq!(t1.hour(), 15);
let t2 = t1.with().hour(3).build()?;
assert_eq!(t2.hour(), 3);

pub fn minute(self, minute: i8) -> TimeWith

Set the minute field on a Time.

One can access this value via Time::minute.

This overrides any previous minute settings.

Errors

This returns an error when TimeWith::build is called if the given minute is outside the range 0..=59.

Example

use jiff::civil::time;

let t1 = time(15, 21, 59, 0);
assert_eq!(t1.minute(), 21);
let t2 = t1.with().minute(3).build()?;
assert_eq!(t2.minute(), 3);

pub fn second(self, second: i8) -> TimeWith

Set the second field on a Time.

One can access this value via Time::second.

This overrides any previous second settings.

Errors

This returns an error when TimeWith::build is called if the given second is outside the range 0..=59.

Example

use jiff::civil::time;

let t1 = time(15, 21, 59, 0);
assert_eq!(t1.second(), 59);
let t2 = t1.with().second(3).build()?;
assert_eq!(t2.second(), 3);

pub fn millisecond(self, millisecond: i16) -> TimeWith

Set the millisecond field on a Time.

One can access this value via Time::millisecond.

This overrides any previous millisecond settings.

Note that this only sets the millisecond component. It does not change the microsecond or nanosecond components. To set the fractional second component to nanosecond precision, use TimeWith::subsec_nanosecond.

Errors

This returns an error when TimeWith::build is called if the given millisecond is outside the range 0..=999, or if both this and TimeWith::subsec_nanosecond are set.

Example

This shows the relationship between Time::millisecond and Time::subsec_nanosecond:

use jiff::civil::time;

let t = time(15, 21, 35, 0).with().millisecond(123).build()?;
assert_eq!(t.subsec_nanosecond(), 123_000_000);

pub fn microsecond(self, microsecond: i16) -> TimeWith

Set the microsecond field on a Time.

One can access this value via Time::microsecond.

This overrides any previous microsecond settings.

Note that this only sets the microsecond component. It does not change the millisecond or nanosecond components. To set the fractional second component to nanosecond precision, use TimeWith::subsec_nanosecond.

Errors

This returns an error when TimeWith::build is called if the given microsecond is outside the range 0..=999, or if both this and TimeWith::subsec_nanosecond are set.

Example

This shows the relationship between Time::microsecond and Time::subsec_nanosecond:

use jiff::civil::time;

let t = time(15, 21, 35, 0).with().microsecond(123).build()?;
assert_eq!(t.subsec_nanosecond(), 123_000);

pub fn nanosecond(self, nanosecond: i16) -> TimeWith

Set the nanosecond field on a Time.

One can access this value via Time::nanosecond.

This overrides any previous nanosecond settings.

Note that this only sets the nanosecond component. It does not change the millisecond or microsecond components. To set the fractional second component to nanosecond precision, use TimeWith::subsec_nanosecond.

Errors

This returns an error when TimeWith::build is called if the given nanosecond is outside the range 0..=999, or if both this and TimeWith::subsec_nanosecond are set.

Example

This shows the relationship between Time::nanosecond and Time::subsec_nanosecond:

use jiff::civil::time;

let t = time(15, 21, 35, 0).with().nanosecond(123).build()?;
assert_eq!(t.subsec_nanosecond(), 123);

pub fn subsec_nanosecond(self, subsec_nanosecond: i32) -> TimeWith

Set the subsecond nanosecond field on a Time.

If you want to access this value on Time, then use Time::subsec_nanosecond.

This overrides any previous subsecond nanosecond settings.

Note that this sets the entire fractional second component to nanosecond precision, and overrides any individual millisecond, microsecond or nanosecond settings. To set individual components, use TimeWith::millisecond, TimeWith::microsecond or TimeWith::nanosecond.

Errors

This returns an error when TimeWith::build is called if the given subsecond nanosecond is outside the range 0..=999,999,999, or if both this and one of TimeWith::millisecond, TimeWith::microsecond or TimeWith::nanosecond are set.

Example

This shows the relationship between constructing a Time value with subsecond nanoseconds and its individual subsecond fields:

use jiff::civil::time;

let t1 = time(15, 21, 35, 0);
let t2 = t1.with().subsec_nanosecond(123_456_789).build()?;
assert_eq!(t2.millisecond(), 123);
assert_eq!(t2.microsecond(), 456);
assert_eq!(t2.nanosecond(), 789);

Trait Implementations

impl Clone for TimeWith

fn clone(&self) -> TimeWith

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TimeWith

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Copy for TimeWith