JSDoc: Namespace: date

The apex.date namespace contains Oracle APEX functions related to date operations.

Since:

21.2

Properties

(static) UNIT :object

Constants for the different date/time units used by apex.date functions.

Type:

object

Properties:

Name	Type	Description
`MILLISECOND`	string	Constant to use for milliseconds
`SECOND`	string	Constant to use for seconds
`MINUTE`	string	Constant to use for minutes
`HOUR`	string	Constant to use for hours
`DAY`	string	Constant to use for days
`WEEK`	string	Constant to use for weeks
`MONTH`	string	Constant to use for months
`YEAR`	string	Constant to use for years

Examples

apex.date.UNIT constant

apex.date.UNIT = {
    MILLISECOND: "millisecond",
    SECOND: "second",
    MINUTE: "minute",
    HOUR: "hour",
    DAY: "day",
    WEEK: "week",
    MONTH: "month",
    YEAR: "year"
};

Example usage

apex.date.add( myDate, 2, apex.date.UNIT.DAY );
apex.date.add( myDate, 1, apex.date.UNIT.YEAR );
apex.date.subtract( myDate, 30, apex.date.UNIT.MINUTE );
apex.date.subtract( myDate, 6, apex.date.UNIT.HOUR );

Functions

(static) add(pDateopt, pAmount, pUnitopt) → {Date}

Add a certain amount of time to an existing date. This function returns the modified date object as well as altering the original object. If the given date object should not be manipulated use apex.date.clone before calling this function. If pDate is not provided it uses the current date & time.

Parameters:

Name	Type	Attributes	Default	Description
`pDate`	Date	<optional>	new Date()	A date object
`pAmount`	number			The amount to add
`pUnit`	string	<optional>	apex.date.UNIT.MILLISECOND	The unit to use - apex.date.UNIT constant

Returns:

The modified date object

Type: Date

Example

Returns the modified date object.

var myDate = new Date( "2021-06-20" );
myDate = apex.date.add( myDate, 2, apex.date.UNIT.DAY );
// myDate is now "2021-06-21"

(static) clone(pDate) → {Date}

Return the cloned instance of a given date object. This is useful when you want to do actions on a date object without altering the original object. If pDate is not provided it uses the current date & time.

Parameters:

Name	Type	Description
`pDate`	Date	A date object

Returns:

The cloned date object

Type: Date

Example

Returns the clone of a given date object.

var myDate = new Date();
var clonedDate = apex.date.clone( myDate );

(static) dayOfWeek(pDateopt) → {number}

Return the day number of week of a given date object. If pDate is not provided it uses the current date & time.

Parameters:

Name	Type	Attributes	Default	Description
`pDate`	Date	<optional>	new Date()	A date object

Returns:

The day number

Type: number

Example

Returns the day number of given week.

var weekDay = apex.date.dayOfWeek( myDate );

(static) daysInMonth(pDateopt) → {number}

Return the day count of a month of a given date object. If pDate is not provided it uses the current date & time.

Parameters:

Name	Type	Attributes	Default	Description
`pDate`	Date	<optional>	new Date()	A date object

Returns:

The days count

Type: number

Example

Returns the day count of given month.

var dayCount = apex.date.daysInMonth( myDate );

(static) endOfDay(pDateopt) → {Date}

Return the end date of a day of a given date object. If pDate is not provided it uses the current date & time.

Parameters:

Name	Type	Attributes	Default	Description
`pDate`	Date	<optional>	new Date()	A date object

Returns:

The end date of a day

Type: Date

Example

Returns the end date of a given day.

var dayEndDate = apex.date.endOfDay( myDate );
// output: "2021-JUN-29 23:59:59" (as date object)

(static) firstOfMonth(pDateopt) → {Date}

Return a new date object for the first day a month of a given date object. If pDate is not provided it uses the current date & time.

Parameters:

Name	Type	Attributes	Default	Description
`pDate`	Date	<optional>	new Date()	A date object

Returns:

The first day as date

Type: Date

Example

Returns the first day of a given month as date object.

var firstDayDate = apex.date.firstOfMonth( myDate );
// output: "2021-JUN-01" (as date object)

(static) format(pDateopt, pFormatopt, pLocaleopt) → {string}

Return the formatted string of a date with a given (Oracle compatible) format mask. If pDate is not provided it uses the current date & time. It uses the default date format mask & locale defined in the application globalization settings.

