Struct Timestamp 

pub struct Timestamp {
    pub nanos: i64,
    pub tz: Option<String>,
}

A nanosecond-precision point in time, Unix-epoch anchored.

Phase 2 scope: construction, arithmetic, equality, ordering, serde. TZ semantics (IANA tz lookup, DST-aware shift) are deferred to Phase 3 — see br-frankenpandas-4r56.

Fields

nanos: i64

Nanoseconds since Unix epoch. i64::MIN is NaT.

tz: Option<String>

Optional IANA time-zone name (e.g. "US/Eastern"). None means naive / UTC-anchored. Phase 2 treats this as opaque metadata; Phase 3 wires chrono_tz interpretation.

Implementations

impl Timestamp

pub const NAT: i64 = i64::MIN

NaT sentinel, parallel to Timedelta::NAT.

pub const fn from_nanos(nanos: i64) -> Self

Construct a UTC-anchored (tz=None) Timestamp from nanoseconds since Unix epoch.

pub fn from_nanos_tz(nanos: i64, tz_name: impl Into<String>) -> Self

Construct a Timestamp tagged with an IANA tz name.

Phase 2 doesn’t interpret the tz — it only carries the name through arithmetic + serde. Phase 3 wires chrono_tz conversion.

pub fn now() -> Self

Returns the current UTC timestamp.

Matches pd.Timestamp.now() / pd.Timestamp.utcnow().

pub fn utcnow() -> Self

Alias for now(). Matches pd.Timestamp.utcnow().

pub fn today() -> Self

Returns today’s date at midnight UTC.

Matches pd.Timestamp.today().

pub const fn nat() -> Self

The NaT sentinel value for a Timestamp.

pub const fn is_nat(&self) -> bool

True iff this Timestamp is NaT.

pub const fn value(&self) -> i64

Nanoseconds since Unix epoch, matching pd.Timestamp.value.

pub const fn unit(&self) -> Option<&'static str>

Stored resolution unit, matching pd.Timestamp.unit.

FrankenPandas Timestamp stores nanoseconds internally, so non-NaT values report ns. NaT has no unit.

pub const fn resolution(&self) -> Option<&'static str>

Return the resolution of the timestamp (always “ns” for nanoseconds).

Matches pd.Timestamp.resolution. Returns None for NaT.

pub const fn asm8(&self) -> i64

Numpy datetime64 scalar payload, matching pd.Timestamp.asm8.

pub const fn to_datetime64(&self) -> i64

Convert to a datetime64 payload, matching pd.Timestamp.to_datetime64().

pub const fn to_numpy(&self) -> i64

Convert to a numpy scalar payload, matching pd.Timestamp.to_numpy().

pub fn timestamp(&self) -> Result<f64, TypeError>

POSIX timestamp in seconds, matching pd.Timestamp.timestamp().

Pandas exposes this through Python’s datetime surface, so sub-microsecond nanoseconds are rounded to six decimal places. NaT raises in pandas; fp-types surfaces the same condition as a missing-value error.

pub fn add_timedelta(&self, td_nanos: i64) -> Self

Add a Timedelta. NaT in either operand → NaT; saturates on overflow. TZ is preserved from self.

pub fn sub_timedelta(&self, td_nanos: i64) -> Self

Subtract a Timedelta. NaT propagation + saturation; TZ preserved.

pub fn sub_timestamp(&self, other: &Self) -> i64

Subtract another Timestamp. Returns a Timedelta (i64 nanos). NaT in either → Timedelta::NAT; saturates on overflow.

pub fn semantic_eq(&self, other: &Self) -> bool

NaT-aware semantic equality: two NaT Timestamps are equal to each other (matches pandas pd.NaT == pd.NaT under equals(), though pandas’s == operator returns False for NaT==NaT — we follow the semantic_eq convention used elsewhere in fp-types).

pub fn floor_to(&self, unit_nanos: i64) -> Self

Round down to the nearest multiple of unit_nanos.

Matches pd.Timestamp(...).floor(unit). NaT in self or a non-positive unit_nanos returns NaT.

pub fn ceil_to(&self, unit_nanos: i64) -> Self

Round up to the nearest multiple of unit_nanos.

Matches pd.Timestamp(...).ceil(unit). NaT or non-positive unit_nanos returns NaT. Already-multiple inputs return self.

pub fn round_to(&self, unit_nanos: i64) -> Self

Round to the nearest multiple of unit_nanos, banker’s rounding (half-to-even) on ties.

Matches pd.Timestamp(...).round(unit). NaT or non-positive unit_nanos returns NaT.

pub fn floor_to_unit(&self, unit: &str) -> Self

Round down to the nearest multiple of the named unit.

Matches pd.Timestamp(...).floor(unit). Unknown unit → NaT.

