Class Calendar
dw.util
Class Calendar
Object
dw.util.Calendar
Represents a Calendar and is based on the java.util.Calendar class. Refer to the java.util.Calendar documentation for more information.

IMPORTANT NOTE: Please use the StringUtils.formatCalendar(Calendar) functions to convert a Calendar object into a String.
Constants
AM_PM  :  Number = 9
Indicates whether the HOUR is before or after noon.
APRIL  :  Number = 3
Value for the month of year field representing April.
AUGUST  :  Number = 7
Value for the month of year field representing August.
DATE  :  Number = 5
Represents a date.
DAY_OF_MONTH  :  Number = 5
Represents a day of the month.
DAY_OF_WEEK  :  Number = 7
Represents a day of the week.
DAY_OF_WEEK_IN_MONTH  :  Number = 8
Represents a day of the week in a month.
DAY_OF_YEAR  :  Number = 6
Represents a day of the year.
DECEMBER  :  Number = 11
Value for the month of year field representing December.
DST_OFFSET  :  Number = 16
Indicates the daylight savings offset in milliseconds.
ERA  :  Number = 0
Indicates the era such as 'AD' or 'BC' in the Julian calendar.
FEBRUARY  :  Number = 1
Value for the month of year field representing February.
FRIDAY  :  Number = 6
Value for the day of the week field representing Friday.
HOUR  :  Number = 10
Represents an hour.
HOUR_OF_DAY  :  Number = 11
Represents an hour of the day.
INPUT_DATE_PATTERN  :  Number = 3
The input date pattern, for instance MM/dd/yyyy
INPUT_DATE_TIME_PATTERN  :  Number = 5
The input date time pattern, for instance MM/dd/yyyy h:mm a
INPUT_TIME_PATTERN  :  Number = 4
The input time pattern, for instance h:mm a
JANUARY  :  Number = 0
Value for the month of year field representing January.
JULY  :  Number = 6
Value for the month of year field representing July.
JUNE  :  Number = 5
Value for the month of year field representing June.
LONG_DATE_PATTERN  :  Number = 1
The long date pattern, for instance MMM/d/yyyy
MARCH  :  Number = 2
Value for the month of year field representing March.
MAY  :  Number = 4
Value for the month of year field representing May.
MILLISECOND  :  Number = 14
Represents a millisecond.
MINUTE  :  Number = 12
Represents a minute.
MONDAY  :  Number = 2
Value for the day of the week field representing Monday.
MONTH  :  Number = 2
Represents a month where the first month of the year is 0.
NOVEMBER  :  Number = 10
Value for the month of year field representing November.
OCTOBER  :  Number = 9
Value for the month of year field representing October.
SATURDAY  :  Number = 7
Value for the day of the week field representing Saturday.
SECOND  :  Number = 13
Represents a second.
SEPTEMBER  :  Number = 8
Value for the month of year field representing September.
SHORT_DATE_PATTERN  :  Number = 0
The short date pattern, for instance M/d/yy
SUNDAY  :  Number = 1
Value for the day of the week field representing Sunday.
THURSDAY  :  Number = 5
Value for the day of the week field representing Thursday.
TIME_PATTERN  :  Number = 2
The time pattern, for instance h:mm:ss a
TUESDAY  :  Number = 3
Value for the day of the week field representing Tuesday.
WEDNESDAY  :  Number = 4
Value for the day of the week field representing Wednesday.
WEEK_OF_MONTH  :  Number = 4
Represents a week of the month.
WEEK_OF_YEAR  :  Number = 3
Represents a week in the year.
YEAR  :  Number = 1
Represents a year.
ZONE_OFFSET  :  Number = 15
Indicates the raw offset from GMT in milliseconds.
Properties
firstDayOfWeek  :  Number
The first day of the week base on locale context. For example, in the US the first day of the week is SUNDAY. However, in France the first day of the week is MONDAY.
time  :  Date
The current time stamp of this calendar. This method is also used to convert a Calendar into a Date.

WARNING: Keep in mind that the returned Date object's time is always interpreted in the time zone GMT. This means time zone information set at the calendar object will not be honored and gets lost.
timeZone  :  String
The current time zone of this calendar.
Constructor Summary
Calendar()
Creates a new Calendar object that is set to the current time.
Calendar(date : Date)
Creates a new Calendar object for the given Date object.
Method Summary
add(field : Number, value : Number) : void
Adds or subtracts the specified amount of time to the given calendar field, based on the calendar's rules.
after(obj : Object) : boolean
Indicates if this Calendar represents a time after the time represented by the specified Object.
before(obj : Object) : boolean
Indicates if this Calendar represents a time before the time represented by the specified Object.
clear() : void
Sets all the calendar field values and the time value (millisecond offset from the Epoch) of this Calendar undefined.
clear(field : Number) : void
Sets the given calendar field value and the time value (millisecond offset from the Epoch) of this Calendar undefined.
compareTo(anotherCalendar : Calendar) : Number
Compares the time values (millisecond offsets from the Epoch) represented by two Calendar objects.
equals(other : Object) : boolean
Compares two calendar values whether they are equivalent.
get(field : Number) : Number
Returns the value of the given calendar field.
getActualMaximum(field : Number) : Number
Returns the maximum value that the specified calendar field could have.
getActualMinimum(field : Number) : Number
Returns the minimum value that the specified calendar field could have.
getFirstDayOfWeek() : Number
Returns the first day of the week base on locale context.
getMaximum(field : Number) : Number
Returns the maximum value for the given calendar field.
getMinimum(field : Number) : Number
Returns the minimum value for the given calendar field.
getTime() : Date
Returns the current time stamp of this calendar.
getTimeZone() : String
Returns the current time zone of this calendar.
hashCode() : Number
Calculates the hash code for a calendar;
isLeapYear(year : Number) : boolean
Indicates if the specified year is a leap year.
isSameDay(other : Calendar) : boolean
Checks, whether two calendar dates fall on the same day.
isSameDayByTimestamp(other : Calendar) : boolean
Checks, whether two calendar dates fall on the same day.
isSet(field : Number) : boolean
Indicates if the field is set.
parseByFormat(timeString : String, format : String) : void
Parses the string according to the date and time format pattern and set the time at this calendar object.
parseByLocale(timeString : String, locale : String, pattern : Number) : void
Parses the string according the date format pattern of the given locale.
roll(field : Number, up : boolean) : void
Rolls the specified field up or down one value.
roll(field : Number, amount : Number) : void
Rolls the specified field using the specified value.
set(field : Number, value : Number) : void
Sets the given calendar field to the given value.
set(year : Number, month : Number, date : Number) : void
Sets the values for the calendar fields YEAR, MONTH, and DAY_OF_MONTH.
set(year : Number, month : Number, date : Number, hourOfDay : Number, minute : Number) : void
Sets the values for the calendar fields YEAR, MONTH, DAY_OF_MONTH, HOUR_OF_DAY, and MINUTE.
set(year : Number, month : Number, date : Number, hourOfDay : Number, minute : Number, second : Number) : void
Sets the values for the calendar fields YEAR, MONTH, DAY_OF_MONTH, HOUR_OF_DAY, MINUTE and SECOND.
setFirstDayOfWeek(value : Number) : void
Sets what the first day of the week is.
setTime(date : Date) : void
Sets the current time stamp of this calendar.

WARNING: Keep in mind that the set Date object's time is always interpreted in the time zone GMT.
setTimeZone(timeZone : String) : void
Sets the current time zone of this calendar.

WARNING: Keep in mind that the time stamp represented by the calendar is always interpreted in the time zone GMT.
Constructor Detail
Calendar
public Calendar()
Creates a new Calendar object that is set to the current time. The default time zone of the Calendar object is GMT.

WARNING: Keep in mind that the time stamp represented by the new calendar is always interpreted in the time zone GMT. This means time zone information at the calendar object needs to be set separately by using the setTimeZone(String) method.

Calendar
public Calendar(date : Date)
Creates a new Calendar object for the given Date object. The time is set to the given Date object's time. The default time zone of the Calendar object is GMT.

WARNING: Keep in mind that the given Date object is always interpreted in the time zone GMT. This means time zone information at the calendar object needs to be set separately by using the setTimeZone(String) method.
Parameters:
date - the date for which the calendar will be set.

Method Detail
add
add(field : Number, value : Number) : void
Adds or subtracts the specified amount of time to the given calendar field, based on the calendar's rules.
Parameters:
field - the calendar field.
value - the amount of date or time to be added to the field

after
after(obj : Object) : boolean
Indicates if this Calendar represents a time after the time represented by the specified Object.
Parameters:
obj - the object to test.
Returns:
true if this Calendar represents a time after the time represented by the specified Object, false otherwise.

before
before(obj : Object) : boolean
Indicates if this Calendar represents a time before the time represented by the specified Object.
Parameters:
obj - the object to test.
Returns:
true if this Calendar represents a time before the time represented by the specified Object, false otherwise.

clear
clear() : void
Sets all the calendar field values and the time value (millisecond offset from the Epoch) of this Calendar undefined.

clear
clear(field : Number) : void
Sets the given calendar field value and the time value (millisecond offset from the Epoch) of this Calendar undefined.
Parameters:
field - the calendar field to be cleared.

compareTo
compareTo(anotherCalendar : Calendar) : Number
Compares the time values (millisecond offsets from the Epoch) represented by two Calendar objects.
Parameters:
anotherCalendar - the Calendar to be compared.
Returns:
the value 0 if the time represented by the argument is equal to the time represented by this Calendar; a value less than 0 if the time of this Calendar is before the time represented by the argument; and a value greater than 0 if the time of this Calendar is after the time represented by the argument.

equals
equals(other : Object) : boolean
Compares two calendar values whether they are equivalent.
Parameters:
other - the object to compare against this calendar.

get
get(field : Number) : Number
Returns the value of the given calendar field.
Parameters:
field - the calendar field to retrieve.
Returns:
the value for the given calendar field.

getActualMaximum
getActualMaximum(field : Number) : Number
Returns the maximum value that the specified calendar field could have.
Parameters:
field - the calendar field.
Returns:
the maximum value that the specified calendar field could have.

getActualMinimum
getActualMinimum(field : Number) : Number
Returns the minimum value that the specified calendar field could have.
Parameters:
field - the calendar field.
Returns:
the minimum value that the specified calendar field could have.

getFirstDayOfWeek
getFirstDayOfWeek() : Number
Returns the first day of the week base on locale context. For example, in the US the first day of the week is SUNDAY. However, in France the first day of the week is MONDAY.
Returns:
the first day of the week base on locale context. For example, in the US the first day of the week is SUNDAY. However, in France the first day of the week is MONDAY.

getMaximum
getMaximum(field : Number) : Number
Returns the maximum value for the given calendar field.
Parameters:
field - the calendar field.
Returns:
the maximum value for the given calendar field.

getMinimum
getMinimum(field : Number) : Number
Returns the minimum value for the given calendar field.
Parameters:
field - the calendar field.
Returns:
the minimum value for the given calendar field.

getTime
getTime() : Date
Returns the current time stamp of this calendar. This method is also used to convert a Calendar into a Date.

WARNING: Keep in mind that the returned Date object's time is always interpreted in the time zone GMT. This means time zone information set at the calendar object will not be honored and gets lost.
Returns:
the current time stamp of this calendar as a Date.

getTimeZone
getTimeZone() : String
Returns the current time zone of this calendar.
Returns:
the current time zone of this calendar.

hashCode
hashCode() : Number
Calculates the hash code for a calendar;

isLeapYear
isLeapYear(year : Number) : boolean
Indicates if the specified year is a leap year.
Parameters:
year - the year to test.
Returns:
true if the specified year is a leap year.

isSameDay
isSameDay(other : Calendar) : boolean
Checks, whether two calendar dates fall on the same day.

The method performs comparison based on both calendar's field values by honoring the defined time zones.

Examples:

