Merge remote-tracking branch 'origin/develop' into develop

README.cn.md

@@ -71,7 +71,7 @@ carbon.SetDefault(carbon.Default{
 // 将标准 time.Time 转换成 Carbon
 carbon.CreateFromStdTime(time.Now())
 // 将 Carbon 转换成标准 time.Time
-carbon.Now().ToStdTime()
+carbon.Now().StdTime()
 ```
 
 ##### 昨天、今天、明天
@@ -1360,8 +1360,9 @@ fmt.Printf("%d", person.Field8) // 1596604455999999999
 
 目前支持的日历有
 
-* [中国农历](./calendar/lunar/README.cn.md "中国农历")
 * [儒略日/简化儒略日](./calendar/julian/README.cn.md "儒略日/简化儒略日")
+* [中国农历](./calendar/lunar/README.cn.md "中国农历")
+* [波斯历/伊朗历](./calendar/persian/README.cn.md "波斯历/伊朗历")
 
 ##### 国际化
 
@@ -1380,14 +1381,16 @@ fmt.Printf("%d", person.Field8) // 1596604455999999999
 * [乌克兰语(uk)](./lang/uk.json "乌克兰语"): 由 [open-git](https://github.com/open-git "open-git") 翻译
 * [罗马尼亚语(ro)](./lang/ro.json "罗马尼亚语"): 由 [DrOctavius](https://github.com/DrOctavius "DrOctavius") 翻译
 * [印度尼西亚语(id)](./lang/id.json "印度尼西亚语"): 由 [justpoypoy](https://github.com/justpoypoy "justpoypoy") 翻译
+* [意大利语(it)](./lang/it.json "意大利语"): 由 [nicoloHevelop](https://github.com/justpoypoy "nicoloHevelop") 翻译
 * [马来西亚巴哈马语(ms-MY)](./lang/ms-MY.json "马来西亚巴哈马语"): 由 [hollowaykeanho](https://github.com/hollowaykeanho "hollowaykeanho") 翻译
 * [法语(fr)](./lang/fr.json "法语"): 由 [hollowaykeanho](https://github.com/hollowaykeanho "hollowaykeanho") 翻译
 * [泰语(th)](./lang/th.json "泰语"): 由 [izcream](https://github.com/izcream "izcream") 翻译
 * [瑞典语(se)](./lang/se.json "瑞典语"): 由 [jwanglof](https://github.com/jwanglof "jwanglof") 翻译
-* [伊朗语(fa)](./lang/fa.json "伊朗语"): 由 [erfanMomeniii](https://github.com/ErfanMomeniii "ErfanMomeniii") 翻译
+* [波斯语(fa)](./lang/fa.json "波斯语"): 由 [erfanMomeniii](https://github.com/ErfanMomeniii "ErfanMomeniii") 翻译
 * [波兰语(nl)](./lang/nl.json "波兰语"): 由 [RemcoE33](https://github.com/RemcoE33 "RemcoE33") 翻译
 * [越南语(vi)](./lang/vi.json "越南语"): 由 [culy247](https://github.com/culy247 "culy247") 翻译
 * [印地语(hi)](./lang/hi.json "印地语"): 由 [chauhan17nitin](https://github.com/chauhan17nitin "chauhan17nitin") 翻译
+* [波兰语(pl)](./lang/pl.json "波兰语"): 由 [gouguoyin](https://github.com/gouguoyin "gouguoyin") 翻译
 
 目前支持的方法有
 

README.jp.md

@@ -75,7 +75,7 @@ carbon.SetDefault(carbon.Default{
 // 標準の time.Time を Carbon に変換します
 carbon.CreateFromStdTime(time.Now())
 // Carbon を標準の time.Time に変換します
-carbon.Now().ToStdTime()
+carbon.Now().StdTime()
 ```
 
 ##### 昨日、今日、明日
@@ -1360,8 +1360,9 @@ fmt.Printf("%d", person.Field8) // 1596604455999999999
 
 現在サポートされているカレンダーは
 
-* [中国の旧暦](./calendar/lunar/README.jp.md "中国の旧暦")
 * [儒略の日/簡略化儒略の日](./calendar/julian/README.jp.md "儒略日/简化儒略日")
+* [中国の旧暦](./calendar/lunar/README.jp.md "中国の旧暦")
+* [ペルシャ暦/イラン暦](./calendar/persian/README.jp.md "ペルシャ暦/イラン暦")
 
 ##### 国際化
 
@@ -1380,14 +1381,16 @@ fmt.Printf("%d", person.Field8) // 1596604455999999999
 * [ウクライナ語(uk)](./lang/uk.json "ウクライナ語")：[open-git](https://github.com/open-git "open-git") から翻訳されます
 * [ルーマニア語(ro)](./lang/ro.json "ルーマニア語"): [DrOctavius](https://github.com/DrOctavius "DrOctavius") から翻訳されます
 * [インドネシア語(id)](./lang/id.json "インドネシア語"): [justpoypoy](https://github.com/justpoypoy "justpoypoy") から翻訳されます
+* [イタリア語(it)](./lang/it.json "イタリア語"): [nicoloHevelop](https://github.com/hollowaykeanho "nicoloHevelop") から翻訳されます
 * [マレーシアバハマ語(ms-MY)](./lang/ms-MY.json "マレーシアバハマ語"): [hollowaykeanho](https://github.com/hollowaykeanho "hollowaykeanho") から翻訳されます
 * [フランス語(fr)](./lang/fr.json "フランス語"): [hollowaykeanho](https://github.com/hollowaykeanho "hollowaykeanho") から翻訳されます
 * [タイ語(th)](./lang/th.json "タイ語"): [izcream](https://github.com/izcream "izcream") から翻訳されます
 * [スウェーデン語(se)](./lang/se.json "スウェーデン語"):  [jwanglof](https://github.com/jwanglof "jwanglof") から翻訳されます
-* [イラン語(fa)](./lang/fa.json "イラン語"):  [Iranian](https://github.com/Iranian "Iranian") から翻訳されます
+* [ペルシア語(fa)](./lang/fa.json "ペルシア語"):  [Iranian](https://github.com/Iranian "Iranian") から翻訳されます
 * [ポーランド語(nl)](./lang/nl.json "ポーランド語"): [RemcoE33](https://github.com/RemcoE33 "RemcoE33") から翻訳されます
 * [ベトナム語(vi)](./lang/vi.json "ベトナム語"): [culy247](https://github.com/culy247 "culy247") から翻訳されます
 * [ヒンディー語(hi)](./lang/hi.json "ヒンディー語"): [chauhan17nitin](https://github.com/chauhan17nitin "chauhan17nitin") から翻訳されます
+* [ポーランド語(pl)](./lang/pl.json "ポーランド語"): [gouguoyin](https://github.com/gouguoyin "gouguoyin") から翻訳されます
 
 現在サポートされている方法
 

README.md

@@ -71,10 +71,10 @@ carbon.SetDefault(carbon.Default{
 ##### Convert between Carbon and Time
 
 ```go
-// Convert standard Time.time into Carbon
+// Convert standard Time.time to Carbon
 carbon.CreateFromStdTime(time.Now())
 // Convert Carbon to standard Time.time
-carbon.Now().ToStdTime()
+carbon.Now().StdTime()
 ```
 
 ##### Yesterday, today and tomorrow
@@ -1355,8 +1355,9 @@ fmt.Printf("%d", person.Field8) // 1596604455999999999
 
 The following calendars are supported
 
-* [Chinese Lunar](./calendar/lunar/README.md "Chinese Lunar")
 * [Julian Day/Modified Julian Day](./calendar/julian/README.md "JD/MJD")
+* [Chinese Lunar](./calendar/lunar/README.md "Chinese Lunar")
+* [Persian/Jalaali](./calendar/persian/README.md "Persian/Jalaali")
 
 ##### I18n
 
@@ -1379,16 +1380,18 @@ The following languages are supported
 * [Ukrainian(uk)](./lang/uk.json "Ukrainian"): translated by [open-git](https://github.com/open-git "open-git")
 * [Romanian(ro)](./lang/ro.json "Romanian"): translated by [DrOctavius](https://github.com/DrOctavius "DrOctavius")
 * [Indonesian(id)](./lang/id.json "Indonesian"): translated by [justpoypoy](https://github.com/justpoypoy "justpoypoy")
+* [Italian(it)](../blob/master/lang/it.json "Italian"): translated by [nicoloHevelop](https://github.com/nicoloHevelop "nicoloHevelop")
 * [Bahasa Malaysia(ms-MY)](./lang/ms-MY.json "Bahasa Malaysia"): translated
   by [hollowaykeanho](https://github.com/hollowaykeanho "hollowaykeanho")
 * [French(fr)](./lang/fr.json "French"): translated
   by [hollowaykeanho](https://github.com/hollowaykeanho "hollowaykeanho")
 * [Thailand(th)](./lang/th.json "Thailand"): translated by [izcream](https://github.com/izcream "izcream")
 * [Swedish(se)](./lang/se.json "Swedish"): translated by [jwanglof](https://github.com/jwanglof "jwanglof")
-* [Iranian(fa)](./lang/fa.json "Iranian"): translated by [erfanMomeniii](https://github.com/erfanMomeniii "erfanMomeniii")
+* [Farsi(fa)](./lang/fa.json "Farsi"): translated by [erfanMomeniii](https://github.com/erfanMomeniii "erfanMomeniii")
 * [Dutch(nl)](./lang/nl.json "Dutch"): translated by [RemcoE33](https://github.com/RemcoE33 "RemcoE33")
 * [VietNamese(vi)](./lang/vi.json "VietNam"): translated by [culy247](https://github.com/culy247 "culy247")
 * [Hindi(hi)](./lang/hi.json "India"): translated by [chauhan17nitin](https://github.com/chauhan17nitin "chauhan17nitin")
+* [Polish(pl)](./lang/pl.json "Polish"): translated by [gouguoyin](https://github.com/gouguoyin "gouguoyin")
 
 The following methods are supported
 

calendar.go

@@ -3,6 +3,7 @@ package carbon
 import (
 	"github.com/golang-module/carbon/v2/calendar/julian"
 	"github.com/golang-module/carbon/v2/calendar/lunar"
+	"github.com/golang-module/carbon/v2/calendar/persian"
 )
 
 // Lunar converts Carbon instance to Lunar instance.
@@ -37,3 +38,19 @@ func CreateFromJulian(f float64) Carbon {
 	t := julian.FromJulian(f).ToGregorian().Time
 	return CreateFromStdTime(t)
 }
+
+// Persian converts Carbon instance to Persian instance.
+// 将 Carbon 实例转化为 Persian 实例
+func (c Carbon) Persian() (j persian.Persian) {
+	if c.Error != nil {
+		return j
+	}
+	return persian.FromGregorian(c.StdTime()).ToPersian()
+}
+
+// CreateFromPersian creates a Carbon instance from Persian date and time.
+// 从 波斯日期 创建 Carbon 实例
+func CreateFromPersian(year, month, day, hour, minute, second int) Carbon {
+	t := persian.FromPersian(year, month, day, hour, minute, second).ToGregorian().Time
+	return CreateFromStdTime(t)
+}

calendar/gregorian.go

@@ -1,3 +1,4 @@
+// Package calendar is part of the Carbon package.
 package calendar
 
 import (
@@ -159,16 +160,25 @@ func (g Gregorian) Year() int {
 }
 
 // Month gets gregorian month like 8.
-// 获取公历月
+// 获取公历月，如 8
 func (g Gregorian) Month() int {
 	if g.IsZero() {
 		return 0
 	}
 	return int(g.Time.Month())
 }
 
+// Week gets gregorian week day like 0.
+// 获取周
+func (g Gregorian) Week() int {
+	if g.IsZero() {
+		return 0
+	}
+	return int(g.Time.Weekday())
+}
+
 // Day gets gregorian day like 5.
-// 获取公历日
+// 获取公历日，如 0
 func (g Gregorian) Day() int {
 	if g.IsZero() {
 		return 0
@@ -177,7 +187,7 @@ func (g Gregorian) Day() int {
 }
 
 // Hour gets gregorian hour like 13.
-// 获取公历小时
+// 获取公历小时，如 13
 func (g Gregorian) Hour() int {
 	if g.IsZero() {
 		return 0
@@ -186,7 +196,7 @@ func (g Gregorian) Hour() int {
 }
 
 // Minute gets gregorian minute like 14.
-// 获取公历分钟数
+// 获取公历分钟数，如 14
 func (g Gregorian) Minute() int {
 	if g.IsZero() {
 		return 0
@@ -195,7 +205,7 @@ func (g Gregorian) Minute() int {
 }
 
 // Second gets gregorian second like 15.
-// 获取公历秒数
+// 获取公历秒数，如 15
 func (g Gregorian) Second() int {
 	if g.IsZero() {
 		return 0
@@ -209,8 +219,8 @@ func (g Gregorian) Location() *time.Location {
 	return g.Time.Location()
 }
 
-// String implements the interface Stringer for Gregorian struct.
-// 实现 Stringer 接口
+// String implements Stringer interface and outputs a string in YYYY-MM-DD HH::ii::ss format like "2019-12-07 00:00:00".
+// 实现 Stringer 接口, 输出 YYYY-MM-DD HH::ii::ss 格式字符串，如 "2019-12-07 00:00:00"
 func (g Gregorian) String() string {
 	if g.IsZero() {
 		return ""

calendar/gregorian_test.go

@@ -56,6 +56,30 @@ func TestGregorian_Month(t *testing.T) {
 	}
 }
 
+func TestGregorian_Week(t *testing.T) {
+	type args struct {
+		g Gregorian
+	}
+	tests := []struct {
+		args args
+		want int
+	}{
+		{
+			args: args{NewGregorian(time.Time{})},
+			want: 0,
+		},
+		{
+			args: args{NewGregorian(time.Date(2020, 8, 5, 13, 14, 15, 0, time.Local))},
+			want: 3,
+		},
+	}
+	for index, tt := range tests {
+		t.Run(strconv.Itoa(index), func(t *testing.T) {
+			assert.Equalf(t, tt.want, tt.args.g.Week(), "args(%v)", tt.args.g)
+		})
+	}
+}
+
 func TestGregorian_Day(t *testing.T) {
 	type args struct {
 		g Gregorian

calendar/julian/julian.go

@@ -1,3 +1,4 @@
+// Package julian is part of the Carbon package.
 package julian
 
 import (
@@ -33,6 +34,9 @@ type Julian struct {
 // FromGregorian creates a Gregorian instance from time.Time.
 // 从标准 time.Time 创建 Gregorian 实例
 func FromGregorian(t time.Time) (g Gregorian) {
+	if t.IsZero() {
+		return
+	}
 	g.Time = t
 	return g
 }
@@ -62,29 +66,33 @@ func FromJulian(f float64) (j Julian) {
 // 将 Gregorian 实例转化为 Julian 实例
 func (g Gregorian) ToJulian() (j Julian) {
 	if g.IsZero() {
-		return j
+		return
 	}
 	y := g.Year()
 	m := g.Month()
 	d := float64(g.Day()) + ((float64(g.Second())/60+float64(g.Minute()))/60+float64(g.Hour()))/24
 	n := 0
+	f := false
 	if y*372+m*31+int(d) >= 588829 {
-		n = y / 100
-		n = 2 - n + n/4
+		f = true
 	}
 	if m <= 2 {
 		m += 12
 		y--
 	}
+	if f {
+		n = y / 100
+		n = 2 - n + n/4
+	}
 	jd := float64(int(365.25*(float64(y)+4716))) + float64(int(30.6001*(float64(m)+1))) + d + float64(n) - 1524.5
 	return FromJulian(jd)
 }
 
 // ToGregorian converts Julian instance to Gregorian instance.
 // 将 Julian 实例转化为 Gregorian 实例
 func (j Julian) ToGregorian() (g Gregorian) {
-	if j.jd == 0 || j.mjd == 0 {
-		return g
+	if j.IsZero() {
+		return
 	}
 	d := int(j.jd + 0.5)
 	f := j.jd + 0.5 - float64(d)
@@ -136,9 +144,18 @@ func (j Julian) MJD(precision ...int) float64 {
 	return parseFloat64(j.mjd, decimalPrecision)
 }
 
+// IsZero reports whether is zero time.
+// 是否是零值时间
+func (j Julian) IsZero() bool {
+	if j.jd == 0 || j.mjd == 0 {
+		return true
+	}
+	return false
+}
+
 // parseFloat64 round to n decimal places
 // 四舍五入保留 n 位小数点
 func parseFloat64(f float64, n int) float64 {
-	p := math.Pow10(n)
-	return math.Round(f*p) / p
+	p10 := math.Pow10(n)
+	return math.Round(f*p10) / p10
 }

calendar/julian/julian_test.go

@@ -23,6 +23,10 @@ func TestGregorian_ToJulian(t *testing.T) {
 			args: args{FromGregorian(time.Time{})},
 			want: want{FromJulian(0)},
 		},
+		{
+			args: args{FromGregorian(time.Date(1800, 1, 1, 0, 0, 0, 0, time.Local))},
+			want: want{FromJulian(2378496.5)},
+		},
 		{
 			args: args{FromGregorian(time.Date(2024, 1, 23, 0, 0, 0, 0, time.Local))},
 			want: want{FromJulian(2460332.5)},
@@ -96,6 +100,10 @@ func TestGregorian_JD(t *testing.T) {
 		args args
 		want float64
 	}{
+		{
+			args: args{FromGregorian(time.Date(1800, 1, 1, 0, 0, 0, 0, time.Local))},
+			want: 2378496.5,
+		},
 		{
 			args: args{FromGregorian(time.Date(2024, 1, 23, 0, 0, 0, 0, time.Local))},
 			want: 2460332.5,