The Uize.Date module is a package under the Uize namespace, providing a suite of utility methods for working with dates.

1.1.1. ISO 8601

var myDate = new Date ('2009-09-27');  // produces an invalid date object

var myDate = Uize.Date.resolve ('2009-09-27');

Uize.Date.getRangeAround ('2009-01-10','month');

There are no dedicated showcase example pages for the Uize.Date module.

SEARCH FOR EXAMPLES

Use the link below to search for example pages on the UIZE Web site that reference the Uize.Date module...

SEARCH

The Uize.Date module defines the Uize.Date object under the Uize namespace.

1.3.1. Features Introduced in This Module

1.3.2. Features Overridden in This Module

1.3.3. Features Inherited From Other Modules

1.3.4. Modules Directly Under This Namespace

1.3.5. Unit Tests

Converts the specified time in the specified time unit to a different specified time unit.

SYNTAX

convertedTimeFLOAT = Uize.Date.convert (timeFLOAT,timeUnitSTR,convertedTimeUnitSTR);

This method allows us to convert from days to milliseconds, seconds to years, years to hours, hours to weeks, months to hours, or from any one of the supported time units to another.

TIME UNITS

The value specified for the timeUnitSTR and convertedTimeUnitSTR parameters can be any one of: ms, seconds, minutes, hours, days, weeks, months, years.

EXAMPLES

var
  timeInDays = Uize.Date.convert (18287659,'ms','days'),
  timeInHours = Uize.Date.convert (15306,'seconds','hours'),
  timeInWeeks = Uize.Date.convert (6,'months','weeks')
;

NOTES

IMPLEMENTATION INFO

Returns a boolean, indicating whether or not the two specified dates can be considered equal, according to the specified level of precision / accuracy.

SYNTAX

datesEqualBOOL = Uize.Date.equal (date1STRorOBJ,date2STRorOBJ,precisionSTR);

You can use this method to easily test if two dates exist together within the same logical date range. For example, you can test to see if two dates are in the same week, the same month, the same quarter of the year, the same decade, etc. Consider the following example...

EXAMPLE

Uize.Date.equal ('2009/09/10 18:19:25','2009/08/01 01:51:47','hour');        // false
Uize.Date.equal ('2009/09/10 18:19:25','2009/08/01 01:51:47','day');         // false
Uize.Date.equal ('2009/09/10 18:19:25','2009/08/01 01:51:47','week');        // false
Uize.Date.equal ('2009/09/10 18:19:25','2009/08/01 01:51:47','month');       // false
Uize.Date.equal ('2009/09/10 18:19:25','2009/08/01 01:51:47','quarter');     // true
Uize.Date.equal ('2009/09/10 18:19:25','2009/08/01 01:51:47','year');        // true
Uize.Date.equal ('2009/09/10 18:19:25','2009/08/01 01:51:47','decade');      // true
Uize.Date.equal ('2009/09/10 18:19:25','2009/08/01 01:51:47','century');     // true

Values specified for the date1STRorOBJ and date2STRorOBJ parameters are of the dateSTRorNUMorOBJ value type. The values that can be specified for the precisionSTR parameter are all the values that can be specified for the rangeSizeSTR parameter of the Uize.Date.getRangeAround method (e.g. 'minute', 'hour', 'am/pm', 'week', 'quarter', 'decade', etc.).

MIND THE GAP

Don't be suckered into thinking that two dates like those shown in the example below should be considered equal when compared with precision down to the second.

Uize.Date.equal ('2009/09/10 18:19:25','2008/09/10 18:19:25','second');  // false

Yes, the hours, minutes, and seconds of the two dates are identical, but they're a full year apart. So, they can't be considered equal down to a second in accuracy. In fact, they can't even be considered equal down to a year in accuracy.

VARIATION 1

datesEqualBOOL = Uize.Date.equal (date1STRorOBJ,date2STRorOBJ);

