Add DiffInDuration and DiffAbsInDuration methods

README.cn.md

@@ -65,7 +65,7 @@ carbon.SetDefault(carbon.Default{
 
 > 如果没有设置，默认布局模板是 `2006-01-02 15:04:05`, 默认时区是 `Local`, 默认一周开始日期是 `Sunday(周日)`, 默认语言是 `en`
 
-##### Carbon 和 time.Time 互转
+##### `Carbon` 和 `time.Time` 互转
 
 ```go
 // 将标准 time.Time 转换成 Carbon
@@ -142,7 +142,7 @@ carbon.Tomorrow().TimestampMicro() // 1596690855999999
 carbon.Tomorrow().TimestampNano() // 1596690855999999999
 ```
 
-##### 创建 Carbon 实例
+##### 创建 `Carbon` 实例
 
 ```go
 // 从秒级时间戳创建 Carbon 实例
@@ -185,7 +185,7 @@ carbon.CreateFromTimeMicro(13, 14, 15, 999999).ToString() // 2020-08-05 13:14:15
 carbon.CreateFromTimeNano(13, 14, 15, 999999999).ToString() // 2020-08-05 13:14:15.999999999 +0800 CST
 ```
 
-##### 将时间字符串解析成 Carbon 实例
+##### 将 `时间字符串` 解析成 `Carbon` 实例
 
 ```go
 carbon.Parse("").ToDateTimeString() // 空字符串
@@ -234,7 +234,7 @@ carbon.Parse("20200805131415.999999999+08:00").ToString() // 2020-08-05 13:14:15
 
 ```
 
-##### 通过格式模板将时间字符串解析成 Carbon 实例
+##### 通过 `格式模板` 将时间字符串解析成 `Carbon` 实例
 
 > 如果使用的字母与格式模板冲突时，请使用转义符转义该字母
 
@@ -245,7 +245,7 @@ carbon.ParseByFormat("今天是 2020年08月05日13时14分15秒", "今天是 Y
 carbon.ParseByFormat("2020-08-05 13:14:15", "Y-m-d H:i:s", carbon.Tokyo).ToDateTimeString() // 2020-08-05 14:14:15
 ```
 
-##### 通过布局模板将时间字符串解析成 Carbon 实例
+##### 通过 `布局模板` 将时间字符串解析成 `Carbon` 实例
 
 ```go
 carbon.ParseByLayout("2020|08|05 13|14|15", "2006|01|02 15|04|05").ToDateTimeString() // 2020-08-05 13:14:15
@@ -540,6 +540,16 @@ carbon.Now().DiffAbsInString(carbon.Now()) // just now
 carbon.Now().AddYearsNoOverflow(1).DiffAbsInString(carbon.Now()) // 1 year
 carbon.Now().SubYearsNoOverflow(1).DiffAbsInString(carbon.Now()) // 1 year
 
+// 相差时长
+now := carbon.Now()
+now.DiffInDuration(now).String() // 0s
+now.AddHour().DiffInDuration(now).String() // 1h0m0s
+now.SubHour().DiffInDuration(now).String() // -1h0m0s
+// 相差时长（绝对值）
+now.DiffAbsInDuration(now) // 0s
+now.AddHour().DiffAbsInDuration(carbon.Now()) // 1h0m0s
+now.SubHour().DiffAbsInDuration(carbon.Now()) // 1h0m0s
+
 // 对人类友好的可读格式时间差
 carbon.Parse("2020-08-05 13:14:15").DiffForHumans() // just now
 carbon.Parse("2019-08-05 13:14:15").DiffForHumans() // 1 year ago

README.jp.md

@@ -540,6 +540,16 @@ carbon.Now().DiffAbsInString(carbon.Now()) // just now
 carbon.Now().AddYearsNoOverflow(1).DiffAbsInString(carbon.Now()) // 1 year
 carbon.Now().SubYearsNoOverflow(1).DiffAbsInString(carbon.Now()) // 1 year
 
+// 相差時間長
+now := carbon.Now()
+now.DiffInDuration(now).String() // 0s
+now.AddHour().DiffInDuration(now).String() // 1h0m0s
+now.SubHour().DiffInDuration(now).String() // -1h0m0s
+// 相差時間長（絶対値）
+now.DiffAbsInDuration(now) // 0s
+now.AddHour().DiffAbsInDuration(carbon.Now()) // 1h0m0s
+now.SubHour().DiffAbsInDuration(carbon.Now()) // 1h0m0s
+
 // 人間に優しい読み取り可能なフォーマットの時間差を取得します
 carbon.Parse("2020-08-05 13:14:15").DiffForHumans() // just now
 carbon.Parse("2019-08-05 13:14:15").DiffForHumans() // 1 year ago

README.md

@@ -68,7 +68,7 @@ carbon.SetDefault(carbon.Default{
 
 > If not set, the default layout is `2006-01-02 15:04:05`, the default timezone is `Local`, the default week start date is `Sunday` and the default language locale is `en`
 
-##### Convert between Carbon and Time
+##### Convert between `Carbon` and `time.Time`
 
 ```go
 // Convert standard Time.time to Carbon
@@ -145,7 +145,7 @@ carbon.Tomorrow().TimestampMicro() // 1596690855999999
 carbon.Tomorrow().TimestampNano() // 1596690855999999999
 ```
 
-##### Create a Carbon instance
+##### Create a `Carbon` instance
 
 ```go
 // Create a Carbon instance from a given timestamp with second
@@ -188,7 +188,7 @@ carbon.CreateFromTimeMicro(13, 14, 15, 999999).ToString() // 2020-08-05 13:14:15
 carbon.CreateFromTimeNano(13, 14, 15, 999999999).ToString() // 2020-08-05 13:14:15.999999999 +0800 CST
 ```
 
-##### Parse a time string as a Carbon instance
+##### Parse a time string as a `Carbon` instance
 
 ```go
 carbon.Parse("").ToDateTimeString() // empty string
@@ -236,15 +236,15 @@ carbon.Parse("20200805131415.999999+08:00").ToString() // 2020-08-05 13:14:15.99
 carbon.Parse("20200805131415.999999999+08:00").ToString() // 2020-08-05 13:14:15.999999999 +0800 CST
 ```
 
-##### Parse a time string as a Carbon instance by format
+##### Parse a time string as a `Carbon` instance by format
 
 ```go
 carbon.ParseByFormat("2020|08|05 13|14|15", "Y|m|d H|i|s").ToDateTimeString() // 2020-08-05 13:14:15
 carbon.ParseByFormat("It is 2020-08-05 13:14:15", "\\I\\t \\i\\s Y-m-d H:i:s").ToDateTimeString() // 2020-08-05 13:14:15
 carbon.ParseByFormat("今天是 2020年08月05日13时14分15秒", "今天是 Y年m月d日H时i分s秒").ToDateTimeString() // 2020-08-05 13:14:15
 ```
 
-##### Parse a time string as a Carbon instance by layout
+##### Parse a time string as a `Carbon` instance by layout
 
 ```go
 carbon.ParseByLayout("2020|08|05 13|14|15", "2006|01|02 15|04|05").ToDateTimeString() // 2020-08-05 13:14:15
@@ -537,6 +537,16 @@ carbon.Now().DiffAbsInString(carbon.Now()) // just now
 carbon.Now().AddYearsNoOverflow(1).DiffAbsInString(carbon.Now()) // 1 year
 carbon.Now().SubYearsNoOverflow(1).DiffAbsInString(carbon.Now()) // 1 year
 
+// Difference in duration
+now := carbon.Now()
+now.DiffInDuration(now).String() // 0s
+now.AddHour().DiffInDuration(now).String() // 1h0m0s
+now.SubHour().DiffInDuration(now).String() // -1h0m0s
+// Difference in duration with absolute value
+now.DiffAbsInDuration(now) // 0s
+now.AddHour().DiffAbsInDuration(carbon.Now()) // 1h0m0s
+now.SubHour().DiffAbsInDuration(carbon.Now()) // 1h0m0s
+
 // Difference in a human-readable format
 carbon.Parse("2020-08-05 13:14:15").DiffForHumans() // just now
 carbon.Parse("2019-08-05 13:14:15").DiffForHumans() // 1 year ago

difference.go

@@ -3,6 +3,7 @@ package carbon
 import (
 	"math"
 	"strings"
+	"time"
 )
 
 // DiffInYears gets the difference in years.
@@ -185,6 +186,32 @@ func (c Carbon) DiffAbsInString(carbon ...Carbon) string {
 	return c.lang.translate(unit, getAbsValue(value))
 }
 
+// DiffInDuration gets the difference in duration.
+// 相差时长
+func (c Carbon) DiffInDuration(carbon ...Carbon) time.Duration {
+	end := c.Now()
+	if c.IsSetTestNow() {
+		end = CreateFromTimestampNano(c.testNow, c.Location())
+	}
+	if len(carbon) > 0 {
+		end = carbon[0]
+	}
+	return end.StdTime().Sub(c.StdTime())
+}
+
+// DiffAbsInDuration gets the difference in duration with absolute value.
+// 相差时长(绝对值)
+func (c Carbon) DiffAbsInDuration(carbon ...Carbon) time.Duration {
+	end := c.Now()
+	if c.IsSetTestNow() {
+		end = CreateFromTimestampNano(c.testNow, c.Location())
+	}
+	if len(carbon) > 0 {
+		end = carbon[0]
+	}
+	return end.StdTime().Sub(c.StdTime()).Abs()
+}
+
 // DiffForHumans gets the difference in a human-readable format, i18n is supported.
 // 获取对人类友好的可读格式时间差，支持i18n
 func (c Carbon) DiffForHumans(carbon ...Carbon) string {

difference_bench_test.go

@@ -114,6 +114,20 @@ func BenchmarkCarbon_DiffAbsInString(b *testing.B) {
 	}
 }
 
+func BenchmarkCarbon_DiffInDuration(b *testing.B) {
+	now := Now()
+	for n := 0; n < b.N; n++ {
+		now.DiffInDuration(Yesterday())
+	}
+}
+
+func BenchmarkCarbon_DiffAbsInDuration(b *testing.B) {
+	now := Now()
+	for n := 0; n < b.N; n++ {
+		now.DiffAbsInDuration(Yesterday())
+	}
+}
+
 func BenchmarkCarbon_DiffForHumans(b *testing.B) {
 	now := Now()
 	for n := 0; n < b.N; n++ {