README
¶
🕐 timefn: Date utility library for Go
This project is a work in progress.
timefn provides utilities for working with time and time periods.
Install
go get github.com/bounoable/timefn
Use
Read the docs for a list of available functions.
Documentation
¶
Index ¶
- Variables
- func AtTime(t time.Time, h, m, s, ns int) time.Time
- func Between(t, l, r time.Time) bool
- func BetweenInclusive(t, l, r time.Time) bool
- func EndOfDay(t time.Time) time.Time
- func EndOfHour(t time.Time) time.Time
- func EndOfISOWeek(t time.Time) time.Time
- func EndOfMinute(t time.Time) time.Time
- func EndOfMonth(t time.Time) time.Time
- func EndOfSecond(t time.Time) time.Time
- func EndOfWeek(t time.Time) time.Time
- func EndOfYear(t time.Time) time.Time
- func SameOrAfter(t, l time.Time) bool
- func SameOrBefore(t, r time.Time) bool
- func StartOfDay(t time.Time) time.Time
- func StartOfHour(t time.Time) time.Time
- func StartOfISOWeek(t time.Time) time.Time
- func StartOfMinute(t time.Time) time.Time
- func StartOfMonth(t time.Time) time.Time
- func StartOfSecond(t time.Time) time.Time
- func StartOfWeek(t time.Time) time.Time
- func StartOfYear(t time.Time) time.Time
- type Period
- func (p Period) Add(d time.Duration) Period
- func (p Period) Contains(t time.Time) bool
- func (p Period) ContainsInclusive(t time.Time) bool
- func (p Period) Cut(cut ...Period) []Period
- func (p Period) CutInclusive(cut ...Period) []Period
- func (p Period) Dates() []time.Time
- func (p Period) DatesStep(step time.Duration) []time.Time
- func (p Period) Format() string
- func (p Period) FormatAs(format string) string
- func (p Period) InYear(year int) bool
- func (p Period) InYearStep(step time.Duration, year int) bool
- func (p Period) IsZero() bool
- func (p Period) Merge(periods []Period) []Period
- func (p Period) MergeStep(step time.Duration, periods []Period) []Period
- func (p Period) OverlapsWith(p2 Period) bool
- func (p Period) OverlapsWithStep(step time.Duration, p2 Period) bool
- func (p Period) SliceDates(fn func(date time.Time, i int) bool) (Period, Period, bool)
- func (p Period) SliceDatesStep(step time.Duration, fn func(date time.Time, i int) bool) (before Period, after Period, found bool)
- func (p Period) String() string
- func (p Period) Validate() error
- func (p Period) Years() []int
- func (p Period) YearsStep(step time.Duration) []int
Constants ¶
This section is empty.
Variables ¶
var DefaultPeriodFormat = "{{ .Start }} -> {{ .End }}"
DefaultPeriodFormat is a variable used as the default format for presenting a period of time. It uses two placeholders, .Start and .End, to represent the start and end of the period respectively. The format string is used in the Format method of the Period type to generate a string representation of the time period.
Functions ¶
func AtTime ¶ added in v0.1.3
AtTime sets the time of the provided time.Time to the specified hours, minutes, seconds and nanoseconds while keeping the same date and location. The returned time.Time will have the same year, month, day and location as the original, but the hour, minute, second and nanosecond values will be replaced with the ones provided as arguments.
func Between ¶
Between checks if a given time [t] falls after time [l] and before time [r]. Returns true if [t] is between [l] and [r], otherwise returns false.
func BetweenInclusive ¶
BetweenInclusive determines if a given time (time.Time) is within or equal to the range of two other specified times, inclusive. The function returns true if the time is equal to or falls between the other two times, otherwise it returns false.
func EndOfDay ¶
EndOfDay returns the end of the day for a given time, represented as a time.Time value. The end of the day is defined as the last possible moment before the start of the next day. This is equivalent to one nanosecond before midnight of the next day in the same location as the input time.
func EndOfHour ¶
EndOfHour returns the time instance representing the end of the hour for the provided time [t]. The end of the hour is defined as one nanosecond before the start of the next hour.
func EndOfISOWeek ¶
EndOfISOWeek returns the last instant within the same ISO week as the provided time.Time. An ISO week starts on Monday and ends on Sunday. The returned time will be at the end of the day, just before midnight, in the location of the provided time.
func EndOfMinute ¶
EndOfMinute returns the exact time at the end of the minute for a given time. This is effectively one nanosecond before the start of the next minute.
func EndOfMonth ¶
EndOfMonth takes a time.Time value and returns a new time.Time value representing the exact end of the same month. The returned time is the last nanosecond of the last day of the month in the same location as the input time.
func EndOfSecond ¶
EndOfSecond returns the last nanosecond of the second specified by the provided time.Time. The returned time.Time has the same year, month, day, hour, minute and second as the input, but its nanoseconds field is set to one less than a full second.
func EndOfWeek ¶
EndOfWeek returns the end of the week for a given time. The end of the week is defined as 23:59:59 on the last day of the week, which depends on the Weekday of the input time. The returned time is in the same location as the input time.
func EndOfYear ¶
EndOfYear returns the latest possible time within the same year as the given time [t]. The returned time is one nanosecond before the start of the next year.
func SameOrAfter ¶
SameOrAfter determines if the given time [t] is the same as or after another time [l]. It returns true if [t] is either equal to [l] or occurs after [l], and false otherwise.
func SameOrBefore ¶
SameOrBefore checks whether a given time is the same as or precedes another specified time. It takes two arguments, both of type time.Time, and returns a boolean. If the first argument is either equal to or comes before the second argument in chronological order, the function returns true. Otherwise, it returns false.
func StartOfDay ¶
StartOfDay returns a new instance of time.Time representing the start of the day of the given time, with the hour, minute, second, and nanosecond fields set to zero while maintaining the same year, month, day and location as the original.
func StartOfHour ¶
StartOfHour returns a new instance of time.Time representing the start of the hour of the provided time value. All minutes, seconds, and nanoseconds values are set to zero while year, month, day, and hour are preserved from the original time value. The location (time zone) of the returned time is also preserved.
func StartOfISOWeek ¶
StartOfISOWeek returns a new time.Time representing the start of the ISO 8601 week for the given time. The start of a week is considered to be Monday. The returned time has the same location and year, month, and day fields as t but the hour, minute, second, and nanosecond fields are all set to zero.
func StartOfMinute ¶
StartOfMinute returns a new instance of time.Time representing the start of the minute of the provided time, with the second and nanosecond fields set to zero. The returned time maintains the same year, month, day, hour and minute as the input but resets the second and nanosecond to their minimum possible values.
func StartOfMonth ¶
StartOfMonth returns a new instance of time.Time set to the first day of the provided time's month, with the hour, minute, second, and nanosecond fields set to zero. The location is preserved.
func StartOfSecond ¶
StartOfSecond returns a new time.Time value representing the start of the second for the given time. The returned time will have its nanosecond field set to 0, effectively rounding down to the nearest second.
func StartOfWeek ¶
StartOfWeek returns the start of the week for a given time. The week starts on Sunday as per Go's time package definition. The returned time has the same location and date but the hour, minute, second, and nanosecond are set to their zero values.
Types ¶
type Period ¶ added in v0.1.4
Period represents a duration of time between two points in time, defined by a start and end time. It provides methods for formatting the period into a string, validating the period, adding a duration to the period, and checking if a given time falls within the period.
Period also includes methods for checking if it overlaps with another period, retrieving the years within the period, checking if the period falls within a specific year, getting all dates within the period, and dividing the period at a given date.
Additionally, it provides functionalities to cut out certain periods from itself and return the remaining periods.
func MergePeriods ¶ added in v0.2.2
MergePeriods consolidates a slice of [Period]s by combining those that overlap or are adjacent into single, continuous periods. It returns a new slice of merged [Period]s, with the start times sorted in ascending order. Adjacency is determined without any minimum duration step, meaning that periods touching at their boundaries are considered overlapping.
func MergePeriodsStep ¶ added in v0.2.2
MergePeriodsStep merges a slice of [Period]s into a continuous sequence where overlapping periods are combined based on a specified minimum duration step. It ensures that any periods that overlap by at least the given step duration are joined into single periods, producing a consolidated timeline. The result is a slice of non-overlapping [Period]s sorted by their start times. If the step duration is zero, adjacent periods will be merged even if they only touch at the end and start times.
func (Period) Add ¶ added in v0.1.5
Add extends the start and end times of the period by a specified duration. It returns a new Period with the updated start and end times.
func (Period) Contains ¶ added in v0.2.0
Contains checks whether a given time falls within the period. It returns true if the time is the same as or after the start of the period, and before the end of the period.
func (Period) ContainsInclusive ¶ added in v0.2.0
ContainsInclusive checks if a given time is within the period, including the start and end times. It returns true if the time falls within or exactly on the start and end times of the period, otherwise it returns false.
func (Period) Cut ¶ added in v0.1.4
Cut removes specified periods from the receiver Period and returns a slice of the remaining [Period]s. This operation is non-destructive to the original Period. If no periods are specified for removal or if none of the specified periods intersect with the receiver, the result will contain the original Period unaltered. If an intersection occurs, the function returns a new set of [Period]s that represent the time spans before and after each intersection, effectively "cutting out" the intersecting ranges. The resulting slice is sorted by the start times of each Period.
func (Period) CutInclusive ¶ added in v0.1.4
CutInclusive trims the specified periods from the receiver Period and returns a slice of [Period]s that represent the remaining time ranges. It does so in an inclusive manner, where the end times of both the receiver and the specified periods are considered part of the cut. If a specified period to cut overlaps with or is within the bounds of the receiver period, it is trimmed accordingly, and the remaining non-overlapping parts are returned. If no overlap exists, the original Period is returned unchanged. The resulting slice of [Period]s is sorted by their start times.
func (Period) Dates ¶ added in v0.1.4
Dates retrieves all the dates within the period, returning a slice of time.Time. Each date is represented by the start of the day, and they are returned in chronological order from the start to the end of the period. If the period is invalid, it returns nil.
func (Period) DatesStep ¶ added in v0.1.4
DatesStep iterates over each date within the period, using a specified step interval. It generates a slice of time.Time representing each date from the start to the end of the period, not including the last date if it is equal to the end date minus the step interval. The step defines the minimum duration to advance when moving to the next date within the period. If any part of the period is invalid, it returns nil.
func (Period) Format ¶ added in v0.1.4
Format returns a string representation of the Period. The formatting is based on the DefaultPeriodFormat which represents the start and end time of the period. If there's an error during the formatting process, it returns a descriptive error message in a string format.
func (Period) FormatAs ¶ added in v0.1.4
FormatAs formats the period using the given format string. The format string can contain placeholders for the start and end times of the period. If an empty string is passed as the format, the default format "{{ .Start }} -> {{ .End }}" is used. If an error occurs during formatting, it returns a string representation of the error message.
func (Period) InYear ¶ added in v0.1.4
InYear checks if the period falls within the specified year. It returns true if the period is at least for a nanosecond in the given year, otherwise it returns false. The year is determined by using the start and end times of the period.
func (Period) InYearStep ¶ added in v0.1.4
InYearStep checks if the period occurs within a specified year, given a step duration. The step duration is the minimum time the period must be within the year for it to be considered as occurring within that year. The function returns true if the period occurs within the specified year, otherwise it returns false.
func (Period) IsZero ¶ added in v0.1.4
IsZero checks if the start and end times of the period are both zero, indicating that the period does not represent a valid time span. It returns true if both times are zero, and false otherwise.
func (Period) Merge ¶ added in v0.2.1
Merge combines the receiver Period with a slice of other [Period]s and returns a new slice of merged [Period]s. Overlapping periods are consolidated into single periods, while non-overlapping periods remain separate. The merge process respects the chronological order of periods.
func (Period) MergeStep ¶ added in v0.2.1
MergeStep merges the Period with a slice of other periods, ensuring that any overlapping periods are combined into continuous periods based on a specified minimum duration step. It returns a slice of merged periods, sorted by their start times. If no additional periods are provided, the result is a slice containing only the original period. The step parameter determines how much overlap is necessary for two periods to be considered as one continuous period.
func (Period) OverlapsWith ¶ added in v0.1.4
OverlapsWith returns whether p and p2 overlap.
func (Period) OverlapsWithStep ¶ added in v0.1.4
OverlapsWithStep returns whether p and p2 overlap. The step parameter defines the minimum duration the two periods must overlap for them to be considered overlapping. For example, if the step is 1 hour, the periods must overlap for at least 1 hour to be considered overlapping. A step of 0 would consider the following two periods to be overlapping:
"2020-01-01 00:00:00 -> 2020-01-02 00:00:00" "2020-01-02 00:00:00 -> 2020-01-03 00:00:00"
[OverlapsWith] is equivalent to OverlapsWithStep with a step of 1 nanosecond.
func (Period) SliceDates ¶ added in v0.1.4
SliceDates divides the Period into two periods based on a user-defined criterion. It iterates over each date within the period, invoking a callback function with the current date and its index. The callback's return value determines where the slicing occurs; if it returns true, slicing is performed at that date. The function returns two [Period]s representing the time spans before and after the slicing point, and a boolean indicating whether the slicing was successful. If no date satisfies the criterion, or if the Period is invalid, the original Period is returned as the first result, with an empty second Period and false for the boolean.
func (Period) SliceDatesStep ¶ added in v0.1.4
func (p Period) SliceDatesStep(step time.Duration, fn func(date time.Time, i int) bool) (before Period, after Period, found bool)
SliceDatesStep divides the Period into two at a date determined by the provided callback function, which is called for each date in the period, with an additional step interval between dates. It returns two [Period]s: one before and one after the date where the callback returns true, along with a boolean indicating if such a date was found. If the period is invalid or no date satisfies the callback, it returns the original Period, an empty Period, and false.
func (Period) String ¶ added in v0.1.4
String returns a string representation of the Period. It leverages the Format method to generate this string, using the default period format defined within the package.
func (Period) Validate ¶ added in v0.1.4
Validate checks the validity of the Period. It returns an error if the Start time is zero, the End time is zero, or if the End time is equal to or before the Start time. If none of these conditions are met, it returns nil indicating that the Period is valid.
func (Period) Years ¶ added in v0.1.4
Years returns a slice of integers representing the years that fall within the period. It calculates this based on the start and end dates of the period. The function includes a year in the result if any part of that year is within the period.
func (Period) YearsStep ¶ added in v0.1.4
YearsStep returns the years of the period. The step defines the minimum duration the period must be in a year for it to be included in the result. For example, if the step is 1 hour, the period must be in a year for at least 1 hour to be included in the result.
A step of 0 would consider the following period to be in the years [2020, 2021]:
"2020-12-31 00:00:00 -> 2021-01-01 00:00:00"
A step of 1 nanosecond would consider the following period to be only in the year 2020:
"2020-12-31 00:00:00 -> 2021-01-01 00:00:00"
Source Files
Directories