timezone

README

go-timezone

---

go-timezone is timezone utility for Go.

It has the following features:

• This library uses only the standard package
• Supports getting offset from timezone abbreviation, which is not supported by the time package
• Determine whether the specified time.Time is daylight saving time
• Change the location of time.Time by specifying the timezone

See godoc for usage.

Data source

https://github.com/tkuchiki/timezones

Contributors

• @alex-tan
• @kkavchakHT
• @scottleedavis
• @sashabaranov

Documentation

Overview

Package timezone provides utility for timezone.

Index

• Variables
• type Timezone
  • func New() *Timezone
  • func (tz *Timezone) FixedTimezone(t time.Time, timezone string) (time.Time, error)
  • func (tz *Timezone) GetAllTimezones() map[string][]string
  • func (tz *Timezone) GetOffset(abbr string, dst ...bool) (int, error)
  • func (tz *Timezone) GetTimezoneAbbreviation(timezone string, dst ...bool) (string, error)
  • func (tz *Timezone) GetTimezones(abbr string) ([]string, error)
  • func (tz *Timezone) GetTzAbbreviationInfo(abbr string) ([]*TzAbbreviationInfo, error)
  • func (tz *Timezone) GetTzAbbreviationInfoByTZName(abbr, tzname string) (*TzAbbreviationInfo, error)
  • func (tz *Timezone) GetTzInfo(timezone string) (*TzInfo, error)
  • func (tz *Timezone) IsDST(t time.Time) bool
  • func (tz *Timezone) Timezones() map[string][]string
  • func (tz *Timezone) TzAbbrInfos() map[string][]*TzAbbreviationInfo
  • func (tz *Timezone) TzInfos() map[string]*TzInfo
• type TzAbbreviationInfo
  • func (tai *TzAbbreviationInfo) CountryCode() string
  • func (tai *TzAbbreviationInfo) IsDST() bool
  • func (tai *TzAbbreviationInfo) Name() string
  • func (tai *TzAbbreviationInfo) Offset() int
  • func (tai *TzAbbreviationInfo) OffsetHHMM() string
• type TzInfo
  • func (ti *TzInfo) CountryCode() string
  • func (ti *TzInfo) DaylightOffset() int
  • func (ti *TzInfo) DaylightOffsetHHMM() string
  • func (ti *TzInfo) HasDST() bool
  • func (ti *TzInfo) IsDeprecated() bool
  • func (ti *TzInfo) LastDST() int
  • func (ti *TzInfo) LinkTo() string
  • func (ti *TzInfo) LongDaylight() string
  • func (ti *TzInfo) LongGeneric() string
  • func (ti *TzInfo) LongStandard() string
  • func (ti *TzInfo) ShortDaylight() string
  • func (ti *TzInfo) ShortGeneric() string
  • func (ti *TzInfo) ShortStandard() string
  • func (ti *TzInfo) StandardOffset() int
  • func (ti *TzInfo) StandardOffsetHHMM() string

Examples

• Timezone.FixedTimezone
• Timezone.GetTimezoneAbbreviation
• Timezone.GetTimezoneAbbreviation (Dst)
• Timezone.GetTimezones
• Timezone.GetTzAbbreviationInfo
• Timezone.GetTzAbbreviationInfo (AmbiguousTimezoneAbbreviationsError)
• Timezone.GetTzAbbreviationInfoByTZName
• Timezone.GetTzInfo
• Timezone.IsDST

Variables

var (
	// ErrAmbiguousTzAbbreviations indicates ambiguous timezone abbreviations.
	ErrAmbiguousTzAbbreviations = errors.New("Ambiguous timezone abbreviations")
)

Types

type Timezone

type Timezone struct {
	// contains filtered or unexported fields
}

Timezone represents a timezone information.

func New

func New() *Timezone

New creates a new Timezone.

func (*Timezone) FixedTimezone

func (tz *Timezone) FixedTimezone(t time.Time, timezone string) (time.Time, error)

FixedTimezone returns the time.Time with the given timezone set from the time.Location.

Example

tz := timezone.New()

_time := time.Date(2020, 1, 1, 0, 0, 0, 0, time.UTC)
fixedTime, _ := tz.FixedTimezone(_time, "Europe/Belgrade")

fmt.Println(fixedTime)

Output:

2020-01-01 01:00:00 +0100 CET

func (*Timezone) GetAllTimezones

func (tz *Timezone) GetAllTimezones() map[string][]string

GetAllTimezones returns the timezones.

Deprecated: Use Timezones.

func (*Timezone) GetOffset

func (tz *Timezone) GetOffset(abbr string, dst ...bool) (int, error)

