datetime Module

The datetime module provides a comprehensive set of functions for date and time operations, including timezone support, timers, and cron-like scheduling.

Functions

Now()

Returns the current time as a datetime.time object.

Returns:

• (time, error): The current time object.

Example:

1
2
3
4
5
6
7
8
9

package main
import fmt
import datetime

var t, _ = datetime.Now()
fmt.Println(t)           // prints RFC3339Nano by default
fmt.Println(t.Year())    // 2025
fmt.Println(t.Month())   // 1..12
fmt.Println(t.Weekday()) // 0..6 (Sunday=0)

NowUnix()

Backward-compatible helper that returns the current Unix timestamp in seconds.

Returns:

• (integer, error): The current Unix timestamp.

Example:

1
2
3
4
5
6

package main
import fmt
import datetime

var sec, _ = datetime.NowUnix()
fmt.Println(sec)

Format(timestamp, format)

Formats a Unix timestamp into a string based on a layout.

Parameters:

• timestamp: An integer representing the Unix timestamp (module-level convenience)
• format: A string representing the layout. Supports RFC3339, or custom Go layout strings.

Returns:

• (string, error): The formatted time string.

Example:

1
2
3
4
5
6
7

package main
import fmt
import datetime

var sec, _ = datetime.NowUnix()
var formatted, _ = datetime.Format(sec, "RFC3339")
fmt.Println(formatted)

You can also call t.Format(layout) on the time object (see below).

time object methods

datetime.time mirrors Go's time.Time API. Below are the key methods.

Accessors

• t.Year() -> int
• t.Month() -> int (1..12). Use datetime.MonthString(int) for names.
• t.Day() -> int
• t.Weekday() -> int (0..6, Sunday=0). Use datetime.WeekdayString(int) for names.
• t.Hour() -> int, t.Minute() -> int, t.Second() -> int, t.Nanosecond() -> int
• t.YearDay() -> int
• t.ISOWeek() -> (int year, int week)
• t.Clock() -> (int h, int m, int s)
• t.Date() -> (int y, int m, int d)
• t.IsZero() -> bool

1
2
3
4
5
6

var t, _ = datetime.Now()
var y = t.Year()
var m = t.Month()
var wd = t.Weekday()
var mname, _ = datetime.MonthString(m)
var wdname, _ = datetime.WeekdayString(wd)

Unix conversions

• t.Unix() -> int
• t.UnixMilli() -> int
• t.UnixMicro() -> int
• t.UnixNano() -> int

Time zone

• t.Location() -> Location
• t.Zone() -> (string name, int offsetSeconds)
• t.In(loc Location) -> time
• t.Local() -> time
• t.UTC() -> time

Arithmetic

• t.Add(d Duration) -> time
• t.Sub(u time) -> Duration (seconds resolution)
• t.AddDate(years, months, days) -> time

Comparisons

• t.After(u time) -> bool
• t.Before(u time) -> bool
• t.Equal(u time) -> bool
• t.Compare(u time) -> int // -1, 0, 1

Rounding

• t.Truncate(d Duration) -> time
• t.Round(d Duration) -> time

Formatting and string forms

• t.Format(layout string) -> string
• t.String() -> string
• t.GoString() -> string

Encoding helpers

• t.MarshalText() -> string (RFC3339Nano)
• t.UnmarshalText(text string) -> time
• t.MarshalJSON() -> string (JSON string, RFC3339Nano)
• t.UnmarshalJSON(json string) -> time
• t.MarshalBinary() -> string (base64)
• t.UnmarshalBinary(b64 string) -> time

Helpers for names

• datetime.MonthString(month int 1..12) -> (string, error)
• datetime.WeekdayString(weekday int 0..6) -> (string, error)

1
2
3

var t, _ = datetime.Now()
var m = t.Month()
var name, _ = datetime.MonthString(m)

Constructors and Parsing

Constructors

• datetime.FromUnix(sec int) -> (time, error)
• datetime.FromUnixMilli(ms int) -> (time, error)
• datetime.FromUnixMicro(us int) -> (time, error)
• datetime.FromUnixNano(ns int) -> (time, error)
• datetime.FromParts(y, m, d, h, min, s, nsec[, loc]) -> (time, error)

