Struct domain::base::record::Ttl

source ·
pub struct Ttl(/* private fields */);
Expand description

A span of time, typically used to describe the time a given DNS record is valid.

Ttl implements many common traits, including core::ops::Add, core::ops::Sub, and other core::ops traits. It implements Default by returning a zero-length Ttl.

§Why not std::time::Duration?

Two reasons make std::time::Duration not suited for representing DNS TTL values:

  1. According to RFC 2181 TTL values have second-level precision while std::time::Duration can represent time down to the nanosecond level. This amount of precision is simply not needed and might cause confusion when sending Durations over the network.
  2. When working with DNS TTL values it’s common to want to know a time to live in minutes or hours. std::time::Duration does not expose easy to use methods for this purpose, while Ttl does.

Ttl provides two methods Ttl::from_duration_lossy and Ttl::into_duration to convert between Duration and Ttl.

Implementations§

source§

impl Ttl

source

pub const SECOND: Ttl = _

A time-to-live of one second.

source

pub const MINUTE: Ttl = _

A time-to-live of one minute.

source

pub const HOUR: Ttl = _

A time-to-live of one hour.

source

pub const DAY: Ttl = _

A time-to-live of one day.

source

pub const ZERO: Ttl = _

A duration of zero time.

source

pub const MAX: Ttl = _

The maximum theoretical time to live.

source

pub const CAP: Ttl = _

The practical maximum time to live as recommended by RFC 8767.

source

pub const MAX_MINUTES: u32 = 71_582_788u32

The maximum number of minutes that a Ttl can represent.

source

pub const MAX_HOURS: u32 = 1_193_046u32

The maximum number of hours that a Ttl can represent.

source

pub const MAX_DAYS: u16 = 49_710u16

The maximum number of days that a Ttl can represent.

source

pub const COMPOSE_LEN: u16 = 4u16

source

pub const fn as_secs(&self) -> u32

Returns the total time to live in seconds.

§Examples
use domain::base::Ttl;

let ttl = Ttl::from_secs(120);
assert_eq!(ttl.as_secs(), 120);
source

pub const fn as_minutes(&self) -> u32

Returns the total time to live in minutes.

§Examples
use domain::base::Ttl;

let ttl = Ttl::from_secs(120);
assert_eq!(ttl.as_minutes(), 2);
source

pub const fn as_hours(&self) -> u32

Returns the total time to live in hours.

§Examples
use domain::base::Ttl;

let ttl = Ttl::from_secs(7200);
assert_eq!(ttl.as_hours(), 2);
source

pub const fn as_days(&self) -> u16

Returns the total time to live in days.

§Examples
use domain::base::Ttl;

let ttl = Ttl::from_secs(172800);
assert_eq!(ttl.as_days(), 2);
source

pub const fn into_duration(&self) -> Duration

Converts a Ttl into a std::time::Duration.

§Examples
use domain::base::Ttl;
use std::time::Duration;

let ttl = Ttl::from_mins(2);
let duration = ttl.into_duration();
assert_eq!(duration.as_secs(), 120);
source

pub const fn from_secs(secs: u32) -> Self

Creates a new Ttl from the specified number of seconds.

source

pub const fn from_mins(minutes: u32) -> Self

Creates a new Ttl from the specified number of minutes.

§Panics

The maximum number of days that a Ttl can represent is 71582788. This method will panic if it is being called with a value greater than that.

source

pub const fn from_hours(hours: u32) -> Self

Creates a new Ttl from the specified number of hours.

§Panics

The maximum number of hours that a Ttl can represent is 1193046. This method will panic if it is being called with a value greater than that.

source

pub const fn from_days(days: u16) -> Self

Creates a new Ttl from the specified number of days.

§Panics

The maximum number of days that a Ttl can represent is 49710. This method will panic if it is being called with a value greater than that.

source

pub const fn from_duration_lossy(duration: Duration) -> Self

Creates a new Ttl from a std::time::Duration.

This operation is lossy as Duration stores seconds as u64, while Ttl stores seconds as u32 to comply with the DNS specifications. Duration also represents time using sub-second precision, which is not kept when converting into a Ttl.

§Examples
use domain::base::Ttl;
use std::time::Duration;

assert_eq!(Ttl::from_duration_lossy(Duration::new(1, 0)), Ttl::from_secs(1));
assert_eq!(Ttl::from_duration_lossy(Duration::new(1, 6000)), Ttl::from_secs(1));
source

pub const fn is_zero(&self) -> bool

Returns true if this Tll spans no time.

This usually indicates a given record should not be cached.

§Examples
use domain::base::Ttl;

assert!(Ttl::ZERO.is_zero());
assert!(Ttl::from_secs(0).is_zero());
assert!(Ttl::from_mins(0).is_zero());
assert!(Ttl::from_hours(0).is_zero());
assert!(Ttl::from_days(0).is_zero());
source

pub const fn checked_add(self, rhs: Ttl) -> Option<Ttl>

Checked Ttl addition. Computes self + other, returning None if overflow occurred.

§Examples
use domain::base::Ttl;

assert_eq!(Ttl::from_secs(0).checked_add(Ttl::from_secs(1)), Some(Ttl::from_secs(1)));
assert_eq!(Ttl::from_secs(1).checked_add(Ttl::MAX), None);
source

pub const fn saturating_add(self, rhs: Ttl) -> Ttl

Saturating Ttl addition. Computes self + other, returning Ttl::MAX if overflow occurred.

§Examples
use domain::base::Ttl;

assert_eq!(Ttl::from_secs(0).saturating_add(Ttl::from_secs(1)), Ttl::from_secs(1));
assert_eq!(Ttl::from_secs(1).saturating_add(Ttl::MAX), Ttl::MAX);
source

pub const fn checked_sub(self, rhs: Ttl) -> Option<Ttl>

Checked Ttl subtraction. Computes self - other, returning None if the result would be negative or if overflow occurred.

§Examples
use domain::base::Ttl;

assert_eq!(Ttl::from_secs(1).checked_sub(Ttl::from_secs(0)), Some(Ttl::from_secs(1)));
assert_eq!(Ttl::from_secs(0).checked_sub(Ttl::from_secs(1)), None);
source

pub const fn saturating_sub(self, rhs: Ttl) -> Ttl

Saturating Ttl subtraction. Computes self - other, returning Ttl::ZERO if the result would be negative or if overflow occurred.

§Examples
use domain::base::Ttl;

assert_eq!(Ttl::from_secs(1).saturating_sub(Ttl::from_secs(0)), Ttl::from_secs(1));
assert_eq!(Ttl::from_secs(0).saturating_sub(Ttl::from_secs(1)), Ttl::ZERO);
source

pub const fn checked_mul(self, rhs: u32) -> Option<Ttl>

Checked Ttl multiplication. Computes self * other, returning None if overflow occurred.

§Examples
use domain::base::Ttl;

assert_eq!(Ttl::from_secs(5).checked_mul(2), Some(Ttl::from_secs(10)));
assert_eq!(Ttl::from_secs(u32::MAX - 1).checked_mul(2), None);
source

pub const fn saturating_mul(self, rhs: u32) -> Ttl

Saturating Duration multiplication. Computes self * other, returning Duration::MAX if overflow occurred.

§Examples
use domain::base::Ttl;

assert_eq!(Ttl::from_secs(5).saturating_mul(2), Ttl::from_secs(10));
assert_eq!(Ttl::from_secs(u32::MAX - 1).saturating_mul(2), Ttl::MAX);
source

pub const fn checked_div(self, rhs: u32) -> Option<Ttl>

Checked Duration division. Computes self / other, returning None if other == 0.

§Examples
use domain::base::Ttl;

assert_eq!(Ttl::from_secs(10).checked_div(2), Some(Ttl::from_secs(5)));
assert_eq!(Ttl::from_mins(1).checked_div(2), Some(Ttl::from_secs(30)));
assert_eq!(Ttl::from_secs(2).checked_div(0), None);
source

pub const fn cap(self) -> Ttl

Caps the value of Ttl at 7 days (604800 seconds) as recommended by RFC 8767.

§Examples
use domain::base::Ttl;

assert_eq!(Ttl::from_mins(5).cap(), Ttl::from_mins(5));
assert_eq!(Ttl::from_days(50).cap(), Ttl::from_days(7));
source

pub fn compose<Target: OctetsBuilder + ?Sized>( &self, target: &mut Target, ) -> Result<(), Target::AppendError>

source

