79 lines
2.8 KiB
Go
79 lines
2.8 KiB
Go
|
package quando
|
||
|
|
|
||
|
|
import "errors"
|
||
|
|
|
||
|
|
// Error Handling Policy
|
||
|
|
//
|
||
|
|
// The quando library follows a strict no-panic policy for all normal operations.
|
||
|
|
// Errors are always returned as values, allowing calling code to handle them
|
||
|
|
// appropriately.
|
||
|
|
//
|
||
|
|
// Exception: Must* functions (e.g., MustParse) are provided for convenience
|
||
|
|
// in tests and initialization code. These functions panic on error and should
|
||
|
|
// never be used in production code where errors need to be handled gracefully.
|
||
|
|
//
|
||
|
|
// Error Types
|
||
|
|
//
|
||
|
|
// The library defines sentinel errors for common error conditions. Use errors.Is()
|
||
|
|
// to check for specific error types:
|
||
|
|
//
|
||
|
|
// date, err := quando.Parse("invalid")
|
||
|
|
// if errors.Is(err, quando.ErrInvalidFormat) {
|
||
|
|
// // Handle invalid format
|
||
|
|
// }
|
||
|
|
//
|
||
|
|
// For errors with context, use fmt.Errorf with %w to wrap errors:
|
||
|
|
//
|
||
|
|
// return Date{}, fmt.Errorf("parsing date %q: %w", input, quando.ErrInvalidFormat)
|
||
|
|
|
||
|
|
// ErrInvalidFormat indicates that a date string could not be parsed.
|
||
|
|
//
|
||
|
|
// This error is returned when:
|
||
|
|
// - The input string doesn't match any supported format
|
||
|
|
// - The format is ambiguous (e.g., "01/02/2026" without year prefix)
|
||
|
|
// - The date components are invalid (e.g., "2026-13-01" for month 13)
|
||
|
|
//
|
||
|
|
// Example:
|
||
|
|
//
|
||
|
|
// date, err := quando.Parse("not-a-date")
|
||
|
|
// if errors.Is(err, quando.ErrInvalidFormat) {
|
||
|
|
// log.Printf("Invalid date format: %v", err)
|
||
|
|
// }
|
||
|
|
var ErrInvalidFormat = errors.New("invalid date format")
|
||
|
|
|
||
|
|
// ErrInvalidTimezone indicates that a timezone name is not recognized.
|
||
|
|
//
|
||
|
|
// This error is returned when:
|
||
|
|
// - The IANA timezone name is not found in the system timezone database
|
||
|
|
// - The timezone string is malformed
|
||
|
|
//
|
||
|
|
// Valid timezone names include "UTC", "America/New_York", "Europe/Berlin", etc.
|
||
|
|
// See the IANA Time Zone Database for a complete list.
|
||
|
|
//
|
||
|
|
// Example:
|
||
|
|
//
|
||
|
|
// date, err := quando.Now().InTimezone("Invalid/Timezone")
|
||
|
|
// if errors.Is(err, quando.ErrInvalidTimezone) {
|
||
|
|
// log.Printf("Unknown timezone: %v", err)
|
||
|
|
// }
|
||
|
|
var ErrInvalidTimezone = errors.New("invalid timezone")
|
||
|
|
|
||
|
|
// ErrOverflow indicates that a date arithmetic operation would result in
|
||
|
|
// a date outside the representable range.
|
||
|
|
//
|
||
|
|
// This error is returned when:
|
||
|
|
// - Adding/subtracting would exceed Go's time.Time range (approximately year 0 to 9999)
|
||
|
|
// - The resulting date would be before the minimum or after the maximum representable time
|
||
|
|
//
|
||
|
|
// Example:
|
||
|
|
//
|
||
|
|
// date := quando.From(time.Date(9999, 12, 31, 0, 0, 0, 0, time.UTC))
|
||
|
|
// result, err := date.Add(1, quando.Years)
|
||
|
|
// if errors.Is(err, quando.ErrOverflow) {
|
||
|
|
// log.Printf("Date overflow: %v", err)
|
||
|
|
// }
|
||
|
|
//
|
||
|
|
// Note: In the current implementation, arithmetic operations that would overflow
|
||
|
|
// are handled by Go's time.Time, which has its own overflow behavior. This error
|
||
|
|
// is reserved for future use when explicit overflow detection is added.
|
||
|
|
var ErrOverflow = errors.New("date overflow")
|