When no precisionSTR parameter is specified, the value 'day' will be used as the default for this parameter. This default provides a convenient way of just testing if two dates are for the same day of the same month of the same year, without regard to hours, minutes, seconds, or milliseconds. This is a typical way to compare two dates, such as testing if a particular date is someone's birthday, or a national holiday, etc.

EXAMPLE

Uize.Date.equal ('2009/09/10 18:19:25','2009/09/10 12:30:10');  // produces true
Uize.Date.equal ('2009/09/10 18:19:25','2009/09/09 18:19:25');  // produces false

VARIATION 2

todayIsBOOL = Uize.Date.equal (date1STRorOBJ);

When no date2STRorOBJ parameter is specified, then the date at the time that the Uize.Date.equal method is called will be used as the default for this parameter. Combined with the sensible defaulting of the precisionSTR parameter, this shorthand provides a convenient way ot testing if today's date is a particular date. Consider a few examples...

EXAMPLES

isTodayHalloween2009 = Uize.Date.equal ('2009-10-31');
isTodayChristmas2010 = Uize.Date.equal ('2009-12-25');
isTodayStartOfRamadan2010 = Uize.Date.equal ('2010-08-11');

Specifying the value null or '' (empty string) for the date2STRorOBJ parameter has the same effect as omitting this parameter.

NOTES

IMPLEMENTATION INFO

IMPLEMENTATION INFO

Converts the specified ISO 8601 format (YYYY-MM-DD) date string and returns the date as a Date object instance.

SYNTAX

dateOBJ = Uize.Date.fromIso8601 (dateIso8601STR);

If the date specified by the dateIso8601STR parameter is not in the ISO 8601 format, then this method will return the value undefined.

EXAMPLES

Uize.Date.fromIso8601 ('1981-01-12');       // 12th January 1981
Uize.Date.fromIso8601 ('99-6-29');          // 29th June 1999
Uize.Date.fromIso8601 ('2001-09-11');       // 11th September 2001
Uize.Date.fromIso8601 ('2008-11-04');       // 4th November 2008
Uize.Date.fromIso8601 ('Fri Jul 16 2006');  // undefined

NOTES

IMPLEMENTATION INFO

Returns an integer, indicating the number of days in the specified month of the specified year.

SYNTAX

daysInMonthINT = Uize.Date.getDaysInMonth (month0to11INT,yearINT);

The value of the month0to11INT parameter should be a number in the range of 0 to 11, where 0 represents January, and 11 represents December.

EXAMPLES

Uize.Date.getDaysInMonth (1,2008);   // returns 29, because 2008 is a leap year
Uize.Date.getDaysInMonth (1,2009);   // returns 28, because 2009 is not a leap year
Uize.Date.getDaysInMonth (3,1876);   // returns 30 for April of any year
Uize.Date.getDaysInMonth (11,1989);  // returns 31 for December of any year

NOTES

IMPLEMENTATION INFO

Returns an object, specifying the "neat" date range of the specified range size around the specified date.

SYNTAX

dateRangeOBJ = Uize.Date.getRangeAround (dateSTRorNUMorOBJ,rangeSizeSTR);

This method can be used to obtain the date range for the week around a specified date, the month around a date, the quarter around a date, the year around a date, etc. The date range is specified by a dateRangeOBJ type value.

2.6.1. rangeSizeSTR

Uize.Date.getRangeAround ('Thu Sep 10 2009 18:19:25','second');
// minValue: Thu Sep 10 2009 18:19:25 (and 0 milliseconds)
// maxValue: Thu Sep 10 2009 18:19:25 (and 999 milliseconds)

Uize.Date.getRangeAround ('Thu Sep 10 2009 18:19:25','minute');
// minValue: Thu Sep 10 2009 18:19:00 (and 0 milliseconds)
// maxValue: Thu Sep 10 2009 18:19:59 (and 999 milliseconds)

Uize.Date.getRangeAround ('Thu Sep 10 2009 18:19:25','hour');
// minValue: Thu Sep 10 2009 18:00:00 (and 0 milliseconds)
// maxValue: Thu Sep 10 2009 18:59:59 (and 999 milliseconds)

Uize.Date.getRangeAround ('Thu Sep 10 2009 18:19:25','am/pm');
// minValue: Thu Sep 10 2009 12:00:00 (and 0 milliseconds)
// maxValue: Thu Sep 10 2009 23:59:59 (and 999 milliseconds)

Uize.Date.getRangeAround ('Thu Sep 10 2009 18:19:25','day');
// minValue: Thu Sep 10 2009 00:00:00 (and 0 milliseconds)
// maxValue: Thu Sep 10 2009 23:59:59 (and 999 milliseconds)

Uize.Date.getRangeAround ('Thu Sep 10 2009 18:19:25','week');
// minValue: Sun Sep 06 2009 00:00:00 (and 0 milliseconds)
// maxValue: Sat Sep 12 2009 23:59:59 (and 999 milliseconds)

Uize.Date.getRangeAround ('Thu Sep 10 2009 18:19:25','month');
// minValue: Tue Sep 01 2009 00:00:00 (and 0 milliseconds)
// maxValue: Wed Sep 30 2009 23:59:59 (and 999 milliseconds)

Uize.Date.getRangeAround ('Thu Sep 10 2009 18:19:25','quarter');
// minValue: Wed Jul 01 2009 00:00:00 (and 0 milliseconds)
// maxValue: Wed Sep 30 2009 23:59:59 (and 999 milliseconds)

Uize.Date.getRangeAround ('Thu Sep 10 2009 18:19:25','year');
// minValue: Thu Jan 01 2009 00:00:00 (and 0 milliseconds)
// maxValue: Thu Dec 31 2009 23:59:59 (and 999 milliseconds)

Uize.Date.getRangeAround ('Thu Sep 10 2009 18:19:25','decade');
// minValue: Sat Jan 01 2000 00:00:00 (and 0 milliseconds)
// maxValue: Thu Dec 31 2009 23:59:59 (and 999 milliseconds)

Uize.Date.getRangeAround ('Thu Sep 10 2009 18:19:25','century');
// minValue: Sat Jan 01 2000 00:00:00 (and 0 milliseconds)
// maxValue: Thu Dec 31 2099 23:59:59 (and 999 milliseconds)

Uize.Date.getRangeAround ('Thu Sep 10 2009 18:19:25','millennium');
// minValue: Sat Jan 01 2000 00:00:00 (and 0 milliseconds)
// maxValue: Tue Dec 31 2999 23:59:59 (and 999 milliseconds)

Uize.Date.getRangeAround ('Thu Sep 10 2009 18:19:25','millisecond');
// minValue: Thu Sep 10 2009 18:19:25 (and N milliseconds)
// maxValue: Thu Sep 10 2009 18:19:25 (and N milliseconds)

2.6.2. Using Date Ranges

page.addChild (
  'datePickerThisWeek',
  Uize.Widget.Picker.Date,
  Uize.Date.getRangeAround (
    '',     // empty string for date means now
    'week'  // range size
  )
);

function dateIsThisWeek (date) {
  return Uize.Date.inRange (
    date,
    Uize.Date.getRangeAround (
      '',     // empty string for date means now
      'week'  // range size
    )
  );
}

NOTES

IMPLEMENTATION INFO

Returns a boolean, indicating whether or not the specified date is within the specified date range.

SYNTAX

inRangeBOOL = Uize.Date.inRange (dateSTRorNUMorOBJ,dateRangeOBJ);

The date range is specified by a dateRangeOBJ type value.

EXAMPLES

Uize.Date.inRange (             // produces the result false
  '2009/09/23 00:00:00',
  {minValue:'2009/09/23 00:00:01',maxValue:'2009/09/23 23:59:59'}
);

Uize.Date.inRange (             // produces the result true
  '2009/09/23 00:00:01',
  {minValue:'2009/09/23 00:00:01',maxValue:'2009/09/23 23:59:59'}
);

Uize.Date.inRange (             // produces the result true
  '2009/09/23 23:59:59',
  {minValue:'2009/09/23 00:00:01',maxValue:'2009/09/23 23:59:59'}
);

