strtotime

strtotime

A Go library that parses human-readable date/time strings into time.Time objects, inspired by PHP's strtotime() function.

Features

• Parses natural language date/time expressions
• Supports relative dates ("tomorrow", "next Friday", "+2 days")
• Handles various date formats (ISO, US, European)
• Custom base time reference support
• Timezone specification (3-letter codes and IANA timezone names)
• Extensible architecture

Installation

go get github.com/KarpelesLab/strtotime

Usage

Basic Usage

package main

import (
    "fmt"
    "time"
    
    "github.com/KarpelesLab/strtotime"
)

func main() {
    // Parse a simple date string
    t, err := strtotime.StrToTime("2023-05-15")
    if err != nil {
        fmt.Printf("Error: %s\n", err)
        return
    }
    fmt.Printf("Date: %s\n", t.Format("2006-01-02 15:04:05"))
    
    // Parse a relative date using the current time as reference
    t, err = strtotime.StrToTime("tomorrow")
    if err != nil {
        fmt.Printf("Error: %s\n", err)
        return
    }
    fmt.Printf("Tomorrow: %s\n", t.Format("2006-01-02"))
    
    // Parse a more complex expression
    t, err = strtotime.StrToTime("next Friday +2 weeks")
    if err != nil {
        fmt.Printf("Error: %s\n", err)
        return
    }
    fmt.Printf("Next Friday +2 weeks: %s\n", t.Format("2006-01-02"))
}

Using Options

You can customize parsing behavior with options:

package main

import (
    "fmt"
    "time"
    
    "github.com/KarpelesLab/strtotime"
)

func main() {
    // Set a specific base time for relative calculations
    baseTime := time.Date(2023, 1, 1, 0, 0, 0, 0, time.UTC)
    t, err := strtotime.StrToTime("next month", strtotime.Rel(baseTime))
    if err != nil {
        fmt.Printf("Error: %s\n", err)
        return
    }
    fmt.Printf("Next month from 2023-01-01: %s\n", t.Format("2006-01-02"))
    
    // Specify a timezone as an option
    loc, _ := time.LoadLocation("America/New_York")
    t, err = strtotime.StrToTime("today", strtotime.InTZ(loc))
    if err != nil {
        fmt.Printf("Error: %s\n", err)
        return
    }
    fmt.Printf("Today in New York: %s\n", t.Format("2006-01-02 15:04:05 MST"))
    
    // Or specify timezone in the string
    t, err = strtotime.StrToTime("January 1 2023 EST")
    if err != nil {
        fmt.Printf("Error: %s\n", err)
        return
    }
    fmt.Printf("Date with timezone: %s\n", t.Format("2006-01-02 15:04:05 MST"))
    
    // Combine multiple options
    t, err = strtotime.StrToTime("tomorrow", strtotime.Rel(baseTime), strtotime.InTZ(loc))
    if err != nil {
        fmt.Printf("Error: %s\n", err)
        return
    }
    fmt.Printf("Tomorrow from 2023-01-01 in New York: %s\n", t.Format("2006-01-02 15:04:05 MST"))
}

Supported Date/Time Formats

The library can understand many different formats and expressions, including:

Simple Words

• now - current time
• today - current date at midnight
• tomorrow - tomorrow at midnight
• yesterday - yesterday at midnight

Relative Dates

• next Monday, last Friday - next/last occurrence of a weekday
• next week, last week - next/last Monday
• next month, last month - same day next/last month
• next year, last year - same day next/last year

Relative Time Adjustments

• +1 day, -2 days - add/subtract specific time units
• +1 week, -3 weeks - with various time units (day, week, month, year, hour, minute, second)
• 4 days - implicit positive adjustment (same as +4 days)

Date Formats

• ISO format: 2023-05-15
• Slash format: 2023/05/15
• US format: 05/15/2023
• European format: 15.05.2023
• With timezone: January 1 2023 EST, June 1 1985 16:30:00 Europe/Paris

Month Names

• Full names: January 15 2023
• Abbreviated: Jan 15, 2023
• With/without commas: Jan 15 2023
• With ordinal suffixes: April 4th
• Month only: January (first day of the month in current year)

Compound Expressions

• next year + 4 days
• next month - 1 week
• next week + 3 days
• tomorrow + 12 hours
• Complex combinations: next year + 1 month + 1 week

Time Unit Handling

The library recognizes various formats for time units:

• Standard forms: day, week, month, year, hour, minute, second
• Plural forms: days, weeks, months, years, hours, minutes, seconds
• Abbreviations: d, w, wk, m, y, yr, h, hr, min, sec
• Common variations: hrs, mon, mins, secs

Timezone Support

The library supports multiple timezone formats:

• 3-letter abbreviations: EST, PST, GMT, UTC, etc.
• IANA timezone names: America/New_York, Europe/Paris, Asia/Tokyo, etc.
• Timezone can be specified in the string: January 1 2023 EST, June 1 1985 16:30:00 Europe/Paris
• Timezone can also be provided as an option: strtotime.InTZ(loc)

Error Handling

The library returns detailed error messages when it fails to parse a string:

t, err := strtotime.StrToTime("invalid date format")
if err != nil {
    fmt.Printf("Error: %s\n", err)
    // Handle the error
}

License

This library is available under the LICENSE included in the repository.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.