timefmt/builder.go

package timefmt

// Builder provides a fluent interface for constructing Format instances.
// It uses a mutable pattern where each method modifies the builder and returns it for chaining.
type Builder struct {
	format *Format
}

// NewBuilder creates a new format builder with an empty format.
func NewBuilder() *Builder {
	return &Builder{
		format: &Format{
			fragments: make([]interface{}, 0),
		},
	}
}

// Year4 adds a 4-digit year (e.g., 2026) to the format.
func (b *Builder) Year4() *Builder {
	b.format.fragments = append(b.format.fragments, Year4Digit)
	return b
}

// Year2 adds a 2-digit year (e.g., 26) to the format.
func (b *Builder) Year2() *Builder {
	b.format.fragments = append(b.format.fragments, Year2Digit)
	return b
}

// MonthNumeric adds a numeric month without leading zero (1-12) to the format.
func (b *Builder) MonthNumeric() *Builder {
	b.format.fragments = append(b.format.fragments, MonthNumeric)
	return b
}

// MonthNumeric2 adds a 2-digit month with leading zero (01-12) to the format.
func (b *Builder) MonthNumeric2() *Builder {
	b.format.fragments = append(b.format.fragments, MonthNumeric2)
	return b
}

// MonthShort adds an abbreviated month name (Jan, Feb, Mar, etc.) to the format.
func (b *Builder) MonthShort() *Builder {
	b.format.fragments = append(b.format.fragments, MonthShort)
	return b
}

// MonthFull adds a full month name (January, February, March, etc.) to the format.
func (b *Builder) MonthFull() *Builder {
	b.format.fragments = append(b.format.fragments, MonthFull)
	return b
}

// DayNumeric adds a numeric day without leading zero (1-31) to the format.
func (b *Builder) DayNumeric() *Builder {
	b.format.fragments = append(b.format.fragments, DayNumeric)
	return b
}

// DayNumeric2 adds a 2-digit day with leading zero (01-31) to the format.
func (b *Builder) DayNumeric2() *Builder {
	b.format.fragments = append(b.format.fragments, DayNumeric2)
	return b
}

// DaySpacePadded adds a space-padded day ( 1-31) to the format.
func (b *Builder) DaySpacePadded() *Builder {
	b.format.fragments = append(b.format.fragments, DaySpacePadded)
	return b
}

// DayOfYear adds a 3-digit day of year (001-365) to the format.
func (b *Builder) DayOfYear() *Builder {
	b.format.fragments = append(b.format.fragments, DayOfYearNumeric)
	return b
}

// DayOfYearSpacePadded adds a space-padded day of year (  1-365) to the format.
func (b *Builder) DayOfYearSpacePadded() *Builder {
	b.format.fragments = append(b.format.fragments, DayOfYearSpacePadded)
	return b
}

// WeekdayShort adds an abbreviated weekday name (Mon, Tue, Wed, etc.) to the format.
func (b *Builder) WeekdayShort() *Builder {
	b.format.fragments = append(b.format.fragments, WeekdayShort)
	return b
}

// WeekdayFull adds a full weekday name (Monday, Tuesday, Wednesday, etc.) to the format.
func (b *Builder) WeekdayFull() *Builder {
	b.format.fragments = append(b.format.fragments, WeekdayFull)
	return b
}

// Hour24 adds a 24-hour format with leading zero (00-23) to the format.
func (b *Builder) Hour24() *Builder {
	b.format.fragments = append(b.format.fragments, Hour24)
	return b
}

// Hour12 adds a 12-hour format without leading zero (1-12) to the format.
func (b *Builder) Hour12() *Builder {
	b.format.fragments = append(b.format.fragments, Hour12)
	return b
}

// Hour12Padded adds a 12-hour format with leading zero (01-12) to the format.
func (b *Builder) Hour12Padded() *Builder {
	b.format.fragments = append(b.format.fragments, Hour12Padded)
	return b
}

// Minute adds a 2-digit minute with leading zero (00-59) to the format.
func (b *Builder) Minute() *Builder {
	b.format.fragments = append(b.format.fragments, Minute)
	return b
}

// MinuteUnpadded adds a minute without leading zero (0-59) to the format.
func (b *Builder) MinuteUnpadded() *Builder {
	b.format.fragments = append(b.format.fragments, MinuteUnpadded)
	return b
}

// Second adds a 2-digit second with leading zero (00-59) to the format.
func (b *Builder) Second() *Builder {
	b.format.fragments = append(b.format.fragments, Second)
	return b
}

// SecondUnpadded adds a second without leading zero (0-59) to the format.
func (b *Builder) SecondUnpadded() *Builder {
	b.format.fragments = append(b.format.fragments, SecondUnpadded)
	return b
}

// Millisecond adds milliseconds as 3 digits (.000) to the format.
func (b *Builder) Millisecond() *Builder {
	b.format.fragments = append(b.format.fragments, Millisecond)
	return b
}

