Struct Date

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

A CBOR-friendly representation of a date and time.

The Date type provides a wrapper around chrono::DateTime<Utc> that supports encoding and decoding to/from CBOR with tag 1, following the CBOR date/time standard specified in RFC 8949.

When encoded to CBOR, dates are represented as tag 1 followed by a numeric value representing the number of seconds since (or before) the Unix epoch (1970-01-01T00:00:00Z). The numeric value can be a positive or negative integer, or a floating-point value for dates with fractional seconds.

Features

• Supports UTC dates with optional fractional seconds
• Provides convenient constructors for common date creation patterns
• Implements the CBORTagged, CBORTaggedEncodable, and CBORTaggedDecodable traits
• Supports arithmetic operations with durations and between dates

Examples

use dcbor::prelude::*;
use dcbor::Date;

// Create a date from a timestamp (seconds since Unix epoch)
let date = Date::from_timestamp(1675854714.0);

// Create a date from year, month, day
let date = Date::from_ymd(2023, 2, 8);

// Convert to CBOR
let cbor = CBOR::from(date);

// Decode from CBOR
let decoded_date: Date = cbor.try_into().unwrap();

Implementations

impl Date

pub fn from_datetime(date_time: DateTime<Utc>) -> Self

Creates a new Date from the given chrono DateTime.

This method creates a new Date instance by wrapping a chrono::DateTime<Utc>.

Arguments

• date_time - A DateTime<Utc> instance to wrap

Returns

A new Date instance

Examples

use dcbor::prelude::*;
use dcbor::Date;
use chrono::{DateTime, Utc};

let datetime = Utc::now();
let date = Date::from_datetime(datetime);

pub fn from_ymd(year: i32, month: u32, day: u32) -> Self

Creates a new Date from year, month, and day components.

This method creates a new Date with the time set to 00:00:00 UTC.

Arguments

• year - The year component (e.g., 2023)
• month - The month component (1-12)
• day - The day component (1-31)

Returns

A new Date instance

Examples

use dcbor::prelude::*;
use dcbor::Date;

// Create February 8, 2023
let date = Date::from_ymd(2023, 2, 8);

Panics

This method panics if the provided components do not form a valid date.

pub fn from_ymd_hms( year: i32, month: u32, day: u32, hour: u32, minute: u32, second: u32, ) -> Self

Creates a new Date from year, month, day, hour, minute, and second components.

Arguments

• year - The year component (e.g., 2023)
• month - The month component (1-12)
• day - The day component (1-31)
• hour - The hour component (0-23)
• minute - The minute component (0-59)
• second - The second component (0-59)

Returns

A new Date instance

Examples

use dcbor::prelude::*;
use dcbor::Date;

// Create February 8, 2023, 15:30:45 UTC
let date = Date::from_ymd_hms(2023, 2, 8, 15, 30, 45);

Panics

This method panics if the provided components do not form a valid date and time.

pub fn from_timestamp(seconds_since_unix_epoch: f64) -> Self

Creates a new Date from seconds since (or before) the Unix epoch.

This method creates a new Date representing the specified number of seconds since the Unix epoch (1970-01-01T00:00:00Z). Negative values represent times before the epoch.

Arguments

• seconds_since_unix_epoch - Seconds from the Unix epoch (positive or negative), which can include a fractional part for sub-second precision

Returns

A new Date instance

Examples

use dcbor::prelude::*;
use dcbor::Date;

// Create a date from a timestamp
let date = Date::from_timestamp(1675854714.0);

// Create a date one second before the Unix epoch
let before_epoch = Date::from_timestamp(-1.0);

// Create a date with fractional seconds
let with_fraction = Date::from_timestamp(1675854714.5);

pub fn from_string(value: impl Into<String>) -> Result<Self>

Creates a new Date from a string containing an ISO-8601 (RFC-3339) date (with or without time).

This method parses a string representation of a date or date-time in ISO-8601/RFC-3339 format and creates a new Date instance. It supports both full date-time strings (e.g., “2023-02-08T15:30:45Z”) and date-only strings (e.g., “2023-02-08”).

Arguments

• value - A string containing a date or date-time in ISO-8601/RFC-3339 format

Returns

• Ok(Date) - A new Date instance if parsing succeeds
• Err - If the string cannot be parsed as a valid date or date-time

Examples

use dcbor::prelude::*;
use dcbor::Date;

// Parse a date-time string
let date = Date::from_string("2023-02-08T15:30:45Z").unwrap();

// Parse a date-only string (time will be set to 00:00:00)
let date = Date::from_string("2023-02-08").unwrap();

pub fn now() -> Self

Creates a new Date containing the current date and time.

Returns

A new Date instance representing the current UTC date and time

Examples

use dcbor::prelude::*;
use dcbor::Date;

let now = Date::now();

pub fn with_duration_from_now(duration: Duration) -> Self

Creates a new Date containing the current date and time plus the given duration.

Arguments

• duration - The duration to add to the current time

Returns

A new Date instance representing the current UTC date and time plus the duration

Examples

use dcbor::prelude::*;
use dcbor::Date;
use std::time::Duration;

// Get a date 1 hour from now
let one_hour_later = Date::with_duration_from_now(Duration::from_secs(3600));

pub fn datetime(&self) -> DateTime<Utc>

Returns the underlying chrono DateTime struct.

