When does dateByAddingComponents:toDate:options return nil?

Question

I've been using dateByAddingComponents:toDate:options: and dateByAddingUnit:value:toDate:options: and using optional binding to get the date out of it. Like this:

guard let startOfNextMonth = calendar.dateByAddingComponents(oneMonthComponent, toDate: startOfThisMonth, options: []) else {
    return nil
}

Where oneMonthComponent is just an NSDateComponent with the month value set to 1.

When I read about it, in the documentation they both say something like:

Returns nil if date falls outside the defined range of the receiver or if the computation cannot be performed.

And I've been wondering, when is that exactly caused. If I'm just adding a month to a date, is there a way that could ever be nil? Is this because some differences in the other calendrical systems, where adding some units don't make sense?

I have searched around and have been unable to find an instance where it would return nil.

Is there anything that could make the code above be nil? What is an example where adding components could be nil?

Answer 1

In practice, if you're just adding a month to a date, you will not get nil values.

You can, though, get a nil value in some degenerate situations. For example, if you are using Islamic calendar and add -9,999,999 years, you'll get a nil (though, curiously, not in other calendars). Other calendars will often overflow/wrap the year in these extreme situations (even though you'd expect them to return nil, given the documentation you quote).

Personally, I suspect there are currently very few situations in which you'll get nil values. I tried all sorts of extreme values and the Islamic calendar was the only one that I succeeded in getting a nil value. The doesn't mean, though, that Apple might not add more robust date validation logic in the future. We'd probably have to get counsel from Apple (or see the source code for NSCalendar) to answer this question definitively.

So, bottom line, I'd suggest keeping your guard statement, but it's unlikely to fail in real-world scenarios.