MBMLDateFunctions Class Reference
| Inherits from | NSObject |
|---|---|
| Declared in | MBMLDateFunctions.h |
Overview
This class contains a set of MBML functions and supporting methods that provide date manipulation tools.
These functions are exposed to the Mockingbird environment via
<Function ... /> declarations in the MBDataEnvironmentModule.xml
file.
For more information on MBML functions, see the MBMLFunction class.
Supporting methods
+ defaultDateParsingFormat
Returns the date parsing format used by default.
+ (NSString *)defaultDateParsingFormatReturn Value
The default date parsing format string.
Discussion
First, the string expression $MBMLDateFunctions:dateParsingFormat is checked
for a value; if a value is present, it is returned.
Otherwise, the value of the constant kRFC1123DateStringFormat is returned.
Note: This method is not exposed to the Mockingbird environment as a an MBML function.
Declared In
MBMLDateFunctions.h
+ defaultDateParsingLocale
Returns the date parsing locale used by default.
+ (NSLocale *)defaultDateParsingLocaleReturn Value
The default date parsing locale.
Discussion
First, the string expression $MBMLDateFunctions:dateParsingLocale is checked
for a value; if a value is present, it is used as the locale identifier.
Otherwise, the value of the constant kMBDateParsingLocaleVariableName is
used to construct the locale.
If all else fails, the device’s current locale is used.
Note: This method is not exposed to the Mockingbird environment as a an MBML function.
Declared In
MBMLDateFunctions.h
+ formatDate:withStyle:usingTimeZone:
Returns a date-formatted string using the specified formatter style.
+ (NSString *)formatDate:(NSDate *)d8 withStyle:(NSDateFormatterStyle)style usingTimeZone:(NSTimeZone *)timeZoneParameters
d8 |
The |
|---|---|
style |
The |
timeZone |
The |
Return Value
A string containing the formatted date.
Discussion
Note: This method is not exposed to the Mockingbird environment as a an MBML function.
Declared In
MBMLDateFunctions.h
+ formatTime:withStyle:
Returns a time-formatted string using the specified formatter style.
+ (NSString *)formatTime:(NSDate *)d8 withStyle:(NSDateFormatterStyle)styleParameters
d8 |
The |
|---|---|
style |
The |
Return Value
A string containing the formatted time.
Discussion
Note: This method is not exposed to the Mockingbird environment as a an MBML function.
Declared In
MBMLDateFunctions.h
+ formatDateTime:withStyle:
Returns a date/time-formatted string using the specified formatter style.
+ (NSString *)formatDateTime:(NSDate *)d8 withStyle:(NSDateFormatterStyle)styleParameters
d8 |
The |
|---|---|
style |
The |
Return Value
A string containing the formatted date/time.
Discussion
Note: This method is not exposed to the Mockingbird environment as a an MBML function.
Declared In
MBMLDateFunctions.h
+ parseDate:fromLocale:usingFormat:
Attempts to parse an NSDate from a string using the specified date format.
+ (NSDate *)parseDate:(NSString *)str fromLocale:(NSLocale *)locale usingFormat:(NSString *)dateFormatParameters
str |
The date string to parse. |
|---|---|
locale |
The locale of the input string |
dateFormat |
A date format string as accepted by |
Return Value
An NSDate representing the parsed date string, or nil if there
was an error parsing the string.
Discussion
Note: This method is not exposed to the Mockingbird environment as a
an MBML function. The mbmlParseDate: method implements the
^parseDate() MBML function.
Declared In
MBMLDateFunctions.h
+ parseDate:
Attempts to parse an NSDate from a string in the locale
defaultDateParsingLocale using the date format returned by the
method defaultDateParsingFormat.
+ (NSDate *)parseDate:(NSString *)strParameters
str |
The date string to parse. |
|---|
Return Value
An NSDate representing the parsed date string, or nil if there
was an error parsing the string.
Discussion
Note: This method is not exposed to the Mockingbird environment as a
an MBML function. The mbmlParseDate: method implements the
^parseDate() MBML function.
Declared In
MBMLDateFunctions.h
Getting the current time
+ currentTime
Returns an NSDate representing the current date and time.
+ (NSDate *)currentTimeReturn Value
An NSDate instance representing the present time.
Discussion
This Mockingbird function accepts no input parameters.
Expression usage
The expression:
^currentTime()
returns an NSDate containing the current date and time.
Declared In
MBMLDateFunctions.h
Calculating time deltas to the present
+ secondsSince:
Returns the number of seconds that have elapsed since the given time in the past.
+ (id)secondsSince:(NSDate *)dateParameters
date |
The function’s input parameter. |
|---|
Return Value
An NSNumber instance containing the number of seconds since
the input date; if the input date is in the future, the return
value will be negative.
Discussion
This Mockingbird function accepts a single object expression parameter
yielding an NSDate instance.
Expression usage
The expression:
^secondsSince($referenceDate)
would return the number of seconds elapsed since $referenceDate.
See Also
Declared In
MBMLDateFunctions.h
+ secondsUntil:
Returns the number of seconds between the present time and the given time in the future.
+ (id)secondsUntil:(NSDate *)dateParameters
date |
The function’s input parameter. |
|---|
Return Value
An NSNumber instance containing the number of seconds until
the input date; if the input date is in the past, the return
value will be negative.
Discussion
This Mockingbird function accepts a single parameter: an object expression
expected to yield an NSDate instance.
Expression usage
The expression:
^secondsUntil($referenceDate)
would return the number of seconds until $referenceDate.
See Also
Declared In
MBMLDateFunctions.h
Converting to and from UNIX timestamps
+ unixTimestampToDate:
Converts a UNIX timestamp into an NSDate.
+ (id)unixTimestampToDate:(id)timestampParameters
timestamp |
The function’s input parameter. |
|---|
Return Value
An NSDate instance containing the date representation of given
timestamp.
Discussion
This Mockingbird function accepts a single numeric expression as an input parameter: the UNIX timestamp.
Expression usage
The expression:
^unixTimestampToDate(1355283900)
would return an NSDate representing 10:45PM ET on December 11, 2012.
See Also
Declared In
MBMLDateFunctions.h
+ dateToUnixTimestamp:
Returns the UNIX timestamp representation of a given NSDate.
+ (id)dateToUnixTimestamp:(NSDate *)dateParameters
date |
The function’s input parameter. |
|---|
Return Value
An NSNumber instance containing the UNIX timestamp
representation of the input date.
Discussion
This Mockingbird function accepts a single input parameter: an object
expression yielding an NSDate instance.
Expression usage
The expression:
^dateToUnixTimestamp(^currentTime())
would return the UNIX timestamp representation of the present time.
See Also
Declared In
MBMLDateFunctions.h
Date/time addition
+ addSecondsToDate:
Returns an NSDate representing the given date plus the specified number
of seconds.
+ (id)addSecondsToDate:(NSArray *)paramsParameters
params |
The function’s input parameters. |
|---|
Return Value
The adjusted date.
Discussion
This Mockingbird function accepts two expressions as input parameters:
seconds, a numeric expression specifying the number of seconds add to the input date
the input date, an object expression yielding an
NSDateor date-formattedNSStringcontaining the date to which seconds will be added
Expression usage
The following expression:
^addSecondsToDate(30|^currentTime())
would result in an NSDate 30 seconds from the present time.
Declared In
MBMLDateFunctions.h
Date/time formatting
+ formatTimeUntil:
Returns a string representation of the time remaining until the given date.
+ (id)formatTimeUntil:(NSDate *)dateParameters
date |
The function’s input parameter. |
|---|
Return Value
An NSString instance containing the time until the input date.
Discussion
This Mockingbird function accepts a single parameter: an object expression
expected to yield an NSDate instance.
Expression usage
The expression:
^formatTimeUntil(^addSecondsToDate(300|^currentTime()))
would return the string “5:00”, indicating that there are 5 minutes until
the time that’s 300 seconds in the future.
Declared In
MBMLDateFunctions.h
+ formatDate:
Accepts a date and a format string, and returns a string representation of the date in the specified format.
+ (id)formatDate:(NSArray *)paramsParameters
params |
The function’s input parameters. |
|---|
Return Value
A date-formatted string.
Discussion
This Mockingbird function accepts two expressions as input parameters:
the input date, an
NSDateor date-formattedNSStringthe output format specifying the date format used to create the returned date string
Expression usage
The following expression:
^formatDate(^currentTime()|MM/dd/yy)
would result in the string “12/12/13” if called on December 12th, 2013.
Declared In
MBMLDateFunctions.h
+ formatSortableDate:
Accepts a date and returns a date string formatted using the format
“YYYY-MM-dd HH:mm:ss”. This format ensures allows dates to be sorted using
simple string sorting.
+ (id)formatSortableDate:(id)inputParameters
input |
The function’s input parameter. |
|---|
Return Value
The date-formatted string.
Discussion
This Mockingbird function accepts a single input parameter, an object
expression yielding either an NSDate or a date-formatted NSString
containing the date to format.
Expression usage
The following expression:
^formatSortableDate(^parseDate(Sun, 26 Oct 1986 00:02:00 EDT))
would result in the string “1986-10-26 00:02:00”.
Note: The time in the returned string will be in 24-hour format.
Declared In
MBMLDateFunctions.h
+ formatShortDate:
Accepts a date and returns a date string formatted using the
NSDateFormatterShortStyle format.
+ (id)formatShortDate:(id)inputParameters
input |
The function’s input parameter. |
|---|
Return Value
The date-formatted string.
Discussion
This Mockingbird function accepts one of two expressions as input parameters:
the input date, an
NSDateorNSStringthat contains the date to formatan optional timezone string, specifying the timezone to use when formatting the input date parameter (if this parameter is omitted, the local timezone is used)
Expression usage
The following expression:
^formatShortDate(^parseDate(Sun, 26 Oct 1986 00:02:00 EDT))
would result in the string “10/26/86”.
Note: The string returned depends on the device’s locale settings and may not match the example above.
Declared In
MBMLDateFunctions.h
+ formatMediumDate:
Accepts a date and returns a date string formatted using the
NSDateFormatterMediumStyle format.
+ (id)formatMediumDate:(id)inputParameters
input |
The function’s input parameter. |
|---|
Return Value
The date-formatted string.
Discussion
This Mockingbird function accepts one of two expressions as input parameters:
the input date, an
NSDateorNSStringthat contains the date to formatan optional timezone string, specifying the timezone to use when formatting the input date parameter (if this parameter is omitted, the local timezone is used)
Expression usage
The following expression:
^formatMediumDate(^parseDate(Sun, 26 Oct 1986 00:02:00 EDT))
would result in the string “Oct 26, 1986”.
Note: The string returned depends on the device’s locale settings and may not match the example above.
Declared In
MBMLDateFunctions.h
+ formatLongDate:
Accepts a date and returns a date string formatted using the
NSDateFormatterLongStyle format.
+ (id)formatLongDate:(id)inputParameters
input |
The function’s input parameter. |
|---|
Return Value
The date-formatted string.
Discussion
This Mockingbird function accepts one of two expressions as input parameters:
the input date, an
NSDateorNSStringthat contains the date to formatan optional timezone string, specifying the timezone to use when formatting the input date parameter (if this parameter is omitted, the local timezone is used)
Expression usage
The following expression:
^formatLongDate(^parseDate(Sun, 26 Oct 1986 00:02:00 EDT))
would result in the string “October 26, 1986”.
Note: The string returned depends on the device’s locale settings and may not match the example above.
Declared In
MBMLDateFunctions.h
+ formatFullDate:
Accepts a date and returns a date string formatted using the
NSDateFormatterFullStyle format.
+ (id)formatFullDate:(id)inputParameters
input |
The function’s input parameter. |
|---|
Return Value
The date-formatted string.
Discussion
This Mockingbird function accepts one of two expressions as input parameters:
the input date, an
NSDateorNSStringthat contains the date to formatan optional timezone string, specifying the timezone to use when formatting the input date parameter (if this parameter is omitted, the local timezone is used)
Expression usage
The following expression:
^formatFullDate(^parseDate(Sun, 26 Oct 1986 00:02:00 EDT))
would result in the string “Sunday, October 26, 1986”.
Note: The string returned depends on the device’s locale settings and may not match the example above.
Declared In
MBMLDateFunctions.h
+ formatShortTime:
Accepts a date and returns a date string formatted using the
NSDateFormatterShortStyle format.
+ (id)formatShortTime:(id)inputParameters
input |
The function’s input parameter. |
|---|
Return Value
The time-formatted string.
Discussion
This Mockingbird function accepts a single input parameter, an object
expression yielding either an NSDate or a date-formatted NSString
containing the date to format.
Expression usage
The following expression:
^formatShortTime(^parseDate(Sun, 26 Oct 1986 00:02:00 EDT))
would result in the string “12:02 AM”.
Note: The string returned depends on the device’s locale settings and may not match the example above.
Declared In
MBMLDateFunctions.h
+ formatMediumTime:
Accepts a date and returns a date string formatted using the
NSDateFormatterMediumStyle format.
+ (id)formatMediumTime:(id)inputParameters
input |
The function’s input parameter. |
|---|
Return Value
The time-formatted string.
Discussion
This Mockingbird function accepts a single input parameter, an object
expression yielding either an NSDate or a date-formatted NSString
containing the date to format.
Expression usage
The following expression:
^formatMediumTime(^parseDate(Sun, 26 Oct 1986 00:02:00 EDT))
would result in the string “12:02:00 AM”.
Note: The string returned depends on the device’s locale settings and may not match the example above.
Declared In
MBMLDateFunctions.h
+ formatLongTime:
Accepts a date and returns a date string formatted using the
NSDateFormatterLongStyle format.
+ (id)formatLongTime:(id)inputParameters
input |
The function’s input parameter. |
|---|
Return Value
The time-formatted string.
Discussion
This Mockingbird function accepts a single input parameter, an object
expression yielding either an NSDate or a date-formatted NSString
containing the date to format.
Expression usage
The following expression:
^formatLongTime(^parseDate(Sun, 26 Oct 1986 00:02:00 EDT))
would result in the string “12:02:00 AM EDT”.
Note: The string returned depends on the device’s locale settings and may not match the example above.
Declared In
MBMLDateFunctions.h
+ formatFullTime:
Accepts a date and returns a date string formatted using the
NSDateFormatterFullStyle format.
+ (id)formatFullTime:(id)inputParameters
input |
The function’s input parameter. |
|---|
Return Value
The time-formatted string.
Discussion
This Mockingbird function accepts a single input parameter, an object
expression yielding either an NSDate or a date-formatted NSString
containing the date to format.
Expression usage
The following expression:
^formatFullTime(^parseDate(Sun, 26 Oct 1986 00:02:00 EDT))
would result in the string “12:02:00 AM Eastern Daylight Time”.
Note: The string returned depends on the device’s locale settings and may not match the example above.
Declared In
MBMLDateFunctions.h
+ formatShortDateTime:
Accepts a date and returns a date string formatted using the
NSDateFormatterShortStyle format.
+ (id)formatShortDateTime:(id)inputParameters
input |
The function’s input parameter. |
|---|
Return Value
The date/time-formatted string.
Discussion
This Mockingbird function accepts a single input parameter, an object
expression yielding either an NSDate or a date-formatted NSString
containing the date to format.
Expression usage
The following expression:
^formatShortDateTime(^parseDate(Sun, 26 Oct 1986 00:02:00 EDT))
would result in the string “10/26/86, 12:02 AM”.
Note: The string returned depends on the device’s locale settings and may not match the example above.
Declared In
MBMLDateFunctions.h
+ formatMediumDateTime:
Accepts a date and returns a date string formatted using the
NSDateFormatterMediumStyle format.
+ (id)formatMediumDateTime:(id)inputParameters
input |
The function’s input parameter. |
|---|
Return Value
The date/time-formatted string.
Discussion
This Mockingbird function accepts a single input parameter, an object
expression yielding either an NSDate or a date-formatted NSString
containing the date to format.
Expression usage
The following expression:
^formatMediumDateTime(^parseDate(Sun, 26 Oct 1986 00:02:00 EDT))
would result in the string “Oct 26, 1986, 12:02:00 AM”.
Note: The string returned depends on the device’s locale settings and may not match the example above.
Declared In
MBMLDateFunctions.h
+ formatLongDateTime:
Accepts a date and returns a date string formatted using the
NSDateFormatterLongStyle format.
+ (id)formatLongDateTime:(id)inputParameters
input |
The function’s input parameter. |
|---|
Return Value
The date/time-formatted string.
Discussion
This Mockingbird function accepts a single input parameter, an object
expression yielding either an NSDate or a date-formatted NSString
containing the date to format.
Expression usage
The following expression:
^formatLongDateTime(^parseDate(Sun, 26 Oct 1986 00:02:00 EDT))
would result in the string “October 26, 1986 at 12:02:00 AM EDT”.
Note: The string returned depends on the device’s locale settings and may not match the example above.
Declared In
MBMLDateFunctions.h
+ formatFullDateTime:
Accepts a date and returns a date string formatted using the
NSDateFormatterLongStyle format.
+ (id)formatFullDateTime:(id)inputParameters
input |
The function’s input parameter. |
|---|
Return Value
The date/time-formatted string.
Discussion
This Mockingbird function accepts a single input parameter, an object
expression yielding either an NSDate or a date-formatted NSString
containing the date to format.
Expression usage
The following expression:
^formatFullDateTime(^parseDate(Sun, 26 Oct 1986 00:02:00 EDT))
would result in the string “Sunday, October 26, 1986 at 12:02:00 AM Eastern
Daylight Time”.
Note: The string returned depends on the device’s locale settings and may not match the example above.
Declared In
MBMLDateFunctions.h
Converting from one string format to another
+ reformatDate:
Accepts a date-formatted string and converts it into a date string of another format.
+ (id)reformatDate:(NSArray *)paramsParameters
params |
The function’s input parameters. |
|---|
Return Value
A date-formatted string.
Discussion
This Mockingbird function accepts two or three pipe-separated expressions as input parameters:
the input date, a date-formatted string to be parsed
an optional input format, specifying the date format used by the input date parameter (if this parameter is omitted, the default format used is the one specified by the
defaultDateParsingFormatmethod)an output format, specifying the date format to be used for creating the returned date string
Expression usage
The following expression:
^reformatDate(26 Oct 1986|dd MMM yyyy|MM/dd/yy)
would result in the string “10/26/86”.
See Also
Declared In
MBMLDateFunctions.h
+ reformatDateWithLocale:
Accepts a date-formatted input string—along with a locale specification for that input string—and converts the input into a date string of another format.
+ (id)reformatDateWithLocale:(NSArray *)paramsParameters
params |
The function’s input parameters. |
|---|
Return Value
A date-formatted string.
Discussion
This Mockingbird function accepts three or four pipe-separated expressions as input parameters:
the input date, a date-formatted string to be parsed
the input date locale, a string specifying the locale identifier of the input date’s locale
an optional input format, specifying the date format used by the input date parameter (if this parameter is omitted, the default format used is the one specified by the
defaultDateParsingFormatmethod)an output format, specifying the date format to be used for creating the returned date string
Expression usage
The following expression:
^reformatDateWithLocale(26 Oct 1986|en_US|dd MMM yyyy|MM/dd/yy)
would result in the string “10/26/86”.
See Also
Declared In
MBMLDateFunctions.h
Parsing date strings
+ mbmlParseDate:
Attempts to construct an NSDate instance by parsing a string.
+ (id)mbmlParseDate:(NSArray *)paramsParameters
params |
The function’s input parameters. |
|---|
Return Value
An NSDate representing the parsed date.
Discussion
This Mockingbird function accepts two or three pipe-separated expressions as input parameters:
the date, a string to be parsed
an optional format string, a string in the format that would be used by a
NSDateFormatter. If this parameter is omitted, the value returned by the methoddefaultDateParsingFormatis used as the format string.
Expression usage
Note: This function is exposed to the Mockingbird environment with a name that differs from that of its implementing method.
Assuming the default date parsing format hasn’t been overridden by the
$MBMLDateFunctions:dateParsingFormat variable, this expression:
^parseDate(Thu, 26 Jan 2012 15:58:19 UTC)
would return an NSDate instance representing a date equivalent to
Thursday, January 26th, 2012 at 10:58:19AM in New York City (eastern standard
time, or the America/New_York timezone).
Declared In
MBMLDateFunctions.h
Time zone information
+ timeZoneOffset
Returns the offset, in minutes, between the current time zone and UTC.
+ (NSNumber *)timeZoneOffsetReturn Value
The time zone offset.
Discussion
This Mockingbird function accepts no input.
Expression usage
The expression:
^timeZoneOffset()
would return an NSNumber instance containing the time zone offset, in
minutes.
Declared In
MBMLDateFunctions.h