Time

Programs often handle times and dates. They read strings in from files, parse them, test them for validity. Times are changed.

With the time package, we access many usable funcs on the Time struct. These methods are reusable and tested—this is a clear advantage.

Now example

Let us start with this simple example. We import the "time" package in the import block at the top. We invoke the Now method from the time package. It returns a struct.

package main

import (
    "fmt"
    "time"
)

func main() {
    // Get the current time.
    t := time.Now()
    fmt.Println(t)

    // Print year, month and day of the current time.
    fmt.Println(t.Year())
    fmt.Println(t.Month())
    fmt.Println(t.Day())
}
2017-02-21 15:08:12.0658324 -0800 PST
2017
February
21

Parse

With this func we convert a string to a Time struct. Parse receives two strings: a form string and the value we are parsing.

package main

import (
    "fmt"
    "time"
)

func main() {
    // This is the value we are trying to parse.
    value := "January 28, 2015"

    // The form must be January 2,2006.
    form := "January 2, 2006"

    // Parse the string according to the form.
    t, _ := time.Parse(form, value)
    fmt.Println(t)
}
2015-01-28 00:00:00 +0000 UTC

Sub, Duration

This example combines many time concepts. It uses Now() twice to measure the time required to run a piece of code. Then it uses Sub() to get a duration.

package main

import (
    "fmt"
    "time"
)

func main() {

    t0 := time.Now()

    // Do a slow operation.
    count := 0
    for i := 0; i < 100000; i++ {
        for x := 0; x < i; x++ {
            count++
        }
    }

    t1 := time.Now()

    // Display result.
    fmt.Println(count)

    // Get duration.
    d := t1.Sub(t0)
    fmt.Println("Duration", d)
    // Get seconds from duration.
    s := d.Seconds()
    fmt.Println("Seconds", s)
    // Get minutes from duration.
    m := d.Minutes()
    fmt.Println("Minutes", m)
}
4999950000
Duration 1.8052613s
Seconds 1.8052613000000002
Minutes 0.030087688333333334

Create Time, time.Date

To create a Time from ints (like the year, month and day) we call the time.Date func. The time.Date func returns a new Time instance.

package main

import (
    "fmt"
    "time"
)

func main() {
    // Create a Date in 2006.
    t := time.Date(2006, 1, 1, 12, 0, 0, 0, time.UTC)
    fmt.Println(t)
}
2006-01-01 12:00:00 +0000 UTC

Before, After

Does one Time come before another? With the Before() func we can determine temporal order. And with After(), we can test whether one time comes after another.

package main

import (
    "fmt"
    "time"
)

func main() {
    // T1 is a time earlier than t2.
    t1 := time.Date(2000, 1, 1, 12, 0, 0, 0, time.UTC)
    t2 := time.Date(2015, 1, 1, 12, 0, 0, 0, time.UTC)

    // This is true: the first time is before the second.
    if t1.Before(t2) {
        fmt.Println(true)
    }

    // This is true.
    if t2.After(t1) {
        fmt.Println(true)
    }

    // This returns false.
    fmt.Println(t1.After(t2))
}
true
true
false

Equal

With the Equal() func we see if two times indicate the same instant. Equal() adjusts for Locations. With the "==" operator, the Locations must also be equal.

package main

import (
    "fmt"
    "time"
)

func main() {
    // These times are created with equal values.
    t1 := time.Date(2015, 1, 1, 12, 0, 0, 0, time.UTC)
    t2 := time.Date(2015, 1, 1, 12, 0, 0, 0, time.UTC)

    // Compare times.
    if t1 == t2 {
        fmt.Println("Times are equal")
    }
    // Equal adjusts for locations.
    if t1.Equal(t2) {
        fmt.Println(true)
    }
}
Times are equal
true

Format

With Format we convert a Date into a string. As with Parse, we use the special date Jan 2, 2006 to indicate the formatting.

package main

import (
    "fmt"
    "time"
)

func main() {
    // This date is used to indicate the layout.
    const layout = "Jan 2, 2006"
    // Format Now with the layout const.
    t := time.Now()
    res := t.Format(layout)
    fmt.Println(res)
}
Jul 27, 2015

Since

The Since() func is an easy way to compute the elapsed hours from a point in time. We do not need to use Now and Sub separately—Since() includes this logic for us.

package main

import (
    "fmt"
    "time"
)

func main() {

    // Part 1: get first day of 2018.
    t := time.Date(2018, 1, 1, 0, 0, 0, 0, time.UTC)
    fmt.Println(t)

    // Part 2: compute days since first day of 2018.
    timePassed := time.Since(t)

    // Part 3: display result.
    fmt.Println("Days passed:", timePassed.Hours() / 24)
}
2018-01-01 00:00:00 +0000 UTC
Days passed: 728.0187105963055

Benchmarks

The time module can be used to take benchmarks. We use Sub to get a difference (a duration) between two times returned by Now calls.

package main

import (
	"fmt"
	"time"
)

const MAX = 10000000

func main() {
    t0 := time.Now()

    // Version 1: describe version.
    for i := 0; i < MAX; i++ {
    }

    t1 := time.Now()

    // Version 2: describe version.
    for i := 0; i < MAX; i++ {
    }

    t2 := time.Now()
    // Benchmark results.
    fmt.Println(t1.Sub(t0))
    fmt.Println(t2.Sub(t1))
}
3.265ms
5.881125ms

With the Time struct, we gain a way to represent a point in time (a Date). And with the methods in time, we can manipulate it. We cannot go back in time, but we can represent it.