isoweek

README

isoweek

The Go package isoweek calculates a starting date and time of ISO 8601 week.

ISO 8601 standard defines the common week number system used in Europe and many other countries. Monday is the first day of a week.

The Go standard library time package has ISOWeek function for getting ISO 8601 week number of a given time.Time, but there is no reverse functionality for getting a date from a week number. This package implements that.

Invalid input is silently accepted. There is a separate Validate function if week number validation is needed.

There are also functions for working with Julian day numbers. Using Julian day numbers is often the easiest and fastest way to do date calculations.

This package does not work with the "traditional" week system used in US/Canada/Japan/etc. (weeks starting on Sundays). However the Julian day number functions may be still useful.

Documentation

https://pkg.go.dev/github.com/snabb/isoweek

Examples

Using weeks with Go standard time.Time

A simple example which gets the starting time of the 1st week of 1985:

	t := isoweek.StartTime(1985, 1, time.UTC)
	fmt.Println(t)
	// Output: 1984-12-31 00:00:00 +0000 UTC

The returned time may be within a previous year as can be seen above.

The AddDate function in Go standard library time package can be used for getting the Time at the end of the week or for iterating through weeks:

	t = t.AddDate(0, 0, 7)
	fmt.Println(t)
	// Output: 1985-01-07 00:00:00 +0000 UTC

	wyear, week := t.ISOWeek()
	fmt.Println(wyear, week)
	// Output: 1985 2

Using weeks, dates and Julian day numbers

The same as above without using Go standard library time package:

	y, m, d := isoweek.StartDate(1985, 1)
	fmt.Println(y, m, d)
	// Output: 1984 December 31

	jdn := isoweek.DateToJulian(y, m, d)
	jdn = jdn + 7 // next week
	y, m, d = isoweek.JulianToDate(jdn)
	fmt.Println(y, m, d)
	// Output: 1985 January 7

	wyear, week := isoweek.FromDate(y, m, d)
	fmt.Println(wyear, week)
	// Output: 1985 2

Repository

https://github.com/snabb/isoweek

License

MIT

Documentation

Overview

Package isoweek calculates a starting date and time of ISO 8601 week.

ISO 8601 standard defines the common week number system used in Europe and many other countries. Monday is the first day of a week.

The Go standard library time package has time.Time.ISOWeek function for getting ISO 8601 week number of a given time.Time, but there is no reverse functionality for getting a date from a week number. This package implements that.

Invalid input is silently accepted. There is a separate Validate function if week number validation is needed.

There are also functions for working with Julian day numbers. Using Julian day numbers is often the easiest and fastest way to do date calculations.

This package does not work with the "traditional" week system used in US/Canada/Japan/etc. (weeks starting on Sundays). However the Julian day number functions may be still useful.

Index

• func DateToJulian(year int, month time.Month, day int) (jdn int)
• func FromDate(year int, month time.Month, day int) (wyear, week int)
• func ISOWeekday(year int, month time.Month, day int) (weekday int)
• func JulianToDate(jdn int) (year int, month time.Month, day int)
• func StartDate(wyear, week int) (year int, month time.Month, day int)
• func StartTime(wyear, week int, loc *time.Location) (start time.Time)
• func Validate(wyear, week int) (ok bool)

Examples

• DateToJulian
• FromDate
• ISOWeekday
• JulianToDate
• StartDate
• StartTime
• Validate

Functions

func DateToJulian

func DateToJulian(year int, month time.Month, day int) (jdn int)

DateToJulian converts a date to a Julian day number.

Example

package main

import (
	"fmt"

	"github.com/snabb/isoweek"
)

func main() {
	fmt.Println(isoweek.DateToJulian(2006, 1, 2))
}

Output:

2453738

func FromDate

func FromDate(year int, month time.Month, day int) (wyear, week int)

FromDate returns ISO 8601 week number of a date.

Example

package main

import (
	"fmt"

	"github.com/snabb/isoweek"
)

func main() {
	fmt.Println(isoweek.FromDate(1984, 1, 1))
}

Output:

1983 52

func ISOWeekday

func ISOWeekday(year int, month time.Month, day int) (weekday int)

ISOWeekday returns the ISO 8601 weekday number of given day. (1 = Mon, 2 = Tue,.. 7 = Sun)

This is different from Go's standard time.Weekday.

Example

package main

import (
	"fmt"

	"github.com/snabb/isoweek"
)

func main() {
	fmt.Println(isoweek.ISOWeekday(1984, 1, 1))
}

Output:

7

func JulianToDate

func JulianToDate(jdn int) (year int, month time.Month, day int)

JulianToDate converts a Julian day number to a date.

Example

package main

import (
	"fmt"

	"github.com/snabb/isoweek"
)

func main() {
	fmt.Println(isoweek.JulianToDate(2453738))
}

Output:

2006 January 2

func StartDate

func StartDate(wyear, week int) (year int, month time.Month, day int)

StartDate returns the starting date (Monday) of the given ISO 8601 week.

Example

package main

import (
	"fmt"

	"github.com/snabb/isoweek"
)

func main() {
	y, m, d := isoweek.StartDate(2000, 1)
	fmt.Println(d, m, y)
}

Output:

3 January 2000

func StartTime

func StartTime(wyear, week int, loc *time.Location) (start time.Time)

StartTime returns the starting time (Monday 00:00) of the given ISO 8601 week.

Example

package main

import (
	"fmt"
	"time"

	"github.com/snabb/isoweek"
)

func main() {
	t := isoweek.StartTime(1985, 1, time.UTC)
	fmt.Println(t)
}

Output:

1984-12-31 00:00:00 +0000 UTC

func Validate

func Validate(wyear, week int) (ok bool)

Validate checks if a week number is valid. Returns true if it is valid.

Example

package main

import (
	"fmt"

	"github.com/snabb/isoweek"
)

func main() {
	fmt.Println(
		isoweek.Validate(2015, 52), isoweek.Validate(2015, 53),
		isoweek.Validate(2015, 54), isoweek.Validate(2016, 0),
		isoweek.Validate(2016, 1))
	fmt.Println(
		isoweek.Validate(2016, 52), isoweek.Validate(2016, 53),
		isoweek.Validate(2016, 54), isoweek.Validate(2017, 0),
		isoweek.Validate(2017, 1))
}

Output:

true true false false true
true false false false true