YLMoment Class Reference
Inherits from | NSObject |
Declared in | YLMoment.h |
Overview
YLMoment is a library which provides an high abstraction level for parsing, validating, manipulating, and formatting the dates in Objective-C.
Its API is inspired by the well known moment.js library, however unlike its father, its core is built upon the Foundation Framework components (NSDate, NSDateFormatter,etc.) for a full interoperability with iOS.
Tasks
Creating and Initializing Moment Objects
-
+ now
-
+ utc
-
– initWithDate:
-
+ momentWithDate:
-
– initWithArray:
-
+ momentWithArray:
-
– initWithDateAsString:
-
+ momentWithDateAsString:
-
– initWithDateAsString:format:
-
+ momentWithDateAsString:format:
-
– initWithDateAsString:format:localeIdentifier:
-
+ momentWithDateAsString:format:localeIdentifier:
-
– initWithDateAsString:format:locale:timeZone:
-
+ momentWithDateAsString:format:locale:timeZone:
Proxy Method
Configuring Moments
Representing Moments as Strings
Validating Moments
Working with Moments
Comparing Moments
Working with Relative Times
-
– fromNow
-
– fromNowWithSuffix:
-
– fromDate:
-
– fromDate:withSuffix:
-
– fromMoment:
-
– fromMoment:withSuffix:
Manipulating Moments
-
– addAmountOfTime:forUnitKey:
-
– addAmountOfTime:forCalendarUnit:
-
– addDuration:
-
– subtractAmountOfTime:forUnitKey:
-
– subtractAmountOfTime:forCalendarUnit:
-
– subtractDuration:
-
– startOf:
-
– startOfCalendarUnit:
-
– endOf:
-
– endOfCalendarUnit:
Getting/Setting Moment Components
Helpers
Properties
calendar
The calendar that will be used for the date calculations.
@property (atomic, strong) NSCalendar *calendar
Availability
0.1.0
Discussion
The default value is set to the current calendar.
Declared In
YLMoment.h
dateStyle
The date style of the receiver.
@property (atomic, assign) NSDateFormatterStyle dateStyle
Availability
0.2.0
Discussion
By default the date style is set to NSDateFormatterLongStyle
.
Declared In
YLMoment.h
day
Gets or sets the day of the month.
@property (nonatomic, assign) NSUInteger day
Availability
0.1.0
Discussion
Accepts numbers from 1 to 31. If the range is exceeded, it will bubble up to the months.
Declared In
YLMoment.h
hour
Gets or sets the hour.
@property (nonatomic, assign) NSUInteger hour
Availability
0.1.0
Discussion
Accepts numbers from 0 to 23. If the range is exceeded, it will bubble up to the day.
Declared In
YLMoment.h
locale
The local that will be used to display the dates.
@property (atomic, strong) NSLocale *locale
Availability
0.1.0
Discussion
The default value is set to the current locale.
Declared In
YLMoment.h
minute
Gets or sets the minutes.
@property (nonatomic, assign) NSUInteger minute
Availability
0.1.0
Discussion
Accepts numbers from 0 to 59. If the range is exceeded, it will bubble up to the hours.
Declared In
YLMoment.h
month
Gets or sets the month.
@property (nonatomic, assign) NSUInteger month
Availability
0.1.0
Discussion
Accepts numbers from 1 to 12. If the range is exceeded, it will bubble up to the year.
Declared In
YLMoment.h
second
Gets or sets the seconds.
@property (nonatomic, assign) NSUInteger second
Availability
0.1.0
Discussion
Accepts numbers from 0 to 59. If the range is exceeded, it will bubble up to the minutes.
Declared In
YLMoment.h
timeStyle
The time style of the receiver.
@property (atomic, assign) NSDateFormatterStyle timeStyle
Availability
0.2.0
Discussion
By default the date style is set to NSDateFormatterLongStyle
.
Declared In
YLMoment.h
Class Methods
calendarUnitForKey:
Returns the NSCalendarUnit
corresponding to a given unit string
key.
+ (NSCalendarUnit)calendarUnitForKey:(NSString *)key
Parameters
- key
A unit string key.
Return Value
The NSCalendarUnit
corresponding to a given unit string key. -1
if the key is unknow.
Availability
0.1.0
Discussion
There are some shorthand keys as well if you’re into that whole brevity thing:
Singular | Plural | Shorthand | NSCalendarUnit Correspondence |
---|---|---|---|
year | years | y | NSCalendarUnitYear |
month | months | M | NSCalendarUnitMonth |
week | weeks | w | NSCalendarUnitWeekOfMonth |
day | days | d | NSCalendarUnitDay |
hour | hours | h | NSCalendarUnitHour |
minute | minutes | m | NSCalendarUnitMinute |
second | seconds | s | NSCalendarUnitSecond |
Declared In
YLMoment.h
momentWithArray:
Creates and returns a moment with an array of numbers that mirror the following components [‘year’, ‘month’, ‘day’, ‘hour’, ‘minute’, ‘second’].
+ (instancetype)momentWithArray:(NSArray *)dateAsArray
Parameters
- dateAsArray
An array which represent the date components.
Availability
0.1.0
Discussion
The moment will create a date in the current timezone.
See Also
Declared In
YLMoment.h
momentWithDate:
Creates and returns a moment using a given date.
+ (instancetype)momentWithDate:(NSDate *)date
Parameters
- date
a date.
Availability
0.1.0
See Also
Declared In
YLMoment.h
momentWithDateAsString:
Creates and returns a moment using the date representation of a given string.
+ (instancetype)momentWithDateAsString:(NSString *)dateAsString
Parameters
- dateAsString
The date string to parse.
Availability
0.1.0
See Also
Declared In
YLMoment.h
momentWithDateAsString:format:
Creates and returns a moment using the date representation of a given string interpreted and using a given date format.
+ (instancetype)momentWithDateAsString:(NSString *)dateAsString format:(NSString *)dateFormat
Parameters
- dateAsString
The date string to parse.
Availability
0.1.0
See Also
Declared In
YLMoment.h
momentWithDateAsString:format:locale:timeZone:
Creates and returns a moment using the date representation of a given string interpreted, a given date format, a given locale, and a time zone.
+ (instancetype)momentWithDateAsString:(NSString *)dateAsString format:(NSString *)dateFormat locale:(NSLocale *)locale timeZone:(NSTimeZone *)timeZone
Parameters
- dateAsString
The date string to parse.
- locale
The locale object.
- timeZone
The time zone object.
Availability
0.4.0
Discussion
The given locale
and timeZone
are set by default to the new
moment. If you want you the global (proxy) value instead, set them to nil.
Declared In
YLMoment.h
momentWithDateAsString:format:localeIdentifier:
Creates and returns a moment using the date representation of a given string interpreted, a given date format, and a given locale identifier.
+ (instancetype)momentWithDateAsString:(NSString *)dateAsString format:(NSString *)dateFormat localeIdentifier:(NSString *)localeIdentifier
Parameters
- dateAsString
The date string to parse.
- localeIdentifier
The identifier for the new locale for the receiver.
Availability
0.1.0
Declared In
YLMoment.h
now
Creates and returns a moment which is set to the current date.
+ (instancetype)now
Availability
0.1.0
Declared In
YLMoment.h
Instance Methods
addAmountOfTime:forCalendarUnit:
Mutates and returns the original moment by adding time. To add time, pass the calendar unit of what time you want to add, and the corresponding amount.
- (YLMoment *)addAmountOfTime:(NSInteger)amount forCalendarUnit:(NSCalendarUnit)unit
Parameters
- amount
The amount of time you want to add.
- unit
The calendar unit of what time you want to add.
Return Value
The current moment with the amount of time added for a fluent interface pattern.
Availability
0.1.0
Declared In
YLMoment.h
addAmountOfTime:forUnitKey:
Mutates and returns the original moment by adding time. To add time, pass the key of what time you want to add, and the corresponding amount.
- (YLMoment *)addAmountOfTime:(NSInteger)amount forUnitKey:(NSString *)key
Parameters
- amount
The amount of time you want to add.
- key
The key of what time you want to add.
Return Value
The current moment with the amount of time added for a fluent interface pattern.
Availability
0.1.0
See Also
Declared In
YLMoment.h
addDuration:
Mutates and returns the original moment by adding a time duration.
- (YLMoment *)addDuration:(NSTimeInterval)duration
Parameters
- duration
A time interval to add.
Return Value
The current moment with the time duration added for a fluent interface pattern.
Availability
0.1.0
Declared In
YLMoment.h
date
Returns the NSDate
corresponding to the current moment.
- (NSDate *)date
Return Value
the NSDate
corresponding to the current moment.
Availability
0.1.0
Discussion
Returns the NSDate
corresponding to the current moment.
Declared In
YLMoment.h
endOf:
Mutates and returns the original moment by setting it to the end of
a given unit of time. This is the same as startOf
, only instead of setting
to the start of a unit of time, it sets to the end of a unit of time.
- (YLMoment *)endOf:(NSString *)unitString
Parameters
- unitString
The key of what time you want to end.
Return Value
The original moment with the setting applied for a fluent interface pattern.
Availability
0.1.0
See Also
Declared In
YLMoment.h
endOfCalendarUnit:
Mutates and returns the original moment by setting it to the end of
a given unit of time. This is the same as startOfCalendarUnit
, only instead
of setting to the start of a unit of time, it sets to the end of a unit of time.
- (YLMoment *)endOfCalendarUnit:(NSCalendarUnit)unit
Parameters
- unit
The key of what time you want to end.
Return Value
The original moment with the setting applied for a fluent interface pattern.
Availability
0.1.0
Declared In
YLMoment.h
format
Returns a string representation of the moment formatted using the
ISO-8601
format.
- (NSString *)format
Return Value
A string representation of the moment formatted using the ISO-8601
format.
Availability
0.1.0
Declared In
YLMoment.h
format:
- (NSString *)format:(NSString *)dateFormat
Parameters
- dateFormat
The date format for the receiver. See Date Formatting Guide_4.html#//apple_ref/doc/uid/TP40002369-SW1) for a list of the conversion specifiers permitted in date format strings.
Availability
0.1.0
Discussion
The breakdown of which string is displayed for each format tokens is outlined in the table below:
Format String | Output String |
---|---|
M/d/y | 11/4/2012 |
MM/dd/yy | 11/04/12 |
MMM d, ‘'yy | Nov 4, ‘12 |
MMMM | November |
E | Sun |
EEEE | Sunday |
‘Week’ w ‘of 52’ | Week 45 of 52 |
‘Day’ D ‘of 365’ | Day 309 of 365 |
QQQ | Q4 |
QQQQ | 4th quarter |
m ‘minutes past’ h | 9 minutes past 8 |
h:mm a | 8:09 PM |
HH:mm:ss’s' | 20:09:00s |
HH:mm:ss:SS | 20:09:00:00 |
h:mm a zz | 8:09 PM CST |
h:mm a zzzz | 8:09 PM Central Standard Time |
yyyy-MM-dd HH:mm:ss Z | 2012-11-04 20:09:00 -0600 |
Declared In
YLMoment.h
fromDate:
Returns a suffixed string representing the relative time from a given date using the locale of the moment.
- (NSString *)fromDate:(NSDate *)date
Parameters
- date
The reference date.
Return Value
A suffixed string representing the relative time from a given date using the locale of the moment.
Availability
0.1.0
See Also
Declared In
YLMoment.h
fromDate:withSuffix:
Returns a suffixed string representing the relative time from a given date using the locale of the moment and suffixed if necessary.
- (NSString *)fromDate:(NSDate *)date withSuffix:(BOOL)suffixed
Parameters
- date
The reference date.
- suffixed
Tells whether the relative time needs to be suffixed. E.g. a relative suffixed time looks that
4 years ago
whereas a relative unsuffixed time looks like this4 years
.
Return Value
A suffixed string representing the relative time from a given date using the locale of the moment and suffixed if necessary.
Availability
0.1.0
Discussion
The breakdown of which string is displayed for each length of time is outlined in the table below:
Range | Key | Sample Output |
---|---|---|
0 to 45 seconds | s | a few seconds ago |
45 to 90 seconds | m | a minute ago |
90 seconds to 45 minutes | mm | 2 minutes ago … 45 minutes ago |
45 to 90 minutes | h | an hour ago |
90 minutes to 22 hours | hh | 2 hours ago … 22 hours ago |
22 to 36 hours | d | a day ago |
36 hours to 25 days | dd | 2 days ago … 25 days ago |
25 to 45 days | M | a month ago |
45 to 345 days | MM | 2 months ago … 11 months ago |
345 to 547 days (1.5 years) | y | a year ago |
548 days+ | yy | 2 years ago … 20 years ago |
Declared In
YLMoment.h
fromMoment:
Returns a suffixed string representing the relative time from a given moment using the locale of the moment.
- (NSString *)fromMoment:(YLMoment *)moment
Parameters
- moment
The reference moment.
Return Value
A suffixed string representing the relative time from a given moment using the locale of the moment.
Availability
0.1.0
See Also
Declared In
YLMoment.h
fromMoment:withSuffix:
Returns a suffixed string representing the relative time from a given moment using the locale of the moment and suffixed if necessary.
- (NSString *)fromMoment:(YLMoment *)moment withSuffix:(BOOL)suffixed
Parameters
- moment
The reference moment.
- suffixed
Tells whether the relative time needs to be suffixed. E.g. a relative suffixed time looks that
4 years ago
whereas a relative unsuffixed time looks like this4 years
.
Return Value
A suffixed string representing the relative time from a given moment using the locale of the moment and suffixed if necessary.
Availability
0.1.0
See Also
Declared In
YLMoment.h
fromNow
Returns a suffixed string representing the relative time using the locale of the moment.
- (NSString *)fromNow
Return Value
A suffixed string with the representing time using the locale of the moment.
Availability
0.1.0
See Also
Declared In
YLMoment.h
fromNowWithSuffix:
Returns a string representing the relative time using the locale of the moment and suffixed if necessary.
- (NSString *)fromNowWithSuffix:(BOOL)suffixed
Parameters
- suffixed
Tells whether the relative time needs to be suffixed. E.g. a relative suffixed time looks that
4 years ago
whereas a relative unsuffixed time looks like this4 years
.
Return Value
a string representing the relative time using the locale of the moment and suffixed if necessary. @see: fromDate:withSuffix:
Declared In
YLMoment.h
initWithArray:
Initializes a moment with an array of numbers that mirror the following components [‘year’, ‘month’, ‘day’, ‘hour’, ‘minute’, ‘second’].
- (instancetype)initWithArray:(NSArray *)dateAsArray
Parameters
- dateAsArray
An array which represent the date components.
Availability
0.1.0
Discussion
The moment will create a date in the current timezone.
Declared In
YLMoment.h
initWithDate:
Initializes a moment using a given date.
- (instancetype)initWithDate:(NSDate *)date
Parameters
- date
a date.
Availability
0.1.0
Declared In
YLMoment.h
initWithDateAsString:
Initializes a moment using the date representation of a given string interpreted.
- (instancetype)initWithDateAsString:(NSString *)dateAsString
Parameters
- dateAsString
The date string to parse.
Availability
0.1.0
Declared In
YLMoment.h
initWithDateAsString:format:
Initialize a moment using the date representation of a given string interpreted and using a given date format.
- (instancetype)initWithDateAsString:(NSString *)dateAsString format:(NSString *)dateFormat
Parameters
- dateAsString
The date string to parse.
Availability
0.1.0
Declared In
YLMoment.h
initWithDateAsString:format:locale:timeZone:
Initialize a moment using the date representation of a given string interpreted, a given date format, a given locale, and a time zone.
- (instancetype)initWithDateAsString:(NSString *)dateAsString format:(NSString *)dateFormat locale:(NSLocale *)locale timeZone:(NSTimeZone *)timeZone
Parameters
- dateAsString
The date string to parse.
- locale
The locale object.
- timeZone
The time zone object.
Availability
0.4.0
Discussion
The given locale
and timeZone
are set by default to the new
moment. If you want you the global (proxy) value instead, set them to nil.
Declared In
YLMoment.h
initWithDateAsString:format:localeIdentifier:
Initialize a moment using the date representation of a given string interpreted, a given date format, and a given locale identifier.
- (instancetype)initWithDateAsString:(NSString *)dateAsString format:(NSString *)dateFormat localeIdentifier:(NSString *)localeIdentifier
Parameters
- dateAsString
The date string to parse.
- localeIdentifier
The identifier for the new locale for the receiver.
Availability
0.1.0
Declared In
YLMoment.h
isEqualToMoment:
Returns a Boolean value that indicates whether a given object
is an YLMoment
object and exactly equal the receiver.
- (BOOL)isEqualToMoment:(YLMoment *)anotherMoment
Parameters
- anotherMoment
The moment to compare with the receiver.
Return Value
YES if the anotherMoment is an YLMoment
object and is exactly
equal to the receiver, otherwise NO.
Availability
0.1.0
Declared In
YLMoment.h
isValid
Returns true whether the current moment is valid.
- (BOOL)isValid
Return Value
true
whether the current moment is valid.
Availability
0.1.0
Declared In
YLMoment.h
startOf:
Mutates and returns the original moment by setting it to the start of a given unit of time.
- (YLMoment *)startOf:(NSString *)unitString
Parameters
- unitString
The key of what time you want to start.
Return Value
The original moment with the setting applied for a fluent interface pattern.
Availability
0.1.0
See Also
Declared In
YLMoment.h
startOfCalendarUnit:
Mutates and returns the original moment by setting it to the start of a given unit of time.
- (YLMoment *)startOfCalendarUnit:(NSCalendarUnit)unit
Parameters
- unit
The key of what time you want to start.
Return Value
The original moment with the setting applied for a fluent interface pattern.
Availability
0.1.0
Declared In
YLMoment.h
subtractAmountOfTime:forCalendarUnit:
Mutates and returns the original moment by subtracting time. To add time, pass the calendar unit of what time you want to subtract, and the corresponding amount.
- (YLMoment *)subtractAmountOfTime:(NSInteger)amount forCalendarUnit:(NSCalendarUnit)unit
Parameters
- amount
The amount of time you want to subtract.
- unit
The calendar unit of what time you want to subtract.
Return Value
The current moment with the amount of time subtracted for a fluent interface pattern.
Availability
0.3.0
See Also
Declared In
YLMoment.h
subtractAmountOfTime:forUnitKey:
Mutates and returns the original moment by subtracting time. To subtract time, pass the key of what time you want to subtract, and the corresponding amount.
- (YLMoment *)subtractAmountOfTime:(NSInteger)amount forUnitKey:(NSString *)key
Parameters
- amount
The amount of time you want to subtract.
- key
The key of what time you want to subtract.
Return Value
The current moment with the amount of time subtracted for a fluent interface pattern.
Availability
0.3.0
Declared In
YLMoment.h
subtractDuration:
Mutates and returns the original moment by subtracting a time duration.
- (YLMoment *)subtractDuration:(NSTimeInterval)duration
Parameters
- duration
A time interval to subtract.
Return Value
The current moment with the time duration subtracted for a fluent interface pattern.
Availability
0.3.0
See Also
Declared In
YLMoment.h