pub fn ceil_to_unit(&self, unit: &str) -> Self

Round up to the nearest multiple of the named unit.

Matches pd.Timestamp(...).ceil(unit). Unknown unit → NaT.

pub fn round_to_unit(&self, unit: &str) -> Self

Round to the nearest multiple of the named unit, banker’s rounding.

Matches pd.Timestamp(...).round(unit). Unknown unit → NaT.

pub fn floor(&self, freq: &str) -> Self

Pandas-named alias for floor_to_unit.

pub fn ceil(&self, freq: &str) -> Self

Pandas-named alias for ceil_to_unit.

pub fn round(&self, freq: &str) -> Self

Pandas-named alias for round_to_unit.

pub fn year(&self) -> Option<i64>

Extract the year component from the timestamp.

Matches pd.Timestamp.year. Returns None for NaT.

pub fn month(&self) -> Option<i64>

Extract the month component (1-12) from the timestamp.

Matches pd.Timestamp.month. Returns None for NaT.

pub fn day(&self) -> Option<i64>

Extract the day component (1-31) from the timestamp.

Matches pd.Timestamp.day. Returns None for NaT.

pub fn hour(&self) -> Option<i64>

Extract the hour component (0-23) from the timestamp.

Matches pd.Timestamp.hour. Returns None for NaT.

pub fn minute(&self) -> Option<i64>

Extract the minute component (0-59) from the timestamp.

Matches pd.Timestamp.minute. Returns None for NaT.

pub fn second(&self) -> Option<i64>

Extract the second component (0-59) from the timestamp.

Matches pd.Timestamp.second. Returns None for NaT.

pub fn microsecond(&self) -> Option<i64>

Extract the microsecond component (0-999999) from the timestamp.

Matches pd.Timestamp.microsecond. Returns None for NaT.

pub fn nanosecond(&self) -> Option<i64>

Extract the nanosecond component (0-999) from the timestamp.

Matches pd.Timestamp.nanosecond. Returns None for NaT.

pub fn dayofweek(&self) -> Option<i64>

Return the day of the week (Monday=0, Sunday=6).

Matches pd.Timestamp.dayofweek. Returns None for NaT.

pub fn weekday(&self) -> Option<i64>

Alias for dayofweek(). Matches pd.Timestamp.weekday.

pub fn day_of_week(&self) -> Option<i64>

Alias for dayofweek(). Matches pd.Timestamp.day_of_week.

pub fn dayofyear(&self) -> Option<i64>

Return the day of the year (1-366).

Matches pd.Timestamp.dayofyear. Returns None for NaT.

pub fn day_of_year(&self) -> Option<i64>

Alias for dayofyear(). Matches pd.Timestamp.day_of_year.

pub fn toordinal(&self) -> Option<i64>

Return the proleptic Gregorian ordinal (number of days since Jan 1, year 1).

Matches pd.Timestamp.toordinal(). Returns None for NaT.

pub fn fromordinal(ordinal: i64) -> Self

Construct a Timestamp from a proleptic Gregorian ordinal.

Matches pd.Timestamp.fromordinal(ordinal). Returns NaT for invalid ordinals.

pub fn to_julian_date(&self) -> f64

Return the Julian Date (astronomical day number).

Matches pd.Timestamp.to_julian_date(). Returns NaN for NaT. The Julian Date is the continuous count of days since the beginning of the Julian Period (January 1, 4713 BC in the proleptic Julian calendar).

pub fn quarter(&self) -> Option<i64>

Return the quarter (1-4) of the year.

Matches pd.Timestamp.quarter. Returns None for NaT.

pub fn weekofyear(&self) -> Option<i64>

Return the ISO week number (1-53).

Matches pd.Timestamp.week. Returns None for NaT.

pub fn week(&self) -> Option<i64>

Alias for weekofyear(). Matches pd.Timestamp.week.

pub fn to_unit(&self, unit: &str) -> Option<i64>

Return the timestamp value in the specified unit.

Matches pd.Timestamp.value when unit is nanoseconds. Supported units: “ns”, “us”, “ms”, “s”.

pub fn is_leap_year(&self) -> Option<bool>

Whether the year is a leap year.

Matches pd.Timestamp.is_leap_year. Returns None for NaT.

pub fn is_month_start(&self) -> Option<bool>

Whether the day is the first day of the month.

Matches pd.Timestamp.is_month_start. Returns None for NaT.

pub fn is_month_end(&self) -> Option<bool>

Whether the day is the last day of the month.

Matches pd.Timestamp.is_month_end. Returns None for NaT.

pub fn is_quarter_start(&self) -> Option<bool>

Whether the day is the first day of a quarter.

Matches pd.Timestamp.is_quarter_start. Returns None for NaT.

