Most Date and Time functions are derived from the uFormatDate function. The only difference is that the other Date and Time functions return only 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").
A time string can be in any of these 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
Note Formats 5 – 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.
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")
uDate("2004-01-04 14:26:33") // returns the date part "2004-01-04"
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:
NNN days
NNN hours
NNN minutes
NNN.NNNN seconds
NNN months
NNN years
start of month
start of year
start of day
weekday N
unixepoch
localtime
utc
Modifiers 1 – 6 simply add the specified amount of time to the date specified by the preceding time string.
The “start of” modifiers (7 – 9) shift the date backward to the beginning of the current month, year, or day.
The “weekday” (10) 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 (11) 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 easily converted to Julian day numbers.
The localtime modifier (12) adjusts the previous time string so that it displays the correct local time. utc undoes this.
These examples show you some typical 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 time zone:
uDatetime(1092941466, 'unixepoch', 'localtime')
Compute the current UNIX timestamp:
uFormatDate ('%s','now')
Compute the number of seconds between two dates:
uJuliandate('now')*86400 - uJuliandate ('2004-01-01 02:34:56')*86400
Compute the date of the first Tuesday in October (January + 9) for the current year:
uDate('now','start of year','+9 months','weekday 2')
The computation of local time varies by locale. The standard C library function localtime() is used to assist in the calculation of local time. Also, the localtime() C function normally only works for years between 1970 and 2037. For dates outside this range, we 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.
This table lists all the date and time functions.
Function |
Description |
---|---|
Returns a year, month, and day from a date in the format YYYY-MM-DD |
|
Returns a year, month, and day from a date in the format YYYY-MM-DD HH.MM.SS |
|
Returns the day number of the date specified |
|
Returns the number of days since the beginning of the year |
|
Returns the hour of the date specified |
|
Returns the quarter of the year |
|
Returns the week number defined by ISO 8601 |
|
Returns the number of days since noon in Greenwich on November 24, 4714 B.C, in the format DDDD.DDDD |
|
Returns the minute of the date specified |
|
Returns the month of the name specified |
|
Returns the name of month of the date specified, in the current locale language |
|
Returns the short form of the name of month of the date specified, in the current locale language |
|
Returns the second of the date specified |
|
Returns the time part from a date in, the format HH.MM.SS |
|
Returns the difference between two dates, in milliseconds |
|
Returns the week of the date specified |
|
Returns the weekday of the date specified |
|
Returns the weekday name of the date specified, in the current locale language |
|
Returns the short form of the weekday name of the date specified in the current locale language |
|
Returns the year of the date specified |
Refer to “Date and Time” for detailed information about the possible modifier arguments.
Returns a year, month, and day from a date in the format YYYY-MM-DD
string uDate([modifiers])
List of strings specifying a date or date calculation. Default is the now modifier.
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 this year.
Returns a year, month, and day from a date in the format YYYY-MM-DD HH.MM.SS
string uDateTime([modifiers])
List of strings specifying a date or date calculation. Default is the now modifier.
Get the datetime part from 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
string uDay([modifiers])
List of strings specifying a date or date calculation. Default is the now modifier.
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])
List of strings specifying a date or date calculation. Default is the now modifier.
Get the day number out of a timestamp:
uDayOfYear("now") // returns how many days have already passed this year
uDayOfYear("1969-03-13 10:22:23.231") // returns "72"
Returns the hour of the date specified
string uHour([modifiers])
List of strings specifying a date or date calculation. Default is the now modifier.
uHour("now") // returns current hour
uHour("1969-03-13 10:22:23.231") // returns "10"
Returns the quarter of the year
string uQuarter([modifiers])
List of strings specifying a date or date calculation. Default is the now modifier.
uQuarter ("now") // returns current quarter
uQuarter ("2005-03-13 10:22:23.231") // returns "1"
Returns the week number defined by ISO 8601
The first week of a year is number 01, which is defined as being the week that contains the first Thursday of the calendar year, which implies that it is also:
The first week that 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 that contains the last Thursday of the calendar year
The last week that is mostly within the calendar year
The week containing December 28th
The week ending with the Sunday nearest to December 31st
number uIsoWeek([modifiers])
List of strings specifying a date or date calculation. Default is the now modifier.
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])
List of strings specifying a date or date calculation. Default is the now modifier.
Convert a date into a numerical value for calculation:
uJuliandate("now") // returns current date in the form "DDDD.DDDD"
Compute the number of seconds between two dates:
uJuliandate('now')*86400 - uJuliandate('2004-01-01 02:34:56')*86400
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])
List of strings specifying a date or date calculation. Default is the now modifier.
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])
List of strings specifying a date or date calculation. Default is the now modifier.
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])
List of strings specifying a date or date calculation. Default is the now modifier.
Get the name of month from a date:
uMonthName("now") // returns current name of month
Set the locale to English:
uSetLocale("English") uMonthName("1969-03-13 10:22:23.231") // returns "March"
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])
List of strings specifying a date or date calculation. Default is the now modifier.
Get the name of month from a date:
uMonthNameShort("now") // returns current name of month.
Set the locale to English:
uSetLocale("English") uMonthNameShort("1969-03-13 10:22:23.231") // returns "Mar"
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])
List of strings specifying a date or date calculation. Default is the now modifier.
uSeconds("now") // returns current second
uSeconds("1969-03-13 10:22:23.231") // returns "23"
Returns the time part from a date, in the format HH.MM.SS.
string uTime([modifiers])
List of strings specifying a date or date calculation. Default is the now modifier.
Get the time part from a timestamp:
uTime() // returns current UTC time
uTime("now","localtime") // returns current local time
Returns the difference between two dates, in milliseconds
string uTimeDiffMs(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
string uWeek([modifiers])
List of strings specifying a date or date calculation. Default is the now modifier.
uWeek("now") // returns current week
uWeek("1969-03-13 10:22:23.231") // returns "10"
Returns the weekday number of the date specified
string uWeekday([modifiers])
List of strings specifying a date or date calculation. Default is the now modifier.
uWeekday("now") // returns current weekday number
uWeekday("1969-03-13 10:22:23.231") // returns "4" for Thursday
Returns the weekday name of the date specified, in the current locale language
string uWeekdayName([modifiers]);
List of strings specifying a date or date calculation. Default is the now modifier.
uWeekdayName("now") // returns current weekday name
Set the locale to English:
uSetLocale("English") uWeekdayName("1969-03-13 10:22:23.231") // returns "Thursday"
Set the locale to German:
uSetLocale("German") uWeekdayName("1969-03-13 10:22:23.231") // returns "Donnerstag"
Returns the short form of the weekday name of the date specified, in the current locale language
string uWeekdayNameShort([modifiers])
List of strings specifying a date or date calculation. Default is the now modifier.
uWeekdayNameShort("now") // returns current weekday name
Set the locale to English:
uSetLocale("English") uWeekdayNameShort("1969-03-13 10:22:23.231") //returns "Thu"
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])
List of strings specifying a date or date calculation. Default is the now modifier.
uYear("now") // returns current year
uYear("1969-03-13 10:22:23.231") // returns "1969"