fly

README

fly

A time and date toolbox for golang.

golang provides time library to deal with time, and it works well. fly aims to provide some convenient features for real-life time process.

Features

• humanize date/time output
• fully compatible with standard time library
• easy conversion between different timezones
• parse date/time in any user-defined format string
• abundant shortcuts for real-life date conversion, such as Tomorrow, Sunday, NextYear...
• access date ranges, floors and ceilings in all time frames(microsecond up to year)

Usage

Quick utc time and local time instance

When getting now time, users can easily access to local time and UTC time:

l := fly.Now()    // Now time with current location timezone if accessible
u := fly.UTCNow() // UTC timezone now

Compatible with standard time.Time

If you have a standard time.Time instance, it can be converted to fly struct:

now := time.Now()
f := fly.New(now)

Add duration the way you like

Need to travel in time(move time forward and backward)? Add method can help:

f := fly.Now()
f, err := f.Add(time.Duration(2*time.Hour))    // set time to 2 hours later
f, err := f.Add(time.Duration(30 * 24 * time.Hour)) // how about 30 days later
f, err := f.Add(time.Duration(100 * 12 * 30 * 24 * time.Hour)) // Around 100 years later, this is time travelling!

This is nothing, afterall calculating time and date is boring. See the magic:

f := fly.Now()
f, err := f.Add("2h")       // 2 hours later
f, err := f.Add("-2h30m")   // 2 and half hours in the past
f, err := f.Add("300s")    // 300 seconds later

Right now, fly supports ns, us, ms, s, m, h and their combinations. If the given parameter can not be parsed as time duration, error will be retured.

Humanize output

If you need to human readble time output, Humanize method is here to help:

f := f.Now()
f.Add("2h2m")
f.Humanize()
// 2 hours from now

Convert to different timezones

To returns the time of the location identified by given name. If name is "" or "UTC", To returns UTC time. If the name is "Local", To returns local time.

Otherwsie, To returns the time at location corresponding to IANA Time Zone, such as "America/New_York", or "Asia/Shanghai".

f := fly.Now()
t, err := f.To("Asia/Shanghai")

Inspiration

fly is heavily inspired by Arrow.

License

MIT License

Documentation

Index

• Constants
• type Duration
  • func ParseDuration(s string) (*Duration, error)
  • func Since(f Fly) *Duration
  • func (d *Duration) Hour() int
  • func (d *Duration) Hours() float64
  • func (d *Duration) Minutes() float64
  • func (d *Duration) Nanoseconds() int64
  • func (d *Duration) Seconds() float64
  • func (d *Duration) String() string
• type Fly
  • func New(t time.Time) *Fly
  • func Now() *Fly
  • func UTCNow() *Fly
  • func (f *Fly) Add(d interface{}) (*Fly, error)
  • func (f *Fly) Ceil(name string) (*Fly, error)
  • func (f *Fly) Floor(name string) (*Fly, error)
  • func (f *Fly) Humanize() string
  • func (f *Fly) Microsecond() int
  • func (f *Fly) Millisecond() int
  • func (f *Fly) Nanosecond() int
  • func (f *Fly) String() string
  • func (f *Fly) To(name string) (*Fly, error)
  • func (f *Fly) Zone() (string, int)

Constants

const (
	Nanosecond  time.Duration = 1
	Microsecond               = 1000 * Nanosecond
	Millisecond               = 1000 * Microsecond
	Second                    = 1000 * Millisecond
	Minute                    = 60 * Second
	Hour                      = 60 * Minute
	Day                       = 24 * Hour
	Week                      = 7 * Day
)

Types

type Duration

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

Duration represents the elapsed time between two instants as an int64 nanosecond count.

func ParseDuration

func ParseDuration(s string) (*Duration, error)

ParseDuration parses a duration string

func Since

func Since(f Fly) *Duration

Since returns the time elapsed since t.

func (*Duration) Hour

func (d *Duration) Hour() int

Hour returns the hour elapsed

func (*Duration) Hours

func (d *Duration) Hours() float64

Hours returns the duration as a floating point number of hours

func (*Duration) Minutes

func (d *Duration) Minutes() float64

Minutes returns the duration as a floating point number of minutes

func (*Duration) Nanoseconds

func (d *Duration) Nanoseconds() int64

Nanoseconds returns the duration as an integer nanosecond count

func (*Duration) Seconds

func (d *Duration) Seconds() float64

Seconds returns the duration as a floating point number of seconds

func (*Duration) String

func (d *Duration) String() string

String returns a string representing the duration in the form "72h3m0.5s".

type Fly

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

Fly is the main data struct

func New

func New(t time.Time) *Fly

New creates and returns a Fly struct from `time.Time` instance

func Now

func Now() *Fly

Now creates an instance with time set to now()

func UTCNow

func UTCNow() *Fly

UTCNow returns right now based on utc time zone

func (*Fly) Add

func (f *Fly) Add(d interface{}) (*Fly, error)

Add moves the time forward by certain mount of duration. Parameter can be either `time.Duration` instance or time string such as "300ms", "-1.5h", "2h 45m"(spaces are handled carefully), each with a decimal number and a time unit. Valid time units are "ns", "us", "ms", "s", "m", "h".

Note that you can move time backward by setting the value to negative, like `time.Duration(-5 * time.Hour)`, or `-5h`. If parameter can not be parsed as duration, an error will be returned

func (*Fly) Ceil

func (f *Fly) Ceil(name string) (*Fly, error)

Ceil returns the result of time ceil of certain unit. Parameter should be hour, minute, second, microsecond, If unit is negative, Ceil returns time unchanged

func (*Fly) Floor

func (f *Fly) Floor(name string) (*Fly, error)

Floor returns the result of time floor of certain unit. Parameter should be hour, minute, second, microsecond, If unit is negative, Floor returns time unchanged

func (*Fly) Humanize

func (f *Fly) Humanize() string

Humanize return the human readable date string

func (*Fly) Microsecond

func (f *Fly) Microsecond() int

Microsecond returns current time milliseconds value

func (*Fly) Millisecond

func (f *Fly) Millisecond() int

Millisecond returns current time milliseconds value

func (*Fly) Nanosecond

func (f *Fly) Nanosecond() int

Nanosecond returns current time milliseconds value Note: Nanosecond is in the range [0, 999999999], which includes seconds and microseconds.

func (*Fly) String

func (f *Fly) String() string

String returns the formatted output time

func (*Fly) To

func (f *Fly) To(name string) (*Fly, error)

To returns the time of the location identified by given name. If name is "" or "UTC", To returns UTC time. If the name is "Local", To returns local time. Otherwsie, To returns the time at location corresponding to IANA Time Zone, such as "America/New_York", or "Asia/Shanghai".

func (*Fly) Zone

func (f *Fly) Zone() (string, int)

Zone return the timezone name, and its offset from UTC