pub fn is_quarter_end(&self) -> Option<bool>

Whether the day is the last day of a quarter.

Matches pd.Timestamp.is_quarter_end. Returns None for NaT.

pub fn is_year_start(&self) -> Option<bool>

Whether the day is the first day of the year (Jan 1).

Matches pd.Timestamp.is_year_start. Returns None for NaT.

pub fn is_year_end(&self) -> Option<bool>

Whether the day is the last day of the year (Dec 31).

Matches pd.Timestamp.is_year_end. Returns None for NaT.

pub fn days_in_month(&self) -> Option<i64>

Return the number of days in the month of this timestamp.

Matches pd.Timestamp.days_in_month. Returns None for NaT.

pub fn daysinmonth(&self) -> Option<i64>

Alias for days_in_month(). Matches pd.Timestamp.daysinmonth.

pub fn normalize(&self) -> Self

Normalize to midnight/day boundary, matching pd.Timestamp.normalize().

pub fn replace( &self, year: Option<i64>, month: Option<i64>, day: Option<i64>, hour: Option<i64>, minute: Option<i64>, second: Option<i64>, microsecond: Option<i64>, nanosecond: Option<i64>, ) -> Self

Replace timestamp components with new values.

Matches pd.Timestamp.replace(). None values keep the existing component.

pub fn isoformat(&self) -> String

Return an ISO 8601 string representation of the timestamp.

Matches pd.Timestamp.isoformat(). NaT returns “NaT”.

pub fn to_iso8601(&self) -> String

Alias for isoformat.

pub fn parse(s: &str) -> Result<Self, TypeError>

Parse a datetime string into a Timestamp.

Supports ISO 8601 formats:

• “2024-01-15” (date only, time defaults to 00:00:00)
• “2024-01-15T10:30:00” (datetime)
• “2024-01-15 10:30:00” (space separator)
• “2024-01-15T10:30:00.123456” (with fractional seconds)
• “2024-01-15T10:30:00Z” (UTC timezone)
• “2024-01-15T10:30:00+05:30” (offset timezone)
• “NaT” (Not a Timestamp)

Matches pd.Timestamp() constructor behavior.

pub fn strftime(&self, format: &str) -> String

Format timestamp using strftime directives.

Matches pd.Timestamp.strftime(format). Supports: %Y (year), %m (month), %d (day), %H (hour), %M (minute), %S (second), %f (microsecond). NaT returns “NaT”.

pub fn day_name(&self) -> String

Return the day of the week as a string (e.g., “Monday”).

Matches pd.Timestamp.day_name(). NaT returns “NaT”.

pub fn month_name(&self) -> String

Return the month name as a string (e.g., “January”).

Matches pd.Timestamp.month_name(). NaT returns “NaT”.

pub fn tz_localize(&self, tz: Option<&str>) -> Self

Localize a naive timestamp to a timezone.

Matches pd.Timestamp.tz_localize(tz). If tz is None, removes the timezone (makes timestamp naive). NaT propagates.

pub fn tz_convert(&self, tz: &str) -> Self

Convert timezone-aware timestamp to another timezone.

Matches pd.Timestamp.tz_convert(tz). If timestamp is naive (no tz), the timezone is simply attached without conversion. NaT propagates. Note: actual UTC offset conversion requires chrono-tz (Phase 3).

pub fn fromtimestamp(ts: f64, tz: Option<&str>) -> Self

Create a Timestamp from a Unix timestamp (seconds since epoch).

Matches pd.Timestamp.fromtimestamp(ts). The optional tz parameter specifies the timezone to localize to.

pub fn from_millis(ms: i64, tz: Option<&str>) -> Self

Create a Timestamp from milliseconds since epoch.

Convenience constructor complementing fromtimestamp.

pub fn from_micros(us: i64, tz: Option<&str>) -> Self

Create a Timestamp from microseconds since epoch.

Convenience constructor complementing fromtimestamp.

pub fn tzinfo(&self) -> Option<&str>

Return the timezone string, or None if naive.

pub fn tzname(&self) -> Option<&str>

Return the timezone name, or None if naive.

Alias for tzinfo() matching pandas Timestamp.tzname().

Trait Implementations

impl Clone for Timestamp

fn clone(&self) -> Timestamp

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Timestamp

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Timestamp

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Timestamp

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

Phase 2 debug-style format; Phase 3 replaces with pandas ISO-8601 notation once chrono interpretation lands.

impl Eq for Timestamp

impl Hash for Timestamp

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 PartialEq for Timestamp

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

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

Orders by nanos axis; NaT is incomparable (None). Tz difference does not affect ordering — two Timestamps at the same absolute nanos compare equal regardless of tz label (Phase 3 will revisit whether tz affects ordering semantics).

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 Serialize for Timestamp

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Timestamp