Tai64

https://docs.rs/tai64/
Admin
Tai64 is a Rust crate that implements the TAI64 and TAI64N (Temps Atomique International) timestamp...
Tokens:2,849
Snippets:31
Trust Score:9.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### from_system_time

Source: https://docs.rs/tai64/latest/src/tai64/lib.rs.html

Converts a standard library SystemTime to TAI64N.

```APIDOC
## fn from_system_time(t: &SystemTime) -> Self

### Description
Converts a `SystemTime` instance into a `TAI64N` value. Requires the `std` feature.

### Parameters
- **t** (&SystemTime) - Required - The system time to convert.
```

--------------------------------

### Test TAI64N system time conversion

Source: https://docs.rs/tai64/latest/src/tai64/lib.rs.html

Verifies that system time remains consistent after conversion to TAI64N and back, covering various durations before the UNIX epoch.

```rust
#[cfg(all(test, feature = "std"))]
mod tests {
    use super::*;

    #[test]
    fn before_epoch() {
        let t = UNIX_EPOCH - Duration::new(0, 1);
        let tai64n = Tai64N::from_system_time(&t);
        let t1 = tai64n.to_system_time();

        assert_eq!(t, t1);

        let t = UNIX_EPOCH - Duration::new(488294802189, 999999999);
        let tai64n = Tai64N::from_system_time(&t);
        let t1 = tai64n.to_system_time();

        assert_eq!(t, t1);

        let t = UNIX_EPOCH - Duration::new(73234, 68416841);
        let tai64n = Tai64N::from_system_time(&t);
        let t1 = tai64n.to_system_time();

        assert_eq!(t, t1);
    }
}
```

--------------------------------

### Convert between TAI64N and SystemTime

Source: https://docs.rs/tai64/latest/src/tai64/lib.rs.html

Methods for converting TAI64N to and from standard library SystemTime, requiring the 'std' feature.

```rust
#[allow(clippy::trivially_copy_pass_by_ref)]
    #[cfg(feature = "std")]
    pub fn from_system_time(t: &SystemTime) -> Self {
        match t.duration_since(UNIX_EPOCH) {
            Ok(d) => Self::UNIX_EPOCH + d,
            Err(e) => Self::UNIX_EPOCH - e.duration(),
        }
    }
```

```rust
#[cfg(feature = "std")]
    pub fn to_system_time(self) -> SystemTime {
        match self.duration_since(&Self::UNIX_EPOCH) {
            Ok(d) => UNIX_EPOCH + d,
            Err(d) => UNIX_EPOCH - d,
        }
    }
```

--------------------------------

### Implement SystemTime conversion

Source: https://docs.rs/tai64/latest/src/tai64/lib.rs.html

Provides a conversion from SystemTime to Tai64N when the 'std' feature is enabled.

```rust
#[cfg(feature = "std")]
impl From<SystemTime> for Tai64N {
    fn from(t: SystemTime) -> Self {
        Tai64N::from_system_time(&t)
    }
}
```

--------------------------------

### to_system_time

Source: https://docs.rs/tai64/latest/src/tai64/lib.rs.html

Converts a TAI64N timestamp to SystemTime.

```APIDOC
## fn to_system_time(self) -> SystemTime

### Description
Converts the `TAI64N` value into a `SystemTime` instance. Requires the `std` feature.
```

--------------------------------

### Tai64 Methods

Source: https://docs.rs/tai64/latest/tai64/struct.Tai64.html

Public methods available on the Tai64 struct for timestamp management.

```APIDOC
## Tai64::now()

### Description
Returns the current TAI64 timestamp based on the system clock.

## Tai64::from_slice(slice: &[u8])

### Description
Parses a TAI64 timestamp from a byte slice. Returns a Result containing the Tai64 instance or an Error.

## Tai64::to_bytes(self)

### Description
Serializes the TAI64 timestamp into an 8-byte array.

## Tai64::from_unix(secs: i64)

### Description
Converts a Unix timestamp (seconds) into a TAI64 instance.

## Tai64::to_unix(self)

### Description
Converts the TAI64 instance into a Unix timestamp (seconds).
```

--------------------------------

### Serde serialization and deserialization

Source: https://docs.rs/tai64/latest/src/tai64/lib.rs.html

Implements Serde traits for TAI64N, requiring the 'serde' feature.

```rust
#[cfg(feature = "serde")]
impl<'de> Deserialize<'de> for Tai64N {
    fn deserialize<D: de::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        use de::Error;
        <[u8; Tai64N::BYTE_SIZE]>::deserialize(deserializer)?
            .try_into()
            .map_err(D::Error::custom)
    }
}
```

```rust
#[cfg(feature = "serde")]
impl Serialize for Tai64N {
    fn serialize<S: ser::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        self.to_bytes().serialize(serializer)
    }
}
```

--------------------------------

### Serialize TAI64N to bytes

Source: https://docs.rs/tai64/latest/src/tai64/lib.rs.html

Serializes a TAI64N instance into a fixed-size byte array.

```rust
impl From<Tai64N> for [u8; Tai64N::BYTE_SIZE] {
    /// Serialize TAI64 to external representation
    fn from(tai: Tai64N) -> [u8; Tai64N::BYTE_SIZE] {
        let mut result = [0u8; Tai64N::BYTE_SIZE];
        result[..Tai64::BYTE_SIZE].copy_from_slice(&tai.0.to_bytes());
        result[Tai64::BYTE_SIZE..].copy_from_slice(&tai.1.to_be_bytes());
        result
    }
}
```

