Timestamp class

A class for formatting timestamps with customizable patterns and timezone support.

The Timestamp class allows you to define how timestamps are formatted and which timezone they should use. It supports a wide variety of tokens for date, time, and timezone components, enabling logging, reporting, or displaying timestamps in various formats.

Basic Usage

// Simple timestamp with default local timezone
final ts = Timestamp(formatter: 'yyyy-MM-dd HH:mm:ss');
print(ts.timestamp); // "2025-11-05 12:52:01"

// With specific timezone
final tsTehran = Timestamp(
  formatter: 'yyyy-MM-dd HH:mm:ss Z',
  timezone: Timezone.named('Asia/Tehran'),
);
print(tsTehran.timestamp); // "2025-11-05 12:52:01 +03:30"

Supported Format Tokens

Tokens are case-sensitive and must match exactly.

Date Tokens

  • Year:
    • yyyy → Full year (2025)
    • yy → Two-digit year (25)
  • Month:
    • MMMM → Full month name (November)
    • MMM → Abbreviated month (Nov)
    • MM → Zero-padded month (11)
    • M → Month without padding (11)
  • Day:
    • dd → Zero-padded day (05)
    • d → Day without padding (5)
  • Weekday:
    • EEEE → Full weekday name (Wednesday)
    • EEE → Abbreviated weekday (Wed)
    • EE → Zero-padded weekday number (03)
    • E → Weekday number (3, where 1=Monday)

Time Tokens

  • 24-Hour Format:
    • HH → Zero-padded hour (14)
    • H → Hour without padding (14)
  • 12-Hour Format:
    • hhhh → Padded hour with AM/PM (02AM)
    • hhh → Hour with AM/PM (2AM)
    • hh → Zero-padded hour (02)
    • h → Hour without padding (2)
  • AM/PM:
    • A → Uppercase (AM, PM)
    • a → Lowercase (am, pm)
  • Minutes:
    • mm → Zero-padded minutes (52)
    • m → Minutes without padding (52)
  • Seconds:
    • ss → Zero-padded seconds (01)
    • s → Seconds without padding (1)

Sub-Second Tokens

Assuming 123456 microseconds:

  • Milliseconds:
    • SSS → Full milliseconds (123)
    • SS → First two digits (12)
    • S → First digit (1)
  • Microseconds:
    • FFF → Full microseconds (456)
    • FF → First two digits (45)
    • F → First digit (4)

Timezone Tokens

  • Z → Offset literal (+03:30)
  • ZZ → Timezone name (Asia/Tehran)
  • ZZZ → Name with offset (Asia/Tehran+03:30)

Literals and Escaping

Non-alphabetical characters (e.g., /, :, , \n) are treated as literals and included in the output as-is.

To include text that contains letters, escape it with single quotes:

// Using literals
Timestamp(formatter: 'yyyy/MM/dd HH:mm:ss')
// Output: "2025/11/05 12:52:01"

// Using escaped text
Timestamp(formatter: "'Time:' hh:mm A")
// Output: "Time: 12:52 PM"

Timestamp(formatter: "'on' EEEE")
// Output: "on Wednesday"

Factory Constructors

For common formats, use the provided factory constructors:

// ISO 8601 / RFC 3339
Timestamp.iso8601()
// Output: "2025-12-18T16:04:56.789+03:30"

// RFC 2822 / HTTP Date
Timestamp.rfc2822()
// Output: "Thu, 18 Dec 2025 16:04:56 +0330"

// Unix epoch milliseconds
Timestamp.millisecondsSinceEpoch()
// Output: "1734530696789"

// No timestamp
Timestamp.none()
// Output: null

Timezone Handling

The timezone parameter allows you to override the system's default timezone. This is useful for:

  • Consistent logging across different server locations
  • Displaying times in a specific region regardless of server timezone
  • File rotation with timezone-aware filenames
// Server in UTC, but want timestamps in Tehran time
final ts = Timestamp(
  formatter: 'yyyy-MM-dd HH:mm:ss Z',
  timezone: Timezone.named('Asia/Tehran'),
);

If timezone is not specified, the local system timezone is used.

Error Handling

// This throws FormatException
Timestamp(formatter: "'unclosed").timestamp;

// This throws FormatException
Timestamp(formatter: 'INVALID_TOKEN').timestamp;
Annotations
  • @immutable

Constructors

Timestamp({required String formatter, Timezone? timezone})
The formatter parameter is a pattern string that defines how the timestamp should be formatted. See below for the supported tokens.
Timestamp.dateOnly({Timezone? timezone})
Creates a Timestamp using the ISO 8601 date-only format.
factory
Timestamp.iso8601({Timezone? timezone})
Creates a Timestamp using ISO 8601 format (identical to RFC 3339).
factory
Timestamp.millisecondsSinceEpoch({Timezone? timezone})
Creates a Timestamp that outputs milliseconds since Unix epoch.
factory
Timestamp.none()
Creates a Timestamp that produces no output.
factory
Timestamp.rfc2822({Timezone? timezone})
Creates a Timestamp using RFC 2822 / HTTP Date format.
factory
Timestamp.rfc3339({Timezone? timezone})
Creates a Timestamp using RFC 3339 format (identical to ISO 8601).
factory

Properties

formatter → TimestampFormatter
TimestampFormatter for formatting timestamps.
final
hashCode → int
The hash code for this object.
no setteroverride
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
timestamp → String?
Gets the current timestamp using this configuration.
no setter
timezone → Timezone?
The timezone configuration for this timestamp.
final

Methods

noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
override