Skip to content

[NEP07] DateTime and Timedelta Types #554

Description

@Nucs

Overview

NumPy's datetime64 and timedelta64 types for time-series data.


NEP 7: Date/Time Types in NumPy

Status: Final | Full Text

Type Definitions

datetime64 (Absolute Time)

  • 64-bit signed integer
  • Units from POSIX epoch (January 1, 1970)
  • NaT (Not a Time) = -2^63

timedelta64 (Relative Time)

  • 64-bit signed integer
  • Represents duration/interval
  • NaT = -2^63

Time Units

Code Meaning datetime64 Range
Y year ± 9.2e18 years
M month ± 7.6e17 years
W week ± 1.7e17 years
D day ± 2.5e16 years
h hour ± 1.0e15 years
m minute ± 1.7e13 years
s second ± 2.9e12 years
ms millisecond ± 2.9e9 years
us microsecond (default) ± 2.9e6 years
ns nanosecond ± 292 years
ps picosecond ± 106 days
fs femtosecond ± 2.6 hours
as attosecond ± 9.2 seconds

Operations

datetime64 vs datetime64

  • Subtraction: → timedelta64
  • Comparisons: ==, !=, <, >, <=, >=
  • NOT allowed: addition, multiplication, division

datetime64 vs timedelta64

  • Add/Subtract: → datetime64

timedelta64 vs timedelta64

  • All arithmetic: +, -, *, /
  • Result unit: More precise of the two

String Notation

dtype('datetime64[us]')   # Long form
dtype('M8[us]')           # Short form
dtype('timedelta64[ms]')  # Long form
dtype('m8[ms]')           # Short form

# With multiples
dtype('M8[100ns]')        # 100 nanoseconds
dtype('M8[3M]')           # 3 months

String Parsing

# ISO 8601 format
t[0] = '2008-07-30T17:31:02'

# Integer (seconds since epoch)
t[1] = 1199164176

# Python datetime
t[2] = datetime.datetime(2008, 7, 30, 17, 31, 1)

Suggested Implementation for NumSharp

New Type Codes

enum NPTypeCode {
    // ... existing ...
    DateTime64,   // M8
    TimeDelta64,  // m8
}

Unit Metadata

enum DateTimeUnit {
    Year, Month, Week, Day,
    Hour, Minute, Second,
    Millisecond, Microsecond, Nanosecond,
    Picosecond, Femtosecond, Attosecond
}

class DateTimeDescriptor {
    public DateTimeUnit Unit { get; }
    public int Multiple { get; }  // e.g., 100 for M8[100ns]
}

Storage

// Internal storage: Int64
// With unit metadata attached to dtype
public struct DateTime64 {
    public long Value;
    public DateTimeUnit Unit;
    
    public bool IsNaT => Value == long.MinValue;
}

C# Type Mapping

// Conversion helpers
public static DateTime64 FromDateTime(DateTime dt, DateTimeUnit unit);
public static DateTime ToDateTime(DateTime64 dt64);

public static TimeDelta64 FromTimeSpan(TimeSpan ts, DateTimeUnit unit);
public static TimeSpan ToTimeSpan(TimeDelta64 td64);

Operation Rules

// datetime64 - datetime64 = timedelta64
public static NDArray Subtract(NDArray a, NDArray b) {
    if (a.TypeCode == NPTypeCode.DateTime64 && 
        b.TypeCode == NPTypeCode.DateTime64) {
        return SubtractDateTimes(a, b);  // Returns timedelta64
    }
    // ...
}

String Parsing

// ISO 8601 parsing
public static DateTime64 Parse(string iso8601, DateTimeUnit unit) {
    var dt = DateTime.Parse(iso8601);
    return FromDateTime(dt, unit);
}

Documentation

See docs/neps/NEP07.md

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

NumPy 2.x ComplianceAligns behavior with NumPy 2.x (NEPs, breaking changes)documentation-neededFeature requires documentation after implementation or depiction of lack of documentationenhancementNew feature or requestmissing feature/sNumPy function not yet implemented in NumSharp

Type

No type

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions