4 - 解析与创建时间.md

###概览

一个关联到具体地区的时间可以由多种方法创建；这种时间可以由一对 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)