Struct `TimeWith`

struct TimeWith { ... }

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

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

Implementations

`impl TimeWith`

fn build(self: 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: 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: 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: 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: 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.

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: 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.

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: 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.

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: 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.

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

`impl Clone for TimeWith`

fn clone(self: &Self) -> TimeWith

`impl Copy for TimeWith`

`impl Debug for TimeWith`

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

`impl Freeze for TimeWith`

`impl RefUnwindSafe for TimeWith`

`impl Send for TimeWith`

`impl Sync for TimeWith`

`impl Unpin for TimeWith`

`impl UnsafeUnpin for TimeWith`

`impl UnwindSafe for TimeWith`

`impl<T> Any for TimeWith`

fn type_id(self: &Self) -> TypeId

`impl<T> Borrow for TimeWith`

fn borrow(self: &Self) -> &T

`impl<T> BorrowMut for TimeWith`

fn borrow_mut(self: &mut Self) -> &mut T

`impl<T> CloneToUninit for TimeWith`

unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)

`impl<T> From for TimeWith`

fn from(t: T) -> T: Returns the argument unchanged.

`impl<T> ToOwned for TimeWith`

fn to_owned(self: &Self) -> T
fn clone_into(self: &Self, target: &mut T)

`impl<T, U> Into for TimeWith`

fn into(self: Self) -> U

Calls U::from(self).

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

`impl<T, U> TryFrom for TimeWith`

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

`impl<T, U> TryInto for TimeWith`

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>