added Period initial commit

example_test.go

@@ -390,3 +390,113 @@ func ExampleAfter() {
 	}
 	// Output: timed out
 }
+
+func ExampleNewPeriod() {
+	// with synchro.Time params
+	p1, _ := synchro.NewPeriod[tz.UTC](
+		synchro.New[tz.UTC](2009, 1, 1, 0, 0, 0, 0),
+		synchro.New[tz.UTC](2009, 1, 10, 23, 59, 59, 0),
+	)
+	// with time.Time params
+	p2, _ := synchro.NewPeriod[tz.UTC](
+		time.Date(2009, 1, 1, 0, 0, 0, 0, time.UTC),
+		time.Date(2009, 1, 10, 23, 59, 59, 0, time.UTC),
+	)
+	// with ISO 8601 date and time format string or bytes
+	p3, _ := synchro.NewPeriod[tz.UTC](
+		"2009-01-01",
+		[]byte("2009-01-10T23:59:59Z"),
+	)
+	// Reverse
+	p4, _ := synchro.NewPeriod[tz.UTC](
+		"2009-01-10T23:59:59",
+		"2009-01-01",
+	)
+	fmt.Printf("p1: %s\n", p1)
+	fmt.Printf("p2: %s\n", p2)
+	fmt.Printf("p3: %s\n", p3)
+	fmt.Printf("p4: %s\n", p4)
+	// Output:
+	// p1: from 2009-01-01 00:00:00 +0000 UTC to 2009-01-10 23:59:59 +0000 UTC
+	// p2: from 2009-01-01 00:00:00 +0000 UTC to 2009-01-10 23:59:59 +0000 UTC
+	// p3: from 2009-01-01 00:00:00 +0000 UTC to 2009-01-10 23:59:59 +0000 UTC
+	// p4: from 2009-01-10 23:59:59 +0000 UTC to 2009-01-01 00:00:00 +0000 UTC
+}
+
+func ExamplePeriod_PeriodicDuration() {
+	p1, _ := synchro.NewPeriod[tz.UTC](
+		"2009-01-01",
+		synchro.New[tz.UTC](2009, 1, 1, 3, 59, 59, 0),
+	)
+	for current := range p1.PeriodicDuration(time.Hour) {
+		fmt.Println(current)
+	}
+	// Output:
+	// 2009-01-01 00:00:00 +0000 UTC
+	// 2009-01-01 01:00:00 +0000 UTC
+	// 2009-01-01 02:00:00 +0000 UTC
+	// 2009-01-01 03:00:00 +0000 UTC
+}
+
+func ExamplePeriod_PeriodicDate() {
+	p1, _ := synchro.NewPeriod[tz.UTC](
+		"2009-01-01",
+		"2009-01-03",
+	)
+	for current := range p1.PeriodicDate(0, 0, 1) {
+		fmt.Println(current)
+	}
+	// Output:
+	// 2009-01-01 00:00:00 +0000 UTC
+	// 2009-01-02 00:00:00 +0000 UTC
+	// 2009-01-03 00:00:00 +0000 UTC
+}
+
+func ExamplePeriod_PeriodicAdvance() {
+	p1, _ := synchro.NewPeriod[tz.UTC](
+		"2009-01-01",
+		time.Date(2013, 1, 3, 0, 0, 0, 0, time.UTC),
+	)
+	for current := range p1.PeriodicAdvance(synchro.Year(1), synchro.Day(1)) {
+		fmt.Println(current)
+	}
+	// Output:
+	// 2009-01-01 00:00:00 +0000 UTC
+	// 2010-01-02 00:00:00 +0000 UTC
+	// 2011-01-03 00:00:00 +0000 UTC
+	// 2012-01-04 00:00:00 +0000 UTC
+}
+
+func ExamplePeriod_PeriodicISODuration() {
+	p1, _ := synchro.NewPeriod[tz.UTC](
+		"2009-01-01",
+		"2009-03-01",
+	)
+	iter, _ := p1.PeriodicISODuration("P1M")
+	for current := range iter {
+		fmt.Println(current)
+	}
+	// Output:
+	// 2009-01-01 00:00:00 +0000 UTC
+	// 2009-02-01 00:00:00 +0000 UTC
+	// 2009-03-01 00:00:00 +0000 UTC
+}
+
+func ExamplePeriod_periodicalSlice() {
+	p1, _ := synchro.NewPeriod[tz.UTC](
+		"2009-01-01T00:00:00",
+		"2009-01-01T03:00:00",
+	)
+
+	got := p1.PeriodicDuration(time.Hour).Slice()
+	fmt.Println("len:", len(got))
+	for _, current := range got {
+		fmt.Println(current)
+	}
+	// Output:
+	// len: 4
+	// 2009-01-01 00:00:00 +0000 UTC
+	// 2009-01-01 01:00:00 +0000 UTC
+	// 2009-01-01 02:00:00 +0000 UTC
+	// 2009-01-01 03:00:00 +0000 UTC
+}

