utc

utc

                                _            _    _                    
                         _   _ | |_  ___    | |_ (_)_ __ ___   ___    
                        | | | || __|/ __|   | __|| | '_ ` _ \ / _ \   
                        | |_| || |_| (__    | |_ | | | | | | |  __/   
                         \___/  \__|\___|    \__||_|_| |_| |_|\___|   

The utc package provides an enhanced alias of Go's time.Time that ensures your times are consistently in UTC. It includes helpful additional methods for common time operations and formatting.

Features

• Guaranteed UTC time handling
• JSON marshaling/unmarshaling support
• SQL database compatibility
• Automatic timezone handling (PST/PDT, EST/EDT, etc.)
• Extensive formatting options:
  • US date formats (MM/DD/YYYY)
  • EU date formats (DD/MM/YYYY)
  • ISO/RFC standards
  • Common components (weekday, month, etc.)
• Timezone conversion methods with fallback support
• Full compatibility with Go's standard time.Time methods

Installation

To install the utc package, use the following command:

go get github.com/agentstation/utc

Usage

1. Import the package:

import "github.com/agentstation/utc"

1. Create a new UTC time:

// Get current time in UTC
now := utc.Now()

// Convert existing time.Time to UTC
myTime := utc.New(someTime)

// Parse a time string
t, err := utc.ParseRFC3339("2023-01-01T12:00:00Z")

1. Format times using various layouts:

t := utc.Now()

// US formats
fmt.Println(t.USDateShort())     // "01/02/2024"
fmt.Println(t.USDateTime12())    // "01/02/2024 03:04:05 PM"

// EU formats
fmt.Println(t.EUDateShort())     // "02/01/2024"
fmt.Println(t.EUDateTime24())    // "02/01/2024 15:04:05"

// ISO/RFC formats
fmt.Println(t.RFC3339())         // "2024-01-02T15:04:05Z"
fmt.Println(t.ISO8601())         // "2024-01-02T15:04:05Z"

// Components
fmt.Println(t.WeekdayLong())     // "Tuesday"
fmt.Println(t.MonthShort())      // "Jan"

1. Convert between timezones:

t := utc.Now()

// Get time in different US timezones
pacific := t.Pacific()   // Handles PST/PDT automatically
eastern := t.Eastern()   // Handles EST/EDT automatically
central := t.Central()   // Handles CST/CDT automatically
mountain := t.Mountain() // Handles MST/MDT automatically

1. JSON and Database operations:

// JSON marshaling
type Event struct {
    StartTime utc.Time `json:"start_time"`
    EndTime   utc.Time `json:"end_time"`
}

// Database operations
type Record struct {
    CreatedAt utc.Time `db:"created_at"`
    UpdatedAt utc.Time `db:"updated_at"`
}

utc

import "github.com/agentstation/utc"

Index

• func ValidateTimezoneAvailability() error
• type Time
  • func New(t time.Time) Time
  • func Now() Time
  • func Parse(layout string, s string) (Time, error)
  • func ParseRFC3339(s string) (Time, error)
  • func ParseRFC3339Nano(s string) (Time, error)
  • func (t Time) ANSIC() string
  • func (t Time) Add(d time.Duration) Time
  • func (t Time) After(u Time) bool
  • func (t Time) Before(u Time) bool
  • func (t Time) CST() time.Time
  • func (t Time) Central() time.Time
  • func (t Time) DateOnly() string
  • func (t Time) EST() time.Time
  • func (t Time) EUDateLong() string
  • func (t Time) EUDateShort() string
  • func (t Time) EUDateTime12() string
  • func (t Time) EUDateTime24() string
  • func (t Time) EUTime12() string
  • func (t Time) EUTime24() string
  • func (t Time) Eastern() time.Time
  • func (t Time) Equal(u Time) bool
  • func (t Time) Format(layout string) string
  • func (t Time) ISO8601() string
  • func (t Time) IsZero() bool
  • func (t Time) Kitchen() string
  • func (t Time) MST() time.Time
  • func (t *Time) MarshalJSON() ([]byte, error)
  • func (t Time) MonthLong() string
  • func (t Time) MonthShort() string
  • func (t Time) Mountain() time.Time
  • func (t Time) PST() time.Time
  • func (t Time) Pacific() time.Time
  • func (t Time) RFC3339() string
  • func (t Time) RFC3339Nano() string
  • func (t Time) RFC822() string
  • func (t Time) RFC822Z() string
  • func (t Time) RFC850() string
  • func (t *Time) Scan(value interface{}) error
  • func (t *Time) String() string
  • func (t Time) Sub(u Time) time.Duration
  • func (t Time) TimeFormat(layout TimeLayout) string
  • func (t Time) TimeOnly() string
  • func (t Time) USDateLong() string
  • func (t Time) USDateShort() string
  • func (t Time) USDateTime12() string
  • func (t Time) USDateTime24() string
  • func (t Time) USTime12() string
  • func (t Time) USTime24() string
  • func (t Time) UTC() time.Time
  • func (t *Time) UnmarshalJSON(data []byte) error
  • func (t *Time) Value() (driver.Value, error)
  • func (t Time) WeekdayLong() string
  • func (t Time) WeekdayShort() string
• type TimeLayout

func ValidateTimezoneAvailability

func ValidateTimezoneAvailability() error

ValidateTimezoneAvailability checks if all timezone locations were properly initialized Returns nil if initialization was successful, otherwise returns the initialization error

type Time

Time is an alias for time.Time that defaults to UTC time.

type Time struct {
    time.Time
}

func New

func New(t time.Time) Time

New returns a new Time from a time.Time

func Now

func Now() Time

Now returns the current time in UTC

func Parse

func Parse(layout string, s string) (Time, error)

Parse parses a time string in the specified format and returns a utc.Time

func ParseRFC3339

func ParseRFC3339(s string) (Time, error)

ParseRFC3339 parses a time string in RFC3339 format and returns a utc.Time

func ParseRFC3339Nano

func ParseRFC3339Nano(s string) (Time, error)

ParseRFC3339Nano parses a time string in RFC3339Nano format and returns a utc.Time

func (Time) ANSIC

func (t Time) ANSIC() string

ANSIC formats time as "Mon Jan _2 15:04:05 2006"

func (Time) Add

func (t Time) Add(d time.Duration) Time

Add returns the time t+d

func (Time) After

func (t Time) After(u Time) bool

After reports whether the time is after u

func (Time) Before

func (t Time) Before(u Time) bool

Before reports whether the time is before u

func (Time) CST

func (t Time) CST() time.Time

CST returns t in CST

func (Time) Central

func (t Time) Central() time.Time

Central returns t in Central time (handles CST/CDT automatically)

func (Time) DateOnly

func (t Time) DateOnly() string

DateOnly formats time as "2006-01-02"

func (Time) EST

func (t Time) EST() time.Time

EST returns t in EST

func (Time) EUDateLong

func (t Time) EUDateLong() string

EUDateLong formats time as "2 January 2006"

func (Time) EUDateShort

func (t Time) EUDateShort() string

EUDateShort formats time as "02/01/2006"

func (Time) EUDateTime12

func (t Time) EUDateTime12() string

EUDateTime12 formats time as "02/01/2006 03:04:05 PM"

func (Time) EUDateTime24

func (t Time) EUDateTime24() string

EUDateTime24 formats time as "02/01/2006 15:04:05"

func (Time) EUTime12

func (t Time) EUTime12() string

EUTime12 formats time as "3:04 PM"

func (Time) EUTime24

func (t Time) EUTime24() string

EUTime24 formats time as "15:04"

func (Time) Eastern

func (t Time) Eastern() time.Time

Eastern returns t in Eastern time (handles EST/EDT automatically)

func (Time) Equal

func (t Time) Equal(u Time) bool

Equal reports whether t and u represent the same time instant

func (Time) Format

func (t Time) Format(layout string) string

Format formats the time using the specified layout

func (Time) ISO8601

func (t Time) ISO8601() string

ISO8601 formats time as "2006-01-02T15:04:05Z07:00" (same as RFC3339)

func (Time) IsZero

func (t Time) IsZero() bool

Add the useful utility methods while maintaining chainability

func (Time) Kitchen

func (t Time) Kitchen() string

Kitchen formats time as "3:04PM"

func (Time) MST

func (t Time) MST() time.Time

MST returns t in MST

func (*Time) MarshalJSON

func (t *Time) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface for utc.Time.

func (Time) MonthLong

func (t Time) MonthLong() string

MonthLong formats time as "January"

func (Time) MonthShort

func (t Time) MonthShort() string

MonthShort formats time as "Jan"

func (Time) Mountain

func (t Time) Mountain() time.Time

Mountain returns t in Mountain time (handles MST/MDT automatically)

func (Time) PST

func (t Time) PST() time.Time

PST returns t in PST

func (Time) Pacific

func (t Time) Pacific() time.Time

Pacific returns t in Pacific time (handles PST/PDT automatically)

func (Time) RFC3339

func (t Time) RFC3339() string

RFC3339 formats time as "2006-01-02T15:04:05Z07:00"

func (Time) RFC3339Nano

func (t Time) RFC3339Nano() string

RFC3339Nano formats time as "2006-01-02T15:04:05.999999999Z07:00"

func (Time) RFC822

func (t Time) RFC822() string

RFC822 formats time as "02 Jan 06 15:04 MST"

func (Time) RFC822Z

func (t Time) RFC822Z() string

RFC822Z formats time as "02 Jan 06 15:04 -0700"

func (Time) RFC850

func (t Time) RFC850() string

RFC850 formats time as "Monday, 02-Jan-06 15:04:05 MST"

func (*Time) Scan

func (t *Time) Scan(value interface{}) error

Scan implements the sql.Scanner interface for database operations for utc.Time It does this by scanning the value into a time.Time, converting the time.Time to UTC, and then assigning the UTC time to the utc.Time.

func (*Time) String

func (t *Time) String() string

String implements the Stringer interface for utc.Time. It prints the time in RFC3339 format.

func (Time) Sub

func (t Time) Sub(u Time) time.Duration

Sub returns the duration t-u

func (Time) TimeFormat

func (t Time) TimeFormat(layout TimeLayout) string

TimeFormat formats the time using the specified layout

func (Time) TimeOnly

func (t Time) TimeOnly() string

TimeOnly formats time as "15:04:05"

func (Time) USDateLong

func (t Time) USDateLong() string

USDateLong formats time as "January 2, 2006"

func (Time) USDateShort

func (t Time) USDateShort() string

USDateShort formats time as "01/02/2006"

func (Time) USDateTime12

func (t Time) USDateTime12() string

USDateTime12 formats time as "01/02/2006 03:04:05 PM"

func (Time) USDateTime24

func (t Time) USDateTime24() string

USDateTime24 formats time as "01/02/2006 15:04:05"

func (Time) USTime12

func (t Time) USTime12() string

USTime12 formats time as "3:04 PM"

func (Time) USTime24

func (t Time) USTime24() string

USTime24 formats time as "15:04"

func (Time) UTC

func (t Time) UTC() time.Time

UTC returns t in UTC

func (*Time) UnmarshalJSON

func (t *Time) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface for utc.Time

func (*Time) Value

func (t *Time) Value() (driver.Value, error)

Value implements the driver.Valuer interface for database operations for utc.Time. It returns the time.Time value and assumes the time is already in UTC.

func (Time) WeekdayLong

func (t Time) WeekdayLong() string

WeekdayLong formats time as "Monday"

func (Time) WeekdayShort

func (t Time) WeekdayShort() string

WeekdayShort formats time as "Mon"

type TimeLayout

type TimeLayout string

Add layout constants at package level

const (
    TimeLayoutUSDateShort  TimeLayout = "01/02/2006"
    TimeLayoutUSDateLong   TimeLayout = "January 2, 2006"
    TimeLayoutUSDateTime12 TimeLayout = "01/02/2006 03:04:05 PM"
    TimeLayoutUSDateTime24 TimeLayout = "01/02/2006 15:04:05"
    TimeLayoutUSTime12     TimeLayout = "3:04 PM"
    TimeLayoutUSTime24     TimeLayout = "15:04"

    TimeLayoutEUDateShort  TimeLayout = "02/01/2006"
    TimeLayoutEUDateLong   TimeLayout = "2 January 2006"
    TimeLayoutEUDateTime12 TimeLayout = "02/01/2006 03:04:05 PM"
    TimeLayoutEUDateTime24 TimeLayout = "02/01/2006 15:04:05"
    TimeLayoutEUTime12     TimeLayout = "3:04 PM"
    TimeLayoutEUTime24     TimeLayout = "15:04"

    TimeLayoutDateOnly     TimeLayout = "2006-01-02"
    TimeLayoutTimeOnly     TimeLayout = "15:04:05"
    TimeLayoutWeekdayLong  TimeLayout = "Monday"
    TimeLayoutWeekdayShort TimeLayout = "Mon"
    TimeLayoutMonthLong    TimeLayout = "January"
    TimeLayoutMonthShort   TimeLayout = "Jan"
)

Generated by gomarkdoc

License

This project is licensed under the MIT License - see the LICENSE file for details.