A time string can be in any of the following formats:
YYYY-MM-DD
YYYY-MM-DD HH:MM
YYYY-MM-DD HH:MM:SS
YYYY-MM-DD HH:MM:SS.SSS
HH:MM
HH:MM:SS
HH:MM:SS.SSS
now
DDDD.DDDD
Formats 5 through 7 that specify only a time assume a date of 2000-01-01. Format 8 is converted into the current date and time, using Universal Coordinated Time (UTC). Format 9 is the Julian day number expressed as a floating point value.
Most of the Date and Time functions are derived from the uFormatDate function. The only difference is that the other Date and Time functions only return a special format or part of the date and they do not have the first format parameter. Therefore, uDate() is equivalent to uFormatDate("%Y-%m-%d").
Getting the current time
If no date is given, the time string now is assumed and the date is set to the current date and time.
uDate() // returns something like "2006-03-01"
uDate() is equivalent to uDate("now")
Getting a special date
IN.Date = uDate("2004-01-04 14:26:33") // returns the date part "2004-01-04"
Modifiers
The time string can be followed by zero or modifiers that alter the date or alter the interpretation of the date. The available modifiers are as follows:
NNN days
NNN hours
NNN minutes
NNN.NNNN seconds
NNN months (see #551 and [1163])
NNN years (see #551 and [1163])
Start of month
Start of year
Start of week (withdrawn -- will not be implemented)
Start of day
Weekday N (see #551 and [1163])
unixepoch
localtime
utc
Julian
Gregorian
The first size modifiers (1 through 6) simply add the specified amount of time to the date specified by the preceding time string. The “start of” modifiers (7 through 10) shift the date backwards to the beginning of the current month, year, or day. The “weekday” modifier advances the date forward to the next date where the weekday number is N: Sunday is 0, Monday is 1, and so on.
The “unixepoch” modifier (12) works only if it immediately follows a time string in the DDDD.DDDDD format. This modifier causes the DDDD.DDDDD to be interpreted not as a Julian day number as it normally would be, but as the number of seconds since 1970. This modifier allows unix-based times to be converted to Julian day numbers easily. The “localtime” modifier (13) adjusts the previous time string so that it displays the correct local time. “utc” undoes this.
The “Julian” modifier (14) assumes that the time string is a Gregorian date and converts the date into a Julian date: “Gregorian” undoes the work of “Julian.”
Date and time calculations
Compute the current date:
uDate('now')
Compute the last day of the current month.
uDate('now','start of month','+1 month','-1 day')
Compute the date and time given a UNIX timestamp 1092941466:
uDatetime(1092941466, 'unixepoch')
Compute the date and time given a UNIX timestamp 1092941466, and compensate for your local timezone.
uDatetime(1092941466, 'unixepoch', ‘localtime’)
Compute the current UNIX timestamp:
strftime('%s','now')
Compute the number of days since the Battle of Hastings:
uJuliandate('now') - uJuliandate('1066-10-14','gregorian')
Compute the number of seconds between two dates:
julianday('now')*86400 - julianday('2004-01-01 02:34:56')*86400
Compute the date of the first Tuesday in October (January + 9) for the current year:
date('now','start of year','+9 months','weekday 2')
Known limitations
The computation of local time depends heavily on the whim of local politicians and as a result, is difficult to get correct for all locales. In this implementation, the standard C library function localtime() is used to assist in the calculation of local time.
The localtime() C function normally only works for years between 1970 and 2037. For dates outside this range, you can attempt to map the year into an equivalent year within this range, do the calculation, then map the year back.
Date computations do not give correct results for dates before Julian day number 0 (-4713-11-24 12:00:00).
All internal computations assume the Gregorian calendar system. When you use the “julian” modifier, it does not convert the date into a real Julian calendar date; instead, it shifts the Gregorian calendar date to align it with the Julian calendar. This means that the “julian” modifier will not work right for dates that exist in the Julian calendar but which do not exist in the Gregorian calendar, for example, 1900-02-29.
Returns the year, month, and day from a date in the format YYYY-MM-DD.
Refer to the “Working with Dates and Times” section
for detailed information about the possible modifier arguments.
string uDate([modifiers])
String specifying a date or date calculation. The default is the now modifier.
To get the date part out of a timestamp:
uDate("now") // returns current date in the form "YYYY-MM-DD".
uDate("now", "start of year", "9 months", "weekday 2") //returns the date of the first Tuesday in October of this year.
Returns year, month, and day from a date in the format YYYY-MM-DD HH:MM:SS.
Please refer to the “Working with Dates and
Times” section for detailed information about the possible
modifier arguments.
string uDateTime([modifiers])
String specifying a date or date calculation. The default is the now modifier.
To get the datetime part out of a timestamp.
uDateTime("now") // returns current date in the form "YYYY-MM-DD HH:MM:SS"
uDateTime("now", "start of month", "1 months", "-1 day") // returns the date of the last day in this month
Returns the day number of the date specified.
Refer to the “Working with Dates and Times” section
for detailed information about the possible modifier arguments.
string uDay([modifiers])
String specifying a date or date calculation. The default is the now modifier.
To get the day number out of a timestamp:
uDay("now") // returns current day number
uDay("1969-03-13 10:22:23.231") // returns "13"
Returns the number of days since the beginning of the year.
string uDayOfYear([modifiers])
String specifying a date or date calculation. The default is the now modifier.
To get the day number out of a timestamp:
uDayOfYear("now") // returns how many day have already passed this year
uDayOfYear("1969-03-13 10:22:23.231") // returns "72"
Returns the hour of the date specified.
Please refer to the “Working with Dates and
Times” section for detailed information about the possible
modifier arguments.
string uHour([modifiers])
String specifying a date or date calculation. The default is the now modifier.
Get the hour from a date.
uHour("now") // returns current hour
uHour("1969-03-13 10:22:23.231") // returns "10"
Returns of the year in which a date occurs.
string uQuarter([modifiers])
String specifying a date or date calculation. The default is the now modifier.
To get the hour from a date:
uHour("now") // returns current quarter
uHour("1969-03-13 10:22:23.231") // returns "10"
Returns the week number as defined by ISO 8601.
The first week of a year is Number 01, which is defined as being the week which contains the first Thursday of the calendar year, which implies that it is also:
The first week which is mostly within the calendar year
The week containing January 4th
The week starting with the Monday nearest to January 1st
The last week of a year, Number 52 or 53, therefore is:
The week which contains the last Thursday of the Calendar year
The last week which is mostly within the Calendar year
The week containing December 28th
The week ending with the Sunday nearest to December 31st
Refer to the “Working with Dates and Times” section
for detailed information about the possible modifier arguments.
number uIsoWeek([modifiers])
String specifying a date or date calculation. The default is the now modifier.
To get the ISO week number from a date.
uIsoWeek("now") // returns current week number
Returns the number of days since noon in Greenwich on November 24, 4714 B.C. in the format DDDD.DDDD. For date and time calculation, the juliandate function is the best choice.
string uJuliandate([modifiers])
String specifying a date or date calculation. The default is the now modifier.
To convert a date into a numerical value for calculation.
uJuliandate(‘now’) // returns current date in the form "DDDD.DDDD"
To compute the number of seconds between two dates:
uJuliandate(‘now’)*86400 - julianday('2004-01-01 02:34:56')*86400
To compute the number of days since the Battle of Hastings:
uJuliandate(‘now’) - uJuliandate('1066-10-14','gregorian')
To compute the date and time given a UNIX timestamp 1092941466, and compensate for your local time zone:
uJuliandate(1092941466, 'unixepoch', 'localtime');
Returns the minute of the date specified.
string uMinute([modifiers])
String specifying a date or date calculation. The default is the now modifier.
Get the minute from a date
uMinute("now") // returns current minute
uMinute("1969-03-13 10:22:23.231") // returns "22"
Returns the month of the date specified.
string uMonth([modifiers])
String specifying a date or date calculation. The default is the now modifier.
To get the month from a date:
uMonth("now") // returns current month
uMonth("1969-03-13 10:22:23.231") // returns "03"
Returns the name of month of the date specified in the current locale language.
string uMonthName([modifiers])
String specifying a date or date calculation. The default is the now modifier.
To get the name of month from a date:
uMonthName("now") // returns current name of month
To set the locale to English:
uSetLocale("English")
uMonthName("1969-03-13 10:22:23.231") // returns "March"
To set the locale to German:
uSetLocale("German")
uMonthName("1969-03-13 10:22:23.231") // returns "März"
Returns the short form of the name of month of the date specified in the current locale language.
string uMonthNameShort([modifiers])
String specifying a date or date calculation. The default is the now modifier.
To get the short-form name of month from a date:
uMonthNameShort("now") // returns current name of month.
To set the locale to English:
uSetLocale("English")
uMonthNameShort("1969-03-13 10:22:23.231") // returns "Mar"
To set the locale to German:
uSetLocale("German")
uMonthNameShort("1969-03-13 10:22:23.231") // returns "Mär"
Returns the second of the date specified.
string uSeconds([modifiers])
String specifying a date or date calculation. The default is the now modifier.
To get the second from a date:
uSeconds("now") // returns current second
uSeconds("1969-03-13 10:22:23.231") // returns "23"
Returns the difference between two dates in milliseconds.
string uTimeDifMs(date1, date2)
The older date
The more recent date
uTimeDiffMs("18:34:20”, “18:34:21”) // returns 1000
uTimeDiffMs("18:34:20”, “18:34:21.200”) // returns 1200
Returns the week of the date specified.
Please refer to the “Working with Dates and
Times” section for detailed information about the possible
modifier arguments.
string uWeek([modifiers])
String specifying a date or date calculation. The default is the now modifier.
To get the week from a date:
uWeek("now") // returns current week
uWeek("1969-03-13 10:22:23.231") // returns "10"
Returns the week of the date specified. The returned values are from 0 (=sunday) to 6.
Refer to the “Working with Dates and Times” section
for detailed information about the possible modifier arguments.
string uWeekday([modifiers])
String specifying a date or date calculation. The default is the now modifier.
Get the weekday from a date
uWeekday("now") // returns current weekday number
uWeekday("1969-03-13 10:22:23.231") // returns "4" for Thursday
Returns the week name of the date specified in the current locale language.
Refer to the “Working with Dates and Times” section
for detailed information about the possible modifier arguments.
string uWeekdayName([modifiers])
String specifying a date or date calculation. The default is the now modifier.
To get the weekday name from a date:
uWeekdayName("now") // returns current weekname
To set the locale to English:
uSetLocale("English")
uWeekdayName("1969-03-13 10:22:23.231") // returns "Thursday"
To set the locale to German:
uSetLocale("German")
uWeekdayName("1969-03-13 10:22:23.231") // returns "Donnerstag"
Returns the short form of the weekname of the date specified in the current locale language.
Refer to the “Working with Dates and Times” section
for detailed information about the possible modifier arguments.
string uWeekdayNameShort([modifiers])
String specifying a date or date calculation. The default is the now modifier.
To get the weekday name from a date:
uWeekdayNameShort("now") // returns current weekname
To set the locale to English:
uSetLocale("English")
uWeekdayNameShort("1969-03-13 10:22:23.231") // returns "Thu"
To set the locale to German:
uSetLocale("German")
uWeekdayNameShort("1969-03-13 10:22:23.231") // returns "Don"
Returns the year of the date specified.
string uYear([modifiers])
String specifying a date or date calculation. The default is the now modifier.
Get the year from a date
uYear("now") // returns current year
uYear("1969-03-13 10:22:23.231") // returns "1969"