Uize.Date.inRange (             // produces the result false
  '2009/09/24 00:00:00',
  {minValue:'2009/09/23 00:00:01',maxValue:'2009/09/23 23:59:59'}
);

2.7.1. Precision to the Millisecond

function isTodayOrLater (date) {
  return Uize.Date.inRange (
    date,
    {minValue:Uize.Date.getRangeAround ('','day').minValue}
  );
}

NOTES

IMPLEMENTATION INFO

Returns a boolean, indicating whether or not the specified year is a leap year.

SYNTAX

isLeapYearBOOL = Uize.Date.isLeapYear (yearINT);

EXAMPLES

Uize.Date.isLeapYear (2008);   // returns true, because 2008 is a leap year
Uize.Date.isLeapYear (2009);   // returns false, because 2009 is not a leap year

NOTES

IMPLEMENTATION INFO

Returns a boolean, indicating whether or not the specified date is within the specified window of recency (as specified in days).

SYNTAX

isRecentBOOL = Uize.Date.isRecent (dateSTRorNUMorOBJ,recencyWindowDaysINT);

The date to be tested for recency can be specified using the dateSTRorNUMorOBJ value type. This method can be useful for filtering content to highlight as new or recent, based upon release date.

VARIATION

isRecentBOOL = Uize.Date.isRecent (
  dateSTRorNUMorOBJ,
  recencyWindowDaysINT,
  referencePointDateSTRorNUMorOBJ
);

The optional referencePointDateSTRorNUMorOBJ parameter lets you specify the reference point date, relative to which the date specified by the dateSTRorNUMorOBJ parameter should be tested for recency. When the optional referencePointDateSTRorNUMorOBJ parameter is not specified, then the default reference point is the time that the Uize.Date.isRecent method is called. It may be, however, that you wish to determine if a date is recent relative to some other reference point date. In such cases, use the referencePointDateSTRorNUMorOBJ parameter.

IMPLEMENTATION INFO

Resolves the specified date to a Date object instance and returns that instance.

SYNTAX

dateOBJ = Uize.Date.resolve (dateSTRorNUMorOBJ);

The date to resolve can be specified using the dateSTRorNUMorOBJ value type. When the specified date is already an instance of the Date object, then that instance is simply returned.

This method can be useful when implementing other methods, to give them flexibility in the manner in which dates can be specified for them. Resolving dates means that your code can be sure to be dealing with Date object instances, and can then have a canonical implementation when dealing with dates.

VARIATION 1

dateOBJ = Uize.Date.resolve (dateSTRorNUMorOBJ,defaultDateANYTYPE);

When the optional defaultDateANYTYPE parameter is specified, the value of this parameter will be returned by the Uize.Date.resolve method when the value specified for the dateSTRorNUMorOBJ parameter is '' (empty string), null, or undefined. This allows us to resolve a date with a default other than the date at the time that the Uize.Date.resolve method is called. Note that the value of the defaultDateANYTYPE parameter is not itself resolved to a date - its value will be returned as is. So, if you want a Date object instance to be the default value for the resolved date, provide the default as a Date object instance.

VARIATION 2

dateOBJ = Uize.Date.resolve ();

When no dateSTRorNUMorOBJ parameter is specified, or if an empty string or the value null is specified for this parameter, then a fresh Date object instance (i.e. now) will be returned.

NOTES

IMPLEMENTATION INFO

Returns a string, representing the specified date in ISO 8601 format (YYYY-MM-DD).

SYNTAX

dateIso8601STR = Uize.Date.toIso8601 (dateSTRorNUMorOBJ);

The date to be formatted in the ISO 8601 format can be specified using the dateSTRorNUMorOBJ value type.

VARIATION

dateIso8601STR = Uize.Date.toIso8601 ();

When no dateSTRorNUMorOBJ parameter is specified, this method will return the current date in ISO 8601 format.

NOTES

IMPLEMENTATION INFO

IMPLEMENTATION INFO

An array of strings, representing the names of the days of the week, starting with Sunday.

