Implement Parse() function that automatically detects and parses common
date formats without requiring explicit layout strings. This provides an
intuitive API for parsing dates from various sources while maintaining
type safety through proper error handling.
Supported formats:
- ISO format (YYYY-MM-DD): "2026-02-09"
- ISO with slash (YYYY/MM/DD): "2026/02/09"
- EU format (DD.MM.YYYY): "09.02.2026"
- RFC2822/RFC1123: "Mon, 09 Feb 2026 00:00:00 +0000"
Key features:
- Detects and rejects ambiguous slash formats (e.g., "01/02/2026")
- Returns clear, contextual errors for invalid or ambiguous inputs
- Never panics - all errors via return values
- Zero allocations for successful parses
- Comprehensive test coverage (98%)
Performance results:
- ISO format: 105.5 ns/op (94x faster than 10µs target)
- ISO slash: 118.3 ns/op
- EU format: 117.4 ns/op
- RFC2822: 257.8 ns/op
Test coverage:
- 42 unit tests covering valid formats, error cases, edge cases
- 3 example tests demonstrating usage patterns
- Benchmarks for all format types
- Parse() function: 100% coverage
Files added:
- parse.go: Main implementation with Parse() and helper functions
- parse_test.go: Comprehensive test suite with table-driven tests
Files modified:
- example_test.go: Added ExampleParse examples
- Add Add(value, unit) method for all 8 units
- Add Sub(value, unit) method (wraps Add with negative value)
- Implement month-end overflow logic for Months/Quarters/Years
- When adding months, if target day doesn't exist, snap to last day of month
- Handle all month-end combinations correctly
- Leap year support (Feb 29 edge cases)
- DST-safe calendar day arithmetic for Days unit
- Negative value support (Add(-1) == Sub(1))
- Method chaining support (fluent API)
- Immutability verified (original date never modified)
- Timezone preservation across operations
- Comprehensive table-driven tests for month-end edge cases
- All 30/31 day month combinations tested
- Leap year tests (Feb 29 -> Feb 28)
- Cross-year boundary tests
- Negative value tests
- Method chaining tests
- Performance benchmarks (all < 1µs)
- 98.8% test coverage (exceeds 95% requirement)
- Godoc with month-end overflow examples
Benchmark results:
- AddDays: ~42ns (< 1µs target) ✓
- AddMonths: ~191ns (< 1µs target) ✓
- AddYears: ~202ns (< 1µs target) ✓
- Method chaining: ~263ns for 3 ops ✓
- Zero allocations for all operations
All acceptance criteria met:
✓ Add() implemented for all 8 units
✓ Sub() implemented for all 8 units
✓ Month-end overflow logic correct
✓ Leap year handling (Feb 29 edge cases)
✓ DST handling (calendar days)
✓ Negative values supported
✓ Method chaining works
✓ Unit tests with 98.8% coverage
✓ Table-driven tests for month-end edge cases
✓ Benchmarks meet <1µs target
✓ Godoc comments with month-end examples
- Create errors.go with sentinel errors
- Define ErrInvalidFormat for parsing errors
- Define ErrInvalidTimezone for timezone errors
- Define ErrOverflow for date arithmetic overflow
- Comprehensive godoc for each error with usage context
- Document no-panic policy in error handling
- Document Must* variant panic behavior
- Example tests showing error handling patterns
- Tests for error uniqueness and errors.Is compatibility
- 100% coverage for error definitions
Error Handling Policy:
- Library never panics in normal operations
- All errors returned as values
- Use errors.Is() for error type checking
- Must* functions panic (for test/init use only)
All acceptance criteria met:
✓ errors.go file created
✓ ErrInvalidFormat defined
✓ ErrInvalidTimezone defined
✓ ErrOverflow defined
✓ Godoc for each error with usage context
✓ Documentation of no-panic policy
✓ Documentation of Must* panic behavior
✓ Example tests showing error handling patterns
- Add Next(weekday) method to jump to next occurrence of a weekday
- Add Prev(weekday) method to jump to previous occurrence of a weekday
- Next ALWAYS returns future date (never today, even if same weekday)
- Prev ALWAYS returns past date (never today, even if same weekday)
- Time of day preserved from source date
- Comprehensive unit tests for all weekday combinations
- Same-weekday edge case tests (Monday.Next(Monday) = next Monday)
- Timezone preservation tests
- Immutability verification tests
- Performance benchmarks (~45ns, well under 1µs target)
- Zero allocations for both operations
- 97.8% test coverage (exceeds 95% requirement)
- Godoc comments with same-weekday behavior examples
All acceptance criteria met:
✓ Next() implemented for all weekdays
✓ Prev() implemented for all weekdays
✓ Next() never returns today (always future)
✓ Prev() never returns today (always past)
✓ Time of day preserved from source
✓ Edge case: Same weekday correctly skips to next/prev week
✓ Unit tests for all weekday combinations
✓ Tests for same weekday edge case
✓ Benchmarks meet <1µs target (~45ns)
✓ Godoc comments with same-weekday behavior example
Changed module path from code.beautifulmachines.dev/quando to
code.beautifulmachines.dev/jakoubek/quando to include user namespace.
Updated:
- go.mod: module declaration
- example_test.go: import path
- Implement StartOf(unit) for Weeks, Months, Quarters, Years
- Implement EndOf(unit) for Weeks, Months, Quarters, Years
- Week snapping follows ISO 8601 (Monday start, Sunday end)
- Month-end handling for all month lengths (28/29/30/31 days)
- Quarter definitions: Q1=Jan-Mar, Q2=Apr-Jun, Q3=Jul-Sep, Q4=Oct-Dec
- Comprehensive unit tests for all units and edge cases
- Leap year handling for February
- Timezone preservation tests
- Immutability verification tests
- Performance benchmarks (all <200ns, well under 1µs target)
- Zero allocations for all operations
- 97.3% test coverage (exceeds 95% requirement)
- Godoc comments with usage examples
All acceptance criteria met:
✓ StartOf(Week) returns Monday 00:00:00
✓ EndOf(Week) returns Sunday 23:59:59
✓ StartOf(Month) returns 1st day 00:00:00
✓ EndOf(Month) handles all month lengths correctly
✓ StartOf(Quarter) returns correct quarter start
✓ EndOf(Quarter) returns correct quarter end
✓ StartOf(Year) returns Jan 1 00:00:00
✓ EndOf(Year) returns Dec 31 23:59:59
✓ Leap year handling for February
✓ Unit tests for all units and edge cases
✓ ISO 8601 week compliance tests
✓ Benchmarks meet <1µs target (all <200ns)
✓ Godoc comments with examples
- Define Unit type as int for type-safe time unit constants
- Implement all 8 unit constants (Seconds through Years) using iota
- Add String() method for debugging and error messages
- Comprehensive unit tests verifying constants, ordering, and comparability
- Type safety tests demonstrating compile-time safety
- Example tests showing usage patterns
- 100% test coverage (exceeds 95% requirement)
All acceptance criteria met:
✓ Unit type defined as int
✓ All 8 unit constants defined (Seconds through Years)
✓ Units use iota for ordering
✓ Godoc comments for Unit type and constants
✓ Unit tests verifying constants
- Add Clock interface with Now() and From(t time.Time) methods
- Implement DefaultClock using time.Now() for production code
- Implement FixedClock with fixed time for deterministic testing
- Add factory functions NewClock() and NewFixedClock(time.Time)
- Comprehensive unit tests demonstrating deterministic test patterns
- Edge case testing (epoch, year 0001, year 9999, nanoseconds)
- Timezone preservation tests
- Example tests showing test usage patterns
- Performance benchmarks for both clock implementations
- 100% test coverage (exceeds 95% requirement)
All acceptance criteria met:
✓ Clock interface defined
✓ DefaultClock implementation using time.Now()
✓ FixedClock implementation with fixed time
✓ NewClock() factory function
✓ NewFixedClock(time.Time) factory function
✓ Unit tests demonstrating deterministic test patterns
✓ Godoc comments
✓ Example test showing test usage pattern
- Add Date struct with time.Time and Lang fields
- Implement package-level constructors: Now(), From(time.Time)
- Add conversion methods: Time(), Unix(), FromUnix(int64)
- Support negative Unix timestamps (dates before 1970)
- Support full time.Time range (year 0001-9999+)
- Add WithLang() for i18n support (placeholder)
- Create package documentation in quando.go
- Comprehensive unit tests with 100% coverage
- Example tests for godoc
- Verify immutability through tests
All acceptance criteria met:
✓ Date struct defined with time.Time and Lang fields
✓ Now() returns current date
✓ From(time.Time) converts to Date
✓ Time() extracts underlying time.Time
✓ Unix() returns Unix timestamp (int64)
✓ FromUnix(int64) creates Date from timestamp
✓ Unit tests with 100% coverage (exceeds 95% requirement)
✓ Godoc comments for all exported types/functions
✓ Example tests in example_test.go