// MillisecondTrim adds milliseconds with trailing zeros removed (.999) to the format.
func (b *Builder) MillisecondTrim() *Builder {
	b.format.fragments = append(b.format.fragments, MillisecondTrim)
	return b
}

// Microsecond adds microseconds as 6 digits (.000000) to the format.
func (b *Builder) Microsecond() *Builder {
	b.format.fragments = append(b.format.fragments, Microsecond)
	return b
}

// MicrosecondTrim adds microseconds with trailing zeros removed (.999999) to the format.
func (b *Builder) MicrosecondTrim() *Builder {
	b.format.fragments = append(b.format.fragments, MicrosecondTrim)
	return b
}

// Nanosecond adds nanoseconds as 9 digits (.000000000) to the format.
func (b *Builder) Nanosecond() *Builder {
	b.format.fragments = append(b.format.fragments, Nanosecond)
	return b
}

// NanosecondTrim adds nanoseconds with trailing zeros removed (.999999999) to the format.
func (b *Builder) NanosecondTrim() *Builder {
	b.format.fragments = append(b.format.fragments, NanosecondTrim)
	return b
}

// AMPM adds an AM/PM marker in uppercase to the format.
func (b *Builder) AMPM() *Builder {
	b.format.fragments = append(b.format.fragments, AMPM)
	return b
}

// AMPMLower adds an am/pm marker in lowercase to the format.
func (b *Builder) AMPMLower() *Builder {
	b.format.fragments = append(b.format.fragments, AMPMLower)
	return b
}

// TimezoneOffset adds a timezone offset as ±HHMM (e.g., -0700) to the format.
func (b *Builder) TimezoneOffset() *Builder {
	b.format.fragments = append(b.format.fragments, TimezoneOffset)
	return b
}

// TimezoneOffsetColon adds a timezone offset as ±HH:MM (e.g., -07:00) to the format.
func (b *Builder) TimezoneOffsetColon() *Builder {
	b.format.fragments = append(b.format.fragments, TimezoneOffsetColon)
	return b
}

// TimezoneOffsetHourOnly adds a timezone offset hours only as ±HH (e.g., -07) to the format.
func (b *Builder) TimezoneOffsetHourOnly() *Builder {
	b.format.fragments = append(b.format.fragments, TimezoneOffsetHourOnly)
	return b
}

// TimezoneOffsetSeconds adds a timezone offset with seconds as ±HHMMSS (e.g., -070000) to the format.
func (b *Builder) TimezoneOffsetSeconds() *Builder {
	b.format.fragments = append(b.format.fragments, TimezoneOffsetSeconds)
	return b
}

// TimezoneOffsetColonSeconds adds a timezone offset with seconds as ±HH:MM:SS (e.g., -07:00:00) to the format.
func (b *Builder) TimezoneOffsetColonSeconds() *Builder {
	b.format.fragments = append(b.format.fragments, TimezoneOffsetColonSeconds)
	return b
}

// TimezoneISO8601 adds an ISO 8601 timezone with Z for UTC (e.g., Z or -0700) to the format.
func (b *Builder) TimezoneISO8601() *Builder {
	b.format.fragments = append(b.format.fragments, TimezoneISO8601)
	return b
}

// TimezoneISO8601Colon adds an ISO 8601 timezone with colon (e.g., Z or -07:00) to the format.
func (b *Builder) TimezoneISO8601Colon() *Builder {
	b.format.fragments = append(b.format.fragments, TimezoneISO8601Colon)
	return b
}

// TimezoneName adds a timezone abbreviation (e.g., MST, PST) to the format.
func (b *Builder) TimezoneName() *Builder {
	b.format.fragments = append(b.format.fragments, TimezoneName)
	return b
}

// Literal adds arbitrary literal text to the format.
func (b *Builder) Literal(s string) *Builder {
	b.format.fragments = append(b.format.fragments, s)
	return b
}

// Dash adds a dash (-) to the format.
func (b *Builder) Dash() *Builder {
	return b.Literal("-")
}

// Slash adds a slash (/) to the format.
func (b *Builder) Slash() *Builder {
	return b.Literal("/")
}

// Colon adds a colon (:) to the format.
func (b *Builder) Colon() *Builder {
	return b.Literal(":")
}

// Space adds a space ( ) to the format.
func (b *Builder) Space() *Builder {
	return b.Literal(" ")
}

// T adds a literal 'T' to the format (commonly used in ISO 8601).
func (b *Builder) T() *Builder {
	return b.Literal("T")
}

// Comma adds a comma and space (, ) to the format.
func (b *Builder) Comma() *Builder {
	return b.Literal(", ")
}

// Period adds a period (.) to the format.
func (b *Builder) Period() *Builder {
	return b.Literal(".")
}

// Build finalizes the builder and returns the constructed Format.
func (b *Builder) Build() *Format {
	return b.format
}