Time Functions

addDays

Adds a specified number of days to a Time object.

Arguments

Time - the Time object to which days will be added.
Int i - the number of days to be added to the time object.

Returns

The Time object resulting from adding the specified number of days to the given time.

Example

The following example adds 15 days to the current time and displays the result.

	display "time in 15 days will be: " + 
	    addDays('now', i : 15)

addHours

Adds a specified number of hours to a Time object.

Arguments

Time - the Time object to which hours will be added.
Int i - the number of hours to be added to the Time object.

Returns

The Time object resulting from adding the specified number of hours to the given time.

Example

The following example adds 12 hours to the current time and displays the result:

display "time in 12 hours will be: " + 
	     addHours('now', i : 12)

addMicroSeconds

Adds a specified number of microseconds to a Time object.

Arguments

Time - the Time object to which microseconds will be added.
Int i - the number of microseconds to be added to the Time object.

Returns

The Time object resulting from adding the specified number of microseconds to the given time.

Example

The following example adds 500 microseconds to the current time and displays the result:

display "time in 500 microseconds will be: " + 
	    addMicroSeconds('now', i : 500)

addMilliSeconds

Adds a specified number of milliseconds to a Time object.

Arguments

Time - the Time object to which milliseconds will be added.
Int i - the number of milliseconds to be added to the Time object.

Returns

The Time object resulting from adding the specified number of milliseconds to the given time.

Example

The following example adds 50,000 milliseconds to the current time and displays the result:

display "time in 50000 milliseconds will be: " + 
	    addMilliSeconds('now', i : 50000)

addMinutes

Adds a specified number of minutes to a Time object.

Arguments

Time - the Time object to which the milliseconds will be added.
Int i - the number of minutes to be added to the Time object.

Returns

The Time object resulting from adding the specified number of milliseconds to the given time.

Example

The following example adds 30 minutes to the current time and displays the result:

display "time in 30 minutes will be: " + 
	    addMinutes('now', i : 30)

addMonths

Adds a specified number of months to a Time object.

Arguments

Time - the Time object to which the months will be added.
Int i - the number of months to be added to the Time object.

Returns

The Time object resulting from adding the specified number of months to the given time.

Example

The following example adds 6 months to the current time and displays the result.

display "time in 6 months will be: " + 
	    addMonths('now', i : 6)

addSeconds

Adds a specified number of seconds to a Time object.

Arguments

Time - the Time object to which the seconds will be added.
Int i - the number of seconds to be added to the Time object.

Returns

The Time object resulting from adding the specified number of seconds to the given time.

Example

The following example adds 50 seconds to the time object and displays the result:

display "time in 50 seconds will be: " + 
	    addSeconds('now', i : 50)

addWeeks

Adds a specified number of weeks to a Time object.

Arguments

Time - the Time object to which the weeks will be added.
Int i - the number of weeks to be added to the Time object.

Returns

The Time object resulting from adding the specified number of weeks to the given time.

Example

The following example adds 50 weeks to the current time and displays the result:

display "time in 50 weeks will be: " + 
	    addWeeks('now', weeks : 50)

addYears

Adds a specified number of years to a Time object.

Arguments

Time - the Time object to which the years will be added.
Int i - the number of years to be added to the Time object.

Returns

The Time object resulting from adding the specified number of years to the given time:

display "time in 10 years will be: " + 
	     addYears('now', i : 10)

add

Adds a specified interval of time to a Time object.

Arguments

Time - the Time object to which the interval of time will be added.
Interval i - interval of time to add to the Time object.

Returns

The Time object resulting from adding the specified interval to the given time.

Example

The following example adds 5 days, 15 hours, and 30 minutes to the current time and displays the result:

display "time in 5 days 15 hours and 30 minutes: \n\n" + 
	    add('now', interval : '5d15h30m')

between

Determines if the given Time object is between two Time objects.

Arguments:

Time - the given Time object.
Time from - the upper bound of the time period in which to search the given time, exclusive.
Time to - the lower bound of the time period in which to search the given time, inclusive.

Returns

true - if the given Time object is contained in the specified period.

false - if the given object is not contained in the specified period.

Example

The following example finds out if the current time is in between the first day and last day of year 2004:

display "is today between 2004-01-01 and 2004-12-31? "+
	between('now', from : '2004-01-01 12:00:00', 
	@to : '2004-12-31 12:00:00')

daysSince

Calculates the days passed between a given time and another time.

Arguments

Time - the Time object.
Time t - the other Time object.

