From 8a1dd407381936ddbe9990672fe98c2e2b9d31a7 Mon Sep 17 00:00:00 2001 From: dudaodong Date: Thu, 18 May 2023 10:27:37 +0800 Subject: [PATCH] doc: add doc for AddYear function --- datetime/datetime.go | 2 + docs/datetime.md | 90 ++++++++---- docs/datetime_zh-CN.md | 318 +++++++++++++++++++++++------------------ 3 files changed, 248 insertions(+), 162 deletions(-) diff --git a/datetime/datetime.go b/datetime/datetime.go index 6e20178..a25508d 100644 --- a/datetime/datetime.go +++ b/datetime/datetime.go @@ -72,6 +72,8 @@ func AddDay(t time.Time, day int64) time.Time { return t.Add(24 * time.Hour * time.Duration(day)) } +// AddYear add or sub year to the time. +// Play: todo func AddYear(t time.Time, year int64) time.Time { return t.Add(365 * 24 * time.Hour * time.Duration(year)) } diff --git a/docs/datetime.md b/docs/datetime.md index fcf45bb..eaee68a 100644 --- a/docs/datetime.md +++ b/docs/datetime.md @@ -26,6 +26,7 @@ import ( - [AddDay](#AddDay) - [AddHour](#AddHour) - [AddMinute](#AddMinute) +- [AddYear](#AddYear) - [BeginOfMinute](#BeginOfMinute) - [BeginOfHour](#BeginOfHour) - [BeginOfDay](#BeginOfDay) @@ -198,6 +199,45 @@ func main() { } ``` +### AddYear + +

Add or sub year to the time.

+ +Signature: + +```go +func AddYear(t time.Time, year int64) time.Time +``` + +Example: + +```go +package main + +import ( + "fmt" + "time" + "github.com/duke-git/lancet/v2/datetime" +) + +func main() { + now := time.Now() + + after1Year := AddYear(now, 1) + diff1 := after1Year.Sub(now) + + before1Year := AddYear(now, -1) + diff2 := before1Year.Sub(now) + + fmt.Println(diff1) + fmt.Println(diff2) + + // Output: + // 8760h0m0s + // -8760h0m0s +} +``` + ### BeginOfMinute

Return beginning minute time of day.

@@ -607,8 +647,8 @@ func main() { now := time.Now() currentDate := datetime.GetNowDate() - fmt.Println(currentDate) - + fmt.Println(currentDate) + // Output: // 2022-01-28 } @@ -671,8 +711,8 @@ func main() { now := time.Now() current := datetime.GetNowDateTime() - fmt.Println(current) - + fmt.Println(current) + // Output: // 2022-01-28 15:59:33 } @@ -702,9 +742,9 @@ import ( func main() { now := time.Now() zeroTime := datetime.GetZeroHourTimestamp() - - fmt.Println(zeroTime) - + + fmt.Println(zeroTime) + // Output: // 1643299200 } @@ -735,8 +775,8 @@ func main() { now := time.Now() nightTime := datetime.GetNightTimestamp() - fmt.Println(nightTime) - + fmt.Println(nightTime) + // Output: // 1643385599 } @@ -842,8 +882,8 @@ import ( func main() { tm := datetime.NewUnixNow() - fmt.Println(tm) - + fmt.Println(tm) + // Output: // &{1647597438} } @@ -874,8 +914,8 @@ import ( func main() { tm := datetime.NewUnix(1647597438) - fmt.Println(tm) - + fmt.Println(tm) + // Output: // &{1647597438} } @@ -906,8 +946,8 @@ import ( func main() { tm, err := datetime.NewFormat("2022-03-18 17:04:05") - fmt.Println(tm) - + fmt.Println(tm) + // Output: // &{1647594245} } @@ -938,8 +978,8 @@ import ( func main() { tm, err := datetime.NewISO8601("2006-01-02T15:04:05.999Z") - fmt.Println(tm) - + fmt.Println(tm) + // Output: // &{1136214245} } @@ -967,8 +1007,8 @@ import ( func main() { tm := datetime.NewUnixNow() - fmt.Println(tm.ToUnix()) - + fmt.Println(tm.ToUnix()) + // Output: // 1647597438 } @@ -996,8 +1036,8 @@ import ( func main() { tm, _ := datetime.NewFormat("2022-03-18 17:04:05") - fmt.Println(tm.ToFormat()) - + fmt.Println(tm.ToFormat()) + // Output: // 2022-03-18 17:04:05 } @@ -1026,8 +1066,8 @@ import ( func main() { tm, _ := datetime.NewFormat("2022-03-18 17:04:05") ts := tm.ToFormatForTpl("2006/01/02 15:04:05") - fmt.Println(ts) - + fmt.Println(ts) + // Output: // 2022/03/18 17:04:05 } @@ -1056,8 +1096,8 @@ import ( func main() { tm, _ := datetime.NewISO8601("2006-01-02T15:04:05.999Z") ts := tm.ToIso8601() - fmt.Println(ts) - + fmt.Println(ts) + // Output: // 2006-01-02T23:04:05+08:00 } diff --git a/docs/datetime_zh-CN.md b/docs/datetime_zh-CN.md index 8158425..d146a8e 100644 --- a/docs/datetime_zh-CN.md +++ b/docs/datetime_zh-CN.md @@ -1,15 +1,17 @@ # Datetime -datetime日期时间处理包，格式化日期，比较日期。 + +datetime 日期时间处理包，格式化日期，比较日期。
## 源码: -- [https://github.com/duke-git/lancet/blob/main/datetime/datetime.go](https://github.com/duke-git/lancet/blob/main/datetime/datetime.go) +- [https://github.com/duke-git/lancet/blob/main/datetime/datetime.go](https://github.com/duke-git/lancet/blob/main/datetime/datetime.go)
## 用法: + ```go import ( "github.com/duke-git/lancet/v2/datetime" @@ -19,74 +21,77 @@ import (
## 目录 -- [AddDay](#AddDay) -- [AddHour](#AddHour) -- [AddMinute](#AddMinute) -- [BeginOfMinute](#BeginOfMinute) -- [BeginOfHour](#BeginOfHour) -- [BeginOfDay](#BeginOfDay) -- [BeginOfWeek](#BeginOfWeek) -- [BeginOfMonth](#BeginOfMonth) -- [BeginOfYear](#BeginOfYear) -- [EndOfMinute](#EndOfMinute) -- [EndOfHour](#EndOfHour) -- [EndOfDay](#EndOfDay) -- [EndOfWeek](#EndOfWeek) -- [EndOfMonth](#EndOfMonth) -- [EndOfYear](#EndOfYear) -- [GetNowDate](#GetNowDate) -- [GetNowTime](#GetNowTime) -- [GetNowDateTime](#GetNowDateTime) -- [GetZeroHourTimestamp](#GetZeroHourTimestamp) -- [GetNightTimestamp](#GetNightTimestamp) -- [FormatTimeToStr](#FormatTimeToStr) -- [FormatStrToTime](#FormatStrToTime) -- [NewUnixNow](#NewUnixNow) -- [NewUnix](#NewUnix) -- [NewFormat](#NewFormat) -- [NewISO8601](#NewISO8601) -- [ToUnix](#ToUnix) -- [ToFormat](#ToFormat) -- [ToFormatForTpl](#ToFormatForTpl) -- [ToIso8601](#ToIso8601) + +- [AddDay](#AddDay) +- [AddHour](#AddHour) +- [AddMinute](#AddMinute) +- [AddYear](#AddYear) +- [BeginOfMinute](#BeginOfMinute) +- [BeginOfHour](#BeginOfHour) +- [BeginOfDay](#BeginOfDay) +- [BeginOfWeek](#BeginOfWeek) +- [BeginOfMonth](#BeginOfMonth) +- [BeginOfYear](#BeginOfYear) +- [EndOfMinute](#EndOfMinute) +- [EndOfHour](#EndOfHour) +- [EndOfDay](#EndOfDay) +- [EndOfWeek](#EndOfWeek) +- [EndOfMonth](#EndOfMonth) +- [EndOfYear](#EndOfYear) +- [GetNowDate](#GetNowDate) +- [GetNowTime](#GetNowTime) +- [GetNowDateTime](#GetNowDateTime) +- [GetZeroHourTimestamp](#GetZeroHourTimestamp) +- [GetNightTimestamp](#GetNightTimestamp) +- [FormatTimeToStr](#FormatTimeToStr) +- [FormatStrToTime](#FormatStrToTime) +- [NewUnixNow](#NewUnixNow) +- [NewUnix](#NewUnix) +- [NewFormat](#NewFormat) +- [NewISO8601](#NewISO8601) +- [ToUnix](#ToUnix) +- [ToFormat](#ToFormat) +- [ToFormatForTpl](#ToFormatForTpl) +- [ToIso8601](#ToIso8601)
## 文档 ## 注: -1. 方法FormatTimeToStr和FormatStrToTime中的format参数值需要传以下类型之一： -- yyyy-mm-dd hh:mm:ss -- yyyy-mm-dd hh:mm -- yyyy-mm-dd hh -- yyyy-mm-dd -- yyyy-mm -- mm-dd -- dd-mm-yy hh:mm:ss -- yyyy/mm/dd hh:mm:ss -- yyyy/mm/dd hh:mm -- yyyy-mm-dd hh -- yyyy/mm/dd -- yyyy/mm -- mm/dd -- dd/mm/yy hh:mm:ss -- yyyy -- mm -- hh:mm:ss -- mm:ss +1. 方法 FormatTimeToStr 和 FormatStrToTime 中的 format 参数值需要传以下类型之一： + +- yyyy-mm-dd hh:mm:ss +- yyyy-mm-dd hh:mm +- yyyy-mm-dd hh +- yyyy-mm-dd +- yyyy-mm +- mm-dd +- dd-mm-yy hh:mm:ss +- yyyy/mm/dd hh:mm:ss +- yyyy/mm/dd hh:mm +- yyyy-mm-dd hh +- yyyy/mm/dd +- yyyy/mm +- mm/dd +- dd/mm/yy hh:mm:ss +- yyyy +- mm +- hh:mm:ss +- mm:ss ### AddDay

将日期加/减天数。

-Signature: +函数签名: ```go func AddDay(t time.Time, day int64) time.Time ``` -Example: +示例: ```go package main @@ -119,13 +124,13 @@ func main() {

将日期加/减小时数。

-Signature: +函数签名: ```go func AddHour(t time.Time, hour int64) time.Time ``` -Example: +示例: ```go package main @@ -158,13 +163,13 @@ func main() {

将日期加/减分钟数。

-Signature: +函数签名: ```go func AddMinute(t time.Time, minute int64) time.Time ``` -Example: +示例: ```go package main @@ -193,17 +198,56 @@ func main() { } ``` +### AddYear + +

将日期加/减年数。

+ +函数签名: + +```go +func AddYear(t time.Time, year int64) time.Time +``` + +示例: + +```go +package main + +import ( + "fmt" + "time" + "github.com/duke-git/lancet/v2/datetime" +) + +func main() { + now := time.Now() + + after1Year := AddYear(now, 1) + diff1 := after1Year.Sub(now) + + before1Year := AddYear(now, -1) + diff2 := before1Year.Sub(now) + + fmt.Println(diff1) + fmt.Println(diff2) + + // Output: + // 8760h0m0s + // -8760h0m0s +} +``` + ### BeginOfMinute

返回指定时间的分钟开始时间。

-Signature: +函数签名: ```go func BeginOfMinute(t time.Time) time.Time ``` -Example: +示例: ```go package main @@ -229,13 +273,13 @@ func main() {

返回指定时间的小时开始时间。

-Signature: +函数签名: ```go func BeginOfHour(t time.Time) time.Time ``` -Example: +示例: ```go package main @@ -261,13 +305,13 @@ func main() {

返回指定时间的当天开始时间。

-Signature: +函数签名: ```go func BeginOfDay(t time.Time) time.Time ``` -Example: +示例: ```go package main @@ -293,13 +337,13 @@ func main() {

返回指定时间的每周开始时间,默认开始时间星期日。

-Signature: +函数签名: ```go func BeginOfWeek(t time.Time, beginFrom ...time.Weekday) time.Time ``` -Example: +示例: ```go package main @@ -325,13 +369,13 @@ func main() {

返回指定时间的当月开始时间。

-Signature: +函数签名: ```go func BeginOfMonth(t time.Time) time.Time ``` -Example: +示例: ```go package main @@ -357,13 +401,13 @@ func main() {

返回指定时间的当年开始时间

-Signature: +函数签名: ```go func BeginOfYear(t time.Time) time.Time ``` -Example: +示例: ```go package main @@ -389,13 +433,13 @@ func main() {

返回指定时间的分钟结束时间。

-Signature: +函数签名: ```go func EndOfMinute(t time.Time) time.Time ``` -Example: +示例: ```go package main @@ -421,13 +465,13 @@ func main() {

返回指定时间的小时结束时间。

-Signature: +函数签名: ```go func EndOfHour(t time.Time) time.Time ``` -Example: +示例: ```go package main @@ -453,13 +497,13 @@ func main() {

返回指定时间的当天结束时间。

-Signature: +函数签名: ```go func EndOfDay(t time.Time) time.Time ``` -Example: +示例: ```go package main @@ -485,13 +529,13 @@ func main() {

返回指定时间的星期结束时间,默认结束时间星期六。

-Signature: +函数签名: ```go func EndOfWeek(t time.Time, endWith ...time.Weekday) time.Time ``` -Example: +示例: ```go package main @@ -517,13 +561,13 @@ func main() {

返回指定时间的当月结束时间。

-Signature: +函数签名: ```go func EndOfMonth(t time.Time) time.Time ``` -Example: +示例: ```go package main @@ -549,13 +593,13 @@ func main() {

返回指定时间的当年结束时间。

-Signature: +函数签名: ```go func EndOfYear(t time.Time) time.Time ``` -Example: +示例: ```go package main @@ -581,13 +625,13 @@ func main() {

获取当天日期，返回格式：yyyy-mm-dd。

-Signature: +函数签名: ```go func GetNowDate() string ``` -Example: +示例: ```go package main @@ -602,8 +646,8 @@ func main() { now := time.Now() currentDate := datetime.GetNowDate() - fmt.Println(currentDate) - + fmt.Println(currentDate) + // Output: // 2022-01-28 } @@ -613,13 +657,13 @@ func main() {

获取当时时间，返回格式：hh:mm:ss

-Signature: +函数签名: ```go func GetNowTime() string ``` -Example: +示例: ```go package main @@ -645,13 +689,13 @@ func main() {

获取当时日期和时间，返回格式：yyyy-mm-dd hh:mm:ss。

-Signature: +函数签名: ```go func GetNowDateTime() string ``` -Example: +示例: ```go package main @@ -666,8 +710,8 @@ func main() { now := time.Now() current := datetime.GetNowDateTime() - fmt.Println(current) - + fmt.Println(current) + // Output: // 2022-01-28 15:59:33 } @@ -677,13 +721,13 @@ func main() {

获取零点时间戳(timestamp of 00:00)

-Signature: +函数签名: ```go func GetZeroHourTimestamp() int64 ``` -Example: +示例: ```go package main @@ -697,9 +741,9 @@ import ( func main() { now := time.Now() zeroTime := datetime.GetZeroHourTimestamp() - - fmt.Println(zeroTime) - + + fmt.Println(zeroTime) + // Output: // 1643299200 } @@ -709,13 +753,13 @@ func main() {

获取午夜时间戳(timestamp of 23:59)。

-Signature: +函数签名: ```go func GetNightTimestamp() int64 ``` -Example: +示例: ```go package main @@ -730,8 +774,8 @@ func main() { now := time.Now() nightTime := datetime.GetNightTimestamp() - fmt.Println(nightTime) - + fmt.Println(nightTime) + // Output: // 1643385599 } @@ -741,13 +785,13 @@ func main() {

将日期格式化成字符串，`format` 参数格式参考注1。

-Signature: +函数签名: ```go func FormatTimeToStr(t time.Time, format string) string ``` -Example: +示例: ```go package main @@ -780,13 +824,13 @@ func main() {

将字符串格式化成时间，`format` 参数格式参考注1。

-Signature: +函数签名: ```go func FormatStrToTime(str, format string) (time.Time, error) ``` -Example: +示例: ```go package main @@ -816,7 +860,7 @@ func main() {

创建一个当前时间的unix时间戳。

-Signature: +函数签名: ```go type theTime struct { @@ -825,7 +869,7 @@ type theTime struct { func NewUnixNow() *theTime ``` -Example: +示例: ```go package main @@ -837,8 +881,8 @@ import ( func main() { tm := datetime.NewUnixNow() - fmt.Println(tm) - + fmt.Println(tm) + // Output: // &{1647597438} } @@ -848,7 +892,7 @@ func main() {

创建一个unix时间戳。

-Signature: +函数签名: ```go type theTime struct { @@ -857,7 +901,7 @@ type theTime struct { func NewUnix(unix int64) *theTime ``` -Example: +示例: ```go package main @@ -869,8 +913,8 @@ import ( func main() { tm := datetime.NewUnix(1647597438) - fmt.Println(tm) - + fmt.Println(tm) + // Output: // &{1647597438} } @@ -880,7 +924,7 @@ func main() {

创建一个yyyy-mm-dd hh:mm:ss格式时间字符串的unix时间戳。

-Signature: +函数签名: ```go type theTime struct { @@ -889,7 +933,7 @@ type theTime struct { func NewFormat(t string) (*theTime, error) ``` -Example: +示例: ```go package main @@ -901,8 +945,8 @@ import ( func main() { tm, err := datetime.NewFormat("2022-03-18 17:04:05") - fmt.Println(tm) - + fmt.Println(tm) + // Output: // &{1647594245} } @@ -912,7 +956,7 @@ func main() {

创建一个iso8601格式时间字符串的unix时间戳。

-Signature: +函数签名: ```go type theTime struct { @@ -921,7 +965,7 @@ type theTime struct { func NewISO8601(iso8601 string) (*theTime, error) ``` -Example: +示例: ```go package main @@ -933,8 +977,8 @@ import ( func main() { tm, err := datetime.NewISO8601("2006-01-02T15:04:05.999Z") - fmt.Println(tm) - + fmt.Println(tm) + // Output: // &{1136214245} } @@ -944,13 +988,13 @@ func main() {

返回unix时间戳。

-Signature: +函数签名: ```go func (t *theTime) ToUnix() int64 ``` -Example: +示例: ```go package main @@ -962,8 +1006,8 @@ import ( func main() { tm := datetime.NewUnixNow() - fmt.Println(tm.ToUnix()) - + fmt.Println(tm.ToUnix()) + // Output: // 1647597438 } @@ -973,13 +1017,13 @@ func main() {

返回格式'yyyy-mm-dd hh:mm:ss'的日期字符串。

-Signature: +函数签名: ```go func (t *theTime) ToFormat() string ``` -Example: +示例: ```go package main @@ -991,8 +1035,8 @@ import ( func main() { tm, _ := datetime.NewFormat("2022-03-18 17:04:05") - fmt.Println(tm.ToFormat()) - + fmt.Println(tm.ToFormat()) + // Output: // 2022-03-18 17:04:05 } @@ -1002,13 +1046,13 @@ func main() {

返回tpl格式指定的日期字符串。

-Signature: +函数签名: ```go func (t *theTime) ToFormatForTpl(tpl string) string ``` -Example: +示例: ```go package main @@ -1021,8 +1065,8 @@ import ( func main() { tm, _ := datetime.NewFormat("2022-03-18 17:04:05") ts := tm.ToFormatForTpl("2006/01/02 15:04:05") - fmt.Println(ts) - + fmt.Println(ts) + // Output: // 2022/03/18 17:04:05 } @@ -1032,13 +1076,13 @@ func main() {

返回iso8601日期字符串。

-Signature: +函数签名: ```go func (t *theTime) ToIso8601() string ``` -Example: +示例: ```go package main @@ -1051,9 +1095,9 @@ import ( func main() { tm, _ := datetime.NewISO8601("2006-01-02T15:04:05.999Z") ts := tm.ToIso8601() - fmt.Println(ts) - + fmt.Println(ts) + // Output: // 2006-01-02T23:04:05+08:00 } -``` \ No newline at end of file +```