Module ringo/utils/dates

Adds useful functions for working with JavaScript Date objects.

Functions

add (date, delta, unit)

Adds delta to the given field or reduces it, if delta is negative. If larger fields are effected, they will be changed accordingly.

Parameters

Date date base date to add or remove time from.
Number delta amount of time to add (positive delta) or remove (negative delta).
String unit (optional) field to change. Possible values: year, quarter, month, week, day (default), hour (24-hour clock), minute, second, millisecond.

Returns

Date date with the calculated date and time

after (a, b)

Checks if date a is after date b. This is equals to compare(a, b) > 0

Parameters

Date a first date
Date b second date

Returns

Boolean true if a is after b, false if not.

before (a, b)

Checks if date a is before date b. This is equals to compareTo(a, b) < 0

Parameters

Date a first date
Date b second date

Returns

Boolean true if a is before b, false if not.

checkDate (fullYear, month, day)

Checks if the date is a valid date. Example: 2007 is no leap year, so checkDate(2007, 1, 29) returns false.

Parameters

Number fullYear
Number month between 0 and 11
Number day between 1 and 31

Returns

Boolean true, if the date is valid, false if not.

compare (a, b)

Compares the time values of a and b.

Parameters

Date a first date
Date b second date

Returns

Number -1 if a is before b, 0 if equals and 1 if a is after b.

dayOfYear (date)

Gets the day of the year for the given date.

Parameters

Date date calculate the day of the year.

Returns

Number day of the year

daysInFebruary (date)

Gets the number of the days in february.

Parameters

Date date of year to find the number of days in february.

Returns

Number days in the february, 28 or 29, if it's a leap year.

daysInMonth (date)

Gets the number of the days in the month.

Parameters

Date date to find the maximum number of days.

Returns

Number days in the month, between 28 and 31.

daysInYear (date)

Gets the number of the days in the year.

Parameters

Date date to find the maximum number of days.

Returns

Number days in the year, 365 or 366, if it's a leap year.

diff (a, b, unit)

Get the difference between two dates, specified by the unit of time.

Parameters

Date a first date
Date b second date
String unit (optional) of time to return. Possible values: year, quarter, month, week, day (default), hour, minute, second, millisecond and mixed (returns an object)

Returns

Number|Object<{days, hours, minutes, seconds, milliseconds}> difference between the given dates in the specified unit of time.

firstDayOfWeek (locale)

Gets the first day of the week.

Parameters

String|java.util.Locale locale (optional) the locale as java Locale object or lowercase two-letter ISO-639 code (e.g. "en")

Returns

Number the first day of the week; 1 = Sunday, 2 = Monday.

format (the, format, locale, timezone)

Format a Date to a string. For details on the format pattern, see http://java.sun.com/j2se/1.4.2/docs/api/java/text/SimpleDateFormat.html

Parameters

Date the Date to format
String format the format pattern
String|java.util.Locale locale (optional) the locale as java Locale object or lowercase two-letter ISO-639 code (e.g. "en")
String|java.util.TimeZone timezone (optional) the timezone as java TimeZone object or an abbreviation such as "PST", a full name such as "America/Los_Angeles", or a custom ID such as "GMT-8:00". If the id is not provided, the default timezone is used. If the timezone id is provided but cannot be understood, the "GMT" timezone is used.

Returns

String the formatted Date

fromUTCDate (year, month, date, hour, minute, second)

Create new Date from UTC timestamp.

Parameters

Number year
Number month
Number date
Number hour
Number minute
Number second

Returns

Date

inPeriod (date, periodStart, periodEnd, periodStartOpen, periodEndOpen)

Look if the date is in the period, using periodStart <= date <= periodEnd.

Parameters

Date date to check, if it's in the period
Date periodStart the period's start
Date periodEnd the period's end
Boolean periodStartOpen start point is open - default false.
Boolean periodEndOpen end point is open - default false.

Returns

Boolean true if the date is in the period, false if not.

isLeapYear (date)

Checks if the date's year is a leap year.

Parameters

Date date to check year

Returns

Boolean true if the year is a leap year, false if not.

overlapping (aStart, aEnd, bStart, bEnd)

Look if two periods are overlapping each other.

Parameters

Date aStart first period's start
Date aEnd first period's end
Date bStart second period's start
Date bEnd second period's end

Returns

Boolean true if the periods are overlapping at some point, false if not.

parse (str)

Parse a string representing a date. For details on the string format, see http://tools.ietf.org/html/rfc3339. Examples include "2010", "2010-08-06", "2010-08-06T22:04:30Z", "2010-08-06T16:04:30-06".

Parameters

String str The date string. This follows the format specified for timestamps on the internet described in RFC 3339.

Returns

Date a date representing the given string

quarterInFiscalYear (date, fiscalYearStart)

Gets the quarter in the fiscal year.

Parameters

Date date to calculate the quarter for.
Date fiscalYearStart first day in the fiscal year, default is the start of the current year

Returns

Number quarter of the year, between 1 and 4.

quarterInYear (date)

Gets the quarter in the year.

Parameters

Date date to calculate the quarter for.

Returns

Number quarter of the year, between 1 and 4.

resetDate (date)

Drops the date values, keeping only hours, minutes, seconds and milliseconds.

Parameters

Date date to reset

Returns

Date date with the original time values and 1970-01-01 as date.

resetTime (date)

Resets the time values to 0, keeping only year, month and day.

Parameters

Date date to reset

Returns

Date date without any time values

secondOfDay (date)

Gets the second of the day for the given date.

Parameters

Date date calculate the second of the day.

Returns

Number second of the day

toISOString (date, withTime, withTimeZone, withSeconds, withMilliseconds)

Create a ISO 8601 compatible string from the date. Note: This is quite similar to Date.toISOString(), which only returns an UTC-based string without the local timezone. If you don't need timezones, Date.toISOString() will be the better choice.

Parameters

Date date to format
Boolean withTime if true, the string will contain the time, if false only the date. Default is true.
Boolean withTimeZone if true, the string will be in local time, if false it's in UTC. Default is true.
Boolean withSeconds if true, the string will contain also the seconds of the date. Default true.
Boolean withMilliseconds if true, the string will contain also the milliseconds of the date. Default false.

Returns

String date as ISO 8601 string.

weekOfMonth (date, locale)

Gets the week of the month for the given date.

Parameters

Date date calculate the week of the month.
String|java.util.Locale locale (optional) the locale as java Locale object or lowercase two-letter ISO-639 code (e.g. "en")

Returns

Number week of the month

weekOfYear (date, locale)

Gets the week of the year for the given date.

Parameters

Date date calculate the week of the year.
String|java.util.Locale locale (optional) the locale as java Locale object or lowercase two-letter ISO-639 code (e.g. "en")

Returns

Number week of the year

yearInCentury (date)

Gets the year of the century for the given date. Examples: 1900 returns 0, 2010 returns 10.

Parameters

Date date calculate the year of the century.

Returns

Number second of the day