RingoJS

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

RingoJS 0.9

• Overview • Module Index