Returns

An Int value representing the number of days between the two given times.

Example

The following example defines a Time variable birthdate, calculates the days passed between 'now' and birthdate and displays the result:

birthdate as Time
	birthdate = '1979-02-19'
	display "days passed since birthdate: " + 
	    daysSince('now', t : birthdate)

formatDate

Formats the Time object with the default mask.

Arguments

Time - the Time object to be formatted.

Returns

A String containing the representation of the Time object formatted with the default mask.

Example

The following example displays the current time formatted with the default mask:

display formatDate('now')

formatDate

Formats the Time object with the specified date formatting style for the default locale.

Arguments

Time - the Time object to be formatted.
Int style - The formatting style. Available styles are Time.DEFAULT, Time.FULL, Time.LONG, and Time.SHORT.

Returns

A String containing the representation of the Time object formatted with the specified style.

Example

The following example displays the current time with the four possible formatting styles:

	defaultDate as String = "Default format --> " + 
	      formatDate('now', dateStyle : Time.DEFAULT)
	
	fullDate as String = "Full format --> " + 
	      formatDate('now', dateStyle : Time.FULL)
	
	longDate as String = "Long format --> " + 
	      formatDate('now', dateStyle : Time.LONG)
	
	shortDate as String = "Short format --> " + 
	      formatDate('now', dateStyle : Time.SHORT)
	
	display defaultDate + "\n\n" + fullDate + "\n\n" + 
	      longDate + "\n\n" + shortDate + "\n\n"

formatTimeOnly

Formats this Time object as a time only, with no time zone correction.

Arguments

Time - The Time object to be formatted.

Returns

A String containing the representation of the Time object formatted as time only.

The following example displays the current time formatted as time only. It should display something similar to 12439d 16:58:58:

display formatTimeOnly('now')

formatTimeOnly

Formats this Time object as a time only, with no time zone correction, applying the specified style.

Arguments

Time - The Time object to be formatted.
Int - The formatting style. Available styles are Time.DEFAULT, Time.FULL, Time.LONG, and Time.SHORT.

Returns

A String containing the representation of the Time object formatted as time only, applying the specified style.

Example

The following example only displays the time representation of the current time in the four available styles:

	
	defaultTime as String = "Default format --> " + 
	     formatTimeOnly('now', intervalStyle : Time.DEFAULT)
	
	fullTime as String = "Full format --> " + 
	     formatTimeOnly('now', intervalStyle : Time.FULL)
	
	longTime as String = "Long format --> " + 
	     formatTimeOnly('now', intervalStyle : Time.LONG)
	
	shortTime as String = "Short format --> " + 
	     formatTimeOnly('now', intervalStyle : Time.SHORT)
	
	display defaultTime + "\n\n" +
	    fullTime + "\n\n" +
	    longTime + "\n\n" +
	    shortTime + "\n\n"

formatTime

Formats the time component of a Time object with a specified style.

Arguments

Time - The Time object to be formatted.
Int timeStyle - The formatting style. Available styles are Time.DEFAULT, Time.FULL, Time.LONG, and Time.SHORT.

Returns

A String containing the time component of the Time object formatted with the specified style.

Example

The following example displays the time component of the current time formatted with the four available styles:

	
	defaultTime as String = "Default format --> " +
	    formatTime('now', timeStyle : Time.DEFAULT)
	
	fullTime as String = "Full format --> " +
	    formatTime('now', timeStyle : Time.FULL)
	
	longTime as String = "Long format --> " + 
	    formatTime('now', timeStyle : Time.LONG)
	
	shortDate as String = "Short format --> " +
	    formatTime('now', timeStyle : Time.SHORT)
	
	display defaultTime + "\n\n" +
	   fullTime + "\n\n" +
	   longTime + "\n\n" +
	   shortTime + "\n\n"

format

Formats a Time object with the default mask.

Arguments

Time - the Time object to be formatted.

Returns

A string containing the representation of the Time object formatted with the default mask.

Example

The following example displays the current time formatted with the default mask.

display format('now')

format

Formats a Time object with a specified date style and time style.

Arguments

Time - The Time object to be formatted.
Int dateStyle - The style to be applied to the date component of the Time object. Available styles are:Time.DEFAULT, Time.FULL, Time.LONG, and Time.SHORT.
Int timeStyle - The style to be applied to the time component of the Time object. Available styles are Time.DEFAULT, Time.FULL, Time.LONG, and Time.SHORT.

Returns

A string containing the representation of the Time object whose date was formatted with the specified date style, and whose time was formatted with the specified time style.

Example

The following example displays the current time with its date in full format style and its time in short format style first, then the same time with its date in short format style and its time in full format style:

	fullDateShortTime as String = "Full date, short time: " +
	    format('now', dateStyle : Time.FULL,
	                timeStyle : Time.SHORT)
	
	shortDateFullTime as String = "Short date, full time: " + 
	    format('now', dateStyle : Time.SHORT, 
	                timeStyle : Time.FULL)
	
	display fullDateShortTime + "\n\n" + shortDateFullTime

format

Formats a Time object by applying a specified formatter.

Arguments

Time - The Time object to be formatted.
Java.Text.DateFormat formatter - The formatter to be applied in order to format the Time object.

Returns

A String containing the representation of the Time object formatted by applying the specified formatter.

Example

The following example displays the current Time formatted with the formatter passed by arguments:

display format('now', formatter : DateFormat.getInstance())

format

Formats a Time object with a specified formatter using the provided time zone and locale.

Arguments

Time - The Time object to be formatted.
Java.Text.DateFormat formatter - The formatter to be applied in order to format the Time object.
Java.Util.TimeZone timeZone - The time zone to apply to the Time object when formatting it.
Java.Util.Locale locale - The locale to apply to the Time object when formatting it.

Returns

A String containing the representation of the Time object formatted by applying the specified formatter and the time zone and locate provided.

Example

The following example displays the current Time formatted applying the formatter passed by arguments, GMT-10 time zone and French locale:

	display format('now', formatter : DateFormat.getInstance(),
	      timeZone : TimeZone.getTimeZone(arg1 : "GMT-10"), 
	      locale : Java.Util.Locale.FRANCE)

format

Formats a Time object with a specified mask.

Arguments

Time - The Time object to be formatted.
String mask - A string containing the mask to apply in order to format the Time object.

Returns

A String containing the representation of the Time object formatted with the specified mask. The String should be written according to the patterns and rules described below.

The following pattern letters are defined (all other characters from 'A' to 'Z' and from 'a' to 'z' are reserved):

Letter	Date or Time Component	Presentation	Example
G	Era designator	Text	AD
y	Year	Year	1996; 96
M	Month in year	Month	July; Jul; 07
w	Week in year	Number	27
W	Week in month	Number	2
D	Day in year	Number	189
d	Day in month	Number	10
F	Day of week in month	Number	2
E	Day in week	Text	Tuesday; Tue
a	Am/pm marker	Text	PM
H	Hour in day (0-23)	Number	0
k	Hour in day (1-24)	Number	24
K	Hour in am/pm (0-11)	Number	0
h	Hour in am/pm (1-12)	Number	12
m	Minute in hour	Number	30
s	Second in minute	Number	55
S	Millisecond	Number	978
z	Time zone	General time zone	Pacific Standard Time; PST; GMT-08:00
Z	Time zone	RFC 822 time zone	-0800

Pattern letters are usually repeated, as their number determines the exact presentation:

Text: For formatting, if the number of pattern letters is 4 or more, the full form is used. Otherwise, a short or abbreviated form is used if available. For parsing, both forms are accepted, independent of the number of pattern letters.
Number: For formatting, the number of pattern letters is the minimum number of digits, and shorter numbers are zero-padded to this number. For parsing, the number of pattern letters is ignored unless it's needed to separate two adjacent fields.
Year: For formatting, if the number of pattern letters is 2, the year is truncated to 2 digits. Otherwise, it is interpreted as a number.

Example

The following example displays the current time formatted with the mask defined by the String passed by arguments. It should display something like: Thu 22 01 2004 04:31:48:975 PM ART:

display 'now'.format("E dd MM yyyy hh:mm:ss:SS a z")

getDateFormat

Returns an appropriate DateFormat based on the parts needed and a style.

Arguments

Int parts - The needed parts. These could be Time.DATE_ONLY, Time.TIME_ONLY, or Time.DATE_TIME.
Int style - The formatting style. Available styles are Time.DEFAULT, Time.FULL, Time.LONG, and Time.SHORT.

Returns

The format based on the required parts and style.

Example

The following example uses the function getDateFormat with different needed parts and style to format the current time:

	fullDateOnly as String
	
	fullDateOnly = "Date only - Full format: " + 
	  'now'.format(Time.getDateFormat(
	        parts : Time.DATE_ONLY, 
	        style : Time.FULL))
	
	shortTimeOnly as String
	shortTimeOnly = "Time only - Short format: " + 
	  'now'.format(Time.getDateFormat(
	        parts : Time.TIME_ONLY,
	        style : Time.SHORT))
	
	longDateTime as String
	longDateTime = "Date time - Long format: " + 
	 'now'.format(Time.getDateFormat(
	        parts : Time.DATE_TIME, 
	        style : Time.FULL))
	
	display fullDateOnly + "\n\n" + shortTimeOnly + "\n\n" + 
	          longDateTime

getDateFormat

Returns an appropriate DateFormat based on the required parts, style, and locale.

Arguments

Int parts - The needed parts. These could be Time.DATE_ONLY, Time.TIME_ONLY, or Time.DATE_TIME.
Int style - The formatting style. Available styles are Time.DEFAULT, Time.FULL, Time.LONG, and Time.SHORT.
Java.Util.Locale - The locale the date formatter will have to apply.

Returns

Returns an appropriate DateFormat based on the required parts, style, and locale.

Example

The following example uses the function getDateFormat with different needed parts and style, and french locale, to format the current time:

	fullDateOnly as String
	fullDateOnly = "Date only - Full format: " + 
	      'now'.format(Time.getDateFormat(
	         parts : Time.DATE_ONLY, 
	         style : Time.FULL, Java.Util.Locale.FRANCE))
	
	shortTimeOnly as String
	shortTimeOnly = "Time only - Short format: " + 
	      'now'.format(Time.getDateFormat(
	          parts : Time.TIME_ONLY, 
	          style : Time.SHORT, Java.Util.Locale.FRANCE))
	
	longDateTime as String
	longDateTime = "Date time - Long format: " + 
	      'now'.format(Time.getDateFormat(
	          parts : Time.DATE_TIME, 
	          style : Time.FULL, Java.Util.Locale.FRANCE))
	
	display fullDateOnly + "\n\n" + shortTimeOnly + "\n\n" + 
	       longDateTime

Time.getEaster

Calculates Easter day for a specified year.

Arguments

y: The year for which you would like to know Easter's date.

Returns

A Time object containing Easter date.

Example

The following example displays Easter date for the year 2007:

display Time.getEaster(y : 2007)

This will show:

Apr 8, 2007 12:00:00 AM

Time.getMonthName

Returns the name of the specified month.

Arguments

monthNum: The number which identifies the month from which you would like to know the name. This number may vary between 1 (January) and 12 (December).

Returns

The name of the specified month.

Example

The following example displays the name of month 2 (February):

display Time.getMonthName(monthNum : 2)

Time.getWeekdayName

Returns the name of the specified weekday.

Arguments

Int dayNum - The number which identifies the day from which you would like to know the name. This number may vary between 0 (Sunday) and 6 (Saturday).

Returns

The name of the specified day.

Example

The following example displays the day 3 (Wednesday):

display Time.getWeekdayName(dayNum : 0)

max

Returns the greater time between two Time objects.

Arguments

Time1: A Time object
Time2: Another Time object

Returns

The greater Time object.

Example

The following example displays the greater Time between the current time and the date the man landed on the moon. The current time is returned:

manOnMoon as Time
manOnMoon = '1969-07-21 02:56:00 -00'
display max(manOnMoon, b : 'now')

min

Returns the smaller Time object between two Time objects.

Arguments

Time a - A Time object.
Time b - Another Time object.

Returns

The smaller Time object.

For example:

manOnMoon as Time
manOnMoon = '1969-07-21 02:56:00 -00'
display min(manOnMoon, b : 'now')

monthsSince

Returns the number of months elapsed since a given Time object.

Arguments

Time: A Time object

Returns

An Int value with the number of whole months elapsed since the time specified by the Time object to the present time. For example, there are two whole months between January 15 and March 15, but only one whole month between January 15 and March 14.

For example:

xMas2007 as Time
xMas2007 = '2007-12-25'
display monthsSince('now', t : xMas2007)

roundToSeconds

Rounds a Time object to the nearest second.

Arguments

Time: A Time object

Returns

A Time object with the value of Time rounded to the nearest second.

Note: The value is rounded, not truncated, so 499 milliseconds or less will be rounded down, while 500 milliseconds or more will be rounded up.

Example

The following example creates a Time object called timeStart with seconds and milliseconds, then it displays the value rounded to the nearest second:

timeStart as Time
time = '2007-04-16 17:21:30.235'
display roundToSeconds(timeStart)

This displays:

Apr 16, 2007 2:21:30 PM