Documentation
¶
Overview ¶
Package timeutil provides time utilities:
- Formatting & parsing with timezone support
- Time ranges (start/end of day, week, month, year)
- Timers (stopwatch, countdown, debounce)
- Common duration helpers
- Business-day calculations
Quick start ¶
// Format with timezone
timeutil.FormatIn(time.Now(), "2006-01-02 15:04:05", "Asia/Shanghai")
// Parse with timezone
t, err := timeutil.ParseIn("2026-08-15 10:00:00", "2006-01-02 15:04:05", "Asia/Shanghai")
// Start of day in local timezone
start := timeutil.StartOfDay(time.Now())
// Stopwatch
sw := timeutil.NewStopwatch()
sw.Start()
// ... do work ...
elapsed := sw.Elapsed()
Index ¶
- Constants
- func AddBusinessDays(t time.Time, n int) time.Time
- func AddDuration(d time.Duration) int64
- func Age(t time.Time) time.Duration
- func BusinessDaysBetween(start, end time.Time) int
- func CalculateAge(birthday time.Time) int
- func Clamp(t, start, end time.Time) time.Time
- func DaysInMonth(t time.Time) int
- func Debounce(wait time.Duration, fn func()) func()
- func DurationToHuman(d time.Duration) string
- func EndOfDay(t time.Time) time.Time
- func EndOfHour(t time.Time) time.Time
- func EndOfMinute(t time.Time) time.Time
- func EndOfMonth(t time.Time) time.Time
- func EndOfWeek(t time.Time) time.Time
- func EndOfYear(t time.Time) time.Time
- func Format(t time.Time, layout string) string
- func FormatDate(t time.Time) string
- func FormatDateTime(t time.Time) string
- func FormatIn(t time.Time, layout, locName string) string
- func FormatTimestamp(t time.Time) string
- func FormatUTC(t time.Time, layout string) string
- func FromMicros(us int64) time.Time
- func FromMillis(ms int64) time.Time
- func FromUnix(sec int64) time.Time
- func In(t time.Time, loc *time.Location) time.Time
- func InLocation(t time.Time, name string) (time.Time, error)
- func IsBusinessDay(t time.Time) bool
- func IsExpired(t time.Time) bool
- func IsLeapYear(t time.Time) bool
- func IsWeekend(t time.Time) bool
- func IsZero(t time.Time) bool
- func Location(name string) (*time.Location, error)
- func Max(a, b time.Time) time.Time
- func MicrosNow() int64
- func MillisNow() int64
- func Min(a, b time.Time) time.Time
- func MustInLocation(t time.Time, name string) time.Time
- func MustLocation(name string) *time.Location
- func MustParse(value, layout string) time.Time
- func NextBusinessDay(t time.Time) time.Time
- func Now() time.Time
- func NowUTC() time.Time
- func Parse(value, layout string) (time.Time, error)
- func ParseDuration(s string) (time.Duration, error)
- func ParseIn(value, layout, locName string) (time.Time, error)
- func ParseLocal(value, layout string) (time.Time, error)
- func ParseUTC(value, layout string) (time.Time, error)
- func PreviousBusinessDay(t time.Time) time.Time
- func StartOfDay(t time.Time) time.Time
- func StartOfHour(t time.Time) time.Time
- func StartOfMinute(t time.Time) time.Time
- func StartOfMonth(t time.Time) time.Time
- func StartOfWeek(t time.Time) time.Time
- func StartOfYear(t time.Time) time.Time
- func UnixNow() int64
- func Yesterday() time.Time
- type Countdown
- type Stopwatch
- type TimeRange
- func (r TimeRange) Contains(t time.Time) bool
- func (r TimeRange) ContainsInclusive(t time.Time) bool
- func (r TimeRange) Duration() time.Duration
- func (r TimeRange) Intersect(other TimeRange) (TimeRange, bool)
- func (r TimeRange) Overlaps(other TimeRange) bool
- func (r TimeRange) Split(n int) []TimeRange
Constants ¶
const ( LayoutDate = "2006-01-02" LayoutDateTime = "2006-01-02 15:04:05" LayoutTime = "15:04:05" LayoutISO8601 = "2006-01-02T15:04:05Z07:00" LayoutRFC3339 = time.RFC3339 LayoutRFC822 = "02 Jan 06 15:04 MST" LayoutRFC1123 = "Mon, 02 Jan 2006 15:04:05 MST" LayoutUnix = "2006-01-02 15:04:05 -0700 MST" LayoutTimestamp = "20060102150405" LayoutSlash = "2006/01/02 15:04:05" LayoutCNDate = "2006年01月02日" LayoutCNTime = "2006年01月02日 15时04分05秒" )
Common time formats.
const ( Nanosecond = time.Nanosecond Microsecond = time.Microsecond Millisecond = time.Millisecond Second = time.Second Minute = time.Minute Hour = time.Hour Day = 24 * time.Hour Week = 7 * 24 * time.Hour )
Common durations for convenience.
Variables ¶
This section is empty.
Functions ¶
func AddBusinessDays ¶
AddBusinessDays adds n business days (Mon-Fri) to the given time, preserving the time-of-day. Negative n subtracts business days.
func AddDuration ¶
AddDuration returns the Unix timestamp after adding d to now.
func BusinessDaysBetween ¶
BusinessDaysBetween returns the number of business days between two times (exclusive of both endpoints). Returns 0 if start >= end.
func CalculateAge ¶
CalculateAge returns the age in years given a birthday.
func Clamp ¶
Clamp ensures a time is within a range. If t is before start, returns start. If t is after end, returns end. Otherwise returns t.
func DaysInMonth ¶
DaysInMonth returns the number of days in the month of the given time.
func Debounce ¶
Debounce creates a debounced function that delays invoking fn until after wait duration has elapsed since the last time it was invoked. The returned function is safe for concurrent use.
func DurationToHuman ¶
DurationToHuman returns a human-readable duration string. e.g. "2h30m", "1d4h", "30s", "500ms".
func EndOfMinute ¶
EndOfMinute returns the end of the minute for the given time.
func EndOfMonth ¶
EndOfMonth returns the end of the month (last day 23:59:59.999999999).
func FormatDate ¶
FormatDate returns the date part as "2006-01-02".
func FormatDateTime ¶
FormatDateTime returns the time as "2006-01-02 15:04:05".
func FormatTimestamp ¶
FormatTimestamp returns the time as a Unix-style timestamp string (e.g. "20260815100000").
func FromMicros ¶
FromMicros converts a Unix timestamp (microseconds) to time.Time.
func FromMillis ¶
FromMillis converts a Unix timestamp (milliseconds) to time.Time.
func InLocation ¶
InLocation converts a time to the named timezone.
func IsBusinessDay ¶
IsBusinessDay returns true if the given time is a weekday (Mon-Fri).
func IsLeapYear ¶
IsLeapYear returns true if the year of the given time is a leap year.
func Location ¶
Location returns the *time.Location for the given name. Returns time.Local if name is empty or "Local". Returns time.UTC if name is "UTC". Returns an error for unknown timezone names.
func MicrosNow ¶
func MicrosNow() int64
MicrosNow returns the current Unix timestamp in microseconds.
func MillisNow ¶
func MillisNow() int64
MillisNow returns the current Unix timestamp in milliseconds.
func MustInLocation ¶
MustInLocation converts a time to the named timezone, panicking on error.
func MustLocation ¶
MustLocation is like Location but panics on error.
func NextBusinessDay ¶
NextBusinessDay returns the next business day after the given time.
func ParseDuration ¶
ParseDuration parses a duration string. Supports standard Go duration syntax (e.g. "1h30m", "500ms") and additional units:
- "d" for days (e.g. "3d" = 72h)
- "w" for weeks (e.g. "2w" = 336h)
func ParseIn ¶
ParseIn parses a time string using the given layout in the specified timezone. The parsed time is adjusted to the given location.
func ParseLocal ¶
ParseLocal parses a time string using the given layout in the local timezone.
func PreviousBusinessDay ¶
PreviousBusinessDay returns the previous business day before the given time.
func StartOfDay ¶
StartOfDay returns the start of the day (00:00:00) for the given time.
func StartOfHour ¶
StartOfHour returns the start of the hour for the given time.
func StartOfMinute ¶
StartOfMinute returns the start of the minute for the given time.
func StartOfMonth ¶
StartOfMonth returns the start of the month (1st day 00:00:00).
func StartOfWeek ¶
StartOfWeek returns the start of the week (Monday 00:00:00) for the given time.
func StartOfYear ¶
StartOfYear returns January 1st 00:00:00 of the given time's year.
Types ¶
type Countdown ¶
type Countdown struct {
// contains filtered or unexported fields
}
Countdown is a countdown timer that calls a function when the countdown reaches zero. It is not reusable; create a new one for each countdown.
func NewCountdown ¶
NewCountdown creates a countdown timer that fires fn after dur. The timer starts immediately.
func (*Countdown) Done ¶
func (c *Countdown) Done() <-chan struct{}
Done returns a channel that is closed when the countdown fires.
type Stopwatch ¶
type Stopwatch struct {
// contains filtered or unexported fields
}
Stopwatch is a simple stopwatch that can be started, stopped, and reset. It is safe for concurrent use.
func NewStopwatch ¶
func NewStopwatch() *Stopwatch
NewStopwatch creates a new stopwatch. The stopwatch is not running.
func (*Stopwatch) Elapsed ¶
Elapsed returns the total elapsed time, including the current running period if the stopwatch is running.
func (*Stopwatch) Lap ¶
Lap records a lap time and returns the duration since the last lap (or since Start if this is the first lap).
func (*Stopwatch) Reset ¶
func (s *Stopwatch) Reset()
Reset resets the stopwatch, clearing all elapsed time and laps.
type TimeRange ¶
TimeRange represents a half-open time range [Start, End).
func NewTimeRange ¶
NewTimeRange creates a TimeRange from start and end times.
func ThisMonthRange ¶
func ThisMonthRange() TimeRange
ThisMonthRange returns the time range for the current month.
func ThisWeekRange ¶
func ThisWeekRange() TimeRange
ThisWeekRange returns the time range for the current week.
func ThisYearRange ¶
func ThisYearRange() TimeRange
ThisYearRange returns the time range for the current year.
func TodayRange ¶
func TodayRange() TimeRange
TodayRange returns the time range for today [StartOfDay, EndOfDay].
func YesterdayRange ¶
func YesterdayRange() TimeRange
YesterdayRange returns the time range for yesterday.
func (TimeRange) ContainsInclusive ¶
ContainsInclusive returns true if the range contains the given time, inclusive of the end boundary.
func (TimeRange) Intersect ¶
Intersect returns the intersection of two ranges, or ok=false if they don't overlap.