SYNTAX

dayNameSTR = Uize.Date.dayNames [dayOfWeekINT];

EXAMPLE

var todaysDayName = Uize.Date.dayNames [(new Date).getDay ()];

In the above example, the variable todaysDayName would be left with the name of the day of the week during which the code is executed.

NOTES

IMPLEMENTATION INFO

.

IMPLEMENTATION INFO

IMPLEMENTATION INFO

An array of strings, representing the names of the months of the year, starting with January.

SYNTAX

monthNameSTR = Uize.Date.monthNames [monthOfYearINT];

EXAMPLE

var todaysMonthName = Uize.Date.monthNames [(new Date).getMonth ()];

In the above example, the variable todaysMonthName would be left with the name of the month of the year during which the code is executed.

NOTES

IMPLEMENTATION INFO

IMPLEMENTATION INFO

An array of strings, representing the short names of the days of the week, starting with Sunday.

SYNTAX

shortDayNameSTR = Uize.Date.shortDayNames [dayOfWeekINT];

EXAMPLE

var todaysShortDayName = Uize.Date.shortDayNames [(new Date).getDay ()];

In the above example, the variable todaysShortDayName would be left with the short name of the day of the week during which the code is executed.

NOTES

IMPLEMENTATION INFO

An array of strings, representing the short names of the months of the year, starting with January.

SYNTAX

shortMonthNameSTR = Uize.Date.shortMonthNames [monthOfYearINT];

EXAMPLE

var todaysShortMonthName = Uize.Date.shortMonthNames [(new Date).getMonth ()];

In the above example, the variable todaysShortMonthName would be left with the short name of the month of the year during which the code is executed.

NOTES

IMPLEMENTATION INFO

A string in ISO 8601 format (YYYY-MM-DD), a string that can be parsed by the Date object, a Date object instance, or a number specifying the Unix Time in milliseconds.

Methods accepting this value type for a parameter may resolve the value '' (empty string), null, or undefined to the date at the time that the method is called (today's date, essentially), or they may provide an alternate defaulting behavior.

EXAMPLES

'Thu Sep 10 2009'             // string that can be parsed by JavaScript's Date object
'2009-09-10'                  // ISO 8601
new Date ('Thu Sep 10 2009')  // JavaScript Date object instance

The above example are all valid ways to specify the same date using the dateSTRorNUMorOBJ value type.

An object, containing minValue and maxValue properties, where the value of these properties are of the type dateSTRorNUMorOBJ, and where the minValue property specifies the start of the date range, and the maxValue property specifies the end of the range.

STRUCTURE

{
  minValue:startDateSTRorNUMorOBJ,
  maxValue:endDateSTRorNUMorOBJ
}

Various methods deal with values of the dateRangeOBJ type. One example is the Uize.Date.getRangeAround method, which returns a dateRangeOBJ value specifying the "neat" date range of the specified range size around the specified date. Another example is the Uize.Date.inRange method, which returns a boolean, indicating whether or not the specified date is within the date range specified by a dateRangeOBJ value.

4.2.1. Boundless Date Ranges

// no upper bound

Uize.Date.inRange ('2009-08-10',{minValue:'2009-09-01'});        // false
Uize.Date.inRange ('2009-09-01',{minValue:'2009-09-01'});        // true
Uize.Date.inRange ('2009-09-10',{minValue:'2009-09-01'});        // true


// no lower bound

Uize.Date.inRange ('2009-08-10',{maxValue:'2009-09-01'});        // true
Uize.Date.inRange ('2009-09-01',{maxValue:'2009-09-01'});        // true
Uize.Date.inRange ('2009-09-10',{maxValue:'2009-09-01'});        // false


// no bound at all

Uize.Date.inRange ('2009-09-10',{});                             // true
Uize.Date.inRange ('2009-09-10',{minValue:null});                // true
Uize.Date.inRange ('2009-09-10',{maxValue:null});                // true
Uize.Date.inRange ('2009-09-10',{minValue:null,maxValue:null});  // true