doc: add doc for DayOfYear

* 增加判断某个日期是一年当中的第几天的方法

* 修改下函数名字

---------

Co-authored-by: huangxingming <huangxingming@kezaihui.com>

datetime/datetime.go

@@ -237,3 +237,13 @@ func BetweenSeconds(t1 time.Time, t2 time.Time) int64 {
 	index := t2.Unix() - t1.Unix()
 	return index
 }
+
+// DayOfYear returns which day of the year the parameter date `t` is.
+// Play: todo
+func DayOfYear(t time.Time) int {
+	y, m, d := t.Date()
+	firstDay := time.Date(y, 1, 1, 0, 0, 0, 0, t.Location())
+	nowDate := time.Date(y, m, d, 0, 0, 0, 0, t.Location())
+
+	return int(nowDate.Sub(firstDay).Hours() / 24)
+}

datetime/datetime_example_test.go

@@ -369,3 +369,23 @@ func ExampleBetweenSeconds() {
 	// 86400
 	// -86400
 }
+
+func ExampleDayOfYear() {
+	date1 := time.Date(2023, 02, 01, 1, 1, 1, 0, time.Local)
+	result1 := DayOfYear(date1)
+
+	date2 := time.Date(2023, 01, 02, 1, 1, 1, 0, time.Local)
+	result2 := DayOfYear(date2)
+
+	date3 := time.Date(2023, 01, 01, 1, 1, 1, 0, time.Local)
+	result3 := DayOfYear(date3)
+
+	fmt.Println(result1)
+	fmt.Println(result2)
+	fmt.Println(result3)
+
+	// Output:
+	// 31
+	// 1
+	// 0
+}

datetime/datetime_test.go

@@ -271,3 +271,18 @@ func TestIsLeapYear(t *testing.T) {
 	assert.Equal(true, result1)
 	assert.Equal(false, result2)
 }
+
+func TestDayOfYear(t *testing.T) {
+	assert := internal.NewAssert(t, "TestDayOfYear")
+	date1 := time.Date(2023, 02, 01, 1, 1, 1, 0, time.Local)
+	result1 := DayOfYear(date1)
+	assert.Equal(31, result1)
+
+	date2 := time.Date(2023, 01, 02, 1, 1, 1, 0, time.Local)
+	result2 := DayOfYear(date2)
+	assert.Equal(1, result2)
+
+	date3 := time.Date(2023, 01, 01, 1, 1, 1, 0, time.Local)
+	result3 := DayOfYear(date3)
+	assert.Equal(0, result3)
+}

docs/datetime.md

@@ -56,6 +56,7 @@ import (
 -   [ToIso8601](#ToIso8601)
 -   [IsLeapYear](#IsLeapYear)
 -   [BetweenSeconds](#BetweenSeconds)
+-   [DayOfYear](#DayOfYear)
 
 <div STYLE="page-break-after: always;"></div>
 
@@ -225,18 +226,18 @@ import (
 func main() {
     now := time.Now()
 
-	after1Year := datetime.AddYear(now, 1)
+    after1Year := datetime.AddYear(now, 1)
-	diff1 := after1Year.Sub(now)
+    diff1 := after1Year.Sub(now)
 
-	before1Year := datetime.AddYear(now, -1)
+    before1Year := datetime.AddYear(now, -1)
-	diff2 := before1Year.Sub(now)
+    diff2 := before1Year.Sub(now)
 
-	fmt.Println(diff1)
+    fmt.Println(diff1)
-	fmt.Println(diff2)
+    fmt.Println(diff2)
 
-	// Output:
+    // Output:
-	// 8760h0m0s
+    // 8760h0m0s
-	// -8760h0m0s
+    // -8760h0m0s
 }
 ```
 
@@ -1161,17 +1162,59 @@ import (
 
 func main() {
     today := time.Now()
-	tomorrow := AddDay(today, 1)
+    tomorrow := AddDay(today, 1)
-	yesterday := AddDay(today, -1)
+    yesterday := AddDay(today, -1)
 
-	result1 := datetime.BetweenSeconds(today, tomorrow)
+    result1 := datetime.BetweenSeconds(today, tomorrow)
-	result2 := datetime.BetweenSeconds(today, yesterday)
+    result2 := datetime.BetweenSeconds(today, yesterday)
 
-	fmt.Println(result1)
+    fmt.Println(result1)
-	fmt.Println(result2)
+    fmt.Println(result2)
 
-	// Output:
+    // Output:
-	// 86400
+    // 86400
-	// -86400
+    // -86400
+}
+```
+
+
+### <span id="DayOfYear">DayOfYear</span>
+
+<p>Returns which day of the year the parameter date `t` is.</p>
+
+<b>Signature:</b>
+
+```go
+func DayOfYear(t time.Time) int
+```
+
+<b>Example:</b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/datetime"
+)
+
+func main() {
+    date1 := time.Date(2023, 02, 01, 1, 1, 1, 0, time.Local)
+    result1 := datetime.DayOfYear(date1)
+
+    date2 := time.Date(2023, 01, 02, 1, 1, 1, 0, time.Local)
+    result2 := datetime.DayOfYear(date2)
+
+    date3 := time.Date(2023, 01, 01, 1, 1, 1, 0, time.Local)
+    result3 := datetime.DayOfYear(date3)
+
+    fmt.Println(result1)
+    fmt.Println(result2)
+    fmt.Println(result3)
+
+    // Output:
+    // 31
+    // 1
+    // 0
 }
 ```

docs/datetime_zh-CN.md

@@ -55,6 +55,7 @@ import (
 -   [ToIso8601](#ToIso8601)
 -   [IsLeapYear](#IsLeapYear)
 -   [BetweenSeconds](#BetweenSeconds)
+-   [DayOfYear](#DayOfYear)
 
 
 <div STYLE="page-break-after: always;"></div>
@@ -225,18 +226,18 @@ import (
 func main() {
     now := time.Now()
 
-	after1Year := datetime.AddYear(now, 1)
+    after1Year := datetime.AddYear(now, 1)
-	diff1 := after1Year.Sub(now)
+    diff1 := after1Year.Sub(now)
 
-	before1Year := datetime.AddYear(now, -1)
+    before1Year := datetime.AddYear(now, -1)
-	diff2 := before1Year.Sub(now)
+    diff2 := before1Year.Sub(now)
 
-	fmt.Println(diff1)
+    fmt.Println(diff1)
-	fmt.Println(diff2)
+    fmt.Println(diff2)
 
-	// Output:
+    // Output:
-	// 8760h0m0s
+    // 8760h0m0s
-	// -8760h0m0s
+    // -8760h0m0s
 }
 ```
 
@@ -1160,17 +1161,58 @@ import (
 
 func main() {
     today := time.Now()
-	tomorrow := AddDay(today, 1)
+    tomorrow := AddDay(today, 1)
-	yesterday := AddDay(today, -1)
+    yesterday := AddDay(today, -1)
 
-	result1 := datetime.BetweenSeconds(today, tomorrow)
+    result1 := datetime.BetweenSeconds(today, tomorrow)
-	result2 := datetime.BetweenSeconds(today, yesterday)
+    result2 := datetime.BetweenSeconds(today, yesterday)
 
-	fmt.Println(result1)
+    fmt.Println(result1)
-	fmt.Println(result2)
+    fmt.Println(result2)
 
-	// Output:
+    // Output:
-	// 86400
+    // 86400
-	// -86400
+    // -86400
+}
+```
+
+### <span id="DayOfYear">DayOfYear</span>
+
+<p>返回参数日期是一年中的第几天。</p>
+
+<b>函数签名:</b>
+
+```go
+func DayOfYear(t time.Time) int
+```
+
+<b>示例:</b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/datetime"
+)
+
+func main() {
+    date1 := time.Date(2023, 02, 01, 1, 1, 1, 0, time.Local)
+    result1 := datetime.DayOfYear(date1)
+
+    date2 := time.Date(2023, 01, 02, 1, 1, 1, 0, time.Local)
+    result2 := datetime.DayOfYear(date2)
+
+    date3 := time.Date(2023, 01, 01, 1, 1, 1, 0, time.Local)
+    result3 := datetime.DayOfYear(date3)
+
+    fmt.Println(result1)
+    fmt.Println(result2)
+    fmt.Println(result3)
+
+    // Output:
+    // 31
+    // 1
+    // 0
 }
 ```