Struct Ttl

pub struct Ttl(/* private fields */);

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

impl Ttl

pub const SECOND: Ttl

A time-to-live of one second.

pub const MINUTE: Ttl

A time-to-live of one minute.

pub const HOUR: Ttl

A time-to-live of one hour.

pub const DAY: Ttl

A time-to-live of one day.

pub const ZERO: Ttl

A duration of zero time.

pub const MAX: Ttl

The maximum theoretical time to live.

pub const CAP: Ttl

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

pub const MAX_MINUTES: u32 = 71_582_788u32

The maximum number of minutes that a Ttl can represent.

pub const MAX_HOURS: u32 = 1_193_046u32

The maximum number of hours that a Ttl can represent.

pub const MAX_DAYS: u16 = 49_710u16

The maximum number of days that a Ttl can represent.

pub const COMPOSE_LEN: u16 = 4u16

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

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

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

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

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

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

Creates a new Ttl from the specified number of seconds.

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.

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.

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.

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

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

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

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

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

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

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

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

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

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

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

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

Trait Implementations

impl Add for Ttl

type Output = Ttl

The resulting type after applying the + operator.

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

Performs the + operation.

impl AddAssign for Ttl

fn add_assign(&mut self, rhs: Ttl)

Performs the += operation.

impl Clone for Ttl

fn clone(&self) -> Ttl

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Ttl

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

Formats the value using the given formatter.

impl Default for Ttl

fn default() -> Ttl

Returns the “default value” for a type.

impl Div<u32> for Ttl

type Output = Ttl

The resulting type after applying the / operator.

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

Performs the / operation.

impl DivAssign<u32> for Ttl

fn div_assign(&mut self, rhs: u32)

Performs the /= operation.

impl From<Ttl> for Duration

fn from(value: Ttl) -> Self

Converts to this type from the input type.

impl Hash for Ttl

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

Feeds this value into the given Hasher.

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

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Mul<u32> for Ttl

type Output = Ttl

The resulting type after applying the * operator.

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

Performs the * operation.

impl MulAssign<u32> for Ttl

fn mul_assign(&mut self, rhs: u32)

Performs the *= operation.

impl Ord for Ttl

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

This method returns an Ordering between self and other.

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

where Self: Sized,

Compares and returns the maximum of two values.

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

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Ttl

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

Tests for self and other values to be equal, and is used by ==.

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

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

impl PartialOrd for Ttl

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

This method returns an ordering between self and other values if one exists.

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

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

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

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

Reads a value from the provided scanner.

impl Sub for Ttl

type Output = Ttl

The resulting type after applying the - operator.

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

Performs the - operation.

impl SubAssign for Ttl

fn sub_assign(&mut self, rhs: Ttl)

Performs the -= operation.

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

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

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

impl Sum for Ttl

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

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

impl ZonefileFmt for Ttl

fn fmt(&self, p: &mut impl Formatter) -> Result

Format the item as zonefile fmt into a fmt::Formatter

fn display_zonefile( &self, display_kind: DisplayKind, ) -> ZoneFileDisplay<'_, Self>

Display the item as a zonefile

impl Copy for Ttl

impl Eq for Ttl

impl StructuralPartialEq for Ttl