kayprish/ck
2
1
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

Add documentation for the julian package

Browse source
This commit is contained in:
Petar Kapriš 2024-07-23 23:00:30 +02:00
parent 6f6b203c5b
commit 299832cb4b
1 changed files with 26 additions and 4 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

30
julian/julian.go
View file

@ -1,10 +1,22 @@
// The julian package enables working with the Julian calendar, as well as
// conversion from the Julian to the Gregorian and vice versa. Gregorian dates
// are usually represented using the Go builtin time.Time type, and Julian
// Dates are represented with the julian.Date type.
// BUG(kayprish) the Go time.Time type doesn't work properly on dates before
// the Christian era, for example, it has the non-existant year 0, and since
// this package depends on that type, and the ck module has no need for BCE
// dates, no special care was taken to make sure BC dates work, only AD date
// conversions are supported
package julian package julian
import "time" import "time"
// TODO: describe how time doesn't go past BCE, and therefore we don't either // `proleptic`, ie. there is no
// Keep in mind, Go's time.Time gregorian dates are `proleptic`, ie. there is // need to give special care to dates before 15. October 1582.
// no need to give special care to dates before 15. October 1582.
// The julian.Date type is meant to represent a date in the Julian calendar,
// and only in the Julian calendar, Gregorian dates are represented with the
// time.Time type.
type Date struct { type Date struct {
year int year int
month time.Month month time.Month
@ -45,6 +57,8 @@ func monthLength(year int, month time.Month) int {
return 28 return 28
} }
// The dateDiff function calculates the Julian date which falls the given
// number of dates before or after the given date.
func dateDiff(d Date, days int) Date { func dateDiff(d Date, days int) Date {
// keep in mind throughout this code that the original "days" value can // keep in mind throughout this code that the original "days" value can
// be negative // be negative
@ -86,7 +100,8 @@ func nextMonth(year int, month time.Month) (int, time.Month) {
} }
} }
func New(year int, month time.Month, day int) Date { // The NewDate function creates a new Julian date
func NewDate(year int, month time.Month, day int) Date {
// TODO: deal with users giving negative dates // TODO: deal with users giving negative dates
for day > monthLength(year, month) { for day > monthLength(year, month) {
day -= monthLength(year, month) day -= monthLength(year, month)
@ -95,6 +110,9 @@ func New(year int, month time.Month, day int) Date {
return Date{year, month, day} return Date{year, month, day}
} }
// The function JDateToTime converts a given Julian date into a Gregorian date
// represented with the time.Time type.
//
// The algorithm, in large part: follows this article: // The algorithm, in large part: follows this article:
// https://en.wikipedia.org/wiki/Conversion_between_Julian_and_Gregorian_calendars // https://en.wikipedia.org/wiki/Conversion_between_Julian_and_Gregorian_calendars
func JDateToTime(d Date) time.Time { func JDateToTime(d Date) time.Time {
@ -121,6 +139,10 @@ func JDateToTime(d Date) time.Time {
return time.Date(d.year, d.month, d.day, 0, 0, 0, 0, time.UTC) return time.Date(d.year, d.month, d.day, 0, 0, 0, 0, time.UTC)
} }
// The function TimeToJDate converts a given Gregorian date into a Julian date.
//
// The algorithm, in large part: follows this article:
// https://en.wikipedia.org/wiki/Conversion_between_Julian_and_Gregorian_calendars
func TimeToJDate(t time.Time) Date { func TimeToJDate(t time.Time) Date {
offset := -2 offset := -2
// The date when the offset changes in the gregorian calendar is always // The date when the offset changes in the gregorian calendar is always