isodates

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 6, 2019 License: MIT Imports: 5 Imported by: 0

README

isodates

Go Report Card

The package isodates helps you convert ISO 8601 formatted date strings into actual time.Time{} instances. Currently, isodates supports the following formats:

  • Date (e.g. "2019-05-23")
  • Date-Time (e.g. "2019-05-23T04:44:33.999Z")
  • Month-Day (e.g. "--12-25")
  • Year-Month (e.g. "2019-04")
  • Week (e.g. "2019-W05")
  • Week-Day (e.g. "2019-W05-3")
Basic Usage

For starters, import isodates into your code:

import "github.com/robsignorelli/isodates"

Parsing inputs gives you the exact date components encoded in the string. These can usually be fed directly to time.Date() with the exception of week parsing. See the section on "Start/End Dates" to see how you can obtain a time.Time at the very first or last nanosecond of the parsed date/range in one step.

// Simple dates
year, month, day, err := isodates.ParseDate("2019-04-01")

// Month/day values
month, day, err := isodates.ParseMonthDay("--12-25")

// Year/month values
year, month, err := isodates.ParseYearMonth("2019-12")

// ISO Week numbers
year, week, err := isodates.ParseWeek("2019-W11")

// ISO Week numbers w/ day offset
year, week, day, err := isodates.ParseWeek("2019-W11-3")

// Date/time timestamps (already a time.Time)
dateTime, err := isodates.ParseDateTime("2019-03-04T16:04:44.45678Z")
Start/End Dates

Standard isodates parser functions just give you the raw components encoded in the input string. Normally you need to feed those to time.Date(...) manually. Most of the ParseXyz() functions, however, have a ParseXyzStart() and a ParseXyzEnd() variant that will return a fully-constructed time.Time representing the first and last nanosecond of the parsed range, respectively. These ranges are in UTC. If you need local times, see the next section.

These are a convenience so that you can easily build date/time ranges that encapsulate the entire block of time represented by the input.

// Jan 6, 2019 12:00:00AM - Jan 12, 2019 11:59:59PM
weekStart, err := isodates.ParseWeekStart("2019-W02")
weekEnd, err := isodates.ParseWeekEnd("2019-W02")

// Feb 1, 2000 12:00:00AM - Feb 29, 2000 11:59:59PM
febStart, err := isodates.ParseYearMonthStart("2000-02")
febEnd, err := isodates.ParseYearMonthEnd("2000-02")
Start/End Dates (Local Time)

All of the Start/End helpers have a variant ending with In that also takes a *time.Location. In these cases, the resulting date/time will be either midnight or 11:59:59pm in the specified time zone.

ny, _ := time.LoadLocation("America/New_York")

// Jan 6, 2019 12:00:00AM - Jan 12, 2019 11:59:59PM
weekStartNY, err := isodates.ParseWeekStartIn("2019-W02", ny)
weekEndNY, err := isodates.ParseWeekEndIn("2019-W02", ny)

// Feb 1, 2000 12:00:00AM - Feb 29, 2000 11:59:59PM
febStartNY, err := isodates.ParseYearMonthStartIn("2000-02", ny)
febEndNY, err := isodates.ParseYearMonthEndIn("2000-02", ny)
Motivation

While parsing ISO 8601 formatted dates is fairly general-purpose, my goal was to centralize the logic associated w/ parsing Date slots when building Alexa skills in Go/Lambda. When a user utters "what should I wear next week" the Alexa skills API will feed an ISO week string representing the range of next week. isodates tries to support all of the various date strings that will get thrown at you. The start/end helpers will make it easier for your to build date ranges from the raw slot data you received.

Documentation

Index

Examples

Constants

View Source 
const ZeroMonth = time.Month(0)

ZeroMonth is our 'no value' month that we return when the operation fails.

Variables

View Source 
var ZeroTime = time.Time{}

ZeroTime is our 'no value' time that we return when the operation fails.

Functions

func AlmostMidnight 

func AlmostMidnight(year int, month time.Month, day int, loc *time.Location) time.Time

AlmostMidnight creates a date/time instance in the given time zone that is exactly 11:59:59pm on the specified date.

func Midnight 

func Midnight(year int, month time.Month, day int, loc *time.Location) time.Time

Midnight creates a date/time instance in the given time zone that is exactly midnight on the specified date.

func ParseDate 

func ParseDate(input string) (year int, month time.Month, day int, err error)

ParseDate accepts an ISO-formatted year-month-day string (e.g. "2019-05-22") and returns the year/month/day it represents.

