SwiftDate 中文文档

2016-12-14 本文已影响1726人 Mee_Leo

SwiftDate概况

从Swift发布起，我们就没有放弃使用Swift。

当然，我们希望在项目能够轻松自如地管理日期和时区，所以创建SwiftDate这个类库。有了“她”在Swift里面优雅地处理时间。

在iOS、macOS、watchOS、tvOS上，以及Swift兼容的平台上（Linux）都能完美运行！

此外，这个类库是免费的，开源的！

老版本

如果你使用的是swift2.2或者swift2.3，你可以到GitHub page

主要特点

这部分内容是swiftdate里面主要特点的一大亮点。

日期进行简单数学运算。例如: aDate + 2.weeks + 1.hour or (1.year - 2.hours + 16.minutes).fromNow()
时区，地区和日历的转换。使用类DateInRegion,通过组件和操作符进行转化。
算术比较运算比较时间。例如，aDate1 >= aDate2 或者 aDate1.isIn(anotherDate, .day)
使用时间组件。比如，用你喜欢的时区格式表述 aDateInRegion.day 或 hour, minutes等等，
最优雅的方式进行时间和字符串之间的转换。支持自定义(可读的)和固定格式(ISO8601, AltRSS, RSS, Extended, .NET和一些按照unicode标准的常规字符串)。
用其他时间单位描述一个时间段。比如120.seconds.in(.minutes) // 2 minutes
快捷获取时间和时间间隔。(isYesterday,isTomorrow,isBefore()...)
...更多令人激动的事情！

环境要求

目前官方的版本是v4，一些要求：

Swift 3.0+
iOS 8 or later
macOS 10.10 or later
watchOS 2.0 or later
tvOS 9.0 or later
...任意安装Swift3以及Swift的基本库的平台

安装

SwiftDate支持多种安装方式。

CocoaPods安装方式

CocoaPods是一个Objective-C和Swift的依赖管理器。

安装CocoaPods命令：

$ gem install cocoapods

SwiftDate 4.+的版本需要使用CocoaPods 1.0.1+。

Podfile文件

在Xcode项目中引入SwiftDate，编辑Podfile新增：

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '8.0'

target 'TargetName' do
pod 'SwiftDate', '~> 4.0'
end

Carthage安装方式

Carthage是一种非集成的依赖管理器，构建依赖，并提供二元框架。

homebrew安装Carthage：

$ brew update
$ brew install carthage

在Xcode项目中使用Carthage引入SwiftDate，只需要在Cartfile中新增：

github "malcommac/SwiftDate" ~> 4.0

Swift Package Manager安装

目前还不支持！

Fork us on GitHub

SwiftDate是开源的类库，源码托管在GitHub上。

👇下面的姿势可以为SwiftDate作贡献：

抓到一个bug，提供详细步骤复现bug，open一个issue。
提出一个功能性的请求，open一个issue。
贡献代码，提交pr。
...

Authors & License

SwiftDate是由Daniele Margutti创建并维护，其中项目的一个主要贡献者是Jeroen Houtzager。

欢迎为开源项目作出贡献！

此库的源代码遵循MIT License, 你可以没有任何限制地在商业项目中使用！

唯一的要求就是增加一行说明：

Date and Time Management is provided by SwiftDate - http://www.swift-date.com
Created by Daniele Margutti and licensed under MIT License.

Your App & SwiftDate

如果你有兴趣，可以整理出使用SwiftDate这个类库的项目。可以在GitHub上开一个issue，提供你的项目名字和链接，我们将会添加到本网站上！

主要概念

Date 和 Absolute Time

Date是日期和时间处理的基础类。在iOS内部，时间以从 2001年1月1日00:00 UTC 的秒数，作为绝对值存储，Date对此进行封装，并提供相关方法。

世界各地的在同一个时刻，你可以认为是同一个物体（除非出现了一个新的星球时间系统）。但是附加上各地不同的表述和计算方式，时间就变得略微复杂。

绝对时间一种通俗的概念：在美国的 A 正在跟在迪拜的 B 进行通电话，这个时刻就可以称为绝对时间；在同一时刻都会有这样的通话，但是由于时区、不用的日历以及不同的字母或符号方法，区域时间就可能不一样。

基础库还支持处理不同的日历体系的 Calendar 日历实例；

在处理跨时区、日历种类和区域的时间转换的时候，都会遇到一些棘手的问题。SwiftDate能够帮你更高效的解决这些问题。

DateInRegion 和 Region

SwiftDate 为了提供完整的时间和日期管理的功能，引入了两个重要的新玩意以及数个扩展。

第一个是一个结构体(struct)，称为Region：region，正如其名称，它是对一个地理位置在时间体系中的描述，其中包含三个不同的特征：

这或许是不太重要的标注说明：

GMT(Greenwich Mean Time)：指格林威治标准时间；

PST(Pacific Standard Time)：指太平洋标准时间；

TimeZone: 用来定义时区。时区在一定程度上表示了不同地区，因此，地区的名字的可作为时区的名称，例如夏威夷时区，北京时间。类似的，格林尼治时间（GMT）或美国西部时间（PST）的偏移量，也可以用来表示时区，例如东八区（GMT +8）
Calendar: 用来表示日历体系，日历体系定义了年与月的长度与划分。SwiftDate 提供了不同日历的信息，还支持不同日历下时间的计算，例如给出绝对时间值，SwiftDate 可以确定他在指定日历系统下的日期。
local: 用来表示当地的时间表述方式。由于各地的文化、语言、规范的不同，时间在各地用不同的分隔符或语法来表示。比如中国地区一般采用年-月-日时：分：表，而美国地区多采用月-日-年时:分:秒

另一个是DateInRegion，是在特定的国家地区 Region 下，描述一个自身与具体时区和日历无关的时间Date。这是由于特定的国家地区一般采用固定的时区、日历系统与表述规范，只要声明了国家地区，就包含了以上三个要素。实际应用中，使用DateInRegion可以方便的操作上下文中的日期。

SwiftDate 为您提供相同的函数和属性，以管理带有地区属性的DateInRegion时间实例和单纯Date时间实例。

默认Region

当你使用普通的Date对象，你可以在Date.defaultRegion中定义的DateInRegion，这个地区包含了：

.timeZone 以 GMT (Greenwich Mean Time)格式表述的时区
.local 以设备的所在地设置日期表述方式
.Calendar 设置为设备默认的日历

您可以调用 Date.setDefaultRegion(:) 以改变时间的默认地区 Date.defaultRegion 。

这个或许不太重要但还是要记住：时间的这些需要在应用启动时设置好（例如，在UIApplication的delegate中函数applicationDidFinishLaunching()中设置就行了）。

时间的组件

概况

使用 SwiftDate，您可以非常方便的操控时间的组件。无论是否设置地区属性，DateInRegion和Date都实现了同一套属性和方法来进行时间日期的管理。

请注意：使用简单时间 Date实例时，实际上是基于了设备默认的地区来初始化了 .defaultRegion。Region.GMT()是由设备默认的locale和Calendar和当前设备所在地的时区所决定，.defaultRegion 的初始值就是Region.GMT()

如果想要修改的默认的区域，调用Date的静态方法 .setDefaultRegion() 即可！

补充说明：

时间的这些属性值需考虑上下文的地区与日历系统；如果调用者是DateInRegion，SwiftDate 将会使用已经指定的.region来计算具体属性值，如果调用者是普通Date，SwiftDate 将会基于默认的Date.defaultRegion来计算属性值。以下所有属性与组件都服从此原则。

era

返回公元状态，我们日常生活中的 2016 年都以公元年为起点，这些时间的 era 都为 1 , 而公元前的年份如 -2000 年，这些时间的 era 都是 0。所以在操作近代时间时，无需考虑此属性。
声明：

public var era: Int

year

返回年份的数值
声明：

public var year: Int

month

返回月份的数值，如 5 月
声明：

public var month: Int

day

返回年月日中 日的数值，如 30日
声明：

public var day: Int

hour

返回时分秒中 时 的数值
声明：

public var hour: Int

nearestHour

根据四舍五入的方法取出时间的最近小时。简单举例：比如 8:15 会返回 8 ，而 8:50 会返回 9
声明：

public var nearestHour: Int

minute

返回时分秒中 分 的数值
声明：

public var minute: Int

second

返回时分秒中 秒 的数值
声明：

public var second: Int

nanosecond

返回时间的 毫秒的数值
声明：

public var nanosecond: Int

注意
公历日历定义一个星期有7天，一年有356天，或闰年366天。然而，356或366都不平均地分成7天的周，因此通常情况下，一年的最后一周在下一年的一天结束，一年的第一周从前一年开始。为了协调这一点，ISO 8601定义了一个周编号年份，包括52或53整周（364或371天），以便一年的第一周被指定为包含一年中第一个星期四的星期。

您可以将yearForWeekOfYear属性与weekOfYear和weekday属性配合使用，以获取与一年中给定星期的特定工作日对应的日期。例如，2005年第53周（ISO 2005-W53-6）的第6天对应于公历日历上2005年1月1日星期六。比如罗马时间 2015-12-31 15:10:12 他的 yearForWeekOfYear 为 2016，weekOfYear 为 1，weekday 为 3

yearForWeekOfYear

在 ISO8601 的周数计算规则下，日期所属的年份。可能是当前日期的前一年，或者下一年，或者当年。
声明：

public var yearForWeekOfYear: Int

weekOfYear

在 ISO 8601 的周数计算规则下，日期所属的周数。如罗马时间 2015-11-31 是第 49 周，2015-12-31 是第一周。
声明：

public var weekOfYear: Int

weekday

在 ISO 8601 的周数计算规则下，在时间所属的周中，是星期几，且规定了 1是星期日，也就是每周的起点是周日。如罗马时间 2015-11-31 是星期四，其 weekday为5。

声明：

public var weekday: Int

weekdayOrdinal

以每个月的第一天为当月第一周的起点，无视全年的星期计算规则，比如每个月第 4 天就是第一周，第 8 天就是第二周。

声明：

public var weekdayOrdinal: Int

weekdayName

某个日期的星期名称，如果你设定是中国地区，那周二为“星期二”，日本地区就是 “火曜日” ，美国地区就是 “Tuesday”，注意此值取决于地区属性。

声明：

public var weekdayName: String

monthDays

时间所在月份，该月份的天数，比如公历中，二月可能有 29 天或 28 天，12 月有 31天。
声明：

public var monthDays: Int

quarter

返回季度单位的数值。注意在常识中，一年分为春夏秋冬四季，但在不同地区季度的起始时间不同，因此此属性在没有赋值的情况下均为 0 ，当您需要使用前，请赋值。
声明：

public var quarter: Int

weekOfMonth

返回月份所包含的周数，此处按照 IOS 8601 的标准，每个月横跨的周数，比如 2015年2月的 weekOfMonth 是 4 ，而 2016 年 2 月的 weekOfMonth 是 5 。
声明：

public var weekOfMonth: Int

shortMonthName

该时间所在月份的简称，比如美国地区 2月全称是 February ，简称是 Feb 即 2015-02-01 改时间的 shortMonthName 就是 Feb。
声明：

public var monthName: Int

leapMonth

返回一个布尔值，说明某个月份是否是闰月。
true，表示该时间所在月份是闰月，否则不是闰月。
声明：

public var leapMonth: Bool

leapYear

返回一个布尔值，说明某个年份是否是闰年。
true，表示该时间所在的年份是闰年，否则不是闰年。
声明：

public var leapYear: Bool

补充说明：
这个值将会在其使用的日历和时区的环境中解释；如果调用者是DateInRegion，系统环境将会使用相关的.region来定义，如果调用者是普通Date，系统环境将会使用默认值Date.defaultRegion来定义。

julianDay

儒略日 (Julian Day) 是天文学家使用从朱利安时期以来连续的天数。详情请见维基百科词条儒略日
声明：

public var julianDay: Double

modifiedJulianDay

儒略日 (Julian Day) 有一些列的计算方法，由于用途是天文领域，且与公历换算复杂，此处不展开叙述，详情请见维基百科词条 Julian Day

声明：

public var modifiedJulianDay: Double

previousWeekend

返回该时间所在周的上个周末，这个周末以元组表示，第一个元素是上周末开始的时间，第二个是上周末的结束时间。且这两个时间都是 DateInRegion 实例。
注意：是上个周的周末，不是时间本来所在周的周末

声明：

public var previousWeekend: (startDate: DateInRegion, endDate: DateInRegion)?

thisWeekend

返回该时间所在周的周末，这个周末以元组表示，第一个元素是本周末开始的时间，第二个是本周末的结束时间。且这两个时间都是 DateInRegion 实例。

声明：

public var thisWeekend: (startDate: DateInRegion, endDate: DateInRegion)?

nextWeekend

返回该时间所在周的下个周末，这个周末以元组表示，第一个元素是下周末开始的时间，第二个是下周末的结束时间。且这两个时间都是 DateInRegion 实例。
注意：是下个周的周末，不是时间本来所在周的周末
声明：

public var nextWeekend: (startDate: DateInRegion, endDate: DateInRegion)?

isToday

返回布尔值，返回调用此属性的时间实例是否在今天。
声明：

public var isToday: Bool

isYesterday

返回布尔值，返回调用此属性的时间实例是否在昨天。
声明：

public var isYesterday: Bool

isTomorrow

返回布尔值，返回调用此属性的时间实例是否在明天。
声明：

public var isTomorrow: Bool

isInWeekend

返回布尔值，返回调用此属性的时间实例是否在其所在周的周末时间段内。
声明：

public var isInWeekend: Bool

isInPast

比较该时间实例与当前时间，换算成时间绝对值来，比较大小，如果比当前时间小，即为过去时间，返回 true；反之，返回 false。简言之：早于现在时刻的时间返回 true 。
声明：

public var isInPast: Bool

isInFuture

比较该时间实例与当前时间，换算成时间绝对值来，比较大小，如果比当前时间大，即为将来时间，返回 true；反之，返回 false。简言之：晚于现在时刻的时间返回 true 。

声明：

public var isInFuture: Bool

isInSameDayOf()

比较时间实例与给定的时间是否为在同一天。比较时采用调用者的时区和日历设置。
声明：

public func isInSameDayOf(date: DateInRegion) -> Bool
public func isInSameDayOf(date: Date) -> Bool

startOfDay

返回当前时间所在 天 的起始时刻，比如 2016-11-11 23:10:00 的 startOfDay 是 2016-11-11 00:00:00 。注意会结合时区和日历。
声明：

public var startOfDay: DateInRegion
public var startOfDay: Date

endOfDay

返回当前时间所在 天 的结束时刻，比如 2016-11-11 23:10:00 的 startOfDay 是 2016-11-11 23:59:59 。注意会结合时区和日历。
声明：

public var endOfDay: DateInRegion
public var endOfDay: Date

nextMonth

时间所在月份的下一个月的同一日的起始时间，比如 2016-03-31 13:30:00 的 nextMonth 是 2016-04-30 00:00:00，注意 SwiftDate 会自动换算不同月份天数不同的问题。
声明：

public var nextMonth: DateInRegion
public var nextMonth: Date

prevMonth

时间所在月份的上一个月的同一日的起始时间，比如 2016-03-31 13:30:00 的 nextMonth 是 2016-02-29 00:00:00，注意 SwiftDate 会自动换算不同月份天数不同的问题。
声明：

public var prevMonth: DateInRegion 
public var prevMonth: Date

startOf()

给定一个单位，返回时间在此单位的起始值，比如给定以年为单位， 2016-11-11 11:11:11 的 startOf() 是 2016-01-01 00:00:00 ；给定时为单位，会反回 2016-11-11 11:00:00
声明：

public func startOf(component: Calendar.Component) -> DateInRegion
public func startOf(component: Calendar.Component) -> Date

解析与创建时间

概览

一个关联到具体地区的时间可以由多种方法创建；这种时间可以由一对 Date 和 Region 组成，或者从自定义时间格式的字符串解析（SwiftDate 支持自定义的时间格式，诸如 ISO8601 标准格式，RSS 或AltRSS 和 .NET 时间），再或者可以通过解析 Calendar.Component对象的集合来创建。
当然你也可以通过数学运算从另两个时间来新建时间。
本章节罗列了所有关于创建时间的方法，无论是否包含地域信息，DateInRegion 和 Date 都适用于这些方法。

根据字符串解析时间

众所周知，解析字时间符串并转换成时间实例很繁琐。SwiftDate 支持众多时间格式，以帮你提高效率，减少开销。
给 format 参数赋值，以声明你使用的时间格式：可以是自定义时间格式或 ISO8601 datetime、.NET datetime 等标准化时间格式。

声明
func init(string: String, format: DateFormat, fromRegion region: Region? = nil) throws

参数

string : this is the string you want to parse
format : this is the format in which you expect the string is formatted. DateFormat is an enum: .custom (for custom format), .iso8601 to parse all available specs for ISO8601 DateTime Format, .extended to parse Extended DateTime format, .rss to parse both RSS and AltRSS datetime formats and .dotNET to parse .NET datetime strings.
region : is the region in which you want to express specified date. If nil or not specified Region.Local(( is used instead.

返回结果
返回结果是包含地区信息的 DateInRegion 时间实例。
例子

let rome = Region(tz: TimeZoneName.europeRome, cal: CalendarName.gregorian, loc: LocaleName.italian)

// 基于自定义时间格式解析时间字符串
let date1 = try! DateInRegion(string: "1999-12-31 23:30:00", format: .custom("yyyy-MM-dd HH:mm:ss"), fromRegion: regionRome)

// 基于 AltRss 标准来解析时间字符串
let date2 = try! "3 feb 2001 15:30:00 +0100".date(format: .rss(alt: true), fromRegion: regionRome)
// 同上
let date3 = try! DateInRegion(string: "3 feb 2001 15:30:00 +0100", format: .ss(alt: true)), fromRegion: regionRome)

//  解析 ISO8601 标准互联网时间字符串
let date4 = DateInRegion(string: "2001-02-03T15:30:00+01:00", format: .iso8601(options: .withInternetDateTime), fromRegion: regionRome)

// 解析自定义时间格式字符串
let date5 = try! DateInRegion(string: "sab 3 feb 2001, 30 minutes after 15 (timezone is +0100)", format: .custom("eee d MMM YYYY, m 'minutes after' HH '(timezone is' Z')'"), fromRegion: regionRome)

获取当前时刻的时间实例

使用默认的 init() 方法可快捷的创建基于设备当前地区和时刻的 DateInRegion 时间实例。

声明
func init()

返回结果
返回的 DateInRegion 对象定义了当前时刻（Date()）和设备当前的所在地区，此地区属性（Region.Local()）包含了时区 .timeZone、区域时间格式 .locale、当地日历种类 .calendar （所有相关设置都会自动更新）

补充说明：地区包含了3个属性：时区（如 GMT +8）、当地时间格式（如中国以年-月-日，美国以月-日-年）、日历种类（如公历、日本日历、佛教日历）

例子

// Create a new DateInRegion which represent the current moment (Date()) in current device's local settings
let now = DateInRegion()

根据给定的时刻和地区来创建时间实例

给定时间和其所在地区，你可以创建对应的 DateInRegion 对象。创建后，使用 DateInRegion 对象进行的所有操作，都将应用对应地区的要求；DateInRegion对应的属性和方法会自动套用区域的设置；
声明
func init(absoluteDate date: Date, in region: Region)
参数

date: define the absolute Date you want to use to create the new DateInRegion. Passed date is indipendent from any geographic timezone/calendar or locale because it's expressed in absolute time.
region: define the destination Region in which you want to express passed date

返回结果
返回对象是一个解析自给定地区的 DateInRegion 时间实例。

例子

// Create a Region in Rome TimeZone with Gregorian Calendar and Italy locale settings
let regionRome = Region(tz: TimeZoneName.europeRome, cal: CalendarName.gregorian, loc: LocaleName.italianItaly)
// Resulting object is DateInRegion which express the current moment in Rome
let dateInRome = DateInRegion(absoluteDate: Date(), in: regionRome)

根据日期要素创建时间

将日历的因素集合以 DateComponents 对象封装后创建 DateInRegion 时间是另一种好方法。DateComponents 实例化对象的TimeZone Locale Calendar 属性都必须声明以保证获得的时间有效；如果缺失任何一个，将会抛出 .MissingCalTzOrLoc 异常。

声明
func init(components: DateComponents)

参数

components: components used to generate the new date

返回结果
返回一个 DateInRegion 时间实例，其日期由传入的 DateComponets 来决定；

例子

var cmp = DateComponents()
cmp.timeZone = TimeZoneName.europeOslo.timeZone
cmp.calendar = CalendarName.gregorian.calendar
cmp.calendar?.locale = LocaleName.englishNorway.locale
cmp.year = 2005
cmp.month = 4
cmp.day = 15
cmp.hour = 20
cmp.minute = 30

// create a new DateInRegion on 15 Apr 2005, 20:30:00 GMT+2
let date = try! DateInRegion(components: cmp)

根据时间组件创建时间

传入一组 Calendar.Component 与对应值组成的数组（由[Calendar.Component:Int] 样式的字典和具体的地区所定义）来创建一个新的 DateInRegion 时间实例
声明
func init(components: [Calendar.Component:Int], in region: Region)

参数

components: components used to generate the new date. It's a dictionary where keys are Calendar.Component and values are Int with relative value. Supported components are: .day,.era,.hour,.minute,.month,.nanosecond,.quarter,.second,.weekOfMonth,.weekOfYear,.weekday,.weekdayOrdinal,.year, .yearForWeekOfYear。
region: is the region in which you want to express specified date. If nil or not specified Region.Local(( is used instead.

返回结果
返回一个 DateInRegion 时间实例，其组件由传入的 DateComponets 来决定；

例子

let c: [Calendar.Component : Int] = [.year: 2002, .month: 3, .hour: 5, .day: 4, .minute: 6, .second: 7, .nanosecond: 87654321]
// create a new DateInRegion on 2002-03-04 at 05:06:07.87654321 (+/-10) in Region.Local()
let date = try! DateInRegion(components: c, fromRegion: nil)

修改时间

SwiftDare 中文版说明文档 - 修改时间 - 5

@(丁香园学习笔记)[swift, 翻译]

概览

使用 SwiftDate 来对时间进行相关修改操作十分简便；修改时间组件，比较两个时间（时间的不同以他们之间的不等组件来表示）。无论是带有地区属性的 DateInRegion 时间实例还是单一结构的 Date 时间实例，都可以进行这些操作。

数学运算

为时间添加组件
你可以使用 Swift 中常用数学运算符，来增减时间元素的值。如+、-

根据你所表达的上下文，SwiftDate 会自动判断并生成带有地区属性的 DateInRegion 时间实例或单一结构的 Date 时间实例。
可用的时间组件有： nanoseconds,seconds,minutes,hours,days,weeks,years
下面是一些数学运算的例子：

// 创建一个罗马时间 2015-01-03 @ 15:10:00
let regionRome = Region(tz: TimeZoneName.europeRome, cal: CalendarName.gregorian, loc: LocaleName.italianItaly)
var date = try! DateInRegion(components: [.year: 2015, .month: 1, .day: 3, .hour: 15, .minute: 10, .second: 0], fromRegion: regionRome)

// 让我试试数学运算符修改时间元素值
date = date + 3.seconds + 15.minutes // -> 03 gen 2015, 15:25:03 CET
date = date - 120.seconds // minus 2 minutes -> 03 gen 2015, 15:23:03 CET
date = date + 3.weeks // 24 gen 2015, 15:23:03 CET
// 你也可以直接增加绝对秒数，SwiftDate 会自动帮你换算
date.add(interval: 10) // 24 gen 2015, 15:23:03 CET

比较时间

概述
在 Swift3 的 Foundation 库中，已经支持比较 Date 时间实例。
SwiftDate 为带有地区属性的 DateInRegion 补充了相似的比较方法，并通过添加新方法扩充了现有 Foundation 库对不同粒度下的时间比较。

比较简单时间
你可以使用 >,>=,<,=< 运算符来比较时间，例如：

// 03 gen 2015, 15:10:00 CET
let date1 = try! DateInRegion(components: [.year: 2015, .month: 1, .day: 3, .hour: 15, .minute: 10, .second: 0], fromRegion: regionRome)
let date2 = try! DateInRegion(components: [.year: 2015, .month: 2, .day: 5, .hour: 15, .minute: 10, .second: 0], fromRegion: regionRome)
        
if date2 > date1 { // DateInRegion supports Equatable protocol you can use >=, <=, < or >
    print("'\(date2)' date is later than '\(date1)'")
}

if date2 == date1 {
  // simple equality
}

时间所对应的单位起始值

概述
利用 .startOf() 方法，传入计算单位后，你可以获得改时间到现在的差值。补充说明：时间是一个点值，而时间的单位都是一段时间的差值，这里的起始值指的就是时间点值在时间单位的区间中的左边界值；比如，2016-11-11 20:39:50 ，以月为单位，起始值是 2016-11-01 00:00:00；以小时为单位，起始值是 2016-11-11 20:00:00。
声明
startOf(component: Calendar.Component) -> DateInRegion
startOf(component: Calendar.Component) -> Date

参数

component: component to alter

返回值
返回给定时间单位区间的起始值所对应的 DateInRegion/Date 时间实例。

例子

// Create a Region in Rome TimeZone with Gregorian Calendar and Italy locale settings
let regionRome = Region(tz: TimeZoneName.europeRome, cal: CalendarName.gregorian, loc: LocaleName.italianItaly)
    
// 03 gen 2015, 15:10:00 CET
let date = try! DateInRegion(components: [.year: 2015, .month: 1, .day: 3, .hour: 15, .minute: 10, .second: 0], fromRegion: regionRome)

let startOfHour = date.startOf(component: .hour) // 03 gen 2015, 15:00:00 CET
let startOfMonth = date.startOf(component: .month) // 01 gen 2015, 00:00:00 CET
let startOfWeek = date.startOf(component: .weekOfMonth) // 28 dic 2014, 00:00:00 CET

时间所对应的单位结束值

概述
利用 .startOf() 方法，传入单位后，你可以获得现有时间对应的结束址。

声明
endOf(component: Calendar.Component) -> DateInRegion
endOf(component: Calendar.Component) -> Date

参数

component: component to alter

返回结果
返回给定时间单位区间的结束址所对应的 DateInRegion/Date 时间实例。

// Create a Region in Rome TimeZone with Gregorian Calendar and Italy locale settings
let regionRome = Region(tz: TimeZoneName.europeRome, cal: CalendarName.gregorian, loc: LocaleName.italianItaly)
    
// 03 gen 2015, 15:10:00 CET
let date = try! DateInRegion(components: [.year: 2015, .month: 1, .day: 3, .hour: 15, .minute: 10, .second: 0], fromRegion: regionRome)

let startOfHour = date.endOf(component: .hour) // 03 gen 2015, 15:59:59 CET
let startOfMonth = date.endOf(component: .month) // 31 gen 2015, 23:59:59 CET
let startOfWeek = date.endOf(component: .weekOfMonth) // 03 gen 2015, 23:59:59 CET

对时间的时刻进行修改

概述
针对现有的时间实例， .atTime(hour:minute:second) 方法可以修改时刻，提供 时 、分、 秒的值，获得一个新的时间，新的实例中日期与日期不变。
异常
如果原时间不能生成新时间，会抛出 .FailedToCalculate 异常。

声明
func atTime(hour: Int, minute: Int, second: Int) throws -> DateInRegion
func atTime(hour: Int, minute: Int, second: Int) throws -> Date

参数

hour: hour(s) to set
minute: minute(s) to set
second: second(s) to set

返回结果
在原时间基础上，依据你提供的时、分、秒生成一个新时间实例，地区设置保持不变。此外，其他的时间组件在必要时 SwiftDate 会加以修改，以保持合理性。

例子

// 生成一个新的罗马时间，日历格式选择公历，时间表述格式以意大利为准。
// 03 gen 2015, 15:10:00 CET
let regionRome = Region(tz: TimeZoneName.europeRome, cal: CalendarName.gregorian, loc: LocaleName.italianItaly)
let date = try! DateInRegion(components: [.year: 2015, .month: 1, .day: 3, .hour: 15, .minute: 10, .second: 0], fromRegion: regionRome)

// 应用 `.atTime()` 方法
let newDateAtGivenTime = try! date.atTime(hour: 09, minute: 10, second: 22) // 03 gen 2015, 09:10:22 CET

对时间的指定组件进行修改

概述
对指定的时间组件的值进行修改，在保证其他组件值合理的情况下，返回一个新的时间实例。

声明
func at(unit: Calendar.Component, value: Int) throws -> DateInRegion
func at(unit: Calendar.Component, value: Int) throws -> Date

参数

unit: calendar component unit to alter

异常
如果给定的组件赋值不成功，不能生成新时间实例时，会抛出 .FailedToCalculate 异常。

返回结果
在原时间基础上，修改给定组件的值，然后生成新的时间实例并返回。SwiftDate 在合理的前提下不会改变与给定组件相比单位更大组件的值。补充说明：如果修改了时间中 日 的值，那所有的时、分、秒等更小的组件的值都会被赋最小值，而 年 月 等更大单位的组件的值会保持原样，这样做是为了保持合理性，03-31，如果对月改成 2 ，那2-31 很明显不合理。比如 2016-11-11 11:11:11 修改了 月 为 12 那，返回的新的时间是 2016-12-01 00:00:00

例子

// 生成一个新的罗马时间，日历格式选择公历，时间表述格式以意大利为准。
// 03 gen 2015, 15:10:00 CET
let regionRome = Region(tz: TimeZoneName.europeRome, cal: CalendarName.gregorian, loc: LocaleName.italianItaly)
let date = try! DateInRegion(components: [.year: 2015, .month: 1, .day: 3, .hour: 15, .minute: 10, .second: 0], fromRegion: regionRome)

let atGivenYear = try! date.at(unit: .year, value: 2020) // 01 gen 2020, 00:00:00 CET. day is altered

批量修改时间组件的值

概述
给定一个 [时间组件 : 值] 的字典，SwiftDate 会根据时间组件的单位由小到大排序，并修改对应组件的值。
在 SwiftDate 中，规定时间组件的由小到大排序为：
.nanosecond,.second,.minute,.hour,.day,.month,.year,.yearForWeekOfYear,.weekOfYear,.weekday,.quarter,.weekdayOrdinal,.weekOfMonth.

声明
func at(unitsWithValues dict: [Calendar.Component : Int]) throws -> DateInRegion
func at(unitsWithValues dict: [Calendar.Component : Int]) throws -> Date

参数

unitsWithValues: calendar component units to alter

异常
对某些时间组件赋值发生错误时，会抛出 .FailedToCalculate 异常。

返回结果
对指定组件赋值后，生成一个新的时间实例，比给定时间组件更大的组件将不会被修改，更小的如果没有赋值将全部赋最小值；这部分的原理，在上一个方法中有补充说明。

例子

// Create a Region in Rome TimeZone with Gregorian Calendar and Italy locale settings
// 03 gen 2015, 15:10:00 CET
let regionRome = Region(tz: TimeZoneName.europeRome, cal: CalendarName.gregorian, loc: LocaleName.italianItaly)
    
let date = try! DateInRegion(components: [.year: 2015, .month: 1, .day: 3, .hour: 15, .minute: 10, .second: 0], fromRegion: regionRome)
let time = try! date.at(unitsWithValues: [.year: 2016, .month: 7]) // 01 gen 2016, 00:00:00 CET

获取多个时间中的最靠前（时间线上最靠右的）的时间

概述
在给定的多个时间实例集合中，返回其中最新的时间实例。比较依据绝对时间值，时间实例的地区，时区，表述格式等组件不会对比较结果产生影响。

声明
(DateInRegion) static func latestDate(_ list: [DateInRegion]) -> DateInRegion
(Date) static func latestDate(_ list: [DateInRegion]) -> Date

例子

// date1 = 2015-01-03 15:10:00
let date1 = try! DateInRegion(components: [.year: 2015, .month: 1, .day: 3, .hour: 15, .minute: 10, .second: 0], fromRegion: regionRome)
// date2 = 2014-12-30 20:10:00
let date2 = try! DateInRegion(components: [.year: 2014, .month: 12, .day: 30, .hour: 20, .minute: 10, .second: 0], fromRegion: regionRome)
// date3 = 2015-01-03 15:20:00
let date3 = try! DateInRegion(components: [.year: 2015, .month: 1, .day: 3, .hour: 15, .minute: 20, .second: 0], fromRegion: regionRome)

// get the latest date in a set
let latestDate = DateInRegion.latestDate([date1,date2,date3]) // is date1 (2015-01-03 14:20:00 +0000)
// or directly via Array extension
let latestDate = [date1,date2,date3].latestDate

获取多个时间中最久远（时间线上最靠左的）的时间

概述
在给定的多个时间实例集合中，返回其中最久远的时间。比较依据绝对时间值，时间实例的地区，时区，表述格式等组件不会对比较结果产生影响。

声明
(DateInRegion) static func earliestDate(_ list: [DateInRegion]) -> DateInRegion
(Date) static func earliestDate(_ list: [DateInRegion]) -> Date

例子

// date1 = 2015-01-03 15:10:00
let date1 = try! DateInRegion(components: [.year: 2015, .month: 1, .day: 3, .hour: 15, .minute: 10, .second: 0], fromRegion: regionRome)
// date2 = 2014-12-30 20:10:00
let date2 = try! DateInRegion(components: [.year: 2014, .month: 12, .day: 30, .hour: 20, .minute: 10, .second: 0], fromRegion: regionRome)
// date3 = 2015-01-03 15:20:00
let date3 = try! DateInRegion(components: [.year: 2015, .month: 1, .day: 3, .hour: 15, .minute: 20, .second: 0], fromRegion: regionRome)
        
// get the latest date in a set
let earliestDate = DateInRegion.earliestDate([date1,date2,date3]) // is date2 30 dic 2014, 20:10:00 CET
// or directly via Array extension
let earliestDate = [date1,date2,date3].earliestDate

给定单位，比较两时间实例

概述
在给定单位的前提下，比较现有时间是否晚于提供的时间。

声明
func compare(to date: DateInRegion, granularity: Calendar.Component) -> ComparisonResult
func compare(to date: Date, granularity: Calendar.Component) -> ComparisonResult

参数

date: date to compare
granularity: 你所期望的比较粒度至少要比两时间之间的最大不同组件之间要小，否则比较结果会显示相等。
补充说明
在同一个月的两个不同时间时间，以 月 为单位比较时，是相等的，比如(伪代码)
date1 = 2016-11-11 11:11:11
date2 = 2016-11-12 11:11:11
但日或者更小的的单位比较，返回结果就是date2 更大

是否早于某时间（给定单位）

概述
在给定单位前提下，比较现有时间是否早于给定时间。

声明
func isBefore(date: DateInRegion, orEqual: Bool = false, granularity: Calendar.Component) -> Bool
func isBefore(date: Date, orEqual: Bool = false, granularity: Calendar.Component) -> Bool

参数

date: date to compare
orEqual: true to also check for equality
granularity: The smallest unit that must, along with all larger units, be less for the given dates.

是否晚于某时间（给定单位）

概述
在给定单位粒度前提下，比较现有时间是否晚于给定时间。

声明
func isAfter(date: DateInRegion, orEqual: Bool = false, granularity: Calendar.Component) -> Bool
func compare(to date: Date, granularity: Calendar.Component) -> ComparisonResult
func isAfter(date: Date, orEqual: Bool = false, granularity: Calendar.Component) -> Bool

参数

date: date to compare
orEqual: true to also check for equality
granularity: The smallest unit that must, along with all larger units, be less for the given dates.

是否等于某时间

概述
比较现有时间实例是否完全等于给定时间。

声明
func isEqual(to compareDate: DateInRegion) -> Bool

参数

compareDate: a date to compare against

修改时间

SwiftDare 中文版说明文档 - 修改时间 - 5

@(丁香园学习笔记)[swift, 翻译]

概览

数学运算

为时间添加组件
你可以使用 Swift 中常用数学运算符，来增减时间元素的值。如+、-

// 创建一个罗马时间 2015-01-03 @ 15:10:00
let regionRome = Region(tz: TimeZoneName.europeRome, cal: CalendarName.gregorian, loc: LocaleName.italianItaly)
var date = try! DateInRegion(components: [.year: 2015, .month: 1, .day: 3, .hour: 15, .minute: 10, .second: 0], fromRegion: regionRome)

// 让我试试数学运算符修改时间元素值
date = date + 3.seconds + 15.minutes // -> 03 gen 2015, 15:25:03 CET
date = date - 120.seconds // minus 2 minutes -> 03 gen 2015, 15:23:03 CET
date = date + 3.weeks // 24 gen 2015, 15:23:03 CET
// 你也可以直接增加绝对秒数，SwiftDate 会自动帮你换算
date.add(interval: 10) // 24 gen 2015, 15:23:03 CET

比较时间

比较简单时间
你可以使用 >,>=,<,=< 运算符来比较时间，例如：

// 03 gen 2015, 15:10:00 CET
let date1 = try! DateInRegion(components: [.year: 2015, .month: 1, .day: 3, .hour: 15, .minute: 10, .second: 0], fromRegion: regionRome)
let date2 = try! DateInRegion(components: [.year: 2015, .month: 2, .day: 5, .hour: 15, .minute: 10, .second: 0], fromRegion: regionRome)
        
if date2 > date1 { // DateInRegion supports Equatable protocol you can use >=, <=, < or >
    print("'\(date2)' date is later than '\(date1)'")
}

if date2 == date1 {
  // simple equality
}

时间所对应的单位起始值

参数

component: component to alter

返回值
返回给定时间单位区间的起始值所对应的 DateInRegion/Date 时间实例。

例子

// Create a Region in Rome TimeZone with Gregorian Calendar and Italy locale settings
let regionRome = Region(tz: TimeZoneName.europeRome, cal: CalendarName.gregorian, loc: LocaleName.italianItaly)
    
// 03 gen 2015, 15:10:00 CET
let date = try! DateInRegion(components: [.year: 2015, .month: 1, .day: 3, .hour: 15, .minute: 10, .second: 0], fromRegion: regionRome)

let startOfHour = date.startOf(component: .hour) // 03 gen 2015, 15:00:00 CET
let startOfMonth = date.startOf(component: .month) // 01 gen 2015, 00:00:00 CET
let startOfWeek = date.startOf(component: .weekOfMonth) // 28 dic 2014, 00:00:00 CET

时间所对应的单位结束值

概述
利用 .startOf() 方法，传入单位后，你可以获得现有时间对应的结束址。

声明
endOf(component: Calendar.Component) -> DateInRegion
endOf(component: Calendar.Component) -> Date

参数

component: component to alter

返回结果
返回给定时间单位区间的结束址所对应的 DateInRegion/Date 时间实例。

// Create a Region in Rome TimeZone with Gregorian Calendar and Italy locale settings
let regionRome = Region(tz: TimeZoneName.europeRome, cal: CalendarName.gregorian, loc: LocaleName.italianItaly)
    
// 03 gen 2015, 15:10:00 CET
let date = try! DateInRegion(components: [.year: 2015, .month: 1, .day: 3, .hour: 15, .minute: 10, .second: 0], fromRegion: regionRome)

let startOfHour = date.endOf(component: .hour) // 03 gen 2015, 15:59:59 CET
let startOfMonth = date.endOf(component: .month) // 31 gen 2015, 23:59:59 CET
let startOfWeek = date.endOf(component: .weekOfMonth) // 03 gen 2015, 23:59:59 CET

对时间的时刻进行修改

声明
func atTime(hour: Int, minute: Int, second: Int) throws -> DateInRegion
func atTime(hour: Int, minute: Int, second: Int) throws -> Date

参数

hour: hour(s) to set
minute: minute(s) to set
second: second(s) to set

例子

// 生成一个新的罗马时间，日历格式选择公历，时间表述格式以意大利为准。
// 03 gen 2015, 15:10:00 CET
let regionRome = Region(tz: TimeZoneName.europeRome, cal: CalendarName.gregorian, loc: LocaleName.italianItaly)
let date = try! DateInRegion(components: [.year: 2015, .month: 1, .day: 3, .hour: 15, .minute: 10, .second: 0], fromRegion: regionRome)

// 应用 `.atTime()` 方法
let newDateAtGivenTime = try! date.atTime(hour: 09, minute: 10, second: 22) // 03 gen 2015, 09:10:22 CET

对时间的指定组件进行修改

概述
对指定的时间组件的值进行修改，在保证其他组件值合理的情况下，返回一个新的时间实例。

声明
func at(unit: Calendar.Component, value: Int) throws -> DateInRegion
func at(unit: Calendar.Component, value: Int) throws -> Date

参数

unit: calendar component unit to alter

异常
如果给定的组件赋值不成功，不能生成新时间实例时，会抛出 .FailedToCalculate 异常。

例子

// 生成一个新的罗马时间，日历格式选择公历，时间表述格式以意大利为准。
// 03 gen 2015, 15:10:00 CET
let regionRome = Region(tz: TimeZoneName.europeRome, cal: CalendarName.gregorian, loc: LocaleName.italianItaly)
let date = try! DateInRegion(components: [.year: 2015, .month: 1, .day: 3, .hour: 15, .minute: 10, .second: 0], fromRegion: regionRome)

let atGivenYear = try! date.at(unit: .year, value: 2020) // 01 gen 2020, 00:00:00 CET. day is altered

批量修改时间组件的值

声明
func at(unitsWithValues dict: [Calendar.Component : Int]) throws -> DateInRegion
func at(unitsWithValues dict: [Calendar.Component : Int]) throws -> Date

参数

unitsWithValues: calendar component units to alter

异常
对某些时间组件赋值发生错误时，会抛出 .FailedToCalculate 异常。

例子

// Create a Region in Rome TimeZone with Gregorian Calendar and Italy locale settings
// 03 gen 2015, 15:10:00 CET
let regionRome = Region(tz: TimeZoneName.europeRome, cal: CalendarName.gregorian, loc: LocaleName.italianItaly)
    
let date = try! DateInRegion(components: [.year: 2015, .month: 1, .day: 3, .hour: 15, .minute: 10, .second: 0], fromRegion: regionRome)
let time = try! date.at(unitsWithValues: [.year: 2016, .month: 7]) // 01 gen 2016, 00:00:00 CET

获取多个时间中的最靠前（时间线上最靠右的）的时间

声明
(DateInRegion) static func latestDate(_ list: [DateInRegion]) -> DateInRegion
(Date) static func latestDate(_ list: [DateInRegion]) -> Date

例子

// date1 = 2015-01-03 15:10:00
let date1 = try! DateInRegion(components: [.year: 2015, .month: 1, .day: 3, .hour: 15, .minute: 10, .second: 0], fromRegion: regionRome)
// date2 = 2014-12-30 20:10:00
let date2 = try! DateInRegion(components: [.year: 2014, .month: 12, .day: 30, .hour: 20, .minute: 10, .second: 0], fromRegion: regionRome)
// date3 = 2015-01-03 15:20:00
let date3 = try! DateInRegion(components: [.year: 2015, .month: 1, .day: 3, .hour: 15, .minute: 20, .second: 0], fromRegion: regionRome)

// get the latest date in a set
let latestDate = DateInRegion.latestDate([date1,date2,date3]) // is date1 (2015-01-03 14:20:00 +0000)
// or directly via Array extension
let latestDate = [date1,date2,date3].latestDate

获取多个时间中最久远（时间线上最靠左的）的时间

声明
(DateInRegion) static func earliestDate(_ list: [DateInRegion]) -> DateInRegion
(Date) static func earliestDate(_ list: [DateInRegion]) -> Date

例子

// date1 = 2015-01-03 15:10:00
let date1 = try! DateInRegion(components: [.year: 2015, .month: 1, .day: 3, .hour: 15, .minute: 10, .second: 0], fromRegion: regionRome)
// date2 = 2014-12-30 20:10:00
let date2 = try! DateInRegion(components: [.year: 2014, .month: 12, .day: 30, .hour: 20, .minute: 10, .second: 0], fromRegion: regionRome)
// date3 = 2015-01-03 15:20:00
let date3 = try! DateInRegion(components: [.year: 2015, .month: 1, .day: 3, .hour: 15, .minute: 20, .second: 0], fromRegion: regionRome)
        
// get the latest date in a set
let earliestDate = DateInRegion.earliestDate([date1,date2,date3]) // is date2 30 dic 2014, 20:10:00 CET
// or directly via Array extension
let earliestDate = [date1,date2,date3].earliestDate

给定单位，比较两时间实例

概述
在给定单位的前提下，比较现有时间是否晚于提供的时间。

声明
func compare(to date: DateInRegion, granularity: Calendar.Component) -> ComparisonResult
func compare(to date: Date, granularity: Calendar.Component) -> ComparisonResult

参数

date: date to compare
granularity: 你所期望的比较粒度至少要比两时间之间的最大不同组件之间要小，否则比较结果会显示相等。
补充说明
在同一个月的两个不同时间时间，以 月 为单位比较时，是相等的，比如(伪代码)
date1 = 2016-11-11 11:11:11
date2 = 2016-11-12 11:11:11
但日或者更小的的单位比较，返回结果就是date2 更大

是否早于某时间（给定单位）

概述
在给定单位前提下，比较现有时间是否早于给定时间。

声明
func isBefore(date: DateInRegion, orEqual: Bool = false, granularity: Calendar.Component) -> Bool
func isBefore(date: Date, orEqual: Bool = false, granularity: Calendar.Component) -> Bool

参数

date: date to compare
orEqual: true to also check for equality
granularity: The smallest unit that must, along with all larger units, be less for the given dates.

是否晚于某时间（给定单位）

概述
在给定单位粒度前提下，比较现有时间是否晚于给定时间。

参数

date: date to compare
orEqual: true to also check for equality
granularity: The smallest unit that must, along with all larger units, be less for the given dates.

是否等于某时间

概述
比较现有时间实例是否完全等于给定时间。

声明
func isEqual(to compareDate: DateInRegion) -> Bool

参数

compareDate: a date to compare against

时间的格式化

概览
SwiftDate 提供多个简便的方法来输出或解析时间和时间间隔字符串，以下为常见时间格式举例：
使用 tr35-31
格式的时间格式字符串，例如 yyyy-MM-dd
对应 2015-01-05

任意符合 ISO8601
及其子规范的时间格式字符串

符合 .NET
的时间格式字符串

扩展化日期／时间格式，详情请参照 EDTF

声明单位的时间差，如 (date2 - date1).in(.hours)

人类可读或口语化的字符串，如 "1 hour ago", "1m", "now"

两个时间之间的差值，比如 "2h,5m,3s"

获取自定义格式的时间字符串

你可以使用 .string()
方法传入自定义格式，获得时间实例生成对应的字符串。字符串的 Unicode 规范与 Cocoa 用法一致。
声明 DateFormat
包含了 .custom
自定义格式，你可以使用通用的// with DateFormat set to .custom([format string])
func string(format: DateFormat) -> String

也可以直接使用接受自定义格式的方法// shortcut to pass directly the format of the string
func string(custom: String) -> String

参数
format
: a DateFormat
struct. To use custom strings pass .custom()
and pass the value of the formatter

例子

let date = DateInRegion()

let str = date.string(format: .custom("yyyy-MM-dd HH:mm:ss")) // example output: 2016-09-28 13:48:17
// you can also use the shortcut:
let str = date.string(custom: "yyyy-MM-dd HH:mm:ss") // same result

获取 ISO8601 格式的时间字符串
SwiftDate 支持 ISO8601
时间规范的所有要求。你可以基于其子规范而自定义格式。
声明// with DateFormat set to .custom() func string(format: DateFormat) -> String

参数
format
: a DateFormat
struct. To use custom strings pass .custom() and pass the value of the formatter

例子

let date = DateInRegion()

// Here some combinations of ISO8601DateTimeFormatter.Options you can set to format (or parse) an ISO8601 datetime
let iso8601_ex_1 = date.string(format: .iso8601(options: [.withInternetDateTime])) // 2016-09-29T10:47:39+02:00
let iso8601_ex_2 = date.string(format: .iso8601(options: [.withFullDate])) // 2016-09-29
let iso8601_ex_3 = date.string(format: .iso8601(options: [.withWeekOfYear,.withYear])) // 2016W40
let iso8601_ex_4 = date.string(format: .iso8601(options: [.withFullTime,.withFullDate,.withSpaceBetweenDateAndTime])) // 2016-09-29 10:49:42+02:00
let iso8601_ex_5 = date.string(format: .iso8601(options: [.withMonth,.withYear,.withTime])) // 20160910:50:36

获取 AltRss 格式的时间字符串
SwiftDate 也提供对 RSS
和AltRSS
时间格式的支持。（包括解析与生成字符串）
声明func string(format: DateFormat) -> String // with DateFormat set to .rss(alt: Bool)

参数
format
: a DateFormat
struct. To get RSS/AltRSS
pass.rss(alt: Bool)
and pass true
or false
to set the alt format.

例子

let date = DateInRegion()

let altrss_string = date.string(format: .rss(alt: true)) // Alt RSS Format: 29 Sep 2016 10:55:34 +0200
let rss_string = date.string(format: .rss(alt: false)) // RSS Format: Thu, 29 Sep 2016 10:55:34 +0200

获取 .NET 格式的时间字符串
SwiftDate 也提供对 .NET
时间格式的支持。（包括解析与生成字符串）
声明func string(format: DateFormat) -> String // with DateFormat set to .dotNET

参数
format
: a DateFormat
struct. To get .NET
pass.dotNET
and pass true
or false
to set the alt format.

例子

let date = DateInRegion()

let donet_string = date.string(format: .dotNET) // /Date(1475139751633+0200)/

获取扩展化（EDTF）格式的时间字符串
SwiftDate 也提供对扩展化日期／时间格式的支持。
声明func string(format: DateFormat) -> String // with DateFormat set to .extended

参数
format
: a DateFormat
struct. To get extended datetime formatted string pass .extended
and pass true
or false
to set the alt format.

例子

let date = DateInRegion()

let str = date.string(format: .extended) // Thu 29-Sep-2016 AD 11:31:23.886 GMT+2

获取时间间隔的字符串表述
借助 SwiftDate ，你可以很方便的将时间间隔或两个时间之间的差值，以一个或多个单位输出成字符串。如果你想要获取的低级单位的值可以被完整进位，那低级单位所对应的值就被赋值为 0。比如 120秒如果转换成分
、秒
的组合，会被转换成 2分 0秒
； 125秒则会得到 2分 5秒

声明多个时间单位时public func in(_ components: [Calendar.Component], of calendar: CalendarName? = nil) -> [Calendar.Component : Int]
单个时间单位时public func in(_ component: Calendar.Component, of calendar: CalendarName? = nil) -> Int?

参数
component
or components
: specify the component or an array of compone .extended
and pass true
or false
to set the alt format.

例子

let dateA = DateInRegion()

let dateB = dateA + 20.minutes + 120.seconds // create another date with some diff
// Get difference in minutes
let diff_in_minutes = (dateB - dateA).in(.minute) // 22 minutes
// Get difference in seconds and minutes
let diff_in_min_and_secs = (dateB - dateA).in([.minute,.second]) // lower components are grouped. You will get .second=0, .minute=2
// This is another example
let another_diff: TimeInterval = 125 // 125 seconds
let diff_in_min_and_secs_2 = another_diff.in([.minute,.second]) // you will get .minute=2 and .second=5

获取 iOS 样式的时间字符串
你可以使用 Foundation
中的时间格式来输出时间字符串。
声明func string(dateStyle: DateFormatter.Style = .medium, timeStyle: DateFormatter.Style = .medium) -> String

参数
dateStyle
: the style used to print a date as DateFormatter.Style
. If not specified.medium
is used.

timeStyle
: the style used to print a time as DateFormatter.Style
. If not specified .medium
is used.

例子

let date = DateInRegion() // create a date from current time in local device's region and calendar

// Some examples of date as string formatted with different styles for date and time
let example_1 = date.string(dateStyle: .medium, timeStyle: .long) // Sep 29, 2015, 1:01:13 PM GMT+2
let example_2 = date.string(dateStyle: .short, timeStyle: .short) // 9/29/15, 1:00 PM
let example_3 = date.string(dateStyle: .long, timeStyle: .none) // September 29, 2015

获取人类可读或白话式时间字符串
你可以使用 Foundation
来自定义日期 - 时间格式来输出时间字符串；同样的，时间间隔也可以使用口语化字符串来表述。
声明获取一个时间与现在时刻的差值时func colloquialSinceNow() throws -> (date: String, time: String?)
获取两个时间之间的差值时func colloquial(toDate date: DateInRegion) throws -> (date: String, time: String?)
注意：该方法返回的是一个日期与时间的元组。
异常如果两个时间采用不同的日历，会抛出 .DifferentCalendar
异常；如果无法计算出两个时间的间隔，会抛出 .FailedToCalculate
异常。
参数
date
: reference date for comparisor

例子

// Returned tuples (in EN):

// "past month" for interval, "Aug, 29 2016" for relevant time
let dateA = DateInRegion() - 1.months
let (colloquial,relevantTime) = try! dateA.colloquialSinceNow()

// Returned tuples (in EN):
// "2 hours ago" for interval, "at 11:28" for relevant time
let dateB = DateInRegion() - 2.hours - 14.minutes
let (colloquial,relevantTime) = try! dateB.colloquialSinceNow()

// Returned tuples (in EN):
// // "14 minutes ago" for interval, nil for relevant time
let dateC = DateInRegion() - 14.minutes
let (colloquial,relevantTime) = try! dateC.colloquialSinceNow()

// Returned tuples (in EN):
// "2012" for interval, "Sep 2012" for relevant time
let dateD = DateInRegion() - 4.years
let (colloquial,relevantTime) = try! dateD.colloquialSinceNow()

指定单位下，获取两个时间之间的间隔字符串
SwiftDate 可以在指定组件单位的前提下，获取两个时间的差值，并输出为字符串；你可以设置任意一个组件的显示位置，比如（年使用 y
或years
来表述）；组件所对应的最大值以及最小值都会被妥善处理，比如日月年这些单位最小值是 1，最大值是 12，而时分秒的最大值是 60 ，最小值是 0。
声明获取一个时间与现在时刻的差值时func timeComponentsSinceNow(options:,shared:) throws -> String
获取两个时间之间的差值时func timeComponents(to:options:shared:) throws -> String

异常如果不能计算出有效的时间间隔，将会抛出 .FailedToCalculate
错误。
参数
to
: reference date for comparisor

options
: struct ComponentsFormatterOptions which defines a list of options used to print time components

例子

let region = Region.GMT()

let dateB = DateInRegion(absoluteDate: Date(), in: region)
let dateC = dateB - 2.years - 4.months - 5.days

let str2 = try! dateC.timeComponents(toDate: dateB, options: ComponentsFormatterOptions(style: .positional)) // -2y 4m 0w 5d 0:00:00

let str3 = try! dateC.timeComponents(toDate: dateB, options: ComponentsFormatterOptions(style: .full)) // -2 years, 4 months, 0 weeks, 5 days, 0 hours, 0 minutes, 0 seconds

let str4 = try! dateC.timeComponents(toDate: dateB, options: ComponentsFormatterOptions(zero: .dropAll)) // -2y 4m 5d
let dateD = dateB + 1.months
let str5 = try! dateD.timeComponentsSinceNow(options: ComponentsFormatterOptions(allowedUnits: [.weekOfMonth,.day], zero: .dropAll)) // 4w 2d

SwiftDate 中文文档

SwiftDate概况

最新发布版本

老版本

主要特点

环境要求

安装

CocoaPods安装方式

Podfile文件

Carthage安装方式

Swift Package Manager安装

Fork us on GitHub

Authors & License

Your App & SwiftDate

主要概念

Date 和 Absolute Time

DateInRegion 和 Region

这或许是不太重要的标注说明：

默认Region

时间的组件

概况

补充说明：

era

year

month

day

hour

nearestHour

minute

second

nanosecond

yearForWeekOfYear

weekOfYear

weekday

weekdayOrdinal

weekdayName

monthDays

quarter

weekOfMonth

shortMonthName

leapMonth

leapYear

julianDay

modifiedJulianDay

previousWeekend

thisWeekend

nextWeekend

isToday

isYesterday

isTomorrow

isInWeekend

isInPast

isInFuture

isInSameDayOf()

startOfDay

endOfDay

nextMonth

prevMonth

startOf()

解析与创建时间

概览

根据字符串解析时间

获取当前时刻的时间实例

根据给定的时刻和地区来创建时间实例

根据日期要素创建时间

根据时间组件创建时间

修改时间

SwiftDare 中文版说明文档 - 修改时间 - 5

概览

数学运算

比较时间

时间所对应的单位起始值

时间所对应的单位结束值

对时间的时刻进行修改

对时间的指定组件进行修改

批量修改时间组件的值

获取多个时间中的最靠前（时间线上最靠右的）的时间

获取多个时间中最久远（时间线上最靠左的）的时间

给定单位，比较两时间实例

是否早于某时间（给定单位）