billymeltdown / nsdate-helper Goto Github PK

A category to extend Cocoa's NSDate class with some convenience functions.

Objective-C 100.00%

nsdate-helper's Introduction

NSDate (Helper)

This is a category for the NSDate class that provides some convenience methods for working with NSDate objects and displaying formatted and relative strings.

More information can be found at my initial blog post.

Anyone is welcome to use it for anything, and to change it as they see fit. If you’d like to contribute back any changes (woot!), please fork and send a pull request!

Usage

Full documentation is now up on the Github wiki for this project. It’s a lot better than this kinda rambling overview here.

Two convenience methods make it easy for you to display some relative date information. stringForDisplayFromDate gives you the kind of relative format you see in the Notes listing on the iPhone:


  NSString *displayString = [NSDate stringForDisplayFromDate:date];

This produces the following kinds of output:

‘3:42 AM’ – if the date is after midnight today
‘Tuesday’ – if the date is within the last seven days
‘Mar 1’ – if the date is within the current calendar year
‘Mar 1, 2008’ – else ;-)


  NSString *displayString = [NSDate stringForDisplayFromDate:date prefixed:YES];

This produces the same as above, but prefixed with ‘at’ or ‘on’ depending on the appropriate English syntax.

Another set of methods provide days-ago information:


  NSDate *date = [NSDate date];
  [date daysAgo]; // provides an NSComponent-based NSUInteger describing days ago.
  [date daysAgoAgainstMidnight]; // better version of daysAgo, works off midnight (hat-tip: "sburlot":http://github.com/sburlot)
  [date stringDaysAgo]; // 'Today', 'Yesterday', or 'N days ago'.

Tired of creating and releasing date formatters? Missing things like to_s(:db)? Me, too. NSDate (Helper) has some static methods to make going back and forth between strings and dates a little less painful, and particularly easier when working with database timestamps (a la SQLite):


  NSDate *date = [NSDate dateFromString:@"2009-03-01 12:15:23"];
  NSString *dbDateString = [NSDate stringFromDate:date]; // returns '2009-03-01 12:15:23'

Who needs NSDateFormatter?


  NSString *otherDateString = [NSDate stringFromDate:date withFormat:@"EEEE"]; // use any format you like

Installation

To use it in your Cocoa project, import the header and implementation files, and then add the header to your project’s _prefix.pch file so that it’s available across your project:


#ifdef __OBJC__
    #import <Foundation/Foundation.h>
    #import <UIKit/UIKit.h>
    #import "NSDate+Helper.h"
#endif

License

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
Neither the name of the ZETETIC LLC nor the
names of its contributors may be used to endorse or promote products
derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY ZETETIC LLC ‘’AS IS’’ AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL ZETETIC LLC BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

nsdate-helper's People

Contributors

Stargazers

Watchers

Forkers

handywang leemax veritech gdey jkubicek logicaroma dev2dev nickvelloff arpitjain11 remear escoz fahimf rmartell sumanthk2006 iabuelruzz romanr dseredinov sinnerschradermobilemirrors mistermaik wrightscs alexnauda jarlehansen duyhungtnn huminzhi augustinelin hyacinth easonoutlook odnairy alsotang jun1st crsantos spencermiles cmendesce 14lox ygurzeev tuyennguyen266 piercifani coderxl shahzadmajeed jianlei markflowers invisibi loftierthoughts mutekinootoko roodkcab adozenlines rahulvishwkarma jhurliman dschoeni massdonati yanbin-ha keho98 quatschsalat hanhailong devsc heliang219 gennick sn0 akotulu sulfo kerryjava jefrydagucci fanzhengfeng dpatel unbirdlikebird mitchellporter menaweb qilifengxiang tdflowers cloudless foxswang torinkwok tonimoeckel 91song huguesbr waynett eusthace811 theiosdevguy ruanjunhao managerorganization jinjian1991 kiemduong 765235992 clayguitar kumarrajeshgupta prashantsharma15 wangzhao168 mihir-elite dwightchan xiongqing disneytom juzihuang imcg33k protonmail stephanluo free-am gopalkrishnareddy wangdu1005 lzhangjianjunl noahxinhao

nsdate-helper's Issues

Implement instance methods for returning strings

I'm not really sure why I didn't do this in the first place, but this would be a lot easier to use and look a tad nicer if I implemented something like:

NSDate *date = [NSDate date];
NSString *dbString = [date string];
NSString *formattedString = [date stringWithFormat:@"yyyy"];

That last one strikes me as nice-to-have and possibly over-complicating things, but definitely need to get some instance methods going here to replace the need to call class methods in a clumsier fashion, e.g.:

NSString *dbString = [NSDate stringFromDate:date];
NSString *formatted = [NSDate stringFromDate:date withFormat:@"yyyy"];

CocoaPods

CocoaPods is awesome, why don't you use it?

Add NSLocale support

This works great for english, but when the device is under another language it stills trows dates in english.

Please add semantic version tags

I’ve recently added NSDate+Helper to the CocoaPods package manager repo.

CocoaPods is a tool for managing dependencies for OSX and iOS Xcode projects and provides a central repository for iOS/OSX libraries. This makes adding libraries to a project and updating them extremely easy and it will help users to resolve dependencies of the libraries they use.

However, NSDate+Helper doesn't have any version tags. I’ve added the current HEAD as version 0.0.1, but a version tag will make dependency resolution much easier.

Semantic version tags (instead of plain commit hashes/revisions) allow for resolution of cross-dependencies.

In case you didn’t know this yet; you can tag the current HEAD as, for instance, version 1.0.0, like so:

$ git tag -a 1.0.0 -m "Tag release 1.0.0"
$ git push --tags

stringForDisplayFromDate:prefixed: returns nil in Release configuration, iOS 5.1 (possibly earlier)

We've had bugs emerge in Codebook and Strip, where I use NSDate+Helper heavily, since the introduction of a static NSCalendar variable in this category's +load implementation. This can be seen with a little NSLog output on the Console in Release configuration on iOS 5.1:

Mar 28 10:59:43 unknown Codebook[11773] <Warning>: date in question: 2012-03-27 19:47:09 +0000
Mar 28 10:59:43 unknown Codebook[11773] <Warning>: today is: 2012-03-28 14:59:43 +0000
Mar 28 10:59:43 unknown Codebook[11773] <Warning>: midnight based on today and calendar components: (null)
Mar 28 10:59:43 unknown Codebook[11773] <Warning>: shared calendar object? (null)

I believe load is not being called at the same time in Release configuration for this category as it is for Debug configuration, and something about when it is being called results in the static calendar variable being null. It could be that there was no 'currentCalendar' when the category was originally loaded (likely not when my view was loaded above). While this was introduced for performance, it's not working in Release, going to have to remove the static variable for now. Open to other ideas, especially if anybody (Jim?) wants to dig into why +load isn't being called at the same time and how we could approach this differently. FWIW, performance doesn't appear to be too bad, I'd be curious to see any metrics demonstrating particularly poor performance (I hadn't noticed any issues myself before this change was introduced).

Support for Locale?

Is there any plan to support more language, like spanish?

Calling stringWithFormat directly as the only use returns nil

If the first use of the library is a call to stringWithFormat then nil is returned. This is happening because the static date formatter has not been initialized in this case.

License Update Coming

So, the code in this little module has been simply (C) Zetetic LLC since we put it up here. In the interests of 1) making it actual open source code and 2) kindly asking others to credit the authors (in this regard, I hope it will encourage others to contribute), I'm planning on adding an actual license to the project.

I intend to use exactly the same one we use for sjlombardo/sqlcipher, unless anybody objects. It's nearly identical to the MIT-style license used by many Ruby projects, and we think it's appropriate. I'm certainly open to other ideas, please feel free to comment.

http://github.com/sjlombardo/sqlcipher/blob/master/README

Regards,
Billy

Date Jumps Year

User denvog reports:

I noticed last week in the Kevin Smith App that some of my dates handled with NSDate+Helper are now jumping a year. It looks like everything in the last week of December/first week of January. For example, a post on Dec 29, 2009 is showing as Dec 29, 2010. While Dec 25 is showing correctly as 2009.

I've done a bunch of logging, and the source data coming in is correct with 2009.

It looks like it is items calling stringForDisplayFromDate

So I think the fix is to change line 129 of NSDate+Helper.m from
[displayFormatter setDateFormat:@"MMM d, YYYY"];

                           [displayFormatter setDateFormat:@"MMM d, yyyy"];

According to this thread there is a difference in calendar as of day, as opposed to calendar year as of week.
http://www.iphonedevsdk.com/forum/iphone-sdk-development/8355-date-formatting-yyyy-vs-yyyy-getting-wrong-year.html

NSDateFormatter is too expensive

It's bad practice to create new instance of NSDateFormatter every time, when I call method. Creation of this object is too expensive. From Apple Data Formatting Guide:

Creating a date formatter is not a cheap operation. If you are likely to use a formatter frequently, it is typically more efficient to cache a single instance than to create and dispose of multiple instances. One approach is to use a static variable.