Example 
package main

import (
	"fmt"

	"github.com/robsignorelli/isodates"
)

func main() {
	year, month, day, err := isodates.ParseDate("2019-02-24")
	if err != nil {
		fmt.Printf("oops: %v\n", err)
	}
	fmt.Printf("Year=%d Month=%d Day=%d", year, month, day)

}

Output:
Year=2019 Month=2 Day=24

func ParseDateEnd 

func ParseDateEnd(input string) (time.Time, error)

ParseDateEnd accepts an ISO-formatted year-month-day string (e.g. "2019-05-22") and returns the given date set to the last nanosecond of 11:59pm in UTC.

func ParseDateEndIn 

func ParseDateEndIn(input string, loc *time.Location) (time.Time, error)

ParseDateEndIn accepts an ISO-formatted year-month-day string (e.g. "2019-05-22") and returns the given date set to the last nanosecond of 11:59pm in the specified location.

func ParseDateStart 

func ParseDateStart(input string) (time.Time, error)

ParseDateStart accepts an ISO-formatted year-month-day string (e.g. "2019-05-22") and returns the given date set to exactly midnight in UTC.

func ParseDateStartIn 

func ParseDateStartIn(input string, loc *time.Location) (time.Time, error)

ParseDateStartIn accepts an ISO-formatted year-month-day string (e.g. "2019-05-22") and returns the given date set to exactly midnight in the specified location.

func ParseDateTime 

func ParseDateTime(input string) (time.Time, error)

ParseDateTime accepts an ISO-formatted date/time string (e.g. "2019-05-22T12:33:53.045Z") and returns the exact date and time that it represents.

Example 
package main

import (
	"fmt"

	"github.com/robsignorelli/isodates"
)

func main() {
	date, err := isodates.ParseDateTime("2019-02-24T06:44:33Z")
	if err != nil {
		fmt.Printf("oops: %v\n", err)
	}
	fmt.Println(date.Format("Jan 2, 2006 3:04PM"))

}

Output:
Feb 24, 2019 6:44AM

func ParseMonthDay 

func ParseMonthDay(input string) (time.Month, int, error)

ParseMonthDay accepts an ISO-formatted month/day string (e.g. "--04-01" is April, 1) and returns the month and day that it represents.

Example 
package main

import (
	"fmt"

	"github.com/robsignorelli/isodates"
)

func main() {
	// Standard usage
	month, day, err := isodates.ParseMonthDay("--04-01")
	fmt.Println(fmt.Sprintf("%d %d %v", month, day, err == nil))

	// Automatic rollover to subsequent months
	month, day, err = isodates.ParseMonthDay("--01-34")
	fmt.Println(fmt.Sprintf("%d %d %v", month, day, err == nil))

}

Output:
4 1 true
2 3 true

func ParseMonthDayEnd 

func ParseMonthDayEnd(input string, year int) (time.Time, error)

ParseMonthDayEnd parses the month/day string (e.g. "--12-24") and returns a date/time at 11:59:59pm in the specified year. The resulting timestamp will be in UTC.

func ParseMonthDayEndIn 

func ParseMonthDayEndIn(input string, year int, loc *time.Location) (time.Time, error)

ParseMonthDayEndIn parses the month/day string (e.g. "--12-24") and returns a date/time at 11:59:59pm in the specified year. The resulting timestamp will be in the specified time zone.

func ParseMonthDayStart 

func ParseMonthDayStart(input string, year int) (time.Time, error)

ParseMonthDayStart parses the month/day string (e.g. "--12-24") and returns a date/time at midnight in the specified year. The resulting timestamp will be in UTC.

func ParseMonthDayStartIn 

func ParseMonthDayStartIn(input string, year int, loc *time.Location) (time.Time, error)

ParseMonthDayStartIn parses the month/day string (e.g. "--12-24") and returns a date/time at midnight in the specified year. The resulting timestamp will be in specified time zone.

func ParseWeek 

func ParseWeek(input string) (year int, week int, err error)

ParseWeek accepts an ISO-formatted year/week string (e.g. "2019-W04") and returns the year and week number that it represents.

Example 
package main

import (
	"fmt"

	"github.com/robsignorelli/isodates"
)

func main() {
	year, weekNumber, err := isodates.ParseWeek("2019-W02")
	fmt.Println(fmt.Sprintf("%d %d %v", year, weekNumber, err == nil))

	// We don't support months outside of 1-53
	year, weekNumber, err = isodates.ParseWeek("2019-W72")
	fmt.Println(fmt.Sprintf("%d %d %v", year, weekNumber, err == nil))

}

Output:
2019 2 true
0 0 false

func ParseWeekDay 

func ParseWeekDay(input string) (year int, weekNum int, day int, err error)

ParseWeekDay extracts all 3 numeric components from an ISO Week-Day string (e.g. "2019-W02-3").

Example 
package main

import (
	"fmt"

	"github.com/robsignorelli/isodates"
)

func main() {
	date, err := isodates.ParseWeekDayStart("2019-W02-2")
	if err != nil {
		fmt.Printf("oops: %v\n", err)
	}
	fmt.Println(date.Format("Jan 2, 2006"))

}

Output:
Jan 8, 2019

func ParseWeekDayEnd 

func ParseWeekDayEnd(input string) (time.Time, error)

ParseWeekDayEnd accepts an ISO-formatted year/week/day string (e.g. "2019-W04-3") and returns the exact date that it represents. The resulting date/time will be at 11:59:59pm in UTC.

func ParseWeekDayEndIn 

func ParseWeekDayEndIn(input string, loc *time.Location) (time.Time, error)

ParseWeekDayEndIn accepts an ISO-formatted year/week/day string (e.g. "2019-W04-3") and returns the exact date that it represents. The resulting date/time will be at 11:59:59pm in the given time zone.

func ParseWeekDayStart 

func ParseWeekDayStart(input string) (time.Time, error)

ParseWeekDayStart accepts an ISO-formatted year/week/day string (e.g. "2019-W04-3") and returns the exact date that it represents. The resulting date/time will be at midnight in UTC.

func ParseWeekDayStartIn 

func ParseWeekDayStartIn(input string, loc *time.Location) (time.Time, error)

ParseWeekDayStartIn accepts an ISO-formatted year/week/day string (e.g. "2019-W04-3") and returns the exact date that it represents. The resulting date/time will be at midnight in the given time zone.

func ParseWeekEnd 

func ParseWeekEnd(input string) (time.Time, error)

ParseWeekEnd returns 11:59:59pm (one nanosecond before midnight) on Sunday of the specified ISO week string. The resulting date/time will be in UTC. If you would like this to be almost-midnight of some local time, use ParseWeekEndIn.

func ParseWeekEndIn 

func ParseWeekEndIn(input string, loc *time.Location) (time.Time, error)

ParseWeekEndIn returns 11:59:59pm (one nanosecond before midnight) on Sunday of the specified ISO week string. This will be in the local time of the specified location.

func ParseWeekStart 

func ParseWeekStart(input string) (time.Time, error)

ParseWeekStart returns midnight on Monday of the specified ISO week string. The resulting date/time will be in UTC. If you would like this to be midnight of some local time, use ParseWeekStartIn.

func ParseWeekStartIn 

func ParseWeekStartIn(input string, loc *time.Location) (time.Time, error)

ParseWeekStartIn returns midnight on Monday of the specified ISO week string. This will be in the local time of the specified location.

func ParseYearMonth 

func ParseYearMonth(input string) (int, time.Month, error)

ParseYearMonth accepts an ISO string such as "2019-04" and returns the individual date components for the year and month (e.g. 2019 and time.April). We also support the variant where you can prefix the year with either "+" or "-".

Example 
package main

import (
	"fmt"

	"github.com/robsignorelli/isodates"
)

func main() {
	year, month, err := isodates.ParseYearMonth("2019-01")
	fmt.Println(fmt.Sprintf("%d %d %v", year, month, err == nil))

}

Output:
2019 1 true

func ParseYearMonthEnd 

func ParseYearMonthEnd(input string) (time.Time, error)

ParseYearMonthEnd returns the last day of the year/month for the parsed input. The resulting date will be at 11:59:59pm in UTC.

func ParseYearMonthEndIn 

func ParseYearMonthEndIn(input string, loc *time.Location) (time.Time, error)

ParseYearMonthEndIn returns the last day of the year/month for the parsed input. The resulting date will be at 11:59:59pm in the specified time zone.

func ParseYearMonthStart 

func ParseYearMonthStart(input string) (time.Time, error)

ParseYearMonthStart returns the first day of the year/month for the parsed input. The resulting date will be at midnight in UTC.

func ParseYearMonthStartIn 

func ParseYearMonthStartIn(input string, loc *time.Location) (time.Time, error)

ParseYearMonthStartIn returns the first day of the year/month for the parsed input. The resulting date will be at midnight in the specified time zone.

Types

This section is empty.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.