Struct TimestampUtils

Source

pub struct TimestampUtils;

Expand description

Comprehensive timestamp utilities for consistent i64 handling

This struct provides a collection of utility functions for working with i64 timestamps, including validation, conversion, and formatting operations. All functions are designed to work with milliseconds since Unix epoch.

§Design Principles

Type Safety: All operations use i64 for consistency
Validation: Range checking prevents invalid timestamps
Migration Support: Conversion utilities for u64 to i64 migration
Error Handling: Proper error types for all failure modes

§Example

use ccxt_core::time::TimestampUtils;

// Get current timestamp
let now = TimestampUtils::now_ms();

// Validate timestamp
let validated = TimestampUtils::validate_timestamp(now).unwrap();

// Convert units
let seconds = TimestampUtils::ms_to_seconds(validated);
let back_to_ms = TimestampUtils::seconds_to_ms(seconds);
assert_eq!(validated, back_to_ms);

Implementations§

Source §

impl TimestampUtils

Source

pub const YEAR_2100_MS: i64 = 4_102_444_800_000i64

Maximum reasonable timestamp (year 2100) to prevent far-future timestamps

Source

pub const UNIX_EPOCH_MS: i64 = 0i64

Minimum reasonable timestamp (year 1970) - Unix epoch start

Source

pub fn now_ms() -> i64

Get current timestamp in milliseconds as i64

Returns the current system time as milliseconds since Unix epoch. This is the primary function for getting current timestamps in the library.

§Example

use ccxt_core::time::TimestampUtils;

let now = TimestampUtils::now_ms();
assert!(now > 1_600_000_000_000); // After 2020

Source

pub fn seconds_to_ms(seconds: i64) -> i64

Convert seconds to milliseconds

§Arguments

seconds - Timestamp in seconds since Unix epoch

§Returns

Timestamp in milliseconds since Unix epoch

§Example

use ccxt_core::time::TimestampUtils;

let seconds = 1704110400; // 2024-01-01 12:00:00 UTC
let milliseconds = TimestampUtils::seconds_to_ms(seconds);
assert_eq!(milliseconds, 1704110400000);

Source

pub fn ms_to_seconds(ms: i64) -> i64

Convert milliseconds to seconds

§Arguments

ms - Timestamp in milliseconds since Unix epoch

§Returns

Timestamp in seconds since Unix epoch

§Example

use ccxt_core::time::TimestampUtils;

let milliseconds = 1704110400000; // 2024-01-01 12:00:00 UTC
let seconds = TimestampUtils::ms_to_seconds(milliseconds);
assert_eq!(seconds, 1704110400);

Source

pub fn validate_timestamp(timestamp: i64) -> Result<i64>

Validate timestamp is within reasonable bounds

Ensures the timestamp is:

Not negative (valid Unix timestamp)
Not too far in the future (before year 2100)

§Arguments

timestamp - Timestamp in milliseconds to validate

§Returns

The validated timestamp if valid, or an error if invalid

§Errors

Error::InvalidRequest if timestamp is negative
Error::InvalidRequest if timestamp is too far in future

§Example

use ccxt_core::time::TimestampUtils;

// Valid timestamp
let valid = TimestampUtils::validate_timestamp(1704110400000).unwrap();
assert_eq!(valid, 1704110400000);

// Invalid timestamp (negative)
let invalid = TimestampUtils::validate_timestamp(-1);
assert!(invalid.is_err());

Source

pub fn parse_timestamp(s: &str) -> Result<i64>

Parse timestamp from string (handles various formats)

Attempts to parse a timestamp from string format, supporting:

Integer strings (milliseconds): “1704110400000”
Decimal strings (seconds with fractional part): “1704110400.123”
Scientific notation: “1.7041104e12”

§Arguments

s - String representation of timestamp

§Returns

Parsed and validated timestamp in milliseconds

§Errors

Error::Parse if string cannot be parsed as number
Error::InvalidRequest if parsed timestamp is invalid

§Example

use ccxt_core::time::TimestampUtils;

// Parse integer milliseconds
let ts1 = TimestampUtils::parse_timestamp("1704110400000").unwrap();
assert_eq!(ts1, 1704110400000);

