SBasic language reference::Date/time functions

Date/time functions:

Function IsDateTime(datetime) as Integer

Checks giving expression is a valid datetime object

Where datetime is some expression
Returns 1 if expression represent a valid DateTime, 0 otherwise.

Function Now As String

Returns current Date and Time

Returns Date and Time object (encoded in string) that represents current time and date.

Function Year(datetime) As Integer
Function Month(datetime) As Integer
Function Day(datetime) As Integer
Function Hour(datetime) As Integer
Function Minute(datetime) As Integer
Function Second(datetime) As Integer
Function Microsecond(datetime) As Integer

Extracts year,month,day,hour,minute or second from DateTime object and returns it

Where datetime is a DateTime object
Returns year,month,day,hour,minute or second number (as integer) if datetime represent a valid DateTime object. If datetime is not valid DateTime object then return value is -1.

Example:

date = Now Print "Now is :", Year(date), " year, ", Month(date)," month", Day(date)," day" Print "Time:", Hour(date), ":", Minute(date)

Function DayNoInMonth(datetime) As Integer
Function DayNoInWeek(datetime) As Integer
Function DayNoInYear(datetime) As Integer
Function DaysInMonth(datetime) As Integer
Function WeekNoInYear(datetime) As Integer

Extracts various information from DateTime object and returns it

Where datetime is a DateTime object
Returns various information (as integer number) if datetime represent a valid DateTime object. If datetime is not valid DateTime object then return value is -1.

Function RoundUpToNextMinute(datetime) As String

Round up a datetime object to next minute and returns it

Where datetime is a DateTime object
Returns rounded up datetime object (encoded in string) to next minute if datetime represent a valid DateTime object. If datetime is not valid DateTime object then return value is -1.

Function MakeDateTime(year,month,day,hour,minute,second) As String

Constructs and returns DateTime object from specified components

Where year,month,day,hour,minute,second is parts of Date and time object.
Returns valid DateTime object (encoded in string).

Function DateTimeToString(datetime, FormatString) As String

Converts DateTime object to custom formatted string and returns it

Where datetime is a DateTime object.
Where FormatString is format string which determines the format of the date and time.
Returns string containing formated date/time.

Many of the formatting commands use the system's locale settings for the date and time, for instance the characters used to separate components of the date and time and the ordering of day, month and year. The list of formatting commands below is divided into two sections, the first of which lists the commands which operate without reference to the locale's date and time settings and the second table lists the commands which do use these settings.

The following formatting commands do not honour the locale-specific system settings:

%% : Include a single '%' character in the string

%* : Abbreviate following item (the following item should not be preceded by a '%' character).

%C : Interpret the argument as the six digit microsecond component of the time. In its abbreviated form, ('%*C') this should be followed by an integer between zero and six - the integer indicates the number of digits to display.

%D : Interpret the argument as the two digit day number in the month. Abbreviation suppresses leading zero.

%E : Interpret the argument as the day name. Abbreviation is language-specific (e.g. English uses the first three letters).

%F : Use this command for locale-independent ordering of date components. This orders the following day/month/year component(s) (%D, %M, %Y for example) according to the order in which they are specified in the string. This removes the need to use %1 to %5 (described below).

%H : Interpret the argument as the one or two digit hour component of the time in 24 hour time format. Abbreviation suppresses leading zero. For locale-dependent hour formatting, use %J.

%I : Interpret the argument as the one or two digit hour component of the time in 12 hour time format. The leading zero is automatically suppressed so that abbreviation has no effect. For locale-dependent hour formatting, use %J.

%M : Interpret the argument as the one or two digit month number. Abbreviation suppresses leading zero.

%N : Interpret the argument as the month name. Abbreviation is language specific, e.g. English uses the first three letters only. When using locale-dependent formatting, (that is, %F has not previously been specified), specifying %N causes any subsequent occurrence of a month specifier in the string to insert the month as text rather than in numeric form. When using locale-independent formatting, specifying %N causes the month to be inserted as text at that position, but any subsequent occurrence of %M will cause the month to be inserted in numeric form.

%S : Interpret the argument as the one or two digit seconds component of the time. Abbreviation suppresses leading zero.

%T : Interpret the argument as the one or two digit minutes component of the time. Abbreviation suppresses leading zero.

%W : Interpret the argument as the one or two digit week number in year. Abbreviation suppresses leading zero.

%X : Interpret the argument as the date suffix. Cannot be abbreviated. When using locale-dependent formatting (that is, %F has not previously been specified), %X causes all further occurrences of the day number to be displayed with the date suffix. When using locale-independent formatting, a date suffix will be inserted only after the occurrence of the day number which %X follows in the format string. Any further occurrence of %D without a following %X will insert the day number without a suffix.

%Y : Interpret the argument as the four digit year number. Abbreviation suppresses the first two digits.

%Z : Interpret the argument as the one, two or three digit day number in the year. Abbreviation suppresses leading zeros.

The following formatting commands do honour the locale-specific system settings:

%. : Interpret the argument as the decimal separator character (as set by TLocale::SetDecimalSeparator()). The decimal separator is used to separate seconds and microseconds, if present.

%: : Interpret the argument as one of the four time separator characters (as set by TLocale::SetTimeSeparator()). Must be followed by an integer between zero and three inclusive to indicate which time separator character is being referred to.

%/ : Interpret the argument as one of the four date separator characters (as set by TLocale::SetDateSeparator()). Must be followed by an integer between zero and three inclusive to indicate which date separator character is being referred to.

%1 : Interpret the argument as the first component of a three component date (i.e. day, month or year) where the order has been set by TLocale::SetDateFormat(). When the date format is EDateEuropean, this is the day, when EDateAmerican, the month, and when EDateJapanese, the year. For more information on this and the following four formatting commands, see the Notes section immediately below.

%2 : Interpret the argument as the second component of a three component date where the order has been set by TLocale::SetDateFormat(). When the date format is EDateEuropean, this is the month, when EDateAmerican, the day and when EDateJapanese, the month.

%3 : Interpret the argument as the third component of a three component date where the order has been set by TLocale::SetDateFormat(). When the date format is EDateEuropean, or EDateAmerican this is the year and when EDateJapanese, the day.

%4 : Interpret the argument as the first component of a two component date (day and month) where the order has been set by TLocale::SetDateFormat(). When the date format is EDateEuropean this is the day, and when EDateAmerican or EDateJapanese, the month.

%5 : Interpret the argument as the second component of a two component date (day and month) where the order has been set by TLocale::SetDateFormat(). When the date format is EDateEuropean this is the month, and when EDateAmerican or EDateJapanese, the day.

%A : Interpret the argument as "am" or "pm" text according to the current language and time of day. Unlike the %B formatting command (described below), %A disregards the locale's 12 or 24 hour clock setting, so that when used without an inserted + or - sign, am/pm text will always be displayed. Whether a space is inserted between the am/pm text and the time depends on the locale-specific settings. However, if abbreviated (%*A), no space is inserted, regardless of the locale's settings. The am/pm text appears before or after the time, according to the position of the %A, regardless of the locale-specific settings. For example, the following ordering of formatting commands causes am/pm text to be printed after the time: %H %T %S %A. Optionally, a minus or plus sign may be inserted between the "%" and the "A". This operates as follows: -

%-A causes am/pm text to be inserted into the descriptor only if the am/pm symbol position has been set in the locale to ELocaleBefore. Cannot be abbreviated using asterisk.

%+A causes am/pm text to be inserted into the descriptor only if the am/pm symbol position has been set in the locale to ELocaleAfter. Cannot be abbreviated using asterisk. For example, the following formatting commands will cause am/pm text to be displayed after the time if the am/pm position has been set in the locale to ELocaleAfter or before the time if ELocaleBefore: %-A %H %T %S %+A.

%B Interpret the argument as am or pm text according to the current language and time of day. Unlike the %A command, when using %B, am/pm text is displayed only if the clock setting in the locale is 12-hour. Whether a space is inserted between the am/pm text and the time depends on the locale-specific settings. However, if abbreviated (%*B), no space is inserted, regardless of the locale's settings. The am/pm text appears before or after the time, according to the location of the "%B", regardless of the locale-specific settings. For example, the following formatting commands cause am/pm text to be printed after the time: %H %T %S %B. Optionally, a minus or plus sign may be inserted between the "%" and the "B". This operates as follows: -

%-B causes am/pm text to be inserted into the descriptor only if using a 12 hour clock and the am/pm symbol position has been set in the locale to ELocaleBefore. Cannot be abbreviated using asterisk.

%+B causes am/pm text to be inserted into the descriptor only if using a 12 hour clock and the am/pm symbol position has been set in the locale to ELocaleAfter. Cannot be abbreviated using asterisk. For example, the following formatting commands cause am/pm text to be printed after the time if the am/pm position has been set in the locale to ELocaleAfter or before the time if ELocaleBefore: %-B %H %T %S %+B.

%J Interpret the argument as the hour component of the time in either 12 or 24 hour clock format depending on the locale's clock format setting. When the clock format has been set to 12 hour, leading zeros are automatically suppressed so that abbreviation has no effect. Abbreviation suppresses leading zero only when using a 24 hour clock.

Notes:

The %1, %2, %3, %4 and %5 formatting commands are used in conjunction with %D, %M and %Y to format the date locale-dependently. When formatting the date locale-dependently, the order of the day, month and year components within the string is determined by the order of the %1 to %5 formatting commands, not that of %D, %M, %Y.

When formatting the date locale-independently (that is, %F has been specified in the format string), the %1 to %5 formatting commands are not required, and should be omitted. In this case, the order of the date components is determined by the order of the %D, %M, %Y format commands within aFormat.

Up to four date separators and up to four time separators can be used to separate the components of a date or time. When formatting a numerical date consisting of the day, month and year or a time containing hours, minutes and seconds, all four separators should always be specified in the format command string. Usually, the leading and trailing separators should not be displayed. In this case, the first and fourth separators should still be specified, but should be represented by a null character.

The date format follows the pattern: -

DateSeparator[0] DateComponent1 DateSeparator[1] DateComponent2 DateSeparator[2] DateComponent3 DateSeparator[3]

where the ordering of date components is determined by the locale's date format setting.

The time format follows the pattern: -

TimeSeparator[0] Hours TimeSeparator[1] Minutes TimeSeparator[2] Seconds TimeSeparator[3]

If the time includes a microseconds component, the third separator should occur after the microseconds, and the seconds and microseconds should be separated by the decimal separator. When formatting a two component time, the following rules apply:

if the time consists of hours and minutes, the third time delimiter should be omitted

if the time consists of minutes and seconds, the second time delimiter should be omitted

Example:
The examples below demonstrate how to format a DateTime object which holds a date/time string, locale-dependently and independently.

The following code fragment is locale-dependent. It assumes the current date and time (datetime) is 2nd January 1997 23:59:59.999999, and uses the system default date and time settings for a UK locale, including the default date and time separators, a 12 hour clock, trailing am/pm text and assumes a point for the decimal separator;

datetime = Now FormatString = "%E%D%X%N%Y %1 %2 %3" str = DateTimeToString(datetime,FormatString) ' str contains "Thursday 02nd January 1997" - no abbreviation Print str FormatString = "%*E%*D%X%*N%*Y %1 %2 '%3" str = DateTimeToString(datetime,FormatString) ' str contains "Thu 2nd Jan '97" - everything abbreviated Print str FormatString = "%D%M%Y%/0%1%/1%2%/2%3%/3" str = DateTimeToString(datetime,FormatString) ' contains "02/01/1997" - no abbreviation; first and third ' date separators are both '\0' Print str FormatString = "%-B%:0%J%:1%T%:2%S%.%*C4%:3%+B" str = DateTimeToString(datetime,FormatString) ' str contains "11:59:59.9999 pm" - first and third time ' separators are both '\0'; locale dependent decimal separator ' separates seconds and microseconds Print str FormatString = "%-B%:0%J%:1%T%:2%S%:3%+B" str = DateTimeToString(datetime,FormatString) ' str contains "11:59:59 pm - as above, but no microseconds Print str

The following code demonstrates formatting two component dates and times.

datetime = Now FormatString = "%-B%:0%J%:1%T%:3%+B" str = DateTimeToString(datetime,FormatString) ' str contains "11:59 pm" - Two component time (hour:minute). ' Third time delimiter omitted as it separates minutes and seconds Print str FormatString = "%M%Y%/0%4%/1%5%/3" str = DateTimeToString(datetime,FormatString) ' contains "02/01" - Two component date (day/month). ' Third date delimiter omitted Print str

The following code demonstrates that the ordering of the %D %M %Y is irrelevant when using locale-dependent formatting. The ordering of the date components is determined by the order of the %1, %2, and %3 formatting commands.

datetime = Now FormatString = "%M%Y%D%/0%1%/1%2%/2%3%/3" str = DateTimeToString(datetime,FormatString) ' str contains 02/01/1997 Print str FormatString = "%Y%D%M%/0%1%/1%2%/2%3%/3" str = DateTimeToString(datetime,FormatString) ' str contains 02/01/1997 Print str FormatString = "%D%M%Y%/0%3%/1%1%/2%2%/3" str = DateTimeToString(datetime,FormatString) ' str contains 1997/02/01 Print str

However, when using locale-independent formatting, the %1, %2 and %3 are not required. The ordering of the date components is determined by the ordering of the %D, %M and %Y.

datetime = Now FormatString = "%F%/0%M%/1%Y%/2%D%/3" str = DateTimeToString(datetime,FormatString) ' str contains 01/1997/02 Print str