pub fn parse<Octs: AsRef<[u8]> + ?Sized>( parser: &mut Parser<'_, Octs>, ) -> Result<Self, ParseError>

Trait Implementations§

source§

impl Add for Ttl

§

type Output = Ttl

The resulting type after applying the + operator.
source§

fn add(self, rhs: Self) -> Self::Output

Performs the + operation. Read more
source§

impl AddAssign for Ttl

source§

fn add_assign(&mut self, rhs: Ttl)

Performs the += operation. Read more
source§

impl Clone for Ttl

source§

fn clone(&self) -> Ttl

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for Ttl

source§

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

Formats the value using the given formatter. Read more
source§

impl Default for Ttl

source§

fn default() -> Ttl

Returns the “default value” for a type. Read more
source§

impl Div<u32> for Ttl

§

type Output = Ttl

The resulting type after applying the / operator.
source§

fn div(self, rhs: u32) -> Ttl

Performs the / operation. Read more
source§

impl DivAssign<u32> for Ttl

source§

fn div_assign(&mut self, rhs: u32)

Performs the /= operation. Read more
source§

impl Hash for Ttl

source§

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher. Read more
1.3.0 · source§

fn hash_slice<H>(data: &[Self], state: &mut H)
where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher. Read more
source§

impl Into<Duration> for Ttl

source§

fn into(self) -> Duration

Converts this type into the (usually inferred) input type.
source§

impl Mul<u32> for Ttl

§

type Output = Ttl

The resulting type after applying the * operator.
source§

fn mul(self, rhs: u32) -> Self::Output

Performs the * operation. Read more
source§

impl MulAssign<u32> for Ttl

source§

fn mul_assign(&mut self, rhs: u32)

Performs the *= operation. Read more
source§

impl Ord for Ttl

source§

fn cmp(&self, other: &Ttl) -> Ordering

This method returns an Ordering between self and other. Read more
1.21.0 · source§

fn max(self, other: Self) -> Self
where Self: Sized,

Compares and returns the maximum of two values. Read more
1.21.0 · source§

fn min(self, other: Self) -> Self
where Self: Sized,

Compares and returns the minimum of two values. Read more
1.50.0 · source§

fn clamp(self, min: Self, max: Self) -> Self
where Self: Sized + PartialOrd,

Restrict a value to a certain interval. Read more
source§

impl PartialEq for Ttl

source§

fn eq(&self, other: &Ttl) -> bool

Tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

impl PartialOrd for Ttl

source§

fn partial_cmp(&self, other: &Ttl) -> Option<Ordering>

This method returns an ordering between self and other values if one exists. Read more
1.0.0 · source§

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator. Read more
1.0.0 · source§

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator. Read more
1.0.0 · source§

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator. Read more
1.0.0 · source§

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator. Read more
source§

impl<S: Scanner> Scan<S> for Ttl

source§

fn scan(scanner: &mut S) -> Result<Self, <S as Scanner>::Error>

Reads a value from the provided scanner. Read more
source§

impl Sub for Ttl

§

type Output = Ttl

The resulting type after applying the - operator.
source§

fn sub(self, rhs: Self) -> Self::Output

Performs the - operation. Read more
source§

impl SubAssign for Ttl

source§

fn sub_assign(&mut self, rhs: Ttl)

Performs the -= operation. Read more
source§

impl<'a> Sum<&'a Ttl> for Ttl

source§

fn sum<I: Iterator<Item = &'a Ttl>>(iter: I) -> Ttl

Takes an iterator and generates Self from the elements by “summing up” the items.
source§

impl Sum for Ttl

source§

fn sum<I: Iterator<Item = Ttl>>(iter: I) -> Ttl

Takes an iterator and generates Self from the elements by “summing up” the items.
source§

impl Copy for Ttl

source§

impl Eq for Ttl

source§

impl StructuralPartialEq for Ttl

Auto Trait Implementations§

§

impl Freeze for Ttl

§

impl RefUnwindSafe for Ttl

§

impl Send for Ttl

§

impl Sync for Ttl

§

impl Unpin for Ttl

§

impl UnwindSafe for Ttl

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

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

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

default unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> CloneToUninit for T
where T: Copy,

source§

unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

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

source§

impl<Source, Target> OctetsInto<Target> for Source
where Target: OctetsFrom<Source>,

§

type Error = <Target as OctetsFrom<Source>>::Error

source§

fn try_octets_into( self, ) -> Result<Target, <Source as OctetsInto<Target>>::Error>

Performs the conversion.
source§

fn octets_into(self) -> Target
where Self::Error: Into<Infallible>,

Performs an infallible conversion.
source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

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

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

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

Performs the conversion.
source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

source§

fn vzip(self) -> V

source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more