https://github.com/taigrr/most-specific-period
https://github.com/taigrr/most-specific-period
go golang hacktoberfest
Last synced: 10 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/taigrr/most-specific-period
- Owner: taigrr
- License: 0bsd
- Created: 2022-02-28T22:10:54.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2026-05-05T22:30:23.000Z (about 1 month ago)
- Last Synced: 2026-05-06T00:33:55.653Z (about 1 month ago)
- Topics: go, golang, hacktoberfest
- Language: Go
- Homepage:
- Size: 55.7 KB
- Stars: 1
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Most Specific Period
[](https://pkg.go.dev/github.com/taigrr/most-specific-period)
[](https://goreportcard.com/report/github.com/taigrr/most-specific-period)
A Go library for selecting the narrowest time period containing a given
timestamp from a set of potentially overlapping periods.
## Installation
```bash
go get github.com/taigrr/most-specific-period
```
## What is a Most Specific Period?
Given overlapping time periods, the MSP algorithm picks the most precise one:
- Given a single valid period containing the timestamp, that period is chosen.
- Given two overlapping periods of different lengths, the shorter one wins.
- Given two periods of equal length, the one that started more recently wins.
- Given two periods with the same duration and start time, the lexicographically
last identifier wins (e.g. "B" over "A").
- Periods that haven't started yet or have already ended are ignored.
## Usage
Implement the `Period` interface or use the built-in `TimeWindow`:
```go
package main
import (
"fmt"
"time"
"github.com/taigrr/most-specific-period/msp"
)
func main() {
now := time.Now()
periods := []msp.Period{
msp.TimeWindow{
StartTime: now.Add(-24 * time.Hour),
EndTime: now.Add(24 * time.Hour),
Identifier: "this-week",
},
msp.TimeWindow{
StartTime: now.Add(-1 * time.Hour),
EndTime: now.Add(1 * time.Hour),
Identifier: "this-morning",
},
}
id, err := msp.MostSpecificPeriod(now, periods...)
if err != nil {
fmt.Println("No matching period")
return
}
fmt.Printf("MSP: %s\n", id) // "this-morning"
}
```
### Period Interface
```go
type Period interface {
GetStartTime() time.Time // Inclusive start time
GetEndTime() time.Time // Exclusive end time
GetIdentifier() string
}
```
### Additional Functions
- `GenerateTimeline(periods...)` — Flatten overlapping periods into a
non-overlapping timeline.
- `GetChangeOvers(periods...)` — Get timestamps where the MSP changes.
- `GetNextChangeOver(t, periods...)` — Get the next changeover after time `t`.
- `FlattenPeriods(periods...)` — Get ordered identifiers at each changeover.
- `ValidTimePeriods(ts, periods...)` — Filter periods valid at timestamp `ts`.
- `GetDuration(start, end)` — Calculate duration between two times.
## CLI
A demo CLI is included. It reads periods from stdin (one per three lines:
identifier, start time, end time in RFC 3339) and displays the timeline
and MSP.
```bash
go run . -d 2024-06-15T12:00:00Z <