DateTools

DateTools was written to streamline date and time handling in Objective-C. Classes and concepts from other languages served as an inspiration for DateTools, especially the DateTime structure and [Time Period Library](Time Period Library) for .NET. Through these classes and others, DateTools removes the boilerplate required to access date components, handles more nuanced date comparisons, and serves as the foundation for entirely new concepts like Time Periods and their collections.

Installation

Cocoapods - Pending! pod 'DateTools'

Manual Installation All the classes required for DateTools are located in the DateTools folder in the root of this repository. They are listed below:

• DateTools.h
• NSDate+DateTools.{h,m}
• DTConstants.h
• DTError.{h,m}
• DTTimePeriod.{h,m}
• DTTimePeriodGroup.{h,m}
• DTTimePeriodCollection.{h,m}
• DTTimePeriodChain.{h,m}

DateTools.h contains the headers for all the other files. Import this if you want to link to the entire framework.

Table of Contents

• NSDate+DateTools
  • Time Ago
  • Date Components
  • Date Editing
  • Date Comparison
  • Formatted Date Strings
• Time Periods
  • Initialization
  • Time Period Info
  • Manipulation
  • Relationships
• Time Period Groups
  • Initialization
  • Time Period Collections
  • Time Period Chains
• Unit Tests
• Credits
• License

##NSDate+DateTools

One of the missions of DateTools was to make NSDate feel more complete. There are many other languages that allow direct access to information about dates from their date classes, but NSDate (sadly) does not. It safely works only in the Unix time offsets through the timeIntervalSince... methods for building dates. But that's not always what we want to do. Sometimes, we would like to work with dates based on their date components (like year, month, day, etc) at a more abstract level. This is where DateTools comes in.

####Time Ago

No date library would be complete without the ability to quickly make an NSString based on how much earlier a date is than now. DateTools has you covered. These "time ago" strings come in a long a short form, with the latter closely resembling Twitter. There are many libraries that do this, so I wanted to pull it into this one.

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

//Output:
//Time Ago: 4 seconds ago
//Time Ago: 4s

####Date Components

There is a lot of boilerplate associated with getting date components from an NSDate. You have to set up a calendar, use the desired flags for the components you want, and finally extract them out of the calendar.

With DateTools, this:

//Create calendar
NSCalendar *calendar = [[NSCalendar alloc] initWithCalendarIdentifier:NSGregorianCalendar];
unitFlags = NSYearCalendarUnit | NSMonthCalendarUnit;
NSDateComponents *dateComponents = [calendar components:unitFlags fromDate:date];

//Get components
NSInteger year = calendar.year;
NSInteger month = calendar.month;

...becomes this:

NSInteger year = date.year;
NSInteger month = date.month;

And if you would like to use a non-Gregorian calendar, that option is available as well.

NSInteger day = [date dayWithCalendar:calendar];

If you would like to override the default calendar that DateTools uses, simply change it in the defaultCalendar method of NSDate+DateTools.m.

####Date Editing

The date editing makes it easy to make a date earlier or later by adding and subtracting date components. For instance, if you would like a date that is 1 year later from a given date, simply call the method dateByAddingYears.

With DateTools, this:

//Create calendar
NSCalendar *calendar = [[NSCalendar alloc] initWithCalendarIdentifier:[NSDate defaultCalendar]];
NSDateComponents *components = [[NSDateComponents alloc] init];

//Make changes
[components setYear:1];

//Get new date with updated year
NSDate *newDate = [calendar dateByAddingComponents:components toDate:date options:0];

...becomes this:

NSDate *newDate = [self.controlDate dateByAddingYears:1];

Subtraction of date components is also fully supported through the dateBySubtractingYears

####Date Comparison

One of the biggest reasons for the DateTools category on NSDate was to greatly increase the flexibility of date comparisons. NSDate gives you four basic methods:

• isEqualToDate:
• earlierDate:
• laterDate:
• compare:

earlierDate: and laterDate: are great, but it would be nice to have a boolean response to help when building logic in code. DateTools has a set of proxy methods that do just that as well as a few other methods for extended flexibility. The new methods are:

• isEarlierThan
• isEarlierThanOrEqualTo
• isLaterThan
• isLaterThanOrEqualTo

These methods are great for comparing dates in a boolean fashion, but what if we want to compare the dates and return some meaningful information about how far they are apart? NSDate comes with two methods timeIntervalSinceDate: and timeIntervalSinceNow which gives you a double offset representing the number of seconds between the two dates. This is great and all, but there are times when I want to know how many years or days something is away. For this, DateTools goes back to the ever-trusty NSCalendar and abstracts all the necessary code out for you.

With Date Tools, this:

NSCalendar *calendar = [[NSCalendar alloc] initWithCalendarIdentifier:[NSDate defaultCalendar]];
NSDate *earliest = [firstDate earlierDate:secondDate];
NSDate *latest = (secondDate == firstDate) ? secondDate : firstDate;
NSInteger multiplier = (secondDate == firstDate) ? -1 : 1;
NSDateComponents *components = [calendar components:allCalendarUnitFlags fromDate:earliest toDate:latest options:0];
NSInteger yearsApart = multiplier*(components.month + 12*components.year);

..becomes this:

NSInteger yearsApart = [firstDate yearsFrom:secondDate];

Methods for comparison in this category include:

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

####Formatted Date Strings

Just for kicks, DateTools has a few convenience methods for quickly creating strings from dates. Those two methods are formattedDateWithStyle: and formattedDateWithFormat:. The current locale is used unless otherwise specified by additional method parameters. Again, just for kicks, really.

##Time Periods

Dates are important, but the real world is a little less discrete than that. Life is made up of spans of time, like an afternoon appointment or a weeklong vacation. In DateTools, time periods are represented by the DTTimePeriod class and come with a suite of initializaiton, manipulation, and comparison methods to make working with them a breeze.

####Initialization

Time peroids consist of an NSDate start date and end date. To initialize a time period, call the init function.

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

or, if you would like to create a time period of a known length that starts or ends at a certain time, try out a few other init methods. The method below, for example, creates a time period starting at the current time that is exactly 5 hours long.

DTTimePeriod *timePeriod = [DTTimePeriod timePeriodWithSize:DTTimePeriodSizeHour amount:5 startingAt:[NSDate date]];

####Time Period Info

####Manipulation

####Relationships

##Time Period Groups

####Introduction

####Time Period Collections

####Time Period Chains

####Documentation

##Unit Tests Unit tests were performed on all the major classes in the library for quality assurance. You can find theses under the "Tests" folder at the top of the library. There are over 300 test cases in all!

If you ever find a test case that is incomplete, please open an issue so we can get it fixed.

##Credits

Many thanks to the .NET team for their DateTime class and a major thank you to Jani Giannoudis for his work on ITimePeriod.

##License

The MIT License (MIT)

Copyright (c) 2014 Matthew York

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.