JHDate 0.5.1

JHDate 0.5.1

测试已测试
语言语言 SwiftSwift
许可证 MIT
发布时间上次发布时间2015年11月
SPM支持SPM

Jeroen Houtzager 维护。



JHDate 0.5.1

  • Hout

JHDate

JHDate是对NSDate的包装,暴露了NSDateComponents、NSCalendar、NSTimeZone、NSLocale和NSDateFormatter的属性。最佳的方式是将其视为在一个时区(timeZone)内、日历系统(calendar)中本地化(locale)的瞬间(date)。目的是替换你的NSDate实例为JHDate以获取相同的功能以及大量本地化的日期、日历、时区、格式化特性。因此提供具备我创建此库时寻找的灵活性的日期功能。

  • 将对象用作NSDate,即作为一个绝对时间。
  • 提供许多NSDate和NSDateComponent变量和方法
  • 可以以任意组件组合初始化一个日期
  • 默认日期是NSDate()
  • 默认日历是NSCalendar.currentCalendar()
  • 默认时区是NSTimeZone.localTimeZone()
  • 包含日期(NSDate)、日历(NSCalendar)、地区(NSLocale)和时区(NSTimeZone)属性
  • 建立了通过运算符在日期之间实施EquatableComparable协议。例如:==, !=, <, >, <=, >=
  • 实施了Hashable协议,因此日期可以用作Dictionary中的键。
  • 实现了与日期组件的日期添加和减运算符。例如:date + 2.days
  • JHDate是不可变的,因此是线程安全的。它包含一个构造函数,可以轻松地以一些调整后的属性创建新的JHDate实例。

示例

查看沙箱

import JHDate

//: #### Initialisers
//: Create a new date object with the current date & time alike NSDate()
let date = JHDate()

//: Create a determined date
let determinedDate = JHDate(year: 2011, month: 2, day: 11)!

//: Create a determined date in a different time zone
let usaTimeZone = NSTimeZone(abbreviation: "EST")!
var usaDate = JHDate(year: 2011, month: 2, day: 11, hour: 14, timeZone: usaTimeZone)!

//: Mind that default values for JHDate(year etc) are taken from the reference date,
//: which is 1 January 2001, 00:00:00.000 in your default time zone and against your current calendar.

//: Week oriented initiailisations are also possible: first week of 2016:
let weekDate = JHDate(yearForWeekOfYear: 2016, weekOfYear: 1, weekday: 1)!
//: In Europe this week starts in 2015 despite the year for the week that is 2016.
//: That is because the Thursday of this week is in 2016 as specified by ISO 8601

//: Create a determined date in a different calendar
let hebrewCalendar = NSCalendar(identifier: NSCalendarIdentifierHebrew)
let hebrewDate = JHDate(year: 2011, month: 2, day: 11, hour: 14, calendar: hebrewCalendar)!

//: Create today's date at start of day
let today = JHDate.today()

//: Create a period that is the next weekend
let weekend = today.nextWeekend()!
let weekendStart = weekend.startDate
let weekendEnd = weekend.endDate

//: #### Calculations
//: One week later
let oneWeekLater = (determinedDate + 1.weeks)!

//: Twelve hours earlier
let earlier = (determinedDate - 12.hours)!

//: Or combinations
let something = ((determinedDate - 12.hours)! + 30.minutes)!

//: Create a new date based on another one with some different components
let newDate = oneWeekLater.withValue(14, forUnit: .Hour)!

//: ... or with a combination of components
let newDate2 = oneWeekLater.withValues([(13, .Hour), (12, .Minute)])!

//: #### NSDate
newDate.timeIntervalSinceReferenceDate
JHDate.earliestDate(newDate, newDate2, today, something)
JHDate.latestDate(newDate, newDate2, today, something)

//: #### Components
newDate2.year
newDate2.month
newDate2.day

newDate2.yearForWeekOfYear
newDate2.weekOfYear
newDate2.weekday

newDate2.hour
newDate2.minute
newDate2.second

//: #### StartOF & EndOF
//: Create new dates based on this week's start & end
let startOfWeek = newDate.startOf(.WeekOfYear)
let endOfWeek = newDate.endOf(.WeekOfYear)

//: Create new dates based on this day's start & end
let startOfDay = newDate.startOf(.Day)
let endOfDay = newDate.endOf(.Day)

//: Create new dates based on this day's start & end
let startOfYear = newDate.startOf(.Year)
let endOfYear = newDate.endOf(.Year)

//: #### Conversions
//: Change time zone
let usaDate2 = JHDate(refDate: newDate2, timeZone: usaTimeZone)

//: Change and time zone calendar to Islamic in Dubai
let dubaiTimeZone = NSTimeZone(abbreviation: "GST")!
let dubaiCalendar = NSCalendar(identifier: NSCalendarIdentifierIslamicCivil)!
let dubaiDate = JHDate(refDate: newDate2, calendar: dubaiCalendar, timeZone: dubaiTimeZone)

//: Again, but now we go to New Delhi
let indiaTimeZone = NSTimeZone(abbreviation: "IST")!
let indiaCalendar = NSCalendar(identifier: NSCalendarIdentifierIndian)!
let indiaDate = JHDate(refDate: newDate2, calendar: dubaiCalendar, timeZone: dubaiTimeZone)

//: #### Equations
//: JHDate conforms to the Equatable protocol. I.e. you can compare with == for equality.
newDate == newDate2
newDate == newDate

//: For equal date values, you should use x.isEqualToDate(y)
let newDate3 = JHDate(refDate: newDate2)!
newDate == newDate3
let newDate4  = JHDate(refDate: newDate2, locale: NSLocale(localeIdentifier: "en_NZ"))!
newDate4 == newDate3
newDate.isEqualToDate(newDate3)
newDate2.toString()
newDate3.toString()
newDate4.toString()

//: #### Comparisons
//: JHDate conforms to the Comparable protocol. I.e. you can compare with <. <=, ==, >=, >
newDate > newDate2
newDate >= newDate2
newDate == newDate2
newDate != newDate2
newDate <= newDate2
newDate < newDate2

//: Mind that comparisons takes the absolute time from the date property into account.
//: calendars and time zones have no effect on the comparison results.
let date1 = JHDate(year: 2000, month: 1, day: 1, hour: 14, timeZone: NSTimeZone(abbreviation: "UTC"))!
let date2 = (date1 + 1.hours)!

//: date1 = 14:00 UTC
//: date2 = 15:00 UTC
date1 > date2
date1 < date2

let indiaDate1 = JHDate(refDate: date1, calendar: indiaCalendar, timeZone: indiaTimeZone)!

//: indiaDate1 = 19:30 IST
//: date1 = 14:00 UTC
//: date2 = 9:00 CST
indiaDate1 > date2
indiaDate1 < date2

indiaDate1.isEqualToDate(date1)

//: QED: same outcome!


//: #### Collections

//: Use as a key in a dictionary
var birthdays = [JHDate: String]()
birthdays[JHDate(year: 1997, month: 5, day: 7)!] = "Jerry"
birthdays[JHDate(year: 1999, month: 12, day: 14)!] = "Ken"
birthdays[JHDate(year: 1990, month: 12, day: 5)!] = "Sinterklaas"
birthdays.sort({ (a: (date: JHDate, String), b: (date: JHDate, String)) -> Bool in
return a.date < b.date
})



//: #### Display
//: JHDate conforms to the ConvertString protocol
date2.description

//: Various NSDateFormatter properties are ported
let date3 = (date1 + 7.hours)!
date3.toString()
date3.toString(.LongStyle)
date3.toString(dateStyle: .LongStyle)
date3.toString(timeStyle: .LongStyle)
date3.toString("dd-MMM-yyyy HH:mm")
(JHDate() + 1.days)!.toRelativeString()

使用方法

要运行示例项目,首先克隆仓库,并在示例目录中运行pod install

要求

需要iOS 9。测试代码需要实现Quick和Nimble。你可以在Examples文件夹中通过运行pod install来做到。

安装

手动

获取git克隆并把你项目的JHDate.swift添加到项目中。

git clone https://github.com/Hout/JHDate.git

设计决策

我在设置库时做了以下决策。我期待对这些决策的反馈。

决策 理由
不包含从字符串初始化的一部分 由于世界上所有不同的表示方式,这太复杂了。与目前可用的便利初始化器相比,它的好处太少。
不要试图模仿所有NSDateFormatterNSDateComponents等对象的属性和函数。例如: NSDateFormatter的localizedStringFromDateweekdaySymbols 有时使用JHDate中的date属性会更简单。
等号==不仅用于日期值,也用于整个对象 类似于NSObject的规定;虽然对象不必是同一实例,但它们必须包含相等的属性

作者

Jeroen Houtzager,请通过GitHub联系我

合作

如果你愿意做出贡献

  • 分支
  • 发送pull请求
  • 提交问题
  • 挑战设计决策
  • 挑战编码
  • 挑战任何东西!

这些库和作者激励了我编写此代码

  • SwiftDate由Daniele Margutti创建。如果你想寻找一个简单的Swift NSDate扩展,我推荐这个。

许可证

JHDate根据MIT许可证提供。有关更多信息,请参阅LICENSE文件。