Go Persian Calendar 使用指南

Go Persian Calendar 是一个用于波斯历(回历)和公历之间转换的 Golang 库。它使用 Julian 日历作为所有转换的接口，包名为 ptime，并且与标准库 time 包兼容。

安装

go get github.com/yaa110/go-persian-calendar

快速开始

1. 导入包

import (
    ptime "github.com/yaa110/go-persian-calendar"
    "time"
    "fmt"
)

2. 公历转波斯历

// 创建一个 time.Time 实例
var t time.Time = time.Date(2016, time.January, 1, 12, 1, 1, 0, ptime.Iran())

// 使用 time.Time 创建 ptime.Time 实例
pt := ptime.New(t)

// 获取波斯历日期
fmt.Println(pt.Date()) // 输出: 1394 دی 11

3. 波斯历转公历

// 创建一个 ptime.Time 实例
var pt ptime.Time = ptime.Date(1394, ptime.Mehr, 2, 12, 59, 59, 0, ptime.Iran())

// 获取 time.Time 实例
t := pt.Time()

// 获取公历日期
fmt.Println(t.Date()) // 输出: 2015 September 24

4. 获取当前时间

// 获取表示当前时间的 ptime.Time 实例
pt := ptime.Now()

// 获取年、月、日
fmt.Println(pt.Date()) // 输出: 1394 بهمن 11
fmt.Println(pt.Year(), pt.Month(), pt.Day()) // 输出: 1394 بهمن 11

// 获取时、分、秒
fmt.Println(pt.Clock()) // 输出: 21 54 30
fmt.Println(pt.Hour(), pt.Minute(), pt.Second()) // 输出: 21 54 30

// 获取 Unix 时间戳
fmt.Println(pt.Unix()) // 输出: 1454277270

// 获取昨天、今天和明天
fmt.Println(pt.Yesterday().Weekday()) // 输出: شنبه
fmt.Println(pt.Weekday()) // 输出: یک‌شنبه
fmt.Println(pt.Tomorrow().Weekday()) // 输出: دوشنبه

// 获取本周的第一天和最后一天
fmt.Println(pt.FirstWeekDay().Date()) // 输出: 1394 بهمن 10
fmt.Println(pt.LastWeekday().Date()) // 输出: 1394 بهمن 16

// 获取本月的第一天和最后一天
fmt.Println(pt.FirstMonthDay().Weekday()) // 输出: پنج‌شنبه
fmt.Println(pt.LastMonthDay().Weekday()) // 输出: جمعه

// 获取本年的第一天和最后一天
fmt.Println(pt.FirstYearDay().Weekday()) // 输出: شنبه
fmt.Println(pt.LastYearDay().Weekday()) // 输出: شنبه

// 获取本月第几周
fmt.Println(pt.MonthWeek()) // 输出: 3

// 获取本年第几周
fmt.Println(pt.YearWeek()) // 输出: 46

// 获取本年剩余周数
fmt.Println(pt.RYearWeek()) // 输出: 6

5. 格式化时间

// 使用 Unix 时间戳创建 ptime.Time 实例
pt := ptime.Unix(1454277270, 0)

fmt.Println(pt.Format("yyyy/MM/dd E hh:mm:ss a")) // 输出: 1394/11/11 یک‌شنبه 09:54:30 ب.ظ

// 格式化符号说明:
// yyyy, yyy, y     年份 (如 1394)
// yy                2位年份表示 (如 94)
// MMM              波斯月份名称 (如 فروردین)
// MMI              Dari 月份名称 (如 حمل)
// MM                2位月份表示 (如 01)
// M                 月份 (如 1)
// rw                本年剩余周数
// w                 本年周数
// W                 本月周数
// RD                本年剩余天数
// D                 本年第几天
// rd                本月剩余天数
// dd                2位天数表示 (如 01)
// d                 天数 (如 1)
// E                 波斯星期名称 (如 شنبه)
// e                 波斯星期简称 (如 ش)
// A                 12小时制全称 (如 قبل از ظهر)
// a                 12小时制简称 (如 ق.ظ)
// HH                24小时制2位表示 [00-23]
// H                 24小时制 [0-23]
// kk                24小时制2位表示 [01-24]
// k                 24小时制 [1-24]
// hh                12小时制2位表示 [01-12]
// h                 12小时制 [1-12]
// KK                12小时制2位表示 [00-11]
// K                 12小时制 [0-11]
// mm                2位分钟表示 [00-59]
// m                 分钟 [0-59]
// ss                2位秒数表示 [00-59]
// s                 秒数 [0-59]
// ns                纳秒
// S                 3位毫秒表示 (如 001)
// z                 时区名称
// Z                 时区偏移 (如 +03:30)

6. 使用标准格式格式化时间

pt := ptime.Date(1394, 7, 2, 14, 7, 8, 0, ptime.Iran())

fmt.Println(pt.TimeFormat("2 Jan 2006")) // 输出: 2 مهر 1394

// 标准格式说明:
// 2006        4位年份 (如 1399)
// 06          2位年份 (如 99)
// 01          2位月份 (如 01)
// 1           1位月份 (如 1)
// Jan         月份名称 (如 آذر)
// January     月份名称 (如 آذر)
// 02          2位天数 (如 07)
// 2           1位天数 (如 7)
// _2          右对齐2位天数 (如  7)
// Mon         星期名称 (如 شنبه)
// Monday      星期名称 (如 شنبه)
// 03          12小时制2位表示 (如 03)
// 3           12小时制1位表示 (如 3)
// 15          24小时制2位表示 (如 15)
// 04          2位分钟表示 (如 03)
// 4           1位分钟表示 (如 03)
// 05          2位秒数表示 (如 09)
// 5           1位秒数表示 (如 9)
// .000        毫秒 (如 .120)
// .000000     微秒 (如 .123400)
// .000000000  纳秒 (如 .123456000)
// .999        去除尾随零的毫秒 (如 .12)
// .999999     去除尾随零的微秒 (如 .1234)
// .999999999  去除尾随零的纳秒 (如 .123456)
// PM          12小时制全称 (如 قبل از ظهر)
// pm          12小时制简称 (如 ق.ظ)
// MST         时区名称
// -0700       时区偏移 (如 +0330)
// -07         时区偏移 (如 +03)
// -07:00      时区偏移 (如 +03:30)
// Z0700       时区偏移 (如 +0330)
// Z07:00      时区偏移 (如 +03:30)

限制

• 公历年份的最小值是 1097，否则会返回零值的 ptime.Time 实例。

完整示例

package main

import (
    ptime "github.com/yaa110/go-persian-calendar"
    "fmt"
    "time"
)

func main() {
    // 当前时间
    now := ptime.Now()
    fmt.Println("当前波斯时间:", now.Format("yyyy/MM/dd E hh:mm:ss a"))
    
    // 公历转波斯历
    gregorian := time.Date(2023, time.July, 15, 14, 30, 0, 0, ptime.Iran())
    persian := ptime.New(gregorian)
    fmt.Println("公历 2023-07-15 对应的波斯历:", persian.Date())
    
    // 波斯历转公历
    persianDate := ptime.Date(1402, ptime.Tir, 24, 14, 30, 0, 0, ptime.Iran())
    gregorianDate := persianDate.Time()
    fmt.Println("波斯历 1402-04-24 对应的公历:", gregorianDate.Format("2006-01-02"))
    
    // 格式化示例
    fmt.Println("格式化日期:", now.Format("yyyy年MM月dd日 E"))
    fmt.Println("12小时制时间:", now.Format("hh:mm:ss a"))
    fmt.Println("24小时制时间:", now.Format("HH:mm:ss"))
}

这个库提供了丰富的功能来处理波斯历和公历之间的转换，以及波斯历的各种操作。