Golang 时间区间处理库 timespan 使用指南

timespan 是一个用于处理时间区间和时间持续操作的 Golang 库，它提供了方便的方法来处理时间段的创建、比较、计算和操作。

安装

go get github.com/Songmu/timespan

基本用法

1. 创建时间区间

package main

import (
	"fmt"
	"time"
	
	"github.com/Songmu/timespan"
)

func main() {
	// 创建当前时间的时间区间
	now := time.Now()
	span := timespan.New(now, now.Add(2*time.Hour))
	
	// 或者使用时间字符串创建
	start, _ := time.Parse(time.RFC3339, "2023-01-01T00:00:00Z")
	end, _ := time.Parse(time.RFC3339, "2023-01-01T02:00:00Z")
	span2 := timespan.New(start, end)
	
	fmt.Println("Span1:", span)
	fmt.Println("Span2:", span2)
}

2. 获取时间区间的属性

func getSpanProperties() {
	start := time.Now()
	end := start.Add(3 * time.Hour)
	span := timespan.New(start, end)
	
	// 获取开始时间
	fmt.Println("Start:", span.Start())
	
	// 获取结束时间
	fmt.Println("End:", span.End())
	
	// 获取持续时间
	fmt.Println("Duration:", span.Duration())
	
	// 检查是否为零值区间
	fmt.Println("IsZero:", span.IsZero())
}

3. 时间区间比较

func compareSpans() {
	// 创建两个时间区间
	span1 := timespan.New(
		time.Date(2023, 1, 1, 9, 0, 0, 0, time.UTC),
		time.Date(2023, 1, 1, 11, 0, 0, 0, time.UTC),
	)
	
	span2 := timespan.New(
		time.Date(2023, 1, 1, 10, 0, 0, 0, time.UTC),
		time.Date(2023, 1, 1, 12, 0, 0, 0, time.UTC),
	)
	
	// 检查是否重叠
	fmt.Println("Overlaps:", span1.Overlaps(span2))
	
	// 检查是否包含另一个区间
	fmt.Println("Contains:", span1.Contains(span2))
	
	// 检查是否包含特定时间点
	t := time.Date(2023, 1, 1, 10, 30, 0, 0, time.UTC)
	fmt.Println("Contains time:", span1.ContainsTime(t))
}

4. 时间区间操作

func spanOperations() {
	span1 := timespan.New(
		time.Date(2023, 1, 1, 9, 0, 0, 0, time.UTC),
		time.Date(2023, 1, 1, 11, 0, 0, 0, time.UTC),
	)
	
	span2 := timespan.New(
		time.Date(2023, 1, 1, 10, 0, 0, 0, time.UTC),
		time.Date(2023, 1, 1, 12, 0, 0, 0, time.UTC),
	)
	
	// 合并两个区间
	merged, err := span1.Union(span2)
	if err != nil {
		fmt.Println("Merge error:", err)
	} else {
		fmt.Println("Merged span:", merged)
	}
	
	// 获取交集
	intersection, err := span1.Intersect(span2)
	if err != nil {
		fmt.Println("Intersection error:", err)
	} else {
		fmt.Println("Intersection:", intersection)
	}
	
	// 扩展时间区间
	extended := span1.Extend(30 * time.Minute)
	fmt.Println("Extended span:", extended)
}

5. 时间区间格式化

func formatSpan() {
	span := timespan.New(
		time.Date(2023, 1, 1, 9, 0, 0, 0, time.UTC),
		time.Date(2023, 1, 1, 11, 0, 0, 0, time.UTC),
	)
	
	// 默认字符串表示
	fmt.Println(span.String())
	
	// 自定义格式化
	fmt.Printf("From %s to %s\n", 
		span.Start().Format("2006-01-02 15:04"), 
		span.End().Format("2006-01-02 15:04"))
}

实际应用示例

检查会议室预订冲突

func checkBookingConflict(newBooking, existingBookings []timespan.TimeSpan) bool {
	for _, existing := range existingBookings {
		if newBooking.Overlaps(existing) {
			return true
		}
	}
	return false
}

计算多个时间区间的总时长

func calculateTotalDuration(spans []timespan.TimeSpan) time.Duration {
	var total time.Duration
	for _, span := range spans {
		total += span.Duration()
	}
	return total
}

注意事项

1. timespan 创建时要求开始时间必须早于或等于结束时间
2. 在进行区间操作(如合并、交集)时，如果区间不满足条件会返回错误
3. 该库适合处理简单的时间区间逻辑，对于复杂的日历调度可能需要更专业的库

timespan 提供了一种简洁的方式来处理 Golang 中的时间区间问题，特别适合需要处理时间段重叠、包含关系等场景的应用。