new Calendar( new Date( "2002/02/28 13:45" ).isSameDay( new Calendar( new Date( "2002/02/28 06:01" ) ) );
would return true.
new Calendar( new Date( "2002/02/28 13:45" ).isSameDay( new Calendar( new Date( "2002/02/12 13:45" ) ) );
would return false.
new Calendar( new Date( "2002/02/28 13:45" ).isSameDay( new Calendar( new Date( "1970/02/28 13:45" ) ) );
would return false.
 var cal1 = new Calendar( new Date( "2002/02/28 02:00" );
 cal1.setTimeZone( "Etc/GMT+1" );
 var cal2 = new Calendar( new Date( "2002/02/28 00:00" );
 cal2.setTimeZone( "Etc/GMT+1" );
 cal1.isSameDay( cal2 );
would return false since the time zone is applied first which results in comparing 2002/02/28 01:00 for cal1 with 2002/02/27 23:00 for cal2.

Parameters:
other - the calendar to compare against this calendar.

isSameDayByTimestamp
isSameDayByTimestamp(other : Calendar) : boolean
Checks, whether two calendar dates fall on the same day.

The method performs comparison based on both calendar's time stamps by ignoring any defined time zones.

Examples:

new Calendar( new Date( "2002/02/28 13:45" ).isSameDayByTimestamp( new Calendar( new Date( "2002/02/28 06:01" ) ) );
would return true.
new Calendar( new Date( "2002/02/28 13:45" ).isSameDayByTimestamp( new Calendar( new Date( "2002/02/12 13:45" ) ) );
would return false.
new Calendar( new Date( "2002/02/28 13:45" ).isSameDayByTimestamp( new Calendar( new Date( "1970/02/28 13:45" ) ) );
would return false.
 var cal1 = new Calendar( new Date( "2002/02/28 02:00" );
 cal1.setTimeZone( "Etc/GMT+1" );
 var cal2 = new Calendar( new Date( "2002/02/28 00:00" );
 cal2.setTimeZone( "Etc/GMT+1" );
 cal1.isSameDayByTimestamp( cal2 );
would return true since the time zone is not applied first which results in comparing 2002/02/28 02:00 for cal1 with 2002/02/28 00:00 for cal2.

Parameters:
other - the calendar to compare against this calendar.

isSet
isSet(field : Number) : boolean
Indicates if the field is set.
Parameters:
field - the field to test.
Returns:
true if the field is set, false otherwise.

parseByFormat
parseByFormat(timeString : String, format : String) : void
Parses the string according to the date and time format pattern and set the time at this calendar object. For the specification of the date and time format pattern see the javadoc of the JDK class java.text.SimpleDateFormat. If a time zone is included in the format string, this time zone is used to interpet the time. Otherwise the currently set calendar time zone is used to parse the given time string.
Parameters:
timeString - the time string to parsed
format - the time format string

parseByLocale
parseByLocale(timeString : String, locale : String, pattern : Number) : void
Parses the string according the date format pattern of the given locale. If the locale name is invalid, an exception is thrown. The currently set calendar time zone is used to parse the given time string.
Parameters:
timeString - the time string to parsed
locale - the locale id, which defines the date format pattern
pattern - the pattern is one of calendar pattern e.g. SHORT_DATE_PATTERN as defined in the regional settings for the locale

roll
roll(field : Number, up : boolean) : void
Rolls the specified field up or down one value.
Parameters:
field - the field to roll.
up - if true rolls the field up, if false rolls the field down.

roll
roll(field : Number, amount : Number) : void
Rolls the specified field using the specified value.
Parameters:
field - the field to roll.
amount - the amount to roll the field.

set
set(field : Number, value : Number) : void
Sets the given calendar field to the given value.
Parameters:
field - the calendar field to set.
value - the value to set in the field.

set
set(year : Number, month : Number, date : Number) : void
Sets the values for the calendar fields YEAR, MONTH, and DAY_OF_MONTH.
Parameters:
year - the value for year.
month - the value for month.
date - the value for date.

set
set(year : Number, month : Number, date : Number, hourOfDay : Number, minute : Number) : void
Sets the values for the calendar fields YEAR, MONTH, DAY_OF_MONTH, HOUR_OF_DAY, and MINUTE.
Parameters:
year - the value for year.
month - the value for month.
date - the value for date.
hourOfDay - the value for hour of day.
minute - the value for minute.

set
set(year : Number, month : Number, date : Number, hourOfDay : Number, minute : Number, second : Number) : void
Sets the values for the calendar fields YEAR, MONTH, DAY_OF_MONTH, HOUR_OF_DAY, MINUTE and SECOND.
Parameters:
year - the value for year.
month - the value for month.
date - the value for date.
hourOfDay - the value for hour of day.
minute - the value for minute.
second - the value for second.

setFirstDayOfWeek
setFirstDayOfWeek(value : Number) : void
Sets what the first day of the week is.
Parameters:
value - the day to set as the first day of the week.

setTime
setTime(date : Date) : void
Sets the current time stamp of this calendar.

WARNING: Keep in mind that the set Date object's time is always interpreted in the time zone GMT. This means that time zone information at the calendar object needs to be set separately by using the setTimeZone(String) method.
Parameters:
date - the current time stamp of this calendar.

setTimeZone
setTimeZone(timeZone : String) : void
Sets the current time zone of this calendar.

WARNING: Keep in mind that the time stamp represented by the calendar is always interpreted in the time zone GMT. Changing the time zone will not change the calendar's time stamp.
Parameters:
timeZone - the current time zone value to set.