// Parse decimal seconds
let ts2 = TimestampUtils::parse_timestamp("1704110400.123").unwrap();
assert_eq!(ts2, 1704110400123);

Source

pub fn format_iso8601(timestamp: i64) -> Result<String>

Format timestamp as ISO 8601 string

Converts a timestamp to ISO 8601 format with millisecond precision. Always uses UTC timezone and includes milliseconds.

§Arguments

timestamp - Timestamp in milliseconds since Unix epoch

§Returns

ISO 8601 formatted string (e.g., “2024-01-01T12:00:00.000Z”)

§Example

use ccxt_core::time::TimestampUtils;

let timestamp = 1704110400000; // 2024-01-01 12:00:00 UTC
let iso_str = TimestampUtils::format_iso8601(timestamp).unwrap();
assert_eq!(iso_str, "2024-01-01T12:00:00.000Z");

Source

pub fn is_reasonable_timestamp(timestamp: i64) -> bool

Check if a timestamp represents a reasonable date

Validates that the timestamp represents a date between 1970 and 2100, which covers all reasonable use cases for cryptocurrency trading.

§Arguments

timestamp - Timestamp in milliseconds to check

§Returns

true if timestamp is reasonable, false otherwise

§Example

use ccxt_core::time::TimestampUtils;

assert!(TimestampUtils::is_reasonable_timestamp(1704110400000)); // 2024
assert!(!TimestampUtils::is_reasonable_timestamp(-1)); // Before 1970

Source

pub fn u64_to_i64(timestamp: u64) -> Result<i64>

👎Deprecated since 0.1.0: Use i64 timestamps directly

Convert u64 to i64 with overflow checking

This function is provided for migration support when converting from old u64 timestamp code to new i64 timestamp code. It performs overflow checking to ensure the conversion is safe.

§Arguments

timestamp - u64 timestamp to convert

§Returns

Converted i64 timestamp if within valid range

§Errors

Error::InvalidRequest if u64 value exceeds i64::MAX

§Example

use ccxt_core::time::TimestampUtils;

let old_timestamp: u64 = 1704110400000;
let new_timestamp = TimestampUtils::u64_to_i64(old_timestamp).unwrap();
assert_eq!(new_timestamp, 1704110400000i64);

Source

pub fn i64_to_u64(timestamp: i64) -> Result<u64>

Convert i64 to u64 with underflow checking

This function is provided for backward compatibility when interfacing with legacy code that expects u64 timestamps. It performs underflow checking to ensure the conversion is safe.

§Arguments

timestamp - i64 timestamp to convert

§Returns

Converted u64 timestamp if non-negative

§Errors

Error::InvalidRequest if i64 value is negative

§Example

use ccxt_core::time::TimestampUtils;

let new_timestamp: i64 = 1704110400000;
let old_timestamp = TimestampUtils::i64_to_u64(new_timestamp).unwrap();
assert_eq!(old_timestamp, 1704110400000u64);

Source

pub fn start_of_day(timestamp: i64) -> Result<i64>

Get timestamp for start of day (00:00:00 UTC)

Given a timestamp, returns the timestamp for the start of that day in UTC.

§Arguments

timestamp - Any timestamp within the target day

§Returns

Timestamp for 00:00:00 UTC of the same day

§Example

use ccxt_core::time::TimestampUtils;

let timestamp = 1704110400000; // 2024-01-01 12:00:00 UTC
let start_of_day = TimestampUtils::start_of_day(timestamp).unwrap();
// Should be 2024-01-01 00:00:00 UTC

Source

pub fn end_of_day(timestamp: i64) -> Result<i64>

Get timestamp for end of day (23:59:59.999 UTC)

Given a timestamp, returns the timestamp for the end of that day in UTC.

§Arguments

timestamp - Any timestamp within the target day

§Returns

Timestamp for 23:59:59.999 UTC of the same day

§Example

use ccxt_core::time::TimestampUtils;

let timestamp = 1704110400000; // 2024-01-01 12:00:00 UTC
let end_of_day = TimestampUtils::end_of_day(timestamp).unwrap();
// Should be 2024-01-01 23:59:59.999 UTC