isnow

README

docs

Documentation

Overview

Package isnow implements the DTimpalr date/time pattern language: an isnow holds at an instant when every field constraint is satisfied. The defining operation is the membership test, Pattern.Holds(at); Next/Prev derive occurrences from it. See github.com/tsvsheet/isnow (SPECIFICATION.md) for the language and specs/contracts/ for the pinned semantics.

Index

• Constants
• func Code(err error) string
• func Is(src string, at time.Time) (bool, error)
• type Pattern
  • func Parse(src string) (Pattern, error)
  • func (p Pattern) Canonical() string
  • func (p Pattern) Explain() string
  • func (p Pattern) Holds(at time.Time) bool
  • func (p Pattern) Next(from time.Time) (time.Time, bool)
  • func (p Pattern) NextContext(ctx context.Context, from time.Time) (time.Time, bool, error)
  • func (p Pattern) Prev(from time.Time) (time.Time, bool)
  • func (p Pattern) PrevContext(ctx context.Context, from time.Time) (time.Time, bool, error)
  • func (p Pattern) String() string

Constants

const (
	// ErrSyntax is a malformed pattern the grammar rejects.
	ErrSyntax errs.Const = "syntax"
	// ErrSymbol is an unknown or ambiguous weekday/time/unit name.
	ErrSymbol errs.Const = "symbol"
	// ErrRange is a value outside its field's domain.
	ErrRange errs.Const = "range"
	// ErrContext is a grammatical but semantically invalid construct.
	ErrContext errs.Const = "context"
)

The four stable error codes every implementation shares (specs/contracts/ semantics.md). Callers match with errors.Is.

Functions

func Code

func Code(err error) string

Code returns the stable string code of a library error (syntax, symbol, range, context), or "" if err is nil or not a library error.

func Is

func Is(src string, at time.Time) (bool, error)

Is is the one-shot membership test: Parse then Holds.

Types

type Pattern

type Pattern struct {
	// contains filtered or unexported fields
}

Pattern is a parsed, canonicalized isnow. The zero value is not usable; obtain one from Parse. Patterns are immutable and safe to copy and share.

func Parse

func Parse(src string) (Pattern, error)

Parse recognizes src, resolves symbols and the shorthand ladder, and validates field domains. It returns one of ErrSyntax, ErrSymbol, ErrRange, or ErrContext.

func (Pattern) Canonical

func (p Pattern) Canonical() string

Canonical returns the fully-qualified seven-field form of the isnow.

func (Pattern) Explain

func (p Pattern) Explain() string

Explain returns a deterministic English description of the isnow, built from the terminology vocabulary. The wording is implementation-defined (not pinned by the conformance corpus).

func (Pattern) Holds

func (p Pattern) Holds(at time.Time) bool

Holds reports whether the isnow holds at the instant: every field constraint and every bound is satisfied. The instant is evaluated in its own location (at.Location()) and truncated to whole seconds.

func (Pattern) Next

func (p Pattern) Next(from time.Time) (time.Time, bool)

Next returns the earliest occurrence strictly after from, or false when none exists within the pattern's window or the 100-year horizon.

func (Pattern) NextContext

func (p Pattern) NextContext(ctx context.Context, from time.Time) (time.Time, bool, error)

NextContext is Next with cancellation: the search aborts and returns ctx's error when the context is done, so an unbounded scan on a pathological pattern (e.g. an impossible bounded window) cannot pin a CPU indefinitely. The context is checked once per civil day, bounding a cancelled search to at most a single day's enumeration.

func (Pattern) Prev

func (p Pattern) Prev(from time.Time) (time.Time, bool)

Prev returns the latest occurrence strictly before from, or false when none.

func (Pattern) PrevContext

func (p Pattern) PrevContext(ctx context.Context, from time.Time) (time.Time, bool, error)

PrevContext is Prev with cancellation (see NextContext).

func (Pattern) String

func (p Pattern) String() string

String returns the canonical form (fmt.Stringer).