DateTools was written to streamline date and time handling in iOS. Classes and concepts from other languages served as an inspiration for DateTools, especially the DateTime structure and 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

---

 

Assuming you have added the localization to your project, DateTools currently supports the following languages:

• ar (Arabic)
• bg (Bulgarian)
• ca (Catalan)
• zh_Hans (Chinese Simplified)
• zh_Hant (Chinese Traditional)
• 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)

If you know a language not listed here, please consider submitting a translation. Localization codes by language.

This project is user driven (by people like you). Pull requests close faster than issues (merged or rejected).

Thanks to Kevin Lawler for his work on NSDate+TimeAgo, which has been officially merged into this library.

There is a lot of boilerplate associated with getting date components from an Date. 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:

…becomes this:

The date editing methods in DateTools makes it easy to shift 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:

…becomes this:

Subtraction of date components is also fully supported through the dateBySubtractingYears

Another mission of the DateTools category is to greatly increase the flexibility of date comparisons. Date 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; to easily ask “is this date earlier than that one?”. 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? Date 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 one wants to know how many years or days are between two dates. For this, DateTools goes back to the ever-trusty NSCalendar and abstracts out all the necessary code for you.

With Date Tools, this:

.becomes this:

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:

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.

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.

A host of methods have been extended to give information about an instance of TimePeriod. A few are listed below

• hasStartDate – Returns true if the period has a start date
• hasEndDate – Returns true if the period has an end date
• isMoment – Returns true if the period has the same start and end date
• durationIn.... – Returns the length of the time period in the requested units

Time periods may also be manipulated. They may be shifted earlier or later as well as expanded and contracted.

Shifting

When a time period is shifted, the start dates and end dates are both moved earlier or later by the amounts requested. To shift a time period earlier, call shiftEarlierWithSize:amount: and to shift it later, call shiftLaterWithSize:amount:. The amount field serves as a multipler, just like in the above initializaion method.

Lengthening/Shortening

When a time periods is lengthened or shortened, it does so anchoring one date of the time period and then changing the other one. There is also an option to anchor the centerpoint of the time period, changing both the start and end dates.

An example of lengthening a time period is shown below:

This doubles a time period of duration 1 minute to duration 2 minutes. The end date of “now” is retained and only the start date is shifted 1 minute earlier.

There may come a need, say when you are making a scheduling app, when it might be good to know how two time periods relate to one another. Are they the same? Is one inside of another? All these questions may be asked using the relationship methods of TimePeriod.

Below is a chart of all the possible relationships between two time periods: 

A suite of methods have been extended to check for the basic relationships. They are listed below:

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

You can also check for the official relationship (like those shown in the chart) with the following method:

All of the possible relationships have been enumerated in the TimePeriodRelation enum.

For a better grasp on how time periods relate to one another, check out the “Time Periods” tab in the example application. Here you can slide a few time periods around and watch their relationships change.

orting Sorting time periods in a collection is easy, just call one of the sort methods. There are a total of three sort options, listed below:

• Start Date – sortByStartAscending, sortByStartDescending
• End Date – sortByEndAscending, sortByEndDescending
• Time Period Duration – sortByDurationAscending, sortByDurationDescending

Operations It is also possible to check an Date’s or TimePeriod’s relationship to the collection. For instance, if you would like to see all the time periods that intersect with a certain date, you can call the periodsIntersectedByDate: method. The result is a new TimePeriodCollection with all those periods that intersect the provided date. There are a host of other methods to try out as well, including a full equality check between two collections.

Time period chains serve as a tightly coupled set of time periods. They are always organized by start and end date, and have their own characteristics like a StartDate and EndDate that are extrapolated from the time periods within. Time period chains do not allow overlaps within their set of time periods. This type of group is ideal for modeling schedules like sequential meetings or appointments.

To make a new chain, call the class method like so:

Any time a date is added to the time chain, it retains its duration, but is modified to have its StartDate be the same as the latest period in the chain’s EndDate. This helps keep the tightly coupled structure of the chain’s time periods. Inserts (besides those at index 0) shift dates after insertion index by the duration of the new time period while leaving those at indexes before untouched. Insertions at index 0 shift the start date of the collection by the duration of the new time period. A full list of operations can be seen below.

Operations Like collections, chains have an equality check and the ability to be shifted earlier and later. Here is a short list of other operations.

GitHub

---

View Github