iso8601/duration.go

@@ -589,6 +589,21 @@ const monthInSecond = 2630016 * time.Second // 30.44 days * 3600 * 24 seconds
 const weekInSecond = 7 * dayInSecond
 const dayInSecond = 24 * 3600 * time.Second
 
+// StdClockDuration converts an ISO8601 Duration to a standard Go time.Duration.
+// The conversion is calculated using hours, minutes, seconds, milliseconds, microseconds and nanoseconds.
+func (d Duration) StdClockDuration() time.Duration {
+	duration := time.Duration(d.Hour)*time.Hour +
+		time.Duration(d.Minute)*time.Minute +
+		time.Duration(d.Second)*time.Second +
+		time.Duration(d.Millisecond)*time.Millisecond +
+		time.Duration(d.Microsecond)*time.Microsecond +
+		time.Duration(d.Nanosecond)
+	if d.Negative {
+		duration = -duration
+	}
+	return time.Duration(duration)
+}
+
 // StdDuration converts the ISO8601 Duration to a standard Go time.Duration.
 // Note: This conversion is an approximation. The duration of some components
 // like years and months are averaged based on typical values:

iso8601/duration_test.go

@@ -1480,6 +1480,109 @@ func TestDuration_StdDuration(t *testing.T) {
 	}
 }
 
+func TestDuration_StdClockDuration(t *testing.T) {
+	tests := []struct {
+		name string
+		d    Duration
+		want time.Duration
+	}{
+		{
+			name: "8765h49m12s", // 1 year
+			d: Duration{
+				Year: 1,
+			},
+			want: 0,
+		},
+		{
+			name: "730h33m36s", // 1 month
+			d: Duration{
+				Month: 1,
+			},
+			want: 0,
+		},
+		{
+			name: "168h0m0s", // 1 week
+			d: Duration{
+				Week: 1,
+			},
+			want: 0,
+		},
+		{
+			name: "24h0m0s", // 1 day
+			d: Duration{
+				Day: 1,
+			},
+			want: 0,
+		},
+		{
+			name: "1h0m0s",
+			d: Duration{
+				Hour: 1,
+			},
+			want: time.Hour,
+		},
+		{
+			name: "1m0s",
+			d: Duration{
+				Minute: 1,
+			},
+			want: time.Minute,
+		},
+		{
+			name: "1s",
+			d: Duration{
+				Second: 1,
+			},
+			want: time.Second,
+		},
+		{
+			name: "1ms",
+			d: Duration{
+				Millisecond: 1,
+			},
+			want: time.Millisecond,
+		},
+		{
+			name: "1µs",
+			d: Duration{
+				Microsecond: 1,
+			},
+			want: time.Microsecond,
+		},
+		{
+			name: "1ns",
+			d: Duration{
+				Nanosecond: 1,
+			},
+			want: time.Nanosecond,
+		},
+		{
+			name: "8765h49m13s", // 1 year + 1 sec
+			d: Duration{
+				Year:   1,
+				Second: 1,
+			},
+			want: time.Second,
+		},
+		{
+			name: "-730h34m36s", // 1 month + 1 minute
+			d: Duration{
+				Month:    1,
+				Minute:   1,
+				Negative: true,
+			},
+			want: -1 * (time.Minute),
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := tt.d.StdClockDuration(); got != tt.want {
+				t.Errorf("Duration.StdClockDuration() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
 func TestNewDuration(t *testing.T) {
 	tests := []struct {
 		d    time.Duration