swift Calendar
作者：想聽丿伱說衹愛我
链接：https://www.jianshu.com/p/4257a1c470e9
来源：简书
著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。
一、简介
Calendar封装了有关时间系统的信息，其中定义了年的开始和长度等。它提供有关日历的信息，并支持日历计算，例如获取符合条件的Date或DateComponents等。
二、API
- 初始化
- 用户当前使用的日历
public static var current: Calendar { get }
默认为gregorian (current)
- 自动跟踪用户设置的日历
public static var autoupdatingCurrent: Calendar { get }
默认为gregorian (autoupdatingCurrent)
- 通过identifier初始化
public init(identifier: Calendar.Identifier)
public enum Identifier {
case gregorian//公历
case buddhist//佛历
case chinese//农历
case coptic//科普特历
case ethiopicAmeteMihret//埃塞俄比亚历
case ethiopicAmeteAlem//埃塞俄比亚阿米特阿莱姆日历
case hebrew//希伯来历
case iso8601//国际标准历法
case indian//印度国定历
case islamic//伊斯兰历
case islamicCivil//伊斯兰希吉来日历
case japanese//和历
case persian//波斯历
case republicOfChina//民国纪年
case islamicTabular//伊斯兰天文历
case islamicUmmAlQura//伊斯兰历（乌姆库拉）
}
let c = Calendar(identifier: .gregorian)//公历
print(c)
//gregorian (fixed)
- 属性
- 日历的标识符
public var identifier: Calendar.Identifier { get }
let c = Calendar(identifier: .gregorian)//公历
print(c.identifier)
//gregorian
- 日历的本地化
public var locale: Locale?
默认为nil
- 日历的时区
public var timeZone: TimeZone
默认为Asia/Shanghai (current)
- 日历的第一个工作日
public var firstWeekday: Int
默认为1，表示为星期一。
- 第一周的最少天数
public var minimumDaysInFirstWeek: Int
默认为1，表示某月的第一周只有一天。
- 标志符
- 纪元标志符
public var eraSymbols: [String] { get }
public var longEraSymbols: [String] { get }
在locale属性为en_US时，eraSymbols默认为 ["BCE", "CE"]。
在locale属性为zh_CN时，eraSymbols默认为 ["公元前", "公元"]。
var c = Calendar(identifier: .gregorian)
c.locale = Locale(identifier: "en_US")
print(c.eraSymbols)
//["BCE", "CE"]
c.locale = Locale(identifier: "zh_CN")
print(c.eraSymbols)
//["公元前", "公元"]
在locale属性为en_US时，longEraSymbols默认为 ["Before Christ", "Anno Domini"]。
在locale属性为zh_CN时，longEraSymbols默认为 ["公元前", "公元"]。
- 月份标志符
public var monthSymbols: [String] { get }
public var shortMonthSymbols: [String] { get }
public var veryShortMonthSymbols: [String] { get }
//独立月份标志符
public var standaloneMonthSymbols: [String] { get }
public var shortStandaloneMonthSymbols: [String] { get }
public var veryShortStandaloneMonthSymbols: [String] { get }
在locale属性为en_US时，monthSymbols默认为 ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"]。shortMonthSymbols默认为 ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]。veryShortMonthSymbols默认为 ["J", "F", "M", "A", "M", "J", "J", "A", "S", "O", "N", "D"]。
standaloneMonthSymbols默认为 ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"]。shortStandaloneMonthSymbols默认为 ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]。veryShortStandaloneMonthSymbols默认为 ["J", "F", "M", "A", "M", "J", "J", "A", "S", "O", "N", "D"]。
注：standaloneMonthSymbols之类的独立属性用于日历标题之类的地方。monthSymbols之类的非独立属性用于上下文（"2020年12月18日 星期五"中的12月）。
- 星期标志符
public var weekdaySymbols: [String] { get }
public var shortWeekdaySymbols: [String] { get }
public var veryShortWeekdaySymbols: [String] { get }
public var standaloneWeekdaySymbols: [String] { get }
public var shortStandaloneWeekdaySymbols: [String] { get }
public var veryShortStandaloneWeekdaySymbols: [String] { get }
在locale属性为en_US时，weekdaySymbols默认为 ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"]。shortWeekdaySymbols默认为 ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]。veryShortWeekdaySymbols默认为 ["S", "M", "T", "W", "T", "F", "S"]。
standaloneWeekdaySymbols默认为 ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"]。shortStandaloneWeekdaySymbols默认为 ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]。veryShortStandaloneWeekdaySymbols默认为 ["S", "M", "T", "W", "T", "F", "S"]。
注：standaloneWeekdaySymbols之类的独立属性用于日历标题之类的地方。weekdaySymbols之类的非独立属性用于上下文（"2020年12月18日 星期五"中的星期五）。
- 季度标志符
public var quarterSymbols: [String] { get }
public var shortQuarterSymbols: [String] { get }
public var standaloneQuarterSymbols: [String] { get }
public var shortStandaloneQuarterSymbols: [String] { get }
在locale属性为en_US时，quarterSymbols默认为 ["1st quarter", "2nd quarter", "3rd quarter", "4th quarter"]。shortQuarterSymbols默认为 ["Q1", "Q2", "Q3", "Q4"]。
standaloneQuarterSymbols默认为 ["1st quarter", "2nd quarter", "3rd quarter", "4th quarter"]。shortStandaloneQuarterSymbols默认为 ["Q1", "Q2", "Q3", "Q4"]。
注：standaloneQuarterSymbols之类的独立属性用于日历标题之类的地方。quarterSymbols之类的非独立属性用于上下文（"2020年12月18日 星期五 第四季度"中的 第四季度）。
- 时间段标志符
public var amSymbol: String { get }
public var pmSymbol: String { get }
在locale属性为en_US时，amSymbol默认为 AM。pmSymbo默认为 PM。
- 范围
- 指定组件的最小范围限制
public func minimumRange(of component: Calendar.Component) -> Range<Int>?
public enum Component {
case era//纪元
case year//年
case month//月
case day//日
case hour//时
case minute//分
case second//秒
case weekday//周几
case weekdayOrdinal//本月的第几个周几
case quarter//季度
case weekOfMonth//一个月的周数
case weekOfYear//一年的周数
case yearForWeekOfYear//ISO8601标准下的年份
case nanosecond//纳秒
case calendar//日历
case timeZone//时区
}
关于Component，可查看DateComponents的初始化方法了解详细。
2月最少为28天，范围为 1..<29。
let c = Calendar(identifier: .gregorian)
print(c.minimumRange(of: .day))
//Optional(Range(1..<29))
- 指定组件的最大范围限制
public func maximumRange(of component: Calendar.Component) -> Range<Int>?
大月有31天，范围为 1..<32。
let c = Calendar(identifier: .gregorian)
print(c.maximumRange(of: .day))
//Optional(Range(1..<32))
- 小组件可以在大组件中使用的范围
public func range(of smaller: Calendar.Component, in larger: Calendar.Component,
for date: Date) -> Range<Int>?
一年最多有366天，范围为 1..<367。
let c = Calendar(identifier: .gregorian)
print(c.range(of: .day, in: .year, for: Date()))
//Optional(Range(1..<367))
- 指定日期所处的开始日期与持续时间
public func dateInterval(of component: Calendar.Component, start: inout Date,
interval: inout TimeInterval, for date: Date) -> Bool
如果能成功计算开始日期与持续时间，则返回true。
如下如示，2020-12-18 07:45:49这个日期在.hour下的开始日期为2020-12-18 07:00:00，持续时间为3600.0，指的就是2020-12-18 07:00:00-2020-12-18 08:00:00这个范围。
let c = Calendar(identifier: .gregorian)
var d = Date()
var t = 0.0
print(d, t)
//2020-12-18 07:45:49 +0000 0.0
print(c.dateInterval(of: .hour, start: &d, interval: &t, for: d))
//ture
print(d, t)
//2020-12-18 07:00:00 +0000 3600.0
- 指定日期所处的日期范围
public func dateInterval(of component: Calendar.Component, for date: Date)
-> DateInterval?
功能与上面方法相同，返回的是日期范围。
如下，2020-12-18 07:54:13在.hour下的日期范围为
2020-12-18 07:00:00 +0000 to 2020-12-18 08:00:00 +0000
let c = Calendar(identifier: .gregorian)
let d = Date()
print(d)
//2020-12-18 07:54:13 +0000
print(c.dateInterval(of: .hour, for: Date()))
//Optional(2020-12-18 07:00:00 +0000 to 2020-12-18 08:00:00 +0000)
- 指定日期的小组件位于大组件的排序位置
public func ordinality(of smaller: Calendar.Component, in larger: Calendar.Component,
for date: Date) -> Int?
如下，2020-12-18 08:33:00 +0000在上海时区的时间为16:33:00，返回的17指的是在.hour下16时为当天的第17个小时，0时为第1个小时。
let c = Calendar(identifier: .gregorian)
let d = Date()
print(d)
//2020-12-18 08:33:00 +0000
print(c.ordinality(of: .hour, in: .day, for: d))
//Optional(17)
- 日期的修改
- 通过日期组件
public func date(byAdding components: DateComponents, to date: Date,
wrappingComponents: Bool = false) -> Date?
给日期增加时间组件的各组件值，获得一个新日期。
wrappingComponents为true时，当组件值超时最大限制时，会减去其最大值。
如下，当给当前日期增加了25小时后，实际上只增加了1小时。
let c = Calendar(identifier: .gregorian)
let d = Date()
print(d)
//2020-12-18 08:51:51 +0000
print(c.date(byAdding: DateComponents(hour: 25), to: d, wrappingComponents: true))
Optional(2020-12-18 09:51:51 +0000)
- 通过日历组件
public func date(byAdding component: Calendar.Component, value: Int, to date: Date,
wrappingComponents: Bool = false) -> Date?
与上面方法不同的是，该方法只能一次更改单个组件的值，而上面方法可以同时更改多个组件的值。wrappingComponents的作用也与上面方法一致。
let c = Calendar(identifier: .gregorian)
let d = Date()
print(d)
//2020-12-19 06:08:25 +0000
print(c.date(byAdding: .hour, value: 30, to: d, wrappingComponents: true))
//Optional(2020-12-19 12:08:25 +0000)
- 日期组件
- 日期组件转换为日期
public func date(from components: DateComponents) -> Date?
let c = Calendar(identifier: .gregorian)
print(c.date(from: DateComponents(year: 2020, month: 12, day: 12,
hour: 12, minute: 12, second: 12)))
//Optional(2020-12-12 04:12:12 +0000)
- 通过日历组件将日期转换为日期组件
public func dateComponents(_ components: Set<Calendar.Component>,
from date: Date) -> DateComponents
该方法会获取属性不完整的日期组件。
let c = Calendar(identifier: .gregorian)
print(c.dateComponents([.year, .month, .day, .hour, .minute, .second], from: Date()))
//year: 2020 month: 12 day: 19 hour: 14 minute: 20 second: 52 isLeapMonth: false
- 通过时区将日期转换为日期组件
public func dateComponents(in timeZone: TimeZone, from date: Date) -> DateComponents
该方法会获取属性完整的日期组件。
let c = Calendar(identifier: .gregorian)
print(c.dateComponents(in: TimeZone.current, from: Date()))
//calendar: gregorian (fixed) timeZone: Asia/Shanghai (current) era: 1 year: 2020
//month: 12 day: 19 hour: 14 minute: 24 second: 56 nanosecond: 984720945
//weekday: 7 weekdayOrdinal: 3 quarter: 0 weekOfMonth: 3 weekOfYear: 51
//yearForWeekOfYear: 2020 isLeapMonth: false
- 获取两个日期的差
public func dateComponents(_ components: Set<Calendar.Component>, from start: Date,
to end: Date) -> DateComponents
差值通过日期组件展示。
let c = Calendar(identifier: .gregorian)
print(c.dateComponents([.hour, .minute, .second], from: Date(), to: Date()+10000))
//hour: 2 minute: 46 second: 40 isLeapMonth: false
- 获取两个日期组件的差
public func dateComponents(_ components: Set<Calendar.Component>,
from start: DateComponents, to end: DateComponents) -> DateComponents
差值通过日期组件展示。
let c = Calendar(identifier: .gregorian)
print(c.dateComponents([.hour, .minute, .second], from: DateComponents(hour: 10),
to: DateComponents(hour: 12, minute: 12, second: 12)))
//hour: 2 minute: 12 second: 12 isLeapMonth: false
- 获取指定日期对应日历组件的值
public func component(_ component: Calendar.Component, from date: Date) -> Int
let c = Calendar(identifier: .gregorian)
print(Date())
//2020-12-19 06:43:03 +0000
print(c.component(.hour, from: Date()))
//14
- 日期的运算
- 获取指定日期的开始日期
public func startOfDay(for date: Date) -> Date
let c = Calendar(identifier: .gregorian)
print(Date())
//2020-12-19 06:44:32 +0000
print(c.startOfDay(for: Date()))
//2020-12-18 16:00:00 +0000
- 比较两日期对应组件值的大小
public func compare(_ date1: Date, to date2: Date,
toGranularity component: Calendar.Component) -> ComparisonResult
public enum ComparisonResult : Int {
case orderedAscending = -1//升序
case orderedSame = 0//相等
case orderedDescending = 1//降序
}
注：并不是单独比较组件的值。比如.second时，2分1秒也会大于1分59秒。实际上是将日期转换为秒，再比较大小。
let c = Calendar(identifier: .gregorian)
print(c.compare(Date(), to: Date()+59, toGranularity: .second).rawValue)
//-1
- 两日期对应组件值是否相同
public func isDate(_ date1: Date, equalTo date2: Date,
toGranularity component: Calendar.Component) -> Bool
注：并不是单独比较组件的值。比如.second时，2分1秒也会大于1分1秒。实际上是将日期转换为秒，再比较大小。
let c = Calendar(identifier: .gregorian)
print(c.isDate(Date(), equalTo: Date()+60, toGranularity: .second))
//false
- 两日期是否在同一天
public func isDate(_ date1: Date, inSameDayAs date2: Date) -> Bool
- 指定日期是否属于今天
public func isDateInToday(_ date: Date) -> Bool
- 指定日期是否属于昨天
public func isDateInYesterday(_ date: Date) -> Bool
- 指定日期是否属于明天
public func isDateInTomorrow(_ date: Date) -> Bool
- 指定日期是否属于周末
public func isDateInWeekend(_ date: Date) -> Bool
注意：有些地区的周末并不是周六与周日。
- 获取指定日期的周末开始日期与持续时间
public func dateIntervalOfWeekend(containing date: Date, start: inout Date,
interval: inout TimeInterval) -> Bool
若能获取到周末，该方法返回true。
如下，因为今天是周六，因此周末是从今天开始，持续172800.0秒，也就是2天。
let c = Calendar(identifier: .gregorian)
var d = Date()
var i = 0.0
print(d, i)
//2020-12-19 07:14:33 +0000 0.0
print(c.dateIntervalOfWeekend(containing: Date(), start: &d, interval: &i))
//true
print(d, i)
//2020-12-18 16:00:00 +0000 172800.0
- 获取指定日期的周末的范围
public func dateIntervalOfWeekend(containing date: Date) -> DateInterval?
功能与上面方法相同，只不过直接返回日期间隔。
let c = Calendar(identifier: .gregorian)
print(c.dateIntervalOfWeekend(containing: Date()))
//Optional(2020-12-18 16:00:00 +0000 to 2020-12-20 16:00:00 +0000)
- 返回指定日期的下一个周末开始日期与持续时间
public func nextWeekend(startingAfter date: Date, start: inout Date,
interval: inout TimeInterval, direction: Calendar.SearchDirection = .forward) -> Bool
public enum SearchDirection {
case forward//查询日期更大的方向，下周末
case backward//查询日期更大的方向，上周末
}
若能获取到周末，该方法返回true。
功能与dateIntervalOfWeekend方法大致相同。
不同在于，如下，因为今天是周六，nextWeekend会获取到下一个星期的周末，而dateIntervalOfWeekend会获取到本周末。
let c = Calendar(identifier: .gregorian)
var d = Date()
var i = 0.0
print(d, i)
//2020-12-19 07:35:25 +0000 0.0
print(c.dateIntervalOfWeekend(containing: Date(), start: &d, interval: &i))
//true
print(d, i)
//2020-12-18 16:00:00 +0000 172800.0
print(c.nextWeekend(startingAfter: Date(), start: &d, interval: &i))
//true
print(d, i)
//2020-12-25 16:00:00 +0000 172800.0
- 获取指定日期的下一个周末的范围
public func nextWeekend(startingAfter date: Date,
direction: Calendar.SearchDirection = .forward) -> DateInterval?
功能与上面方法相同，只不过直接返回日期间隔。
let c = Calendar(identifier: .gregorian)
print(Date())
//2020-12-19 07:42:47 +0000
print(c.nextWeekend(startingAfter: Date()))
//Optional(2020-12-25 16:00:00 +0000 to 2020-12-27 16:00:00 +0000)
- 日期的匹配
- 匹配满足日期组件（或最接近）的日期
public func enumerateDates(startingAfter start: Date,
matching components: DateComponents,
matchingPolicy: Calendar.MatchingPolicy,
repeatedTimePolicy: Calendar.RepeatedTimePolicy = .first,
direction: Calendar.SearchDirection = .forward,
using block: (Date?, Bool, inout Bool) -> Void)
如果不可能完全匹配，并且matchingPolicy为strict，则会将nil传递给闭包，并且枚举结束。
逻辑上，strict匹配将无限期地搜索到将来，但如果找不到匹配项，则继续进行枚举并没有意义。
若已成功匹配日期，可通过在闭包中将inout Bool值设置为true来停止枚举并函数返回。
匹配策略
public enum MatchingPolicy {
//如果DateComponents的下一个更高组件没有匹配的时间，算法将返回存在的现有时间。
//例如，在夏令时过渡时间可能没有2:37 am，那么结果将是3:00 am。
case nextTime
//与nextTime相同，但会保留下一个组件值。
//例如，在夏令时过渡时间可能没有2:37 am，那么结果将是3:37 am。
case nextTimePreservingSmallerComponents
//与nextTime相同，但会减小组件值和保留下一个组件值。
//例如，在夏令时过渡时间可能没有2:37 am，那么结果将是1:37 am。
case previousTimePreservingSmallerComponents
//精确查询匹配项
//例如，在公历中搜索2月29日，上面的三个枚举选项可能改为选择3月1日（如果年份不是闰年）。
case strict
}
结果选择策略
public enum RepeatedTimePolicy {
//有多个匹配结果时，将返回第一个结果
case first
//有多个匹配结果时，将返回最后一个结果
case last
}
查询方向
public enum SearchDirection {
case forward//向日期更大的方向查询
case backward//向日期更小的方向查询
}
闭包
(Date?, Bool, inout Bool) -> Void
Date?为匹配到的日期。Bool为true时，表示此日期为完全匹配日期组件。inout Bool赋值为true后，会停止遍历。
let c = Calendar(identifier: .gregorian)
c.enumerateDates(startingAfter: Date(), matching: DateComponents(month: 2, day: 29),
matchingPolicy: .nextTime, repeatedTimePolicy: .first) { (a, b, c) in
let formatter = DateFormatter()
formatter.dateFormat = "yyyy-MM-dd HH:mm:ss"
print(formatter.string(from: a!), b , c)
if b {
//b为true表示完全匹配日期组件
//matchingPolicy为strict时，所有结果的b都为true
c = true//设置为true可停止遍历
}
}
//2021-03-01 00:00:00 false false
//2022-03-01 00:00:00 false false
//2023-03-01 00:00:00 false false
//2024-02-29 00:00:00 true false
- 获取第一个满足日期组件（或最接近）的日期
public func nextDate(after date: Date, matching components: DateComponents,
matchingPolicy: Calendar.MatchingPolicy,
repeatedTimePolicy: Calendar.RepeatedTimePolicy = .first,
direction: Calendar.SearchDirection = .forward) -> Date?
功能与enumerateDates方法相同，但只返回第一个匹配的日期。
let a = c.nextDate(after: Date(), matching: DateComponents(month: 2, day: 29),
matchingPolicy: .nextTime, repeatedTimePolicy: .first, direction: .forward)
let formatter = DateFormatter()
formatter.dateFormat = "yyyy-MM-dd HH:mm:ss"
print(formatter.string(from: a!))
- 日期是否匹配日期组件
public func date(_ date: Date, matchesComponents components: DateComponents) -> Bool
let c = Calendar(identifier: .gregorian)
print(Date())
//2020-12-21 07:53:08 +0000
print(c.date(Date(), matchesComponents: DateComponents(month: 12, day: 21)))
//true
- 日期的更改
- 通过组件值更改日期
public func date(bySetting component: Calendar.Component, value: Int,
of date: Date) -> Date?
枚举参数可查看enumerateDates方法。
更改组件值时通常会要求同时更高或耦合的组件。例如，将weekday设置为“星期四”的通常还要求更改day的组件值，并且可能还要求更改month和year。
如果不存在满足条件的日期，此时会返回下一个可用日期。
当更改组件值时，更小组件值会重置。例如将month变成3，那么结果会变成03-01 00:00:00
let c = Calendar(identifier: .gregorian)
print(Date())
//2020-12-21 07:29:09 +0000
let d = c.date(bySetting: .month, value: 3, of: Date())
//Optional(2021-02-28 16:00:00 +0000)
print(d)
- 通过时分秒更改日期
public func date(bySettingHour hour: Int, minute: Int, second: Int, of date: Date,
matchingPolicy: Calendar.MatchingPolicy = .nextTime,
repeatedTimePolicy: Calendar.RepeatedTimePolicy = .first,
direction: Calendar.SearchDirection = .forward) -> Date?
枚举参数可查看enumerateDates方法。
如果不存在满足条件的日期，此时会返回下一个可用日期。
let c = Calendar(identifier: .gregorian)
let formatter = DateFormatter()
formatter.dateFormat = "yyyy-MM-dd HH:mm:ss"
print(formatter.string(from: Date()))
//2020-12-21 15:48:26
let a = c.date(bySettingHour: 11, minute: 12, second: 13, of: Date())
print(formatter.string(from: a!))
//2020-12-21 11:12:13