| |
OScript API/Built-in Package Index |
The Date package supplies a set of built-ins for querying the current time and date, and creating and manipulating Date values. The major functionalities offered are the following:
Returns the number of clock tick since the start of the process.
Returns a copy of theDate with the time portion cleared to 00:00:00.
Converts a Date to an Integer or an Integer to a Date.
Breaks a Date into a List of numerical date elements.
Returns a String representation of a Date.
Returns the day of the month for a specified Date.
Returns the day of the week for a specified Date.
Returns the year for a specified Date.
Returns the number of hours past midnight for a specified Date.
Creates a Date from a List of numerical date elements.
Returns the elapsed time in microseconds; useful for calculating timing.
Returns the number of minutes past the hour for a specified Date.
Returns the numerical month for a specified Date.
Calculates a Date relative to the specified Date, as specified by a cron-like string.
Calculates a Date relative to the specified Date, as specified by a set of bit masks.
Returns a Date for the current date and time.
Returns the number of seconds past the minute for a given Date.
Creates a Date from a String representation.
Returns the current value of the server system clock.
Returns the elapsed time in milliseconds; useful for calculating timing.
Returns a copy of theDate with the date portion cleared.
Converts the time portion of a Date value from a Date to an Integer or from an Integer to a Date.
Converts the time portion of a Date value from a Date to a Real value
Returns the current Greenwich Mean time.
Returns the year from a given Date.
Returns Returns the number of clock tick since the start of the process.
The number of clock tick since the start of the process.
Returns a copy of the specified Date, clearing the time in the copy to 00:00:00. See Time().
The output from a test is:
Specifies a Date for which a time-cleared copy will be returned.
A new date whose time information is set to 00:00:00.
This simple example demonstrates how Date() can be used to isolate the date portion of a Date value:
Date rightNow = Date.Now() Date todaysDate = Date.Date( rightNow ) Echo( "The date is ", todaysDate )
The output from a test is:
The date is Thu Aug 06 00:00:00 1998
Converts the date portion of a Date value to or from an Integer number of days relative to October 15, 1582 (the start of the Gregorian Calendar). To convert the time portion of a Date value, see TimeInteger().
If nDays is not specified, theDate is converted to an Integer number of days relative to October 15, 1582. Otherwise, if nDays is specified, the time portion of theDate will fill in the resulting Date converted from nDays.
An Integer number of days since October 15, 1582, which, if specified, is converted to the date portion of a new Date value.
If nDays is not specified, an Integer conversion of the date portion of theDate into a number of days relative to October 15, 1582. Otherwise, it returns a new Date value converted from nDays and the time portion of theDate.
Note that negative integers are handled as well, referring to a given number of days before October 15, 1582.
This example uses DateInteger() to calculate a relative date:
Echo( "Today is ", Date.Now() ) Echo( "Five days from now is ", calculateLaterDate( Date.Now(), 5 ) ) function Date CalculateLaterDate( Date theDate, Integer moreDays ) Integer dateDays = Date.DateInteger( theDate ) Integer laterDays = dateDays + moreDays Date laterDate = Date.DateInteger( theDate, laterDays ) return laterDate end
The output of this example is:
Today is Tue Aug 11 10:44:49 1998 Five days from now is Sun Aug 16 10:44:49 1998
Converts a Date to a List with six individual date elements. See ListToDate().
The result from one test is:
Specifies a Date to convert to a List.
A List containing the following integer elements:
This example uses the DateToList function which converts the Date to the List:
Date rightNow = Date.Now() List dateList = Date.DateToList( rightNow ) String hours = Str.String( dateList [ 4 ] ) String minutes = Str.String( dateList [ 5 ] ) Echo( 'It is ' + hours + ' hours and ' + minutes + ' minutes past midnight.' )
The result from one test is:
It is 11 hours and 51 minutes past midnight.
Converts a Date to a String. The optional format String allows for a high degree of customization in the resulting String representation. See StringToDate().
Specifies a Date to be converted.
Specifies an String indicating how the resulting String should be formatted. It can contain both text, and any of the following format characters:
| Value | Description |
|---|---|
| %% | A percentage sign |
| %a | The three-character abbreviated weekday name (e.g., Mon, Tue, etc.) |
| %b | The three-character abbreviated month name (e.g., Jan, Feb, etc.) |
| %d | The two-digit day of the month, from 01 to 31 (e.g., 01-31) |
| %j | The three-digit day of year, from 001 through 366 |
| %m | The two-digit month (e.g., 01-12) |
| %p | AM or PM |
| %w | The 1-digit weekday, from 1 through 7, where 1= Sunday |
| %y | The two-digit year (e.g., 93) |
| %A | The full weekday name (e.g., Monday) |
| %B | The full month name (e.g., January) |
| %H | The two-digit hour on a 24-hour clock, from 00 to 23 |
| %I | The two-digit hour, from 01 through 12 |
| %M | The minutes past the hour, from 00 to 59 |
| %S | The seconds past the minute, from 00 to 59 |
| %L | The three-digit milliseconds, from 000 to 999 |
| %Y | The year, including the century (e.g., 1993) |
| %P | AD or BC |
If a valid Date is specified, a String representation of the Date is returned, 0 otherwise. If no format String is specified, the default format String is used, namely "%a %b %d %H:%M:%S %Y".
This example uses DateToString() to convert a Date to a custom String representation:
Date rightNow = Date.Now() Echo( Date.DateToString( rightNow, "It is now %H:%M on %A, %B %d." ) )
The output of this example is:
It is now 10:51 on Tuesday, August 11.
Returns the day of the month for a specified Date.
Specifies a Date for which the day of the month is returned.
An Integer, from 1 to 31, representing the day of the month for the given Date.
This example uses the Day() function to return the day of the month from the given Date:
Integer daysLeft Integer dayOfMonth = Date.Day( Date.Now() ) if dayOfMonth <= 15 daysLeft = ( 15 - dayOfMonth ) else daysLeft = ( 31 - dayOfMonth ) end Echo( "There are ", daysLeft, " days til payday!" )
The output of this example is:
There are 4 days til payday!
Returns the day of the week for a specified Date.
Specifies a Date for which the day of the week is returned.
An Integer, from 1 to 7, representing the day of the week, where 1 = Sunday.
This example uses the DayOfWeek() function to return the day of the week from a given Date:
Date rightNow = Date.Now() Integer dayOfWeek = Date.DayOfWeek( rightNow ) String todayString = Date.DateToString( rightNow, "%A" ) if ( dayOfWeek == 0 || dayOfWeek == 7 ) Echo( todayString, " is the weekend!" ) else Echo( todayString, " is a weekday." ) end
The output of this example is:
Tuesday is a weekday.
Returns the day of the year for a specified Date.
Specifies a Date for which the day of the year is returned.
An Integer, from 1 to 366, representing the number of days since January 1, where January 1 = 1.
This example uses the DateOfYear() function to return the day of the year from a given Date:
Integer dayOfYear = Date.DayOfYear( Date.Now() ) Date taxDate = Date.StringToDate( "April 15", "%B %d" ) Integer tilTaxes = Date.DayOfYear( taxDate ) - dayOfYear if tilTaxes < 0 tilTaxes = ( tilTaxes + 365 ) end Echo( "Taxes are due in only ", tilTaxes, " days!" )
The output of this example is:
Taxes are due in only 247 days!
Returns the number of hours past midnight for a specified Date.
Specifies a Date for which the number of hours past midnight is returned.
An Integer, from 0 to 23, representing the number of hours past midnight for the given Date.
The value returned is not rounded and represents the number of whole hours that have passed. For instance, Date.Hour() on a Date with a time of 4:59 PM would return 16.
Converts a List of numerical date elements to a new Date.
Specifies a List to convert to a Date.
It must contain the following Integer elements:
| Value | Description |
|---|---|
| 1 | year |
| 2 | month (integer from 1 to 12; January = 1) |
| 3 | day of the month (integer from 1 to 31) |
| 4 | hours since midnight (integer from 0 to 23) |
| 5 | minutes past the hour (integer from 0 to 59) |
| 6 | seconds past the minute (integer from 0 to 59) |
A Date if the elements in the given List specify valid values (i.e., not out of the specified range), Undefined otherwise.
This example uses the ListToDate function which converts the List to Date:
List dateList = { 1976, 7, 4, 0, 0, 0 } Date USDate = Date.ListToDate( dateList ) String stringDate = Date.DateToString( USDate, "%B %d, %Y" ) Echo( "Independence day for the US was " + stringDate + "." )
The output of this example is:
Independence day for the US was July 04, 1976.
Returns an Integer elapsed time in microseconds. MicroTick() is most often used for timing operations, possibly for system logging or performance evaluation. See Tick() and Systime().
For legacy reasons, the time returned is a 32-bit value, which means that MicroTick()'s value will roll over every 2147 seconds, or approximately 36 minutes. Any code using MicroTick() should be prepared for potential roll-overs.
An Integer elapsed time in microseconds.
This function is most often used to compare two elapsed time values, allowing a relatively fine granularity of timing between Date.MicroTick() calls to be determined.
This example uses MicroTick() for simple performance timing:
Integer i Integer start = Date.MicroTick() for ( i = 0; i < 100000; i += 1 ) end Integer endTime = Date.MicroTick() Integer duration = endTime > start ? endTime - start : endTime + (1 << 31) - start Echo( "It took ", duration, "µs to count to a hundred thousand in Oscript." )
The output of this example is:
It took 250790µs to count to a hundred thousand in Oscript.
Returns the number of minutes past the hour from a given Date.
Specifies a Date for which the minute past the hour is returned.
An Integer, from 0 to 59, representing the number of minutes past the hour for the specified Date.
Returns the index of the month for a specified Date.
Specifies a Date for which the month is returned.
An Integer, from 1 to 12, representing the month index, where January = 1.
This example uses Month() to return the index of the month:
Integer month = Date.Month( Date.Now() ) Integer seasonIndex = ( month / 3 ) + 1 List seasons = { "winter", "spring", "summer", "fall" } String monthString = Date.DateToString( Date.Now(), "%B" ) Echo( monthString, " is in ", seasons[ seasonIndex ], "." )
The output of this example is:
August is in summer.
Calculates a relative date from a Date based on a cron-like string. The crontabStr is similar to the a standard UN#X crontab string.
This method works like NextTime().
The initial date.
It is similar to the a standard UN#X crontab string. It consists of 5 fields separated by spaces or tabs of integer patterns that specify the following:
Each of these patterns may be either an asterisk (meaning all legal values) or a list of elements separated by commas. An element is either a number or two numbers separated by a minus sign (meaning an inclusive range).
Unlike the UN#X crontab, we only use a 5 minute resolution. So minute values that are not increments of 5 will be rounded down to the previous increment of 5.
Returns the next date.
Calculates a relative date from a Date based on a set of relative time and date mask information. Note that this does no simply calculate a relative date based on integer offsets. Instead, the use of masks allows certain information in the Date to be preserved, while other information can be set to vary at a certain granularity. For simply calculating relative dates, see DateInteger() and TimeInteger().
The initial date.
Specifies minutes of hour mask using bits (0-11), 5 min. resolution.
Specifies hours of day mask using bits (0-23).
Specifies days of week mask using bits (0-6) or (0-31).
Specifies months of year mask using bits (0-11). If this parameter is set then DaysOfWeek parameter must utilize mask using (0-31).
Returns the next date based upon the set of masks.
This example uses NextTime() to calculate relative dates:
Integer i Integer allDays = 1 Integer allHours = 1 << ( 24 - 1 ) Integer allMinutes = 1 << ( 1 - 1 ) Integer allMonths = 0 Date d = Date.Now() // The output is the next four Sundays. for i = 1 to 4 echo( d = Date.NextTime( d, allMinutes, allHours, allDays, allMonths ) ) end
The output from a test is:
Sun Aug 16 23:00:00 1998 Sun Aug 23 23:00:00 1998 Sun Aug 30 23:00:00 1998 Sun Sep 06 23:00:00 1998
Returns the current date and time.
A Date representing the current server system date and time, if successful.
Now() is the simple and oft-used function for querying the current date and time, as seen in this example:
Echo( "The current date and time is ", Date.Now() )
The output of this example is:
The current date and time is Wed Aug 12 00:55:38 1998
Returns the number of seconds past the minute for a given Date.
Specifies a Date for which the number of seconds past the minute is returned..
An Integer, from 0 to 59, representing the number of seconds past the minute for the given Date.
Converts a String representation of a Date to a Date, using a format string to specify the translation. See DateToString().
Specifies a String to be converted.
Specifies a String indicating how to interpret theString. It can contain both text and any of the following format characters:
| Value | Description |
|---|---|
| %% | A percentage sign |
| %b | The three-character abbreviated month name (e.g., Jan, Feb, etc.) |
| %d | The two-digit day of the month, from 01 to 31 (e.g., 01-31) |
| %m | The two-digit month (e.g., 01-12) |
| %p | AM or PM |
| %y | The two-digit year (e.g., 93) |
| %B | The full month name (e.g., January) |
| %H | The two-digit hour on a 24-hour clock, from 00 to 23 |
| %I | The two-digit hour, from 01 through 12 |
| %M | The minutes past the hour, from 00 to 59 |
| %S | The seconds past the minute, from 00 to 59 |
| %L | The three-digit milliseconds, from 000 to 999 |
| %Y | The year, including the century (e.g., 1993) |
| %P | AD or BC |
A Date if the given arguments specify a valid Date and format, otherwise Undefined.
This example uses the DateToString function which converts the String to Date:
Date theDate String dateString = "January 05, 1993" theDate = Date.StringToDate( dateString, "%B %d, %Y" )
Returns the current value of the server system clock, timed in seconds.
An Integer indicating the current value of the server system clock, in seconds.
This function is most often used to compare two system clock values to calculate timing in seconds. See Tick().
Returns an Integer elapsed time in milliseconds. Tick() is most often used for timing operations, possibly for system logging or performance evaluation. See Systime().
An Integer elapsed time in milliseconds.
This function is most often used to compare two elapsed time values, allowing a relatively fine granularity of timing between Date.Tick() calls to be determined.
This example uses Tick() for simple performance timing:
Integer i Integer start = Date.Tick() for ( i = 0; i < 100000; i += 1 ) end Echo( "It took ", Date.Tick() - start, "ms to count to a hundred thousand in Oscript." )
The output of this example is:
It took 246ms to count to a hundred thousand in Oscript.
Returns a copy of the specified Date, clearing the date portion of the copy. See Date().
Specifies a Date for which a date-cleared copy will be returned.
A Date where the time information remains unaltered and the Date information is set to the first representable day (January 1, 0001).
This example uses Time() to isolate the Time portion of a Date value:
Date theTime = Date.Time( Date.Now() ) String timeString = Date.DateToString( theTime, "%M minutes past %I %p" ) Echo( "The time is now " + timeString + "." ) The output of this example is: The time is now 48 minutes past 11 AM.
Converts the time portion of a Date value to or from an Integer number of seconds since midnight. To convert the date portion of a Date value, see DateInteger().
If nSeconds is not specified, the time portion of theDate is converted to an Integer number of seconds since midnight. Otherwise, if nSeconds is specified, a new Date value is returned with the date portion taken from theDate and time from nSeconds.
An Integer number of seconds since midnight, which, if specified, is converted to the time portion of a new Date value.
If nSeconds is not specified, an Integer conversion of the time portion of theDate into a number seconds since midnight. Otherwise, it returns a new Date value converted from nSeconds and the date portion of theDate.
This example uses TimeInteger() to convert the time portion a Date value into an Integer number of seconds:
Integer nSeconds = Date.TimeInteger( Date.Now() ) Integer lunchSeconds = ( 12 * 60 * 60 ) - nSeconds if ( lunchSeconds < 0 ) Echo( "It is ", -lunchSeconds / 60 / 60, " hours after lunch." ) else Echo( "It is ", lunchSeconds / 60 / 60, " hours before lunch." ) end
The output of this example for a random test time is:
It is 2 hours after lunch.
Converts the time portion of a Date value to or from an Real number of seconds since midnight.
If nSeconds is not specified, the time portion of theDate is converted to an Real number of seconds since midnight. Otherwise, if nSeconds is specified, a new Date value is returned with the date portion taken from theDate and time from nSeconds.
A Real number of seconds since midnight, which, if specified, is converted to the time portion of a new Date value.
If nSeconds is not specified, an Real conversion of the time portion of theDate into a number seconds since midnight. Otherwise, it returns a new Date value converted from nSeconds and the date portion of theDate.
This example uses TimeReal() to convert the time portion a Date value into an Real number of seconds:
Real nSeconds = Date.TimeReal( Date.Now() ) Real lunchSeconds = ( 12.5 * 60 * 60 ) - nSeconds if ( lunchSeconds < 0 ) Echo( "It is ", -lunchSeconds / 60 / 60, " hours after lunch." ) else Echo( "It is ", lunchSeconds / 60 / 60, " hours before lunch." ) end
The output of this example for a random test time is:
It is 1.660555555556 hours after lunch.
Returns the current Greenwich Mean time.
The current Greenwich Mean time.
Returns the year for a specified Date.
Specifies a Date for which the year is returned.
An Integer representing the year, where positive values represent years A.D., 0 represents 1 B.C., -1 represents 2 B.C., and so on.
This example uses Year() to return the year from a given Date:
Integer year = Date.Year( Date.Now() ) if ( year % 4 == 0 && year % 100 != 0 ) Echo( year, " is a leap year." ) else Echo( year, " is not a leap year." ) end
The output of this example is:
1998 is not a leap year.
| Copyright © 2023 OpenText Corporation. All rights reserved. |