--------------------------------

### duration_since

Source: https://docs.rs/tai64/latest/src/tai64/lib.rs.html

Calculates the duration between two TAI64N timestamps.

```APIDOC
## fn duration_since(&self, other: &Self) -> Result<Duration, Duration>

### Description
Returns the duration elapsed since another TAI64N timestamp. Returns `Ok(Duration)` if `other` is earlier than `self`, otherwise returns `Err(Duration)`.

### Parameters
- **other** (&Self) - Required - The timestamp to compare against.
```

--------------------------------

### Perform TAI64N arithmetic

Source: https://docs.rs/tai64/latest/src/tai64/lib.rs.html

Implements addition and subtraction of Duration from TAI64N, handling nanosecond carries.

```rust
#[allow(clippy::suspicious_arithmetic_impl)]
impl ops::Add<Duration> for Tai64N {
    type Output = Self;

    fn add(self, d: Duration) -> Self {
        let n = self.1 + d.subsec_nanos();

        let (carry, n) = if n >= NANOS_PER_SECOND {
            (1, n - NANOS_PER_SECOND)
        } else {
            (0, n)
        };

        Tai64N(self.0 + d.as_secs() + carry, n)
    }
}
```

```rust
impl ops::Sub<Duration> for Tai64N {
    type Output = Self;

    fn sub(self, d: Duration) -> Self {
        let (carry, n) = if self.1 >= d.subsec_nanos() {
            (0, self.1 - d.subsec_nanos())
        } else {
            (1, NANOS_PER_SECOND + self.1 - d.subsec_nanos())
        };
        Tai64N(self.0 - carry - d.as_secs(), n)
    }
}
```

--------------------------------

### Parse TAI64N from bytes

Source: https://docs.rs/tai64/latest/src/tai64/lib.rs.html

Parses TAI64N from a byte array or slice, validating the nanosecond component.

```rust
impl TryFrom<[u8; Self::BYTE_SIZE]> for Tai64N {
    type Error = Error;

    /// Parse TAI64 from external representation
    fn try_from(bytes: [u8; Tai64N::BYTE_SIZE]) -> Result<Self, Error> {
        let secs = Tai64::from_slice(&bytes[..Tai64::BYTE_SIZE])?;

        let mut nano_bytes = [0u8; 4];
        nano_bytes.copy_from_slice(&bytes[Tai64::BYTE_SIZE..]);
        let nanos = u32::from_be_bytes(nano_bytes);

        if nanos < NANOS_PER_SECOND {
            Ok(Tai64N(secs, nanos))
        } else {
            Err(Error::NanosInvalid)
        }
    }
}
```

```rust
impl<'a> TryFrom<&'a [u8]> for Tai64N {
    type Error = Error;

    fn try_from(slice: &'a [u8]) -> Result<Self, Error> {
        let bytes: [u8; Tai64N::BYTE_SIZE] = slice.try_into().map_err(|_| Error::LengthInvalid)?;
        bytes.try_into()
    }
}
```

--------------------------------

### Convert Tai64 to Tai64N

Source: https://docs.rs/tai64/latest/src/tai64/lib.rs.html

Converts a Tai64 value to Tai64N by setting the nanosecond component to zero.

```rust
impl From<Tai64> for Tai64N {
    /// Remove the nanosecond component from a TAI64N value
    fn from(other: Tai64) -> Self {
        Tai64N(other, 0)
    }
}
```

--------------------------------

### Calculate duration between TAI64N instances

Source: https://docs.rs/tai64/latest/src/tai64/lib.rs.html

Calculates the duration elapsed between two TAI64N timestamps.

```rust
pub fn duration_since(&self, other: &Self) -> Result<Duration, Duration> {
        if self >= other {
            let (carry, n) = if self.1 >= other.1 {
                (0, self.1 - other.1)
            } else {
                (1, NANOS_PER_SECOND + self.1 - other.1)
            };

            let s = (self.0).0 - carry - (other.0).0;
            Ok(Duration::new(s, n))
        } else {
            #[allow(clippy::unwrap_used)]
            Err(other.duration_since(self).unwrap())
        }
    }
```

--------------------------------

### Tai64 Struct Definition

Source: https://docs.rs/tai64/latest/tai64/struct.Tai64.html

The core structure definition for the Tai64 type.

```rust
pub struct Tai64(pub u64);
```

--------------------------------

### Define TAI64N error types

Source: https://docs.rs/tai64/latest/src/tai64/lib.rs.html

Defines error variants for TAI64N operations and implements Display and Error traits.

```rust
#[derive(Copy, Clone, Debug, Eq, PartialEq)]
pub enum Error {
    /// Invalid length
    LengthInvalid,

    /// Nanosecond part must be <= 999999999.
    NanosInvalid,
}
```

```rust
impl fmt::Display for Error {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let description = match self {
            Error::LengthInvalid => "length invalid",
            Error::NanosInvalid => "invalid number of nanoseconds",
        };

        write!(f, "{}", description)
    }
}
```

```rust
#[cfg(feature = "std")]
impl std::error::Error for Error {}
```

--------------------------------

### Define Error Enum

Source: https://docs.rs/tai64/latest/tai64/enum.Error.html

The structure of the Error enum used for reporting TAI64-related issues.

```rust
pub enum Error {
    LengthInvalid,
    NanosInvalid,
}
```
Tokens:
Raw