Currently not supported Oracle specific formats are: SYEAR,SYYYY,IYYY,YEAR,IYY,SCC,TZD,TZH,TZM,TZR,AD,BC,CC,EE,FF,FX,IY,RM,TS,E,I,J,Q,X

Parameters:

Name	Type	Attributes	Default	Description
`pDate`	Date	<optional>	new Date()	A date object
`pFormat`	string	<optional>	apex.locale.getDateFormat()	The format mask
`pLocale`	string	<optional>	apex.locale.getLanguage()	The locale

Returns:

The formatted date string

Type: string

Example

Returns the formatted date string.

var dateString = apex.date.format( myDate, "YYYY-MM-DD HH24:MI" );
// output: "2021-06-29 15:30"

var dateString = apex.date.format( myDate, "Day, DD Month YYYY" );
// output: "Wednesday, 29 June 2021"

var dateString = apex.date.format( myDate, "Day, DD Month YYYY", "de" );
// output: "Mittwoch, 29 Juni 2021"

(static) getDayOfYear(pDateopt) → {number}

Return the day number of a year of a given date object. If pDate is not provided it uses the current date & time.

Parameters:

Name	Type	Attributes	Default	Description
`pDate`	Date	<optional>	new Date()	A date object

Returns:

The day number

Type: number

Example

Returns the day number of given year.

var dayNumber = apex.date.getDayOfYear( myDate );

(static) isAfter(pDate1, pDate2, pUnitopt) → {boolean}

Return true if the first date object is after the second date. pUnit controls the precision of the comparison.

Parameters:

Name	Type	Attributes	Default	Description
`pDate1`	Date			A date object
`pDate2`	Date			A date object
`pUnit`	string	<optional>	apex.date.UNIT.MILLISECOND	The unit to use - apex.date.UNIT constant

Returns:

is the date after

Type: boolean

Example

Returns if a date object is before another.

var isDateAfter = apex.date.isAfter( myDate1, myDate2, apex.date.UNIT.SECOND );

(static) isBefore(pDate1, pDate2, pUnitopt) → {boolean}

Return true if the first date object is before the second date. pUnit controls the precision of the comparison.

Parameters:

Name	Type	Attributes	Default	Description
`pDate1`	Date			A date object
`pDate2`	Date			A date object
`pUnit`	string	<optional>	apex.date.UNIT.MILLISECOND	The unit to use - apex.date.UNIT constant

Returns:

is the date before

Type: boolean

Example

Returns if a date object is before another.

var isDateBefore = apex.date.isBefore( myDate1, myDate2, apex.date.UNIT.SECOND );

(static) isBetween(pDate1, pDate2, pDate3, pUnitopt) → {boolean}

Return true if the first date object is between the second date and the third date. pUnit controls the precision of the comparison.

Parameters:

Name	Type	Attributes	Default	Description
`pDate1`	Date			A date object
`pDate2`	Date			A date object
`pDate3`	Date			A date object
`pUnit`	string	<optional>	apex.date.UNIT.MILLISECOND	The unit to use - apex.date.UNIT constant

Returns:

is the date between

Type: boolean

Example

Returns if a date object is between 2 another.

var isDateBetween = apex.date.isBetween( myDate1, myDate2, myDate3, apex.date.UNIT.SECOND );

(static) isLeapYear(pDateopt) → {boolean}

Return true if a given date object is within a leap year. If pDate is not provided it uses the current date & time.

Parameters:

Name	Type	Attributes	Default	Description
`pDate`	Date	<optional>	new Date()	A date object

Returns:

is a leap year

Type: boolean

Example

Returns if it's a leap year for a given date.

var isLeapYear = apex.date.isLeapYear( myDate );

(static) ISOWeek(pDateopt) → {number}

Return the ISO-8601 week number of the year of a given date object. If pDate is not provided it uses the current date & time.

Parameters:

Name	Type	Attributes	Default	Description
`pDate`	Date	<optional>	new Date()	A date object

Returns:

The week number

Type: number

Example

Returns the ISO-8601 week number.

var weekNumber = apex.date.ISOWeek( myDate );

(static) isSame(pDate1, pDate2, pUnitopt) → {boolean}

Return true if the first date object is the same as the second date. pUnit controls the precision of the comparison.

Parameters:

Name	Type	Attributes	Default	Description
`pDate1`	Date			A date object
`pDate2`	Date			A date object
`pUnit`	string	<optional>	apex.date.UNIT.MILLISECOND	The unit to use - apex.date.UNIT constant

Returns:

is the date same

Type: boolean

Example

Returns if a date object is the same as another.

var isDateSame = apex.date.isSame( myDate1, myDate2, apex.date.UNIT.SECOND );

(static) isSameOrAfter(pDate1, pDate2, pUnitopt) → {boolean}

Return true if the first date object is the same or after the second date. pUnit controls the precision of the comparison.

Parameters:

Name	Type	Attributes	Default	Description
`pDate1`	Date			A date object
`pDate2`	Date			A date object
`pUnit`	string	<optional>	apex.date.UNIT.MILLISECOND	The unit to use - apex.date.UNIT constant

Returns:

is the date same/after

Type: boolean

Example

Returns if a date object is the same or after another.

var isDateSameAfter = apex.date.isSameOrAfter( myDate1, myDate2, apex.date.UNIT.SECOND );

(static) isSameOrBefore(pDate1, pDate2, pUnitopt) → {boolean}

Return true if the first date object is the same or before the second date. pUnit controls the precision of the comparison.

Parameters:

Name	Type	Attributes	Default	Description
`pDate1`	Date			A date object
`pDate2`	Date			A date object
`pUnit`	string	<optional>	apex.date.UNIT.MILLISECOND	The unit to use - apex.date.UNIT constant

Returns:

is the date same/before

Type: boolean

Example

Returns if a date object is the same or before another.

var isDateSameBefore = apex.date.isSameOrBefore( myDate1, myDate2, apex.date.UNIT.SECOND );

(static) isValid(pDate) → {boolean}

Return true if a given object is a valid date object.

Parameters:

Name	Type	Description
`pDate`	Date	A date object

Returns:

is it a valid date

Type: boolean

Example

Returns if a date object is valid.

var isDateValid = apex.date.isValid( myDate );

(static) isValidString(pDateString) → {boolean}

Return true if a given string can parse into a date object. Note: This could be browser specific dependent on the implementation of Date.parse.

Most browsers expect a string in ISO format (ISO 8601) and shorter versions of it, like "2021-06-15T14:30:00" or "2021-06-15T14:30" or "2021-06-15"

Parameters:

Name	Type	Description
`pDateString`	string	A date string

Returns:

is it a valid date

Type: boolean

Example

Returns if a date string is valid.

var isDateValid = apex.date.isValidString( "2021-06-29 15:30" );

(static) lastOfMonth(pDateopt) → {Date}

Return a new date object for the last day of a month of a given date object. If pDate is not provided it uses the current date & time.

Parameters:

Name	Type	Attributes	Default	Description
`pDate`	Date	<optional>	new Date()	A date object

Returns:

The last day as date

Type: Date

Example

Returns the last day of a given month as date.

var lastDayDate = apex.date.lastOfMonth( myDate );
// output: "2021-JUN-30" (as date object)

(static) max(…pDatesopt) → {Date}

Return the maximum date of given date object arguments. If pDates is not provided it uses the current date & time.

Parameters:

Name	Type	Attributes	Default	Description
`pDates`	date	<optional> <repeatable>	[new Date()]	Multiple date objects as arguments

Returns:

The max date object

Type: Date

Example

Returns the maximum (most distant future) of the given date.

var maxDate = apex.date.max( myDate1, myDate2, myDate3 );

(static) min(…pDatesopt) → {Date}

Return the minimum date of given date object arguments. If pDates is not provided it uses the current date & time.

Parameters:

Name	Type	Attributes	Default	Description
`pDates`	date	<optional> <repeatable>	[new Date()]	Multiple date objects as arguments

Returns:

The min date object

Type: Date

Example

Returns the minimum (most distant future) of the given date.

var minDate = apex.date.min( myDate1, myDate2, myDate3 );

(static) monthsBetween(pDate1, pDate2) → {number}

Return the count of months between 2 date objects.

Parameters:

Name	Type	Description
`pDate1`	Date	A date object
`pDate2`	Date	A date object

Returns:

The month count

Type: number

Example

Returns the count of months between 2 dates.

var months = apex.date.monthsBetween( myDate1, myDate2 );

(static) parse(pDateString, pFormatopt) → {Date}

Return the parsed date object of a given date string and a (Oracle compatible) format mask. It uses the default date format mask defined in the application globalization settings.

Currently not supported Oracle specific formats are: SSSSS,SYEAR,SYYYY,IYYY,YEAR,IYY,SCC,TZD,TZH,TZM,TZR,AD,BC,CC,EE,FF,FX,IW,IY,RM,TS,WW,E,I,J,Q,W,X

Parameters:

Name	Type	Attributes	Default	Description
`pDateString`	string			A formatted date string
`pFormat`	string	<optional>	apex.locale.getDateFormat()	The format mask

Returns:

The date object

Type: Date

Example

Returns the parsed date object.

var date = apex.date.parse( "2021-06-29 15:30", "YYYY-MM-DD HH24:MI" );
var date = apex.date.parse( "2021-JUN-29 08:30 am", "YYYY-MON-DD HH12:MI AM" );

(static) secondsPastMidnight(pDateopt) → {number}

Return the seconds past midnight of day of a given date object.

Parameters:

Name	Type	Attributes	Default	Description
`pDate`	Date	<optional>	new Date()	A date object

Returns:

seconds past midnight

Type: number

Example

Returns the seconds past midnight.

var seconds = apex.date.secondsPastMidnight( myDate );

(static) setDayOfYear(pDateopt, pDay) → {Date}

Set the day number of a year of a given date object. If the given date object should not be manipulated use apex.date.clone before calling this function. If pDate is not provided it uses the current date & time.

Parameters:

Name	Type	Attributes	Default	Description
`pDate`	Date	<optional>	new Date()	A date object
`pDay`	number			The day number

Returns:

The date object

Type: Date

Example

Returns the date object.

var myDate = new Date();
apex.date.setDayOfYear( myDate, 126 );

(static) since(pDateopt, pShortopt) → {string}

Return the relative date in words of a given date object This is the client side counterpart of the PL/SQL function APEX_UTIL.GET_SINCE. If pDate is not provided it uses the current date & time.

Parameters:

Name	Type	Attributes	Default	Description
`pDate`	string	<optional>	new Date()	A date object
`pShort`	boolean	<optional>	false	Whether to return a short version of relative date

Returns:

The formatted date string

Type: string

Example

Returns the relative date in words.

var sinceString = apex.date.since( myDate );
// output: "2 days from now" or "30 minutes ago"

var sinceString = apex.date.since( myDate, true );
// output: "In 1.1y" or "30m"

(static) startOfDay(pDateopt) → {Date}

Return the start date of a day of a given date object. If pDate is not provided it uses the current date & time.

Parameters:

Name	Type	Attributes	Default	Description
`pDate`	Date	<optional>	new Date()	A date object

Returns:

The start date of a day

Type: Date

Example

Returns the start date of a given day.

var dayStartDate = apex.date.startOfDay( myDate );
// output: "2021-JUN-29 24:00:00" (as date object)

(static) subtract(pDateopt, pAmount, pUnitopt) → {Date}

Subtract a certain amount of time of an existing date. This function returns the modified date object as well as altering the original object. If the given date object should not be manipulated use apex.date.clone before calling this function. If pDate is not provided it uses the current date & time.

Parameters:

Name	Type	Attributes	Default	Description
`pDate`	Date	<optional>	new Date()	A date object
`pAmount`	number			The amount to subtract
`pUnit`	string	<optional>	apex.date.UNIT.MILLISECOND	The unit to use - apex.date.UNIT constant

Returns:

The modified date object

Type: Date

Example

Returns the modified date object.

var myDate = new Date( "2021-06-20" )
myDate = apex.date.subtract( myDate, 2, apex.date.UNIT.DAY );
// myDate is now "2021-06-19"

(static) toISOString(pDateopt) → {string}

Return the ISO format string (ISO 8601) without timezone information of a given date object. If pDate is not provided it uses the current date & time.

Parameters:

Name	Type	Attributes	Default	Description
`pDate`	Date	<optional>	new Date()	A date object

Returns:

The formatted date string

Type: string

Example

Returns date as ISO format string.

var isoFormat = apex.date.toISOString( myDate );
// output: "2021-06-15T14:30:00"

(static) weekOfMonth(pDateopt) → {number}

Return the week number of a month of a given date object. If pDate is not provided it uses the current date & time.

Parameters:

Name	Type	Attributes	Default	Description
`pDate`	Date	<optional>	new Date()	A date object

Returns:

The week number

Type: number

Example

Returns the week number of given month.

var weekNumber = apex.date.weekOfMonth( myDate );