API Reference › DateTime

DateTime

Inherits from Value
Sealed

DateTime — UTC date and time via Erlang calendar/os modules.

Provides class-side constructors for creating UTC datetime values and instance methods for access, arithmetic, comparison, and formatting.

Examples

now := DateTime now                              // current UTC time
dt := DateTime year: 2026 month: 2 day: 18
dt year                                          // => 2026
dt asString                                      // => "2026-02-18T00:00:00Z"
dt addDays: 7                                    // => a DateTime(2026-02-25T00:00:00Z)

Methods

Class Methods

new: _ source

Use 'DateTime year: y month: m day: d', 'DateTime fromTimestamp: ts', or 'DateTime fromString: str' to create a DateTime.

now Sealed source

Current UTC time.

Examples

DateTime now                                   // => a DateTime(...)
monotonicNow Sealed source

Monotonic clock value in nanoseconds (for measuring intervals). Returns an Integer, not a DateTime.

Examples

start := DateTime monotonicNow
// ... do work ...
elapsed := DateTime monotonicNow - start       // nanoseconds
year: y month: m day: d Sealed source

Construct from year, month, day (time defaults to 00:00:00).

Examples

DateTime year: 2026 month: 2 day: 18
// => a DateTime(2026-02-18T00:00:00Z)
year: y month: m day: d hour: h minute: mi second: s Sealed source

Construct from year, month, day, hour, minute, second.

Examples

DateTime year: 2026 month: 2 day: 18 hour: 10 minute: 30 second: 0
// => a DateTime(2026-02-18T10:30:00Z)
fromTimestamp: ts Sealed source

Construct from Unix epoch timestamp (seconds).

Examples

DateTime fromTimestamp: 0
// => a DateTime(1970-01-01T00:00:00Z)
fromString: str Sealed source

Parse an ISO 8601 string.

Examples

DateTime fromString: '2026-02-18T10:30:00Z'
// => a DateTime(2026-02-18T10:30:00Z)

Instance Methods

year source

Year component.

month source

Month component (1-12).

day source

Day component (1-31).

hour source

Hour component (0-23).

minute source

Minute component (0-59).

second source

Second component (0-59).

asTimestamp source

Convert to Unix epoch timestamp (seconds).

asString source

Format as ISO 8601 string.

Examples

(DateTime year: 2026 month: 2 day: 18) asString
// => "2026-02-18T00:00:00Z"
printString source

Human-readable representation.

addSeconds: secs source

Add seconds, return new DateTime.

Examples

(DateTime year: 2026 month: 1 day: 1) addSeconds: 3600
// => a DateTime(2026-01-01T01:00:00Z)
addDays: days source

Add days, return new DateTime.

Examples

(DateTime year: 2026 month: 1 day: 1) addDays: 7
// => a DateTime(2026-01-08T00:00:00Z)
diffSeconds: other source

Difference in seconds between this and another DateTime.

Examples

a := DateTime year: 2026 month: 1 day: 2
b := DateTime year: 2026 month: 1 day: 1
a diffSeconds: b                               // => 86400
< other source

True if this DateTime is earlier than other.

Examples

(DateTime year: 2025 month: 1 day: 1) < (DateTime year: 2026 month: 1 day: 1)  // => true
> other source

True if this DateTime is later than other.

Examples

(DateTime year: 2026 month: 1 day: 1) > (DateTime year: 2025 month: 1 day: 1)  // => true
<= other source

True if this DateTime is earlier than or equal to other.

Examples

(DateTime year: 2026 month: 1 day: 1) <= (DateTime year: 2026 month: 1 day: 1)  // => true
>= other source

True if this DateTime is later than or equal to other.

Examples

(DateTime year: 2026 month: 1 day: 1) >= (DateTime year: 2026 month: 1 day: 1)  // => true
=:= other source

True if this DateTime represents the same instant as other.

Examples

dt =:= dt    // => true
=/= other source

True if this DateTime is not strictly equal to other.

Examples

(DateTime year: 2026 month: 1 day: 1) =/= (DateTime year: 2026 month: 1 day: 2)  // => true
/= other source

True if this DateTime does not represent the same instant as other.

Examples

(DateTime year: 2026 month: 1 day: 1) /= (DateTime year: 2026 month: 1 day: 2)  // => true

Inherited Methods

From Value

inspect

Return a developer-readable string representation showing fields.

Produces ClassName(field: value, ...). Field values are recursively inspected — strings are quoted, nested objects show their own inspect. A class with no fields produces ClassName().

Examples

ValuePoint x: 3 y: 4        inspect   // => "ValuePoint(x: 3, y: 4)"
ValuePoint new              inspect   // => "ValuePoint(x: 0, y: 0)"

From Object

class

Return the class of the receiver.

Examples

42 class              // => Integer
"hello" class         // => String
isNil

Test if the receiver is nil. Returns false for all objects except nil.

Examples

42 isNil              // => false
nil isNil             // => true
notNil

Test if the receiver is not nil. Returns true for all objects except nil.

Examples

42 notNil             // => true
nil notNil            // => false
ifNil: _nilBlock

If the receiver is nil, evaluate nilBlock. Otherwise return self.

Examples

42 ifNil: [0]         // => 42
nil ifNil: [0]        // => 0
ifNotNil: notNilBlock

If the receiver is not nil, evaluate notNilBlock with self.

Examples

42 ifNotNil: [:v | v + 1]   // => 43
nil ifNotNil: [:v | v + 1]  // => nil
ifNil: _nilBlock ifNotNil: notNilBlock

If nil, evaluate nilBlock; otherwise evaluate notNilBlock with self.

Examples

42 ifNil: [0] ifNotNil: [:v | v + 1]    // => 43
nil ifNil: [0] ifNotNil: [:v | v + 1]   // => 0
ifNotNil: notNilBlock ifNil: _nilBlock

If not nil, evaluate notNilBlock with self; otherwise evaluate nilBlock.

Examples

42 ifNotNil: [:v | v + 1] ifNil: [0]    // => 43
nil ifNotNil: [:v | v + 1] ifNil: [0]   // => 0
printString

Return a developer-readable string representation.

Default implementation returns "a ClassName". Subclasses such as Integer, String, and List override this to return richer output.

Examples

42 printString            // => "42"
displayString

Return a user-facing string representation for display purposes.

Default implementation delegates to printString. Subclasses such as String and Symbol override this to return a more readable form without developer annotations (e.g. no surrounding quotes or # prefix).

Examples

42 displayString             // => "42"
inspect

Inspect the receiver.

Examples

42 inspect             // => "42"
yourself Sealed

Return the receiver itself. Useful for cascading side effects.

Examples

42 yourself            // => 42
hash

Return a hash value for the receiver.

Examples

42 hash
respondsTo: selector Sealed

Test if the receiver responds to the given selector.

Examples

42 respondsTo: #abs    // => true
fieldNames Sealed

Return the names of fields.

Examples

42 fieldNames             // => #()
fieldAt: name Sealed

Return the value of the named field.

Examples

object fieldAt: #name
fieldAt: name put: value Sealed

Set the value of the named field (returns new state).

Examples

object fieldAt: #name put: "Alice"
perform: selector Sealed

Send a unary message dynamically.

Examples

42 perform: #abs       // => 42
perform: selector withArguments: args Sealed

Send a message dynamically with arguments.

Examples

3 perform: #max: withArguments: #(5)   // => 5
subclassResponsibility

Raise an error indicating this method must be overridden by a subclass.

Examples

self subclassResponsibility
notImplemented

Raise an error indicating this method has not yet been implemented.

Use this for work-in-progress stubs. Distinct from subclassResponsibility, which signals an interface contract violation.

Examples

self notImplemented
show: aValue

Send aValue to the current transcript without a trailing newline.

Nil-safe: does nothing when no transcript is set (batch compile, tests).

Examples

42 show: "value: "
showCr: aValue

Send aValue to the current transcript followed by a newline.

Nil-safe: does nothing when no transcript is set (batch compile, tests).

Examples

42 showCr: "hello world"
isKindOf: aClass

Test if the receiver is an instance of aClass or any of its subclasses.

Examples

42 isKindOf: Integer    // => true
42 isKindOf: Object     // => true
#foo isKindOf: Symbol   // => true
#foo isKindOf: String   // => false
error: message

Raise an error with the given message.

Examples

self error: "something went wrong"

From ProtoObject

== other

Test value equality (Erlang ==).

Examples

42 == 42           // => true
"abc" == "abc"     // => true
/= other

Test value inequality (negation of ==).

Examples

1 /= 2             // => true
42 /= 42           // => false
class

Return the class of the receiver.

Examples

42 class            // => Integer
"hello" class       // => String
doesNotUnderstand: selector args: arguments

Handle messages the receiver does not understand. Override for custom dispatch.

Examples

42 unknownMessage   // => ERROR: does_not_understand
perform: selector withArguments: arguments

Send a message dynamically with an arguments list.

Examples

42 perform: #abs withArguments: #()   // => 42
performLocally: selector withArguments: arguments

Execute a class method in the caller's process, bypassing gen_server dispatch.

The caller takes responsibility for knowing the method does not mutate class state. Useful for long-running class methods that would otherwise block the class object's gen_server.

Limitations: only resolves methods defined directly on the target class module (does not walk the superclass chain). Class variables and self are not available to the method (nil and #{} are passed).

Examples

MyClass performLocally: #run:ctx: withArguments: #(input, ctx)
perform: selector withArguments: arguments timeout: timeoutMs

Send a message dynamically with an arguments list and explicit timeout.

The timeout (in milliseconds or #infinity) applies to the gen_server:call when the receiver is an actor. For value types, timeout is ignored.

Examples

actor perform: #query withArguments: #(sql) timeout: 30000