DateTools,多是最好用的iOS日期工具库

项目简介

DateTools 用于提升Objective-C中日期和时间相关操做的效率.灵感来源于 DateTime和[Time Period Library](Time Period Library).

• 项目主页: DateTools
• 最新示例: 点击下载
• 工程简议: 支持国际化,支持中文输出,真的很贴心!

安装

使用 Cocoapods 安装

pod 'DateTools'

NSDate+DateTools

DateTools让NSDate功能更完整,可让你更容易地去获取日期各个组件的信息,如年 月 日等.

获取字符串形式的时间间隔.

DateTools 可让你获取距离一个过去的时间点距离当前时间的字符串表示.和Twitter中很像,这个时间字符串有完整形式和缩略形式两种.你能够像下面这样使用:

NSDate *timeAgoDate = [NSDate dateWithTimeIntervalSinceNow:-4];
NSLog(@"Time Ago: %@", timeAgoDate.timeAgoSinceNow);
NSLog(@"Time Ago: %@", timeAgoDate.shortTimeAgoSinceNow);

//输出:
//Time Ago: 4 seconds ago
//Time Ago: 4s

// 若是工程支持国际化,而且模拟器或真机环境设为简体中文,则会输出:
// Time Ago: 4秒钟前
// Time Ago: 4秒

若是你的工程支持国际化,DateTools如今会自动支持如下语言的本地化:

• ar (Arabic)
• bg (Bulgarian)
• ca (Catalan)
• zh_Hans (简体中文)
• zh_Hant (繁体中文)
• cs (Czech)
• da (Danish)
• nl (Dutch)
• en (English)
• fi (Finnish)
• fr (French)
• de (German)
• gre (Greek)
• gu (Gujarati)
• he (Hebrew)
• hi (Hindi)
• hu (Hungarian)
• is (Icelandic)
• id (Indonesian)
• it (Italian)
• ja (Japanese)
• ko (Korean)
• lv (Latvian)
• ms (Malay)
• nb (Norwegian)
• pl (Polish)
• pt (Portuguese)
• ro (Romanian)
• ru (Russian)
• sl (Slovenian)
• es (Spanish)
• sv (Swedish)
• th (Thai)
• tr (Turkish)
• uk (Ukrainian)
• vi (Vietnamese)
• cy (Welsh)
• hr (Croatian)

获取日期的某个组成部分,如年月周日时分秒等.

使用 DateTools 能够很容易地获取日期对象的某一组成部分:

NSDate * date = [NSDate date];
NSInteger year = date.year;
NSInteger month = date.month;
NSLog(@"year: %ld, month: %ld", (long)year, (long)month); // year: 2015, month: 9

若是你不想使用公历,能够这样作:

NSInteger day = [date dayWithCalendar:calendar];

若是你想改变 DateTools 使用的默认日历,能够改写 <code>NSDate+DateTools.m</code> 中的 <code>defaultCalendar</code> 方法.

日期编辑

可使用 dateByAdding... 或 dateBySubtractingYears... 进行日期按年/月/日/时分/秒等增长或减小:

NSDate * date = [NSDate date];
NSInteger oldYear = date.year;
    
NSDate *newDate = [date dateByAddingYears:1];
NSInteger newYear = newDate.year;
    
NSLog(@"oldYear: %ld newYear: %ld", (long)oldYear, (long)newYear); // 输出: oldYear: 2015 newYear: 2016

日期比较

DateTools 提供下列方法,比较两个日期的大小,返回结果为一个布尔值:

• isEarlierThan
• isEarlierThanOrEqualTo
• isLaterThan
• isLaterThanOrEqualTo

若是想获取两个日期具体的差值: 获取毫秒间隔可使用 NSDate 提供的 <code>timeIntervalSinceDate:</code>和 <code>timeIntervalSinceNow</code> 方法;获取相差多少年/月/周/日/时/分/秒等,能够直接使用 DateTools的扩展方法.

NSInteger yearsApart = [firstDate yearsFrom:secondDate];

相似yearsFrom:用于日期比较的方法包括:

• <code>yearsFrom:</code>, <code>yearsUntil</code>, <code>yearsAgo</code>, <code>yearsEarlierThan:</code>, <code>yearsLaterThan:</code>
• <code>monthsFrom:</code>, <code>monthsUntil</code>, <code>monthsAgo</code>, <code>monthsEarlierThan:</code>, <code>monthsLaterThan:</code>
• <code>weeksFrom:</code>, <code>weeksUntil</code>, <code>weeksAgo</code>, <code>weeksEarlierThan:</code>, <code>weeksLaterThan:</code>
• <code>daysFrom:</code>, <code>daysUntil</code>, <code>daysAgo</code>, <code>daysEarlierThan:</code>, <code>daysLaterThan:</code>
• <code>hoursFrom:</code>, <code>hoursUntil</code>, <code>hoursAgo</code>, <code>hoursEarlierThan:</code>, <code>hoursLaterThan:</code>
• <code>minutesFrom:</code>, <code>minutesUntil</code>, <code>minutesAgo</code>, <code>minutesEarlierThan:</code>, <code>minutesLaterThan:</code>
• <code>secondsFrom:</code>, <code>secondsUntil</code>, <code>secondsAgo</code>, <code>secondsEarlierThan:</code>, <code>secondsLaterThan:</code>

日期的格式化输出

可使用 code>formattedDateWithStyle:</code> 和 <code>formattedDateWithFormat:</code> 方法格式化输出日期:

NSDate * date = [NSDate date];
NSString * dateStr = [date formattedDateWithStyle: NSDateFormatterFullStyle];
    
// 此处输出的具体内容会根据你的手机或模拟器语言环境的不一样而不一样.
NSLog(@"%@", dateStr); // 输出: 2015年9月25日 星期五
    
dateStr =  [date formattedDateWithFormat:@"YYYY/MM/dd HH:mm:ss"];
NSLog(@"%@", dateStr); // 输出: 2015/09/25 15:19:23

时间段

DateTools 经过 DTTimePeriod类来简化时间段相关的操做.

初始化

已知开始和结束时间,可使用下面的方法初始化时间段对象:

DTTimePeriod *timePeriod = [[DTTimePeriod alloc] initWithStartDate:startDate endDate:endDate];

或者,已知起始或结束时间,同时知道时间段的总时长,能够用相似下面的方法建立时间端对象:

// 建立一个时间段,从如今开始,共5个小时.
DTTimePeriod *timePeriod = [DTTimePeriod timePeriodWithSize:DTTimePeriodSizeHour amount:5 startingAt:[NSDate date]];

时间段信息

能够经过 DTTimePeriod 的实例方法来获取时间段的相关信息:

• <code>hasStartDate</code> - 返回YES,若是有起始时间.
• <code>hasEndDate</code> - 返回YES,若是有结束时间.
• <code>isMoment</code> - 返回YES,若是起始时间和结束时间相同.
• <code>durationIn....</code> - 返回指定单位下时间段的长度.

DTTimePeriod *timePeriod = [[DTTimePeriod alloc] initWithStartDate:date endDate: [date dateByAddingDays: 10]];
    
NSLog(@"相差 %g 天", [timePeriod durationInDays]); // 输出: 相差 10 天

操做

能够对时间段进行移动,延长或缩短的操做.

移动

当一个时间段被移动时,起始时间和结束时间会相应地同步迁移或推后.可使用下面两个方法移动时间段:

• <code>shiftEarlierWithSize:amount:</code> 时间段总体前移
• <code>shiftLaterWithSize:amount:</code> 时间段总体推后

延长/缩短

能够经过保持起始点/中间时间点/结束时间点不变,而后改变开始或结束时间点,以获得延长或缩短期段的目的:

// 经过前移起始时间,把时间段总时长从1分钟变为2分钟.
DTTimePeriod *timePeriod  = [DTTimePeriod timePeriodWithSize:DTTimePeriodSizeMinute endingAt:[NSDate date]];
[timePeriod lengthenWithAnchorDate:DTTimePeriodAnchorEnd size:DTTimePeriodSizeMinute amount:1];

关系

可使用 DTTimePeriod 的关系操做相关的方法,来判断两个时间段的相互关系,如是否包含,是不是同一段时间等.

基础

下图表格列出了两个时间段全部可能的关系:

可经过下列方法判断两个时间段的关系:

• isEqualToPeriod:
• isInside:
• contains:
• overlapsWith:
• intersects:

你能够经过下面这个方法获取相对于另外一个时间段的关系:

-(DTTimePeriodRelation)relationToPeriod:(DTTimePeriod *)period;

全部可能的时间段间的关系都列在了枚举 DTTimePeriodRelation 中了.

点击示例中 Time Periods 按钮,而后滑动滑块,能够更好地掌握时间段之间的相互关系

时间段集合

DateTools 提供两种时间段集合类: <code>DTTimePeriodCollection</code> 和 <code>DTTimePeriodChain</code>.前者,容许存储彼此有交集的时间段;后者,不容许存储彼此有交集的时间段.

这两个时间段集合类,操做和 NSArray 很像.你能够添加,插入和移除 DTTimePeriod 对象,就像你在数组时的那样.惟一的不一样是,两中集合存储时间段的方式.

<code>DTTimePeriodCollection</code> 和 <code>DTTimePeriodChain</code>,是为了简化基于多个时间段的逻辑处理.好比同一团队中,给不一样的人设置任务的起始和结束时间,此时若是使用 DTTimePeriodCollection 来处理各个时间段,能够直接获得团队总任务的起始时间和结束时间.

DTTimePeriodCollection

DTTimePeriodCollection 是一个规则相对宽松的集合.默认无序(指的是顺序和各个时间段的起止时间无关.),但支持手动排序;拥有本身的属性,好比基于内粗存储的时间段计算出的此集合的开始时间和结束时间.这个结合容许存储有交集的时间段.

能够像下面这样建立新的DTTimePeriodCollection集合:

// 建立集合.
DTTimePeriodCollection *collection = [DTTimePeriodCollection collection];
    
// 建立时间段
NSDateFormatter * dateFormatter = [[NSDateFormatter alloc]init];
[dateFormatter setDateFormat: @"YYYY MM dd HH:mm:ss.SSS"];
DTTimePeriod *firstPeriod = [DTTimePeriod timePeriodWithStartDate:[dateFormatter dateFromString:@"2014 11 05 18:15:12.000"] endDate:[dateFormatter dateFromString:@"2015 11 05 18:15:12.000"]];
DTTimePeriod *secondPeriod = [DTTimePeriod timePeriodWithStartDate:[dateFormatter dateFromString:@"2015 11 05 18:15:12.000"] endDate:[dateFormatter dateFromString:@"2016 11 05 18:15:12.000"]];
    
// 把时间段添加到集合中.
[collection addTimePeriod:firstPeriod];
[collection addTimePeriod:secondPeriod];
    
// 从集合中获取时间段.
firstPeriod = collection[0];

排序

有三类给集合内时间段排序的方法:

• 根据起始时间排序 - <code>sortByStartAscending</code>, <code>sortByStartDescending</code>
• 根据结束时间排序 - <code>sortByEndAscending</code>, <code>sortByEndDescending</code>
• 根据时长排序 - <code>sortByDurationAscending</code>, <code>sortByDurationDescending</code>

操做

也能够去获取一个 NSDate 对象或一个 DTTimePeriod 对象与一个 时间段结合的相对关系.例如,你能够经过 <cdoe>periodsIntersectedByDate:</code> 方法获取全部与某个时间有交集的时间段.这个方法会返回一个新的 DTTimePeriodCollection 对象,里面包含全部符合条件的时间段.

有许多相似的方法,以下图:

DTTimePeriodChain

DTTimePeriodChain 以较为严格的方式存储时间段对象. DTTimePeriodChain集合一般依据开始和结束时间存储时间段对象,而且有本身的属性,如 根据内部存储的时间段对象推断出来的此集合的开始时间和结束时间. DTTimePeriodChain 内部存储的时间段对象不容许有交集.这种集合很适用于连续会议或约会等日程类事务的建模.

建立一个新的 DTTimePeriodChain 集合:

// 建立集合.
DTTimePeriodChain *chain = [DTTimePeriodChain chain];

// 建立时间段
NSDateFormatter * dateFormatter = [[NSDateFormatter alloc]init];
[dateFormatter setDateFormat: @"YYYY MM dd HH:mm:ss.SSS"];

DTTimePeriod *firstPeriod = [DTTimePeriod timePeriodWithStartDate:[dateFormatter dateFromString:@"2014 11 05 18:15:12.000"] endDate:[dateFormatter dateFromString:@"2015 11 05 18:15:12.000"]];
DTTimePeriod *secondPeriod = [DTTimePeriod timePeriodWithStartDate:[dateFormatter dateFromString:@"2015 11 05 18:15:12.000"] endDate:[dateFormatter dateFromString:@"2016 11 05 18:15:12.000"]];

// 添加时间段对象到集合中.
[chain addTimePeriod:firstPeriod];

// 若是后存入的时间和前一个存入的时间没法先后彻底衔接,则后一个时间会适当前移或后移,以使先后时间段紧凑.
[chain addTimePeriod:secondPeriod];

// 获取集合中的元素.
firstPeriod = chain[0];

新加入的时间段,时长不变,起始时间变为前一个时间段的结束时间,结束时间对应前移后后移.在非零位置新插入的时间,其后的时间段相应后移.在零位置插入的时间,集合的起始时间前移.操做图解以下:

操做 像 DTTimePeriodCollection 同样, DTTimePeriodChain 也能够进行相等性比较,而且也能够前移后后移.其余执行的方法在下图列出: