hdate

package module
v1.2.1 Latest Latest
Warning

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

 Go to latest Published: Jul 20, 2025 License: GPL-2.0 Imports: 8 Imported by: 20

README

hdate

Build Status Go Report Card GoDoc

Hebcal's hdate package converts between Hebrew and Gregorian dates.

It also includes functions for calculating personal anniversaries (Yahrzeit, Birthday) according to the Hebrew calendar.

Internally, it uses R.D. (Rata Die) day numbers.

Example

package main

import (
	"fmt"
	"time"

	"github.com/hebcal/hdate"
)

func main() {
	hd := hdate.New(5765, hdate.Adar2, 22)
	year, month, day := hd.Greg()
	fmt.Println(year, month, day)
	// Output: 2005 April 2

	hd2 := hdate.FromGregorian(2008, time.November, 13)
	fmt.Println(hd2)
	// Output: 15 Cheshvan 5769
}

Documentation

Overview

Hebcal's hdate package converts between Hebrew and Gregorian dates.

It also includes functions for calculating personal anniversaries (Yahrzeit, Birthday) according to the Hebrew calendar.

See also https://en.wikipedia.org/wiki/Rata_Die

Index

Examples

Constants

View Source 
const Epoch int64 = -1373428

Epoch is the Hebrew Calendar epoch using R.D. Rata Die numbers

Variables

This section is empty.

Functions

func DayOnOrBefore 

func DayOnOrBefore(dayOfWeek time.Weekday, rataDie int64) int64

Applying DayOnOrBefore to d+6 gives us the dayOfWeek on or after an absolute day rataDie.

Similarly, applying it to d+3 gives the dayOfWeek nearest to rataDie, applying it to d-1 gives the dayOfWeek previous to rataDie, and applying it to d+7 gives the dayOfWeek following rataDie.

func DaysInMonth 

func DaysInMonth(month HMonth, year int) int

DaysInMonth returns the number of days in Hebrew month in a given year (29 or 30).

Example 
package main

import (
	"fmt"

	"github.com/hebcal/hdate"
)

func main() {
	days := hdate.DaysInMonth(hdate.Kislev, 5783)
	fmt.Println(days)
}

Output:

30

func DaysInYear 

func DaysInYear(year int) int

DaysInYear computes the number of days in the Hebrew year.

The year can be 353, 354, 355, 383, 384 or 385 days long.

Example 
package main

import (
	"fmt"

	"github.com/hebcal/hdate"
)

func main() {
	days := hdate.DaysInYear(5782)
	fmt.Println(days)
}

Output:

384

func IsLeapYear 

func IsLeapYear(year int) bool

IsLeapYear returns true if Hebrew year is a leap year.

func LongCheshvan 

func LongCheshvan(year int) bool

LongCheshvan returns true if Cheshvan is long (30 days) in Hebrew year.

func MonthsInYear 

func MonthsInYear(year int) int

MonthsInYear returns the number of months in this Hebrew year (either 12 or 13 depending on leap year).

func ShortKislev 

func ShortKislev(year int) bool

ShortKislev returns true if Kislev is short (29 days) in Hebrew year.

func ToRD 

func ToRD(year int, month HMonth, day int) int64

ToRD converts Hebrew date to R.D. (Rata Die) fixed days. R.D. 1 is the imaginary date Monday, January 1, 1 on the Gregorian Calendar.

Note also that R.D. = Julian Date − 1,721,424.5

https://en.wikipedia.org/wiki/Rata_Die

Example 
package main

import (
	"fmt"

	"github.com/hebcal/hdate"
)

func main() {
	rataDie := hdate.ToRD(5769, hdate.Cheshvan, 15)
	fmt.Println(rataDie)
}

Output:

733359

Types

type HDate 

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

HDate represents a Hebrew date.

To keep things simple, HDate represents just a day, month, and year.

Although Hebrew dates begin at sunset, HDate does not attempt to represent any concept of the time of day. For halachic times, see the Zmanim interface.

func FromGregorian 

func FromGregorian(year int, month time.Month, day int) HDate

Creates an HDate from Gregorian year, month and day.

Example

***** HDate **** 

package main

import (
	"fmt"
	"time"

	"github.com/hebcal/hdate"
)

func main() {
	hd := hdate.FromGregorian(2008, time.November, 13)
	fmt.Println(hd)
}

Output:

15 Cheshvan 5769

func FromProlepticGregorian added in v1.2.0 

func FromProlepticGregorian(year int, month time.Month, day int) HDate

Creates an HDate from Gregorian year, month and day, using the Proleptic Gregorian calendar.

func FromRD 

func FromRD(rataDie int64) HDate

Converts absolute Rata Die days to Hebrew date.

Panics if rataDie is before the Hebrew epoch.

Example 
package main

import (
	"fmt"

	"github.com/hebcal/hdate"
)

func main() {
	hd := hdate.FromRD(733359)
	fmt.Println(hd)
}

Output:

15 Cheshvan 5769

func FromTime 

func FromTime(t time.Time) HDate

Creates an HDate from a Time object. Hours, minutes and seconds are ignored.

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hebcal/hdate"
)

func main() {
	t := time.Date(2008, time.November, 13, 0, 0, 0, 0, time.UTC)
	hd := hdate.FromTime(t)
	fmt.Println(hd)
}

Output:

15 Cheshvan 5769

func GetBirthdayOrAnniversary 

func GetBirthdayOrAnniversary(hyear int, date HDate) (HDate, error)

GetBirthdayOrAnniversary calculates a birthday or anniversary (non-yahrzeit). hyear must be after original date of anniversary. Returns an error when requested year precedes or is same as original year.

Hebcal uses the algorithm defined in "Calendrical Calculations" by Edward M. Reingold and Nachum Dershowitz.

The birthday of someone born in Adar of an ordinary year or Adar II of a leap year is also always in the last month of the year, be that Adar or Adar II. The birthday in an ordinary year of someone born during the first 29 days of Adar I in a leap year is on the corresponding day of Adar; in a leap year, the birthday occurs in Adar I, as expected.

Someone born on the thirtieth day of Marcheshvan, Kislev, or Adar I has his birthday postponed until the first of the following month in years where that day does not occur. [Calendrical Calculations p. 111]

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hebcal/hdate"
)

func main() {
	hd := hdate.FromGregorian(2014, time.March, 2)
	fmt.Println(hd)
	yahrzeit, _ := hdate.GetBirthdayOrAnniversary(5783, hd)
	fmt.Println(yahrzeit)
}

Output:

30 Adar I 5774
1 Nisan 5783

func GetYahrzeit 

func GetYahrzeit(hyear int, date HDate) (HDate, error)

GetYahrzeit calculates yahrzeit. hyear must be after original date of death. Returns an error when requested year precedes or is same as original year.

Hebcal uses the algorithm defined in "Calendrical Calculations" by Edward M. Reingold and Nachum Dershowitz.

The customary anniversary date of a death is more complicated and depends also on the character of the year in which the first anniversary occurs. There are several cases:

  • If the date of death is Marcheshvan 30, the anniversary in general depends on the first anniversary; if that first anniversary was not Marcheshvan 30, use the day before Kislev 1.
  • If the date of death is Kislev 30, the anniversary in general again depends on the first anniversary — if that was not Kislev 30, use the day before Tevet 1.
  • If the date of death is Adar II, the anniversary is the same day in the last month of the Hebrew year (Adar or Adar II).
  • If the date of death is Adar I 30, the anniversary in a Hebrew year that is not a leap year (in which Adar only has 29 days) is the last day in Shevat.
  • In all other cases, use the normal (that is, same month number) anniversary of the date of death. [Calendrical Calculations p. 113]
Example 
package main

import (
	"fmt"
	"time"

	"github.com/hebcal/hdate"
)

func main() {
	hd := hdate.FromGregorian(2014, time.March, 2)
	fmt.Println(hd)
	yahrzeit, _ := hdate.GetYahrzeit(5783, hd)
	fmt.Println(yahrzeit)
}

Output:

30 Adar I 5774
30 Sh'vat 5783

func New 

func New(year int, month HMonth, day int) HDate

Creates a new HDate from year, Hebrew month, and day of month.

Panics if Hebrew year is less than 1, if Hebrew month is not in the range [Tishrei..Adar2], or if Hebrew day is not in the range [1..30]

Example 
package main

import (
	"fmt"

	"github.com/hebcal/hdate"
)

func main() {
	hd := hdate.New(5782, hdate.Nisan, 30)
	fmt.Println(hd)
}

Output:

30 Nisan 5782

func (*HDate) Abs 

func (hd *HDate) Abs() int64

