impl TimeWith

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));

# Ok::<(), Box<dyn std::error::Error>>(())

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());

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);

# Ok::<(), Box<dyn std::error::Error>>(())

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);

# Ok::<(), Box<dyn std::error::Error>>(())

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);

# Ok::<(), Box<dyn std::error::Error>>(())

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);

# Ok::<(), Box<dyn std::error::Error>>(())

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);

# Ok::<(), Box<dyn std::error::Error>>(())

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);

# Ok::<(), Box<dyn std::error::Error>>(())

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);

# Ok::<(), Box<dyn std::error::Error>>(())