gdate

package module
v0.1.13 Latest Latest
Warning

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

 Go to latest Published: Jun 4, 2024 License: Unlicense Imports: 4 Imported by: 5

README

gdate

A Go package to parse and order genealogical dates.

Check Status Test Status Go Report Card go.dev reference

Overview

The following types of date are supported:

  • Precise, dates that have a known year, month and day
  • Year, dates that occur within a known specific year
  • BeforeYear, dates that are before the start of a specific year, often written as "bef. 1905"
  • AfterYear, dates that are after the start of a specific year, often written as "aft. 1921"
  • AboutYear, dates that are near to a specific year, often written as "abt. 1850"
  • YearQuarter, a year plus the quarter according to the UK general register office convention,
  • EstimatedYear, dates that are estimated to be a specific year, often written as "est. 1960"
  • Unknown, an unknown date

Usage

An example of using Parse to parse input strings and SortsBefore to order the resulting dates:

package gdate_test

import (
	"fmt"
	"sort"

	"github.com/iand/gdate"
)

func Example() {
	input := []string{
		"7 Nov 1880",
		"5 Nov 1878",
		"6 Apr 1877",
		"before 1877",
		"not a date",
		"after 1878",
		"1885",
		"about 1879",
	}

	dates := []gdate.Date{}

	for _, in := range input {
		dt, _ := gdate.Parse(in)
		dates = append(dates, dt)
	}

	sort.Slice(dates, func(i, j int) bool {
		return gdate.SortsBefore(dates[i], dates[j])
	})

	fmt.Println("sorted dates")
	for _, dt := range dates {
		fmt.Printf(" - %s\n", dt.String())
	}

	// Output:
	// sorted dates
	//  - bef. 1877
	//  - 6 Apr 1877
	//  - 5 Nov 1878
	//  - aft. 1878
	//  - abt. 1879
	//  - 7 Nov 1880
	//  - 1885
	//  - not a date
}

License

This is free and unencumbered software released into the public domain. For more information, see http://unlicense.org/ or the accompanying UNLICENSE file.

Documentation

Overview

Example 
package main

import (
	"fmt"
	"sort"

	"github.com/iand/gdate"
)

func main() {
	input := []string{
		"7 Nov 1880",
		"5 Nov 1878",
		"6 Apr 1877",
		"before 1877",
		"not a date",
		"after 1878",
		"1885",
		"about 1879",
	}

	dates := []gdate.Date{}

	for _, in := range input {
		dt, _ := gdate.Parse(in)
		dates = append(dates, dt)
	}

	sort.Slice(dates, func(i, j int) bool {
		return gdate.SortsBefore(dates[i], dates[j])
	})

	fmt.Println("sorted dates")
	for _, dt := range dates {
		fmt.Printf(" - %s\n", dt.String())
	}

}

Output:

sorted dates
 - bef. 1877
 - 6 Apr 1877
 - 5 Nov 1878
 - aft. 1878
 - abt. 1879
 - 7 Nov 1880
 - 1885
 - not a date

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func IsUnknown 

func IsUnknown(d Date) bool

IsUnknown reports whether d is an Unknown date

func IsUnknownInterval 

func IsUnknownInterval(in Interval) bool

IsUnknownInterval reports whether in is an unknown interval

func SortsBefore 

func SortsBefore(a, b Date) bool

SortsBefore reports whether a should sort before b chronologically

Types

type AboutYear 

type AboutYear struct {
	C Calendar
	Y int
}

AboutYear represents a date that is near to a specific year

func (*AboutYear) Calendar added in v0.1.1 

func (a *AboutYear) Calendar() Calendar

func (*AboutYear) Occurrence 

func (a *AboutYear) Occurrence() string

func (*AboutYear) SortsBefore 

func (a *AboutYear) SortsBefore(d Date) bool

func (*AboutYear) String 

func (a *AboutYear) String() string

func (*AboutYear) Year 

func (a *AboutYear) Year() int

type AboutYearsInterval 

type AboutYearsInterval struct {
	Y int
}

func (*AboutYearsInterval) Precise 

func (i *AboutYearsInterval) Precise() string

func (*AboutYearsInterval) Rough 

func (i *AboutYearsInterval) Rough() string

func (*AboutYearsInterval) Years 

func (p *AboutYearsInterval) Years() int

type AfterYear 

type AfterYear struct {
	C Calendar
	Y int
}

AfterYear represents a date that is after the end of a specific year

func (*AfterYear) Calendar added in v0.1.1 

func (a *AfterYear) Calendar() Calendar

func (*AfterYear) Occurrence 

func (a *AfterYear) Occurrence() string

func (*AfterYear) SortsBefore 

func (a *AfterYear) SortsBefore(d Date) bool

func (*AfterYear) String 

func (a *AfterYear) String() string

type BeforeYear 

type BeforeYear struct {
	C Calendar
	Y int
}

BeforeYear represents a date that is before the start of a specific year. It sorts before any date with that year.

func (*BeforeYear) Calendar added in v0.1.1 

func (b *BeforeYear) Calendar() Calendar

