Handle times, dates, calendars, and durations like a pro in Objective-C with YLMoment

Working with dates in Objective-C is not really easy; at least for beginners. You have to deal with various classes provided by the “Foundation Framework” such as NSDate, NSDateComponents, NSDateFormatterNSCalendar, NSTimeZone or with NSLocale (for user language/region).

In order to make your life easier, YLMoment has been written to provide you an unique API (class) to dealing with dates, durations, times and calendars in Objective-C inspired by the well-known moment.js library.

This post aims to present you the potential of this library by showing you several hands-on examples.


We start by showing you how to create a new moment. There are several initializers to help you creating a moment, for example, by passing a date, an array or string with a format that will be parsed into a date.

// Create a new moment object
YLMoment *now = [YLMoment now];
NSLog(@"%@", now); // Display: 2013-11-09T19:16:33+0100

// Create a new moment in the past, using a string date
YLMoment *past = [YLMoment momentWithDateAsString:@"May 4, 2012" format:@"MMM d, y"];
NSLog(@"%@", past); // Display: 2012-05-04T00:00:00+0100

// Create a new moment in the future, using an array
YLMoment *future = [YLMoment momentWithArray:@[@2034, @3, @14]];
NSLog(@"%@", [future format:@"d MMMM y"]); // Display: 14 March 2034

// Create a moment with a french locale
YLMoment *moment = [YLMoment momentWithDateAsString:@"4 septembre 2008" format:@"d MMMM y" localeIdentifier:@"fr_FR"];
NSLog(@"%@", moment); // Display: 2008-09-04T00:00:00+0200

// Create an invalid date
YLMoment *invalid = [YLMoment momentWithDateAsString:@"not a date"];
NSLog(@"%@, %d", invalid, [invalid isValid]); // Display: Invalid Date, 0

To help you, you can find a well presented format string list here.

Working with dates

Now we are going to go a bit further by working with dates, for example by using a method to determine the time that has passed since now, by determining the end of the year or by adding/subtracting some amount of time to a moment.

// Set the moment to GMT+0 (UTC)
[[YLMoment proxy] setTimeZone:[NSTimeZone timeZoneWithAbbreviation:@"UTC"]];
// Now
NSLog(@"%@", [[YLMoment now] format:nil]); // Display: November 17, 2013 at 4:02:41 PM GMT
// When was I born?
YLMoment *birthday = [YLMoment momentWithDateAsString:@"December 11, 1986" format:@"MMMM d, y"];
NSLog(@"I was born %@", [birthday fromNow]); // Display: I was born 27 years ago
// How old am I?
NSLog(@"I am %@ old", [birthday fromNowWithSuffix:NO]); // Display: I am 27 years old
// When will the end of year be?
YLMoment *endOfYear = [[YLMoment now] endOf:@"year"];
NSLog(@"%@", [endOfYear fromNow]); // Display: in a month
// When will the end february 2014 be?
YLMoment *lastDayOfFebruary = [[[YLMoment momentWithArray:@[@2014, @2, @1]] endOf:@"month"] startOf:@"day"];
NSLog(@"%@", [lastDayOfFebruary format:nil]); // Display: February 28, 2014 at 12:00:00 AM GMT

// When will the last day of february plus one day be?
YLMoment *firstMarch = [lastDayOfFebruary addAmountOfTime:1 forUnitKey:@"day"];
NSLog(@"%@", [firstMarch format:nil]); // Display: March 1, 2014 at 12:00:00 AM GMT


To conclude, although that YLMoment is under development (currently 0.2), you have seen it makes your life easier to work with dates, times, durations and calendars in Objective-C by providing you a nice set of API. I hope that this short overview gave you a good idea of what is possible with YLMoment. Moreover YLMoment provides unit tests which make its use more robust and so more comfortable.

If you have not tested this library yet, it’s time for you to give it a try.

You can find its github page here.

1 Star2 Stars3 Stars4 Stars5 Stars (4 votes, average: 3.75 out of 5)
Share on FacebookShare on Google+Tweet about this on TwitterShare on LinkedInShare on RedditPin on Pinterest


Time limit is exhausted. Please reload CAPTCHA.

  1. Mazyod · November 9, 2013

    That’s a superb API. I am just wondering about 2 important things when dealing with dates:
    1 – Calendars
    2 – DST

    As you may well be aware, adding a “day” to an NSDate isn’t as simple as adding a time interval of 60*60*24. This has been explained by Apple engineers at WWDC, since DST isn’t taken into account this way. It should be a day should be added by setting NSDateComponents and adding the components to an NSDate through a calendar.

    • Yannick Loriot · November 9, 2013

      Yes the ‘addAmountOfTime:forUnitKey:‘ method uses the NSDateComponent and the NSCalendar components to compute the new dates. I tried to use as much as possible the Core Foundations classes to build this library in order to make the core more robust. I should update the post by explaining that (I’ll add some examples for these details).

      Thank you for the hints. 🙂