GetOffset returns the timezone offset with the given timezone abbreviation. If also given dst=true, returns the daylight savings timezone offset. Returns a ErrAmbiguousTzAbbreviations error if timezone abbreviation has more than one meaning.

Deprecated: Use GetTzAbbreviationInfo or GetTzAbbreviationInfoByTZName

func (*Timezone) GetTimezoneAbbreviation

func (tz *Timezone) GetTimezoneAbbreviation(timezone string, dst ...bool) (string, error)

GetTimezoneAbbreviation returns the timezone abbreviation with the given timezone. If also given dst=true, returns the daylight savings timezone abbreviation.

Example

tz := timezone.New()

abbr, _ := tz.GetTimezoneAbbreviation("Europe/London")

fmt.Println(abbr)

Output:

GMT

Example (Dst)

tz := timezone.New()

abbr, _ := tz.GetTimezoneAbbreviation("Europe/London", true)

fmt.Println(abbr)

Output:

BST

func (*Timezone) GetTimezones

func (tz *Timezone) GetTimezones(abbr string) ([]string, error)

GetTimezones returns the timezones with the given timezone abbreviation.

Example

tz := timezone.New()
timezones, _ := tz.GetTimezones("UTC")

fmt.Println(timezones)

Output:

[Etc/UCT Etc/UTC Etc/Universal Etc/Zulu UCT UTC Universal Zulu]

func (*Timezone) GetTzAbbreviationInfo

func (tz *Timezone) GetTzAbbreviationInfo(abbr string) ([]*TzAbbreviationInfo, error)

GetTzAbbreviationInfo returns the slice of TzAbbreviationInfo with the given timezone abbreviation. Returns a ErrAmbiguousTzAbbreviations error if timezone abbreviation has more than one meaning.

Example

tz := timezone.New()
tzAbbrInfos, _ := tz.GetTzAbbreviationInfo("EET")

fmt.Println(tzAbbrInfos[0].Name())
fmt.Println(tzAbbrInfos[0].Offset())
fmt.Println(tzAbbrInfos[0].OffsetHHMM())

Output:

Eastern European Time/Eastern European Standard Time
7200
+02:00

Example (AmbiguousTimezoneAbbreviationsError)

tz := timezone.New()
tzAbbrInfos, _ := tz.GetTzAbbreviationInfo("BST")

fmt.Println(tzAbbrInfos[0].Name())
fmt.Println(tzAbbrInfos[0].Offset())
fmt.Println(tzAbbrInfos[0].OffsetHHMM())
fmt.Println(tzAbbrInfos[1].Name())
fmt.Println(tzAbbrInfos[1].Offset())
fmt.Println(tzAbbrInfos[1].OffsetHHMM())
fmt.Println(tzAbbrInfos[2].Name())
fmt.Println(tzAbbrInfos[2].Offset())
fmt.Println(tzAbbrInfos[2].OffsetHHMM())

Output:

Bolivia Summer Time
-12756
-03:27
British Summer Time
3600
+01:00
Bougainville Standard Time
39600
+11:00

func (*Timezone) GetTzAbbreviationInfoByTZName

func (tz *Timezone) GetTzAbbreviationInfoByTZName(abbr, tzname string) (*TzAbbreviationInfo, error)

GetTzAbbreviationInfoByTZName returns the TzAbbreviationInfo with the given timezone abbreviation and timezone name. Even if timezone abbreviation has more than one meanings, it can be identified by tzname.

Example

tz := timezone.New()
tzAbbrInfo, _ := tz.GetTzAbbreviationInfoByTZName("BST", "British Summer Time")

fmt.Println(tzAbbrInfo.Name())
fmt.Println(tzAbbrInfo.Offset())
fmt.Println(tzAbbrInfo.OffsetHHMM())

Output:

British Summer Time
3600
+01:00

func (*Timezone) GetTzInfo

func (tz *Timezone) GetTzInfo(timezone string) (*TzInfo, error)

GetTzInfo returns the TzInfo with the given timezone.

Example

tz := timezone.New()
tzInfo, _ := tz.GetTzInfo("Europe/London")

fmt.Println(tzInfo.LongStandard())
fmt.Println(tzInfo.ShortStandard())
fmt.Println(tzInfo.StandardOffset())
fmt.Println(tzInfo.StandardOffsetHHMM())
fmt.Println(tzInfo.LongDaylight())
fmt.Println(tzInfo.ShortDaylight())
fmt.Println(tzInfo.DaylightOffset())
fmt.Println(tzInfo.DaylightOffsetHHMM())

Output:

Greenwich Mean Time
GMT
0
+00:00
British Summer Time
BST
3600
+01:00

func (*Timezone) IsDST

func (tz *Timezone) IsDST(t time.Time) bool

IsDST returns whether a given time is daylight saving time or not.

Example

tz := timezone.New()

loc, _ := time.LoadLocation("America/New_York")
_time := time.Date(2021, 7, 1, 0, 0, 0, 0, loc)
isDST := tz.IsDST(_time)

_time = time.Date(2021, 1, 1, 0, 0, 0, 0, loc)
isNotDST := tz.IsDST(_time)
fmt.Println(isDST)
fmt.Println(isNotDST)

Output:

true
false

func (*Timezone) Timezones

func (tz *Timezone) Timezones() map[string][]string

Timezones returns the all timezones.

func (*Timezone) TzAbbrInfos

func (tz *Timezone) TzAbbrInfos() map[string][]*TzAbbreviationInfo

TzAbbrInfos returns the all tzAbbrInfos.

func (*Timezone) TzInfos

func (tz *Timezone) TzInfos() map[string]*TzInfo

TzInfos returns the all tzInfos.

type TzAbbreviationInfo

type TzAbbreviationInfo struct {
	// contains filtered or unexported fields
}

TzAbbreviationInfo represents timezone abbreviation information about a particular timezone.

func (*TzAbbreviationInfo) CountryCode

func (tai *TzAbbreviationInfo) CountryCode() string

CountryCode returns the ISO 3166-1 alpha-2 country code. It returns the empty string if there is no CountryCode.

func (*TzAbbreviationInfo) IsDST

func (tai *TzAbbreviationInfo) IsDST() bool

IsDST reports whether or not it is daylight savings time.

func (*TzAbbreviationInfo) Name

func (tai *TzAbbreviationInfo) Name() string

Name returns the time name.

func (*TzAbbreviationInfo) Offset

func (tai *TzAbbreviationInfo) Offset() int

Offset returns the time offset.

func (*TzAbbreviationInfo) OffsetHHMM

func (tai *TzAbbreviationInfo) OffsetHHMM() string

OffsetHHMM returns the time offset in (+/-)hh:mm format.

type TzInfo

type TzInfo struct {
	// contains filtered or unexported fields
}

TzInfo represents information about a particular timezone.

func (*TzInfo) CountryCode

func (ti *TzInfo) CountryCode() string

CountryCode returns the ISO 3166-1 alpha-2 country code. It returns the empty string if there is no CountryCode.

func (*TzInfo) DaylightOffset

func (ti *TzInfo) DaylightOffset() int

DaylightOffset returns the daylight saving time offset It returns the 0 if there is no daylight saving.

func (*TzInfo) DaylightOffsetHHMM

func (ti *TzInfo) DaylightOffsetHHMM() string

DaylightOffsetHHMM returns the daylight saving time offset in (+/-)hh:mm format. It returns the "+00:00" if there is no daylight saving.

func (*TzInfo) HasDST

func (ti *TzInfo) HasDST() bool

HasDST reports whether or not it has daylight savings time.

func (*TzInfo) IsDeprecated

func (ti *TzInfo) IsDeprecated() bool

IsDeprecated reports whether the timezone is deprecated.

func (*TzInfo) LastDST

func (ti *TzInfo) LastDST() int

LastDST returns the last year when there was daylight savings time. It returns the 0 if has never observed daylight savings.

func (*TzInfo) LinkTo

func (ti *TzInfo) LinkTo() string

LinkTo returns the source of the alias. It returns the empty string if there is no alias.

func (*TzInfo) LongDaylight

func (ti *TzInfo) LongDaylight() string

LongDaylight returns the daylight saving time name. It returns the empty string if there is no daylight saving time name.

func (*TzInfo) LongGeneric

func (ti *TzInfo) LongGeneric() string

LongGeneric returns the generic time name. It returns the empty string if there is no generic time name.

func (*TzInfo) LongStandard

func (ti *TzInfo) LongStandard() string

LongStandard returns the standard time name.

func (*TzInfo) ShortDaylight

func (ti *TzInfo) ShortDaylight() string

ShortDaylight returns the daylight saving timezone abbreviation. It returns the empty string if there is no daylight saving timezone abbreviation.

func (*TzInfo) ShortGeneric

func (ti *TzInfo) ShortGeneric() string

ShortGeneric returns the generic timezone abbreviation. It returns the empty string if there is no generic timezone abbreviation.

func (*TzInfo) ShortStandard

func (ti *TzInfo) ShortStandard() string

ShortStandard returns the standard timezone abbreviation.

func (*TzInfo) StandardOffset

func (ti *TzInfo) StandardOffset() int

StandardOffset returns the standard time offset

func (*TzInfo) StandardOffsetHHMM

func (ti *TzInfo) StandardOffsetHHMM() string

StandardOffsetHHMM returns the standard time offset in (+/-)hh:mm format.