1
2

var t1, _ = datetime.FromUnix(1730928000)
var t2, _ = datetime.FromParts(2025, 11, 6, 12, 34, 56, 0)

Parsing

• datetime.Parse(layout, value string) -> (time, error)
• datetime.ParseRFC3339(value string) -> (time, error)
• datetime.ParseRFC3339Nano(value string) -> (time, error)

1

var t, err = datetime.Parse("2006-01-02", "2025-11-06")

Named constants

The datetime module exposes Go-like named constants as zero-arg functions:

Weekdays (Sunday=0..Saturday=6)

• datetime.Sunday()
• datetime.Monday()
• datetime.Tuesday()
• datetime.Wednesday()
• datetime.Thursday()
• datetime.Friday()
• datetime.Saturday()

Example:

1
2
3
4

var t, _ = datetime.Now()
if t.Weekday() == datetime.Saturday() {
    fmt.Println("Weekend!")
}

Months (1..12)

• datetime.January()
• datetime.February()
• datetime.March()
• datetime.April()
• datetime.May()
• datetime.June()
• datetime.July()
• datetime.August()
• datetime.September()
• datetime.October()
• datetime.November()
• datetime.December()

Example:

1
2
3
4

var t, _ = datetime.Now()
if t.Month() == datetime.November() {
    fmt.Println("It's November")
}

Sleep(seconds)

Pauses the execution for a given number of seconds.

Parameters:

• seconds: An integer or float representing the number of seconds to sleep.

Example:

1
2
3
4
5
6
7

package main
import fmt
import datetime

fmt.Println("Sleeping for 2 seconds...")
datetime.Sleep(2)
fmt.Println("Awake!")

year()

Returns the year of the datetime object.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

package main
import datetime
import fmt

// Get the current date and time
var now,_ = datetime.Now()
fmt.Println(now)
// Get the year
var year, yearErr = datetime.Year(now)
fmt.Println("Current Year:", year) // Example: Current Year: 2025

Month(timestamps)

Returns the month of a given Unix timestamp.

Parameters:

• timestamp: An integer representing the Unix timestamp.

Returns:

• (integer, error): The month (1-12).

Example:

1
2
3
4
5
6
7

package main
import fmt
import datetime

var now, _ = datetime.Now()
var month, _ = datetime.Month(now)
fmt.Println("Month:", month)

Day(timestamp)

Returns the day of the month of a given Unix timestamp.

Parameters:

• timestamp: An integer representing the Unix timestamp.

Returns:

• (integer, error): The day of the month (1-31).

Example:

1
2
3
4
5
6
7

package main
import fmt
import datetime

var now, _ = datetime.Now()
var day, _ = datetime.Day(now)
fmt.Println("Day:", day)

ConvertTZ(timestamp, fromTZ, toTZ)

Converts a timestamp from one timezone to another.

Parameters:

• timestamp: An integer representing the Unix timestamp.
• fromTZ: The source timezone (e.g., "UTC").
• toTZ: The target timezone (e.g., "America/New_York").

Returns:

• (integer, error): The converted Unix timestamp.

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

package main
import fmt
import datetime

var nowUTC, _ = datetime.Now()
var nyTime, err = datetime.ConvertTZ(nowUTC, "UTC", "America/New_York")
if err != None {
    fmt.Println("Convert error:", err)
} else {
    fmt.Println("NY timestamp:", nyTime)
}

NowInTZ(timezone)

Returns the current time in a specific timezone.

Parameters:

• timezone: The timezone (e.g., "America/New_York").

Returns:

• (integer, error): The current Unix timestamp in the specified timezone.

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

package main
import fmt
import datetime

var tokyoNow, err = datetime.NowInTZ("Asia/Tokyo")
if err != None {
    fmt.Println("Error:", err)
} else {
    fmt.Println("Tokyo now:", tokyoNow)
}

LocalTime(locale)

Returns the current time for a given locale.

Parameters:

• locale: A two-letter country code (e.g., "US", "GB").

Returns:

• (integer, error): The current Unix timestamp in the locale's timezone.

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

package main
import fmt
import datetime