Converts Hebrew date to R.D. (Rata Die) fixed days.

R.D. 1 is the imaginary date Monday, January 1, 1 on the Gregorian Calendar.

Example 
package main

import (
	"fmt"

	"github.com/hebcal/hdate"
)

func main() {
	hd := hdate.New(5765, hdate.Adar2, 22)
	rataDie := hd.Abs()
	fmt.Println(rataDie)
}

Output:

732038

func (HDate) After 

func (hd HDate) After(dayOfWeek time.Weekday) HDate

After returns an HDate corresponding to the dayOfWeek after the Hebrew date specified by hd.

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hebcal/hdate"
)

func main() {
	orig := hdate.FromGregorian(2014, time.February, 19)
	hd := orig.After(time.Saturday)
	fmt.Println(hd.Gregorian().Format(time.RFC1123))
	orig = hdate.FromGregorian(2014, time.February, 22)
	hd = orig.After(time.Saturday)
	fmt.Println(hd.Gregorian().Format(time.RFC1123))
	orig = hdate.FromGregorian(2014, time.February, 23)
	hd = orig.After(time.Saturday)
	fmt.Println(hd.Gregorian().Format(time.RFC1123))
}

Output:

Sat, 22 Feb 2014 00:00:00 UTC
Sat, 01 Mar 2014 00:00:00 UTC
Sat, 01 Mar 2014 00:00:00 UTC

func (HDate) Before 

func (hd HDate) Before(dayOfWeek time.Weekday) HDate

Before returns an HDate representing the dayOfWeek before the Hebrew date specified by hd.

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hebcal/hdate"
)

func main() {
	orig := hdate.FromGregorian(2014, time.February, 19)
	hd := orig.Before(time.Saturday)
	fmt.Println(hd.Gregorian().Format(time.RFC1123))
}

Output:

Sat, 15 Feb 2014 00:00:00 UTC

func (HDate) Day 

func (hd HDate) Day() int

Day returns the day of month (1-30) of hd.

Example 
package main

import (
	"fmt"

	"github.com/hebcal/hdate"
)

func main() {
	hd := hdate.New(5769, hdate.Cheshvan, 15)
	fmt.Println(hd.Day())
}

Output:

15

func (HDate) DaysInMonth 

func (hd HDate) DaysInMonth() int

Returns the number of days in this date's month (29 or 30).

Example 
package main

import (
	"fmt"

	"github.com/hebcal/hdate"
)

func main() {
	hd := hdate.New(5765, hdate.Adar2, 22)
	days := hd.DaysInMonth()
	fmt.Println(days)
}

Output:

29

func (HDate) Greg 

func (hd HDate) Greg() (int, time.Month, int)

Converts this Hebrew Date to Gregorian year, month and day.

Example 
package main

import (
	"fmt"

	"github.com/hebcal/hdate"
)

func main() {
	hd := hdate.New(5765, hdate.Adar2, 22)
	year, month, day := hd.Greg()
	fmt.Println(year, month, day)
}

Output:

2005 April 2

func (HDate) Gregorian 

func (hd HDate) Gregorian() time.Time

Converts this Hebrew Date to a Gregorian time object.

Hours, minutes and seconds are set to 0, and timezone is set to UTC.

Example 
package main

import (
	"fmt"

	"github.com/hebcal/hdate"
)

func main() {
	hd := hdate.New(5765, hdate.Adar2, 22)
	t := hd.Gregorian()
	fmt.Println(t)
}

Output:

2005-04-02 00:00:00 +0000 UTC

func (HDate) IsLeapYear 

func (hd HDate) IsLeapYear() bool

IsLeapYear returns true if this HDate occurs during a Hebrew leap year.

Example 
package main

import (
	"fmt"

	"github.com/hebcal/hdate"
)

func main() {
	hd := hdate.New(5765, hdate.Adar2, 22)
	leap := hd.IsLeapYear()
	fmt.Println(leap)
}

Output:

true

func (HDate) MarshalJSON 

func (hd HDate) MarshalJSON() ([]byte, error)

func (HDate) Month 

func (hd HDate) Month() HMonth

Month returns the Hebrew month of hd.

Example 
package main

import (
	"fmt"

	"github.com/hebcal/hdate"
)

func main() {
	hd := hdate.New(5769, hdate.Cheshvan, 15)
	fmt.Println(hd.Month())
}

Output:

Cheshvan

func (HDate) MonthName 

func (hd HDate) MonthName(locale string) string

MonthName returns a string representation of the month name.

If locale is "he", returns Hebrew (e.g. "תִשְׁרֵי", "שְׁבָט", "אַדָר ב׳")

Otherwise returns an English transliteration (e.g. "Tishrei", "Sh'vat", "Adar II").

Example 
package main

import (
	"fmt"

	"github.com/hebcal/hdate"
)

func main() {
	hd := hdate.New(5765, hdate.Adar2, 22)
	fmt.Println(hd.MonthName("en"))
	fmt.Println(hd.MonthName("he"))
	fmt.Println(hd.MonthName("he-x-NoNikud"))
}

Output:

Adar II
אַדָר ב׳
אדר ב׳

func (HDate) Nearest 

func (hd HDate) Nearest(dayOfWeek time.Weekday) HDate

Nearest returns an HDate representing the nearest dayOfWeek to the Hebrew date specified by hd.

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hebcal/hdate"
)

func main() {
	orig := hdate.FromGregorian(2014, time.February, 19)
	hd := orig.Nearest(time.Saturday)
	fmt.Println(hd.Gregorian().Format(time.RFC1123))
	orig = hdate.FromGregorian(2014, time.February, 18)
	hd = orig.Nearest(time.Saturday)
	fmt.Println(hd.Gregorian().Format(time.RFC1123))
}

Output:

Sat, 22 Feb 2014 00:00:00 UTC
Sat, 15 Feb 2014 00:00:00 UTC

func (HDate) Next 

func (hd HDate) Next() HDate

Next returns the next Hebrew date.

Example 
package main

import (
	"fmt"

	"github.com/hebcal/hdate"
)

func main() {
	orig := hdate.New(5782, hdate.Nisan, 30)
	hd := orig.Next()
	fmt.Println(hd)
}

Output:

1 Iyyar 5782

func (HDate) OnOrAfter 

func (hd HDate) OnOrAfter(dayOfWeek time.Weekday) HDate

OnOrAfter returns an HDate corresponding to the dayOfWeek on or after the Hebrew date specified by hd.

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hebcal/hdate"
)

func main() {
	orig := hdate.FromGregorian(2014, time.February, 19)
	hd := orig.OnOrAfter(time.Saturday)
	fmt.Println(hd.Gregorian().Format(time.RFC1123))
	orig = hdate.FromGregorian(2014, time.February, 22)
	hd = orig.OnOrAfter(time.Saturday)
	fmt.Println(hd.Gregorian().Format(time.RFC1123))
	orig = hdate.FromGregorian(2014, time.February, 23)
	hd = orig.OnOrAfter(time.Saturday)
	fmt.Println(hd.Gregorian().Format(time.RFC1123))
}

Output:

Sat, 22 Feb 2014 00:00:00 UTC
Sat, 22 Feb 2014 00:00:00 UTC
Sat, 01 Mar 2014 00:00:00 UTC

func (HDate) OnOrBefore 

func (hd HDate) OnOrBefore(dayOfWeek time.Weekday) HDate

OnOrBefore returns an HDate corresponding to the dayOfWeek on or before the Hebrew date specified by hd.

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hebcal/hdate"
)

func main() {
	orig := hdate.FromGregorian(2014, time.February, 19)
	hd := orig.OnOrBefore(time.Saturday)
	fmt.Println(hd.Gregorian().Format(time.RFC1123))
	orig = hdate.FromGregorian(2014, time.February, 22)
	hd = orig.OnOrBefore(time.Saturday)
	fmt.Println(hd.Gregorian().Format(time.RFC1123))
	orig = hdate.FromGregorian(2014, time.February, 23)
	hd = orig.OnOrBefore(time.Saturday)
	fmt.Println(hd.Gregorian().Format(time.RFC1123))
}

Output:

Sat, 15 Feb 2014 00:00:00 UTC
Sat, 22 Feb 2014 00:00:00 UTC
Sat, 22 Feb 2014 00:00:00 UTC

func (HDate) Prev 

func (hd HDate) Prev() HDate

Prev returns the previous Hebrew date.

Example 
package main

import (
	"fmt"

	"github.com/hebcal/hdate"
)

func main() {
	orig := hdate.New(5782, hdate.Tishrei, 1)
	hd := orig.Prev()
	fmt.Println(hd)
}

Output:

29 Elul 5781

func (HDate) ProlepticGreg added in v1.2.0 

func (hd HDate) ProlepticGreg() (int, time.Month, int)

Converts this Hebrew Date to Proleptic Gregorian year, month and day.

func (HDate) String 

func (hd HDate) String() string

String returns a string representation of the Hebrew date in English transliteration (e.g. "15 Cheshvan 5769").

Example 
package main

import (
	"fmt"

	"github.com/hebcal/hdate"
)

func main() {
	hd := hdate.New(5783, hdate.Elul, 29)
	str := hd.String()
	fmt.Println(str)
}

Output:

29 Elul 5783

func (*HDate) UnmarshalJSON 

func (hd *HDate) UnmarshalJSON(b []byte) error

func (HDate) Weekday 

func (hd HDate) Weekday() time.Weekday

Weekday returns the day of the week specified by hd.

Example 
package main

import (
	"fmt"

	"github.com/hebcal/hdate"
)

func main() {
	hd := hdate.New(5765, hdate.Adar2, 22)
	dayOfWeek := hd.Weekday()
	fmt.Println(dayOfWeek)
}

Output:

Saturday

func (HDate) Year 

func (hd HDate) Year() int

Year returns the Hebrew year of hd.

Example 
package main

import (
	"fmt"

	"github.com/hebcal/hdate"
)

func main() {
	hd := hdate.New(5769, hdate.Cheshvan, 15)
	fmt.Println(hd.Year())
}

Output:

5769

type HMonth 

type HMonth int

An HMonth specifies a Hebrew month of the year (Nisan = 1, Tishrei = 7, ...). 

const (
	// Nissan / ניסן
	Nisan HMonth = 1 + iota
	// Iyyar / אייר
	Iyyar
	// Sivan / סיון
	Sivan
	// Tammuz (sometimes Tamuz) / תמוז
	Tamuz
	// Av / אב
	Av
	// Elul / אלול
	Elul
	// Tishrei / תִשְׁרֵי
	Tishrei
	// Cheshvan / חשון
	Cheshvan
	// Kislev / כסלו
	Kislev
	// Tevet / טבת
	Tevet
	// Sh'vat / שבט
	Shvat
	// Adar or Adar Rishon / אדר
	Adar1
	// Adar Sheini (only on leap years) / אדר ב׳
	Adar2
)

func MonthFromName 

func MonthFromName(monthName string) (HMonth, error)

MonthFromName parses a Hebrew month string name to determine the month number.

With the exception of Adar 1/Adar 2, Hebrew months are unique to their second letter. 

N         Nisan  (November?)
I         Iyyar
E        Elul
C        Cheshvan
K        Kislev
Si Sh     Sivan, Shvat
Ta Ti Te Tamuz, Tishrei, Tevet
Av Ad    Av, Adar

אב אד אי אל   אב אדר אייר אלול
ח            חשון
ט            טבת
כ            כסלו
נ            ניסן
ס            סיון
ש            שבט
תמ תש        תמוז תשרי

Adar1, Adar 1, Adar I, אדר א׳
Adar2, Adar 2, Adar II, אדר ב׳
Example 
package main

import (
	"fmt"

	"github.com/hebcal/hdate"
)

func main() {
	var month hdate.HMonth
	month, _ = hdate.MonthFromName("Shvat")
	fmt.Printf("%s (%d)\n", month, int(month))
	month, _ = hdate.MonthFromName("cheshvan")
	fmt.Printf("%s (%d)\n", month, int(month))
	month, _ = hdate.MonthFromName("טבת")
	fmt.Printf("%s (%d)\n", month, int(month))
	month, _ = hdate.MonthFromName("Adar 1")
	fmt.Printf("%s (%d)\n", month, int(month))
	month, _ = hdate.MonthFromName("Adar 2")
	fmt.Printf("%s (%d)\n", month, int(month))
}

Output:

Sh'vat (11)
Cheshvan (8)
Tevet (10)
Adar I (12)
Adar II (13)

func (HMonth) String 

func (m HMonth) String() string

String returns the English name of the month ("Nisan", "Iyyar", ...).

Example 
package main

import (
	"fmt"

	"github.com/hebcal/hdate"
)

func main() {
	month := hdate.Adar2
	fmt.Println(month.String())
}

Output:

Adar II

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.