func (*BeforeYear) Occurrence 

func (b *BeforeYear) Occurrence() string

func (*BeforeYear) SortsBefore 

func (b *BeforeYear) SortsBefore(d Date) bool

func (*BeforeYear) String 

func (b *BeforeYear) String() string

type Calendar added in v0.1.1 

type Calendar int
const (
	Gregorian   Calendar = 0
	Julian      Calendar = 1 // Julian calendar with the first day of the year being 1 Jan
	Julian25Mar Calendar = 2 // Julian calendar with the first day of the year being 25 Mar
)

func (Calendar) JulianDay added in v0.1.1 

func (c Calendar) JulianDay(y, m, d int) int

The JulianDay is the count of days elapsed since the beginning of the Julian period

func (Calendar) String added in v0.1.1 

func (c Calendar) String() string

type ComparableDate added in v0.1.1 

type ComparableDate interface {
	// EarliestJulianDay returns the earliest Julian day that is included by the date
	EarliestJulianDay() int
	// LatestJulianDay returns the latest Julian day that is included by the date
	LatestJulianDay() int
}

type Date 

type Date interface {
	String() string
	Occurrence() string
	Calendar() Calendar
}

func Parse 

func Parse(s string) (Date, error)

Parse uses heuristics to parse s into the highest precision date available using the default parser which does not set a calendar and only handles English. An Unknown date is returned for any string that does not contain a detectable date.

type EstimatedYear 

type EstimatedYear struct {
	C Calendar
	Y int
}

EstimatedYear represents a date that is estimated to be a specific year

func (*EstimatedYear) Calendar added in v0.1.1 

func (e *EstimatedYear) Calendar() Calendar

func (*EstimatedYear) Occurrence 

func (e *EstimatedYear) Occurrence() string

func (*EstimatedYear) SortsBefore 

func (e *EstimatedYear) SortsBefore(d Date) bool

func (*EstimatedYear) String 

func (e *EstimatedYear) String() string

func (*EstimatedYear) Year 

func (e *EstimatedYear) Year() int

type Interval 

type Interval interface {
	Precise() string
	Rough() string
}

func IntervalBetween 

func IntervalBetween(a, b Date) Interval

type MonthYear 

type MonthYear struct {
	C Calendar
	M int
	Y int
}

Year is a date for which only the month and year is known or a period of time that may span an entire month. It sorts before any date with a higher numeric year.

func (*MonthYear) Calendar added in v0.1.1 

func (m *MonthYear) Calendar() Calendar

func (*MonthYear) EarliestJulianDay added in v0.1.1 

func (m *MonthYear) EarliestJulianDay() int

func (*MonthYear) LatestJulianDay added in v0.1.1 

func (m *MonthYear) LatestJulianDay() int

func (*MonthYear) Occurrence 

func (m *MonthYear) Occurrence() string

func (*MonthYear) String 

func (m *MonthYear) String() string

func (*MonthYear) Year 

func (m *MonthYear) Year() int

type Parser 

type Parser struct {

	// ReckoningLocation specifies the location from which the date originated and is used
	// to set the calendar based on the year of calendar change in that location. To force
	// a known calendar to be used, set this to ReckoningLocationNone and set the Calendar
	// field to the required calendar.
	ReckoningLocation ReckoningLocation

	// AssumeGROQuarter controls whether the parse will assume that ambiguous dates consisting of a month and a year,
	// where the month is the start or end of a quarter, refer to the UK General Register Office quarter
	// containing that month, so July 1850 will be parsed as 3rd Quarter, 1850
	AssumeGROQuarter bool

	// Calendar specifies the calendar to use for the date if ReckoningLocation is set to ReckoningLocationNone.
	Calendar Calendar
}

A Parser converts strings into dates

func (*Parser) Parse 

func (p *Parser) Parse(s string) (Date, error)

Parse uses heuristics to parse s into the highest precision date available. An Unknown date is returned for any string that does not contain a detectable date.

type Precise 

type Precise struct {
	C Calendar
	Y int
	M int // 1-12 like go's time package
	D int
}

Precise is a date with a known year, month and day.

func AsPrecise 

func AsPrecise(d Date) (*Precise, bool)

AsPrecise returns the date as a precise date and true if possible, false if it is not possible to convert.

func (*Precise) Calendar added in v0.1.1 

func (p *Precise) Calendar() Calendar

func (*Precise) DateInYear 

func (p *Precise) DateInYear(long bool) string

func (*Precise) EarliestJulianDay added in v0.1.1 

func (p *Precise) EarliestJulianDay() int

func (*Precise) LatestJulianDay added in v0.1.1 

func (p *Precise) LatestJulianDay() int

func (*Precise) Occurrence 

func (p *Precise) Occurrence() string

func (*Precise) String 

func (p *Precise) String() string

func (*Precise) Year 

func (p *Precise) Year() int

type PreciseInterval 

type PreciseInterval struct {
	Y, M, D int
}

func AsPreciseInterval 

func AsPreciseInterval(in Interval) (*PreciseInterval, bool)

AsPreciseInterval returns the interval as a PreciseInterval and true if possible, false if it is not possible to convert.

func (*PreciseInterval) ApproxDays 

func (p *PreciseInterval) ApproxDays() int

func (*PreciseInterval) Months 

func (p *PreciseInterval) Months() int

func (*PreciseInterval) Precise 

func (p *PreciseInterval) Precise() string

func (*PreciseInterval) Rough 

func (p *PreciseInterval) Rough() string

func (*PreciseInterval) YMD 

func (p *PreciseInterval) YMD() (int, int, int)

func (*PreciseInterval) Years 

func (p *PreciseInterval) Years() int

type ReckoningLocation added in v0.1.1 

type ReckoningLocation int

The ReckoningLocation is the location used to determine the reckoning of the calendar which determines the date on which the first day of the year changed to 1 Jan and the date on which the calendar changed from Julian to Gregorian 

const (
	// TODO: non-English reckonings
	ReckoningLocationNone ReckoningLocation = 0
	EnglandAndWales       ReckoningLocation = 1
	Scotland              ReckoningLocation = 2
	Ireland               ReckoningLocation = 3
)

func (ReckoningLocation) Calendar added in v0.1.1 

func (r ReckoningLocation) Calendar(y int) Calendar

StartOfYear returns calendar in use for the year specified.

type Unknown 

type Unknown struct {
	C    Calendar
	Text string
}

Unknown is an unknown date. It sorts after every other type of date.

func (*Unknown) Calendar added in v0.1.1 

func (u *Unknown) Calendar() Calendar

func (*Unknown) Occurrence 

func (u *Unknown) Occurrence() string

func (*Unknown) SortsBefore 

func (u *Unknown) SortsBefore(d Date) bool

func (*Unknown) String 

func (u *Unknown) String() string

type UnknownInterval 

type UnknownInterval struct{}

func (*UnknownInterval) Precise 

func (i *UnknownInterval) Precise() string

func (*UnknownInterval) Rough 

func (i *UnknownInterval) Rough() string

type Year 

type Year struct {
	C Calendar
	Y int
}

Year is a date for which only the year is known or a period of time that may span an entire year. It sorts before any date with a higher numeric year.

func AsYear 

func AsYear(d Date) (*Year, bool)

AsYear returns the date as a Year and true if possible, false if it is not possible to convert.

func (*Year) Calendar added in v0.1.1 

func (y *Year) Calendar() Calendar

func (*Year) EarliestJulianDay added in v0.1.1 

func (y *Year) EarliestJulianDay() int

func (*Year) LatestJulianDay added in v0.1.1 

func (y *Year) LatestJulianDay() int

func (*Year) Occurrence 

func (y *Year) Occurrence() string

func (*Year) String 

func (y *Year) String() string

func (*Year) Year 

func (y *Year) Year() int

type YearQuarter 

type YearQuarter struct {
	C Calendar
	Y int
	Q int
}

YearQuarter represents quarter of a specific year, based on GRO quarters Values of Q correspond to quarters as follows: 1 = Jan-Mar, known as MAR QTR 2 = Apr-Jun, known as JUN QTR 3 = Jul-Sep, known as SEP QTR 4 = Oct-Dec, known as DEC QTR

func (*YearQuarter) Calendar added in v0.1.1 

func (y *YearQuarter) Calendar() Calendar

func (*YearQuarter) EarliestJulianDay added in v0.1.1 

func (y *YearQuarter) EarliestJulianDay() int

func (*YearQuarter) LatestJulianDay added in v0.1.1 

func (y *YearQuarter) LatestJulianDay() int

func (*YearQuarter) MonthRange 

func (y *YearQuarter) MonthRange() string

func (*YearQuarter) Occurrence 

func (y *YearQuarter) Occurrence() string

func (*YearQuarter) String 

func (y *YearQuarter) String() string

func (*YearQuarter) Year 

func (y *YearQuarter) Year() int

type YearRange added in v0.1.1 

type YearRange struct {
	C     Calendar
	Lower int // first year of the range
	Upper int // last year of the range
}

YearRange represents a date that is within the range of two years, including the upper and lower year.

func (*YearRange) Calendar added in v0.1.1 

func (y *YearRange) Calendar() Calendar

func (*YearRange) EarliestJulianDay added in v0.1.1 

func (y *YearRange) EarliestJulianDay() int

func (*YearRange) LatestJulianDay added in v0.1.1 

func (y *YearRange) LatestJulianDay() int

func (*YearRange) Occurrence added in v0.1.1 

func (y *YearRange) Occurrence() string

func (*YearRange) String added in v0.1.1 

func (y *YearRange) String() string

type YearsInterval 

type YearsInterval struct {
	Y int
}

func AsYearsInterval 

func AsYearsInterval(in Interval) (*YearsInterval, bool)

AsYearsInterval returns the interval as a YearsInterval and true if possible, false if it is not possible to convert.

func (*YearsInterval) Precise 

func (i *YearsInterval) Precise() string

func (*YearsInterval) Rough 

func (i *YearsInterval) Rough() string

func (*YearsInterval) Years 

func (p *YearsInterval) Years() int

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.