RingoJS

Module ringo/utils/dates

Adds useful functions for working with JavaScript Date objects.

Example

const dates = require("ringo/utils/dates");
const now = new Date(2016, 0, 1);
const y2k = new Date(2000, 0, 1);

dates.after(now, y2k); // --> true
dates.before(now, y2k); // --> false
dates.isLeapYear(y2k); // --> true
dates.weekOfYear(y2k); // --> 52 (1st week starts at 3rd)
dates.yearInCentury(y2k); // --> 0
dates.diff(y2k, now); // --> 5844
dates.diff(y2k, now, "mixed"); // { days: 5844, hours: 0, ... }

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.

Example

const d1 = new Date(Date.UTC(2016, 0, 1, 0, 0));
const d2 = dates.add(d1, 1, "hour");
dates.diff(d1, d2, "hours"); // --> 1

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, and their respective plural form.

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 no 29th February
dates.checkDate(2007, 1, 29); // --> 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.

Example

const d1 = new Date(Date.UTC(2016, 0, 1, 0, 0));
const d2 = new Date(Date.UTC(2017, 0, 1));
dates.diff(d1, d2, "years"); // --> 1
dates.diff(d1, d2, "year"); // --> 1
dates.diff(d1, d2, "minutes"); // --> 527040
dates.diff(d1, d2, "mixed"); // --> { days: 366, hours: 0, … }

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); and their respective plural form.

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

java.util.Locale locale

(optional) the locale as java Locale

Returns

Number

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

format (date, format, locale, timezone)

Format a Date to a string in a locale-sensitive manner. For details on the format pattern, see java.text.SimpleDateFormat .

Example

const y2k = new Date(Date.UTC(2000, 0, 1));
// "year 2000"
dates.format(y2k, "'year' yyyy");
// "Samstag, Januar 1, '00"
dates.format(y2k, "EEEE, MMMM d, ''yy", "de");
// "1999-12-31"
dates.format(y2k, "yyyy-MM-dd", "de", "GMT-1");
// "2000-01-01 00:00:00 GMT-00:00"
dates.format(y2k, "yyyy-MM-dd HH:mm:ss z", "de", "GMT-0");
// "1999-12-31 14:00:00 GMT-10:00"
dates.format(y2k, "yyyy-MM-dd HH:mm:ss z", "de", "GMT-10");

Parameters

Date 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, millisecond)

Create new Date from UTC timestamp. This is an alternative to new Date(Date.UTC(…));

Parameters

Number year
Number month
Number date
Number hour

(optional, default 0)
Number minute

(optional, default 0)
Number second

(optional, default 0)
Number millisecond

(optional, default 0)

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, format, locale, timezone, lenient)

Parse a string to a date using date and time patterns from Java's SimpleDateFormat. If no format is provided, the default follows RFC 3339 for timestamps on the internet. The parser matches the pattern against the string with lenient parsing: Even if the input is not strictly in the form of the pattern, but can be parsed with heuristics, then the parse succeeds.

Example

// parses input string as local time:
// Wed Jun 29 2016 12:11:10 GMT+0200 (MESZ)
let pattern = "yyyy-MM-dd'T'HH:mm:ss.SSS";
dates.parse("2016-06-29T12:11:10.001", pattern);

// enforces UTC on the input date string
// Wed Jun 29 2016 14:11:10 GMT+0200 (MESZ)
dates.parse("2016-06-29T12:11:10.001", pattern, "en", "UTC");

// accepting month names in German
dates.parse("29. Juni 2016", "dd. MMM yyyy", "de", "UTC");

// Fri Jan 01 2016 01:00:00 GMT+0100 (MEZ)
dates.parse("2016");

// Sat Aug 06 2016 02:00:00 GMT+0200 (MESZ)
dates.parse("2016-08-06");

// Sun Aug 07 2016 00:04:30 GMT+0200 (MESZ)
dates.parse("2016-08-06T22:04:30Z");

// Sun Aug 07 2016 00:04:30 GMT+0200 (MESZ)
dates.parse("2016-08-06T16:04:30-06");

Parameters

String str

The date string.
String format

(optional) a specific format pattern for the parser
String|java.util.Locale locale

(optional) the locale as java.util.Locale object or an ISO-639 alpha-2 code (e.g. "en", "de") as string
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.
Boolean lenient

(optional) disables lenient parsing if set to false.

Returns

Date|NaN

a date representing the given string, or NaN for unrecognizable strings

quarterInFiscalYear (date, fiscalYearStart)

Gets the quarter in the fiscal year.

Example

// Farmers (grassland calendar starts with 1st May)
// returns 4th quarter
dates.quarterInFiscalYear(new Date(2016, 3, 30), new Date(0, 4, 1));

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.

Example

const d = new Date(2016, 5, 10, 10, 20, 30);

// Thu Jan 01 1970 10:20:30 GMT+0100 (MEZ)
dates.resetDate(d);

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.

Example

const d = new Date(2016, 5, 10, 10, 20, 30);

// Fri Jun 10 2016 00:00:00 GMT+0200 (MESZ)
dates.resetTime(d);

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)

Creates an ISO 8601 compatible string from the date. This is similar to Date.toISOString(), which only returns an UTC-based string. If you don't need a timezone, Date.toISOString() will be the better choice. Use this function only if you need to include the timezone offset in your string, or if you need to control the granularity of the output fields.

Example

// "2018-08-08T17:16:44.926+02:00"
dates.toISOString(new Date(), true, true);

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 false.
Boolean withSeconds

if true, the string will contain also the seconds of the date. Default is true.
Boolean withMilliseconds

if true, the string will contain the millisecond part of the date. Default is true.

Returns

String

date as ISO 8601 string.

toInstant (date)

Converts the given date to a java.time.Instant instance. Helps to interact with the java.time API for dates, times, and durations.

Parameters

null date

{Date} the JavaScript Date object to convert

Returns

java.time.Instant

instant instance at the given point in time

See

java.time

toOffsetDateTime (date)

Converts the given date to a java.time.OffsetDateTime instance using the date's offset. Helps to interact with the java.time API for dates, times, and durations.

Parameters

null date

{Date} the JavaScript Date object to convert

Returns

java.time.OffsetDateTime

time instance with offset representing the given date

See

java.time

weekOfMonth (date, locale)

Gets the week of the month for the given date.

Parameters

Date date

calculate the week of the month.
java.util.Locale locale

(optional) the locale as java Locale

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.
java.util.Locale locale

(optional) the locale as java Locale

Returns

Number

week of the year

yearInCentury (date)

Gets the year of the century for the given date.

Example

dates.yearInCentury(new Date(1900, 0, 1)); // --> 0
dates.yearInCentury(new Date(2016, 0, 1)); // --> 16

Parameters

Date date

calculate the year of the century.

Returns

Number

second of the day

main

• Overview • Module Index