This method provides access to the wrapped chrono::DateTime<Utc> instance.

Returns

The wrapped DateTime<Utc> instance

Examples

use dcbor::prelude::*;
use dcbor::Date;
use chrono::Datelike;

let date = Date::now();
let datetime = date.datetime();
let year = datetime.year();

pub fn timestamp(&self) -> f64

Returns the Date as the number of seconds since the Unix epoch.

This method converts the date to a floating-point number representing the number of seconds since the Unix epoch (1970-01-01T00:00:00Z). Negative values represent times before the epoch. The fractional part represents sub-second precision.

Returns

Seconds since the Unix epoch as a f64

Examples

use dcbor::prelude::*;
use dcbor::Date;

let date = Date::from_ymd(2023, 2, 8);
let timestamp = date.timestamp();

Trait Implementations

impl Add<Duration> for Date

type Output = Date

The resulting type after applying the + operator.

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

Performs the + operation.

impl Add<f64> for Date

type Output = Date

The resulting type after applying the + operator.

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

Performs the + operation.

impl AsRef<Date> for Date

fn as_ref(&self) -> &Self

Converts this type into a shared reference of the (usually inferred) input type.

impl CBORTagged for Date

Implementation of the CBORTagged trait for Date.

This implementation specifies that Date values are tagged with CBOR tag 1, which is the standard CBOR tag for date/time values per RFC 8949.

fn cbor_tags() -> Vec<Tag>

Returns the CBOR tags associated with the Date type.

For dates, this is always tag 1, which is the standard CBOR tag for date/time values.

Returns

A vector containing tag 1

impl CBORTaggedDecodable for Date

Implementation of the CBORTaggedDecodable trait for Date.

This implementation creates a Date from an untagged CBOR value representing seconds since the Unix epoch.

fn from_untagged_cbor(cbor: CBOR) -> Result<Self>

Creates a Date from an untagged CBOR value.

The CBOR value must be a numeric value (integer or floating-point) representing the number of seconds since the Unix epoch.

Arguments

• cbor - The untagged CBOR value

Returns

• Ok(Date) - A new Date instance if decoding succeeds
• Err - If the CBOR value is not a valid timestamp

fn from_tagged_cbor(cbor: CBOR) -> Result<Self>

where Self: Sized,

Creates an instance of this type by decoding it from tagged CBOR.

fn from_tagged_cbor_data(data: impl AsRef<[u8]>) -> Result<Self>

where Self: Sized,

Creates an instance of this type by decoding it from binary encoded tagged CBOR.

fn from_untagged_cbor_data(data: impl AsRef<[u8]>) -> Result<Self>

where Self: Sized,

Creates an instance of this type by decoding it from binary encoded untagged CBOR.

impl CBORTaggedEncodable for Date

Implementation of the CBORTaggedEncodable trait for Date.

This implementation converts a Date to an untagged CBOR value representing the number of seconds since the Unix epoch.

fn untagged_cbor(&self) -> CBOR

Converts this Date to an untagged CBOR value.

The date is converted to a numeric value representing the number of seconds since the Unix epoch. This value may be an integer or a floating-point number, depending on whether the date has fractional seconds.

Returns

A CBOR value representing the timestamp

fn tagged_cbor(&self) -> CBOR

Returns the tagged CBOR encoding of this instance.

fn tagged_cbor_data(&self) -> Vec<u8>

Returns the tagged value in CBOR binary representation.

impl Clone for Date

fn clone(&self) -> Date

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Date

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

Formats the value using the given formatter.

impl Default for Date

fn default() -> Self

Returns the “default value” for a type.

impl Display for Date

Implementation of the Display trait for Date.

This implementation provides a string representation of a Date in ISO-8601 format. For dates with time exactly at midnight (00:00:00), only the date part is shown. For other times, a full date-time string is shown.

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

Formats the Date as a string in ISO-8601 format.

Examples

use dcbor::prelude::*;
use dcbor::Date;

// A date at midnight will display as just the date
let date = Date::from_ymd(2023, 2, 8);
assert_eq!(date.to_string(), "2023-02-08");

// A date with time will display as date and time
let date = Date::from_ymd_hms(2023, 2, 8, 15, 30, 45);
assert_eq!(date.to_string(), "2023-02-08T15:30:45Z");

impl From<Date> for CBOR

fn from(value: Date) -> Self

Converts to this type from the input type.

impl From<DateTime<Utc>> for Date

fn from(value: DateTime<Utc>) -> Self

Converts to this type from the input type.

impl Hash for Date

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 Ord for Date

fn cmp(&self, other: &Date) -> 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 Date

fn eq(&self, other: &Date) -> 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 Date

fn partial_cmp(&self, other: &Date) -> 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 Sub<Duration> for Date

type Output = Date

The resulting type after applying the - operator.

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

Performs the - operation.

impl Sub<f64> for Date

type Output = Date

The resulting type after applying the - operator.

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

Performs the - operation.

impl Sub for Date

type Output = f64

The resulting type after applying the - operator.

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

Performs the - operation.

impl TryFrom<&str> for Date

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: &str) -> Result<Self>

Performs the conversion.

impl TryFrom<CBOR> for Date

type Error = Error

The type returned in the event of a conversion error.

fn try_from(cbor: CBOR) -> Result<Self>

Performs the conversion.

impl Eq for Date

impl StructuralPartialEq for Date