Golang time.UnixMilli Function

The time.UnixMilli function in Golang is part of the time package and is used to convert Unix time in milliseconds since the Unix epoch into a time.Time object. This function is particularly useful when working with timestamps that include millisecond precision, which is common in many systems that track time in milliseconds.

Table of Contents

1. Introduction
2. time.UnixMilli Function Syntax
3. Examples
   • Basic Usage
   • Converting Unix Millisecond Timestamps to time.Time
   • Handling Edge Cases
4. Real-World Use Case
5. Conclusion

Introduction

The time.UnixMilli function allows you to create a time.Time object from a Unix timestamp given in milliseconds. This is useful for interpreting or displaying Unix timestamps that require millisecond-level precision.

time.UnixMilli Function Syntax

The syntax for the time.UnixMilli function is as follows:

func UnixMilli(ms int64) Time

Parameters:

• ms: The number of milliseconds since the Unix epoch (January 1, 1970).

Returns:

• Time: A time.Time value representing the specified Unix timestamp in milliseconds.

Examples

Basic Usage

This example demonstrates how to use the time.UnixMilli function to convert a Unix timestamp in milliseconds into a time.Time object.

Example

package main

import (
	"fmt"
	"time"
)

func main() {
	// Define a Unix timestamp in milliseconds
	timestampMilli := int64(1691490000000) // Corresponds to 2023-08-08 12:00:00 UTC

	// Convert the Unix timestamp to a time.Time object
	t := time.UnixMilli(timestampMilli)

	// Print the converted time
	fmt.Println("Converted time:", t)
}

Output:

Converted time: 2023-08-08 12:00:00 +0000 UTC

Converting Unix Millisecond Timestamps to time.Time

This example shows how to convert multiple Unix millisecond timestamps into time.Time objects.

Example

package main

import (
	"fmt"
	"time"
)

func main() {
	// Define a slice of Unix timestamps in milliseconds
	timestamps := []int64{
		1625616000000, // 2021-07-07 00:00:00 UTC
		1657152000000, // 2022-07-07 00:00:00 UTC
		1688688000000, // 2023-07-07 00:00:00 UTC
	}

	// Convert each Unix millisecond timestamp to a time.Time object and print it
	for _, ts := range timestamps {
		t := time.UnixMilli(ts)
		fmt.Println("Converted time:", t)
	}
}

Output:

Converted time: 2021-07-07 00:00:00 +0000 UTC
Converted time: 2022-07-07 00:00:00 +0000 UTC
Converted time: 2023-07-07 00:00:00 +0000 UTC

Handling Edge Cases

This example demonstrates how the time.UnixMilli function handles edge cases, such as very large or very small Unix millisecond timestamps.

Example

package main

import (
	"fmt"
	"time"
)

func main() {
	// Define edge case Unix timestamps in milliseconds
	negativeTimestamp := int64(-62135596800000) // Corresponds to year 1
	largeTimestamp := int64(253402300799999)    // Corresponds to 9999-12-31 23:59:59.999 UTC

	// Convert the Unix timestamps to time.Time objects
	tNegative := time.UnixMilli(negativeTimestamp)
	tLarge := time.UnixMilli(largeTimestamp)

	// Print the converted times
	fmt.Println("Converted time for negative timestamp:", tNegative)
	fmt.Println("Converted time for large timestamp:", tLarge)
}

Output:

Converted time for negative timestamp: 0001-01-01 00:00:00 +0000 UTC
Converted time for large timestamp: 9999-12-31 23:59:59.999 +0000 UTC

Real-World Use Case

Converting Timestamps from APIs or Databases

In real-world applications, the time.UnixMilli function can be used to convert Unix timestamps in milliseconds from APIs, databases, or logs into human-readable dates.

Example: Parsing a Timestamp from a JSON Response

package main

import (
	"encoding/json"
	"fmt"
	"time"
)

// ExampleResponse represents a JSON response with a Unix millisecond timestamp
type ExampleResponse struct {
	Timestamp int64 `json:"timestamp"`
}

func main() {
	// Example JSON response with a Unix millisecond timestamp
	jsonResponse := `{"timestamp": 1691490000000}`

	// Unmarshal the JSON response into a struct
	var response ExampleResponse
	err := json.Unmarshal([]byte(jsonResponse), &response)
	if err != nil {
		fmt.Println("Error unmarshaling JSON:", err)
		return
	}

	// Convert the Unix millisecond timestamp to a time.Time object
	parsedTime := time.UnixMilli(response.Timestamp)

	// Print the parsed time
	fmt.Println("Parsed time from JSON:", parsedTime)
}

Output:

Parsed time from JSON: 2023-08-08 12:00:00 +0000 UTC

Conclusion

The time.UnixMilli function in Go is a practical tool for converting Unix timestamps in milliseconds into time.Time objects. Whether you’re working with timestamps from APIs, databases, or other systems, time.UnixMilli makes it easy to handle and interpret these timestamps with millisecond precision.