var usNow, err = datetime.LocalTime("US")
if err != None {
    fmt.Println("Error:", err)
} else {
    fmt.Println("US local time:", usNow)
}

GetSystemTZ()

Returns the system's timezone name.

Returns:

• (string, error): The system timezone.

Example:

1
2
3
4
5
6

package main
import fmt
import datetime

var tz, _ = datetime.GetSystemTZ()
fmt.Println("System TZ:", tz)

GetTZOffset(timezone)

Returns the timezone offset in seconds from UTC.

Parameters:

• timezone: The timezone name.

Returns:

• (integer, error): The offset in seconds.

Example:

1
2
3
4
5
6

package main
import fmt
import datetime

var offset, _ = datetime.GetTZOffset("America/New_York")
fmt.Println("NY offset (seconds):", offset)

Timers and Tickers

NewTimer(id, delay_seconds)

Creates a new timer that will fire after a delay.

Example:

1
2
3
4
5
6

package main
import fmt
import datetime

var _ = datetime.NewTimer("job1", 2)
fmt.Println("Timer scheduled for 2s")

CheckTimer(id)

Checks if a timer has fired.

Example:

1
2
3
4
5
6

package main
import fmt
import datetime

var fired, _ = datetime.CheckTimer("job1")
fmt.Println("Timer fired:", fired)

StopTimer(id)

Stops a timer.

Example:

1
2
3
4
5
6

package main
import fmt
import datetime

var _ = datetime.StopTimer("job1")
fmt.Println("Timer stopped")

NewTicker(id, interval_seconds)

Creates a new ticker that fires at regular intervals.

Example:

1
2
3
4
5
6

package main
import fmt
import datetime

var _ = datetime.NewTicker("tick1", 5)
fmt.Println("Ticker 'tick1' every 5s started")

StopTicker(id)

Stops a ticker.

Example:

1
2
3
4
5
6

package main
import fmt
import datetime

var _ = datetime.StopTicker("tick1")
fmt.Println("Ticker 'tick1' stopped")

Cron Scheduling

IsValidCron(expression)

Validates a cron expression.

Example:

1
2
3
4
5
6

package main
import fmt
import datetime

var ok, _ = datetime.IsValidCron("0 0 * * *")
fmt.Println("Daily cron valid:", ok)

NextCronExecution(expression, timestamp)

Calculates the next execution time of a cron expression.

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

package main
import fmt
import datetime

var now, _ = datetime.Now()
var next, err = datetime.NextCronExecution("0 0 * * *", now)
if err != None {
    fmt.Println("Error:", err)
} else {
    fmt.Println("Next daily run:", next)
}

ParseCron(expression)

Parses a cron expression.

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

package main
import fmt
import datetime

var cron, err = datetime.ParseCron("*/15 * * * *")
if err != None {
    fmt.Println("Parse error:", err)
} else {
    fmt.Println("Cron job:", cron)
}

ScheduleCron(id, expression)

Schedules a cron job.

Example:

1
2
3
4
5
6

package main
import fmt
import datetime

var _ = datetime.ScheduleCron("jobA", "0 * * * *")
fmt.Println("Scheduled hourly job 'jobA'")

StopCron(id)

Stops a scheduled cron job.

Example:

1
2
3
4
5
6

package main
import fmt
import datetime

var _ = datetime.StopCron("jobA")
fmt.Println("Stopped job 'jobA'")

ListCronJobs()

Lists all active cron jobs.

Example:

1
2
3
4
5
6

package main
import fmt
import datetime

var jobs, _ = datetime.ListCronJobs()
fmt.Println("Active cron jobs:", jobs)

EveryMinute(), Hourly(), Daily(), Weekly(), Monthly()

Returns common cron expressions.

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

package main
import fmt
import datetime

var everyMinute, _ = datetime.EveryMinute()
var hourly, _ = datetime.Hourly()
var daily, _ = datetime.Daily()
var weekly, _ = datetime.Weekly()
var monthly, _ = datetime.Monthly()

fmt.Println(everyMinute)
fmt.Println(hourly)
fmt.Println(daily)
fmt.Println(weekly)
fmt.Println(monthly)