Date and time functions

You can use the date and time functions to perform various operations on dates and times in the Transformer stage.

Functions that specify dates, times, or timestamps in the arguments use strings with specific formats:

For a date, the format is %yyyy-%mm-%dd
For a time, the format is %hh:%nn:%ss. If extended to include microseconds, the format is %hh:%nn:%ss.x where x gives the number of decimal places seconds is given to.
For a timestamp, the format is %yyyy-%mm-%dd %hh:%nn:%ss. If extended to include microseconds, the format is %yyyy-%mm-%dd %hh:%nn:%ss.x, where x gives the number of decimal places seconds is given to.

Functions that have days of week in the argument take a string specifying the day of the week. The day is specified as a three-letter abbreviation, or the full name. For example, the strings "thu" and "thursday" are both valid.

The following functions are in the Date & Time category of the expression editor. Square brackets indicate an argument is optional. The examples show the function as it appears in a Derivation field in the Transformer stage.

CurrentDate

Returns the date that the job runs in date format.

Input: -
Output: date
Examples. Use this function to add a new column containing the date to the data output by the Transformer stage:
```
CurrentDate()
```

CurrentTime

Returns the time at which the job runs in time format.

Input: -
Output: time
Examples. Use this function to add a new column containing the time to the data output by the Transformer stage:
```
CurrentTime()
```

CurrentTimeMS

Returns the time at which the job runs in time format, the time includes microseconds.

Input: -
Output: time
Examples. Use this function to add a new column containing the time to the data output by the Transformer stage. You must set the Extended field in the column metadata to Microseconds to contain the full time:
```
CurrentTimeMS()
```

CurrentTimestamp

Returns a timestamp giving the date and time that the job runs in timestamp format.

Input: -
Output: timestamp
Examples. Use this function to add a new column containing the timestamp to the data output by the Transformer stage:
```
CurrentTimestamp()
```

CurrentTimestampMS

Returns a timestamp giving the date and time that the job runs in timestamp format, the time part includes microseconds.

Input: -
Output: timestamp
Examples. Use this function to add a new column containing the timestamp to the data output by the Transformer stage. You must set the Extended field in the column metadata to Microseconds to contain the full timestamp.
```
CurrentTimestampMS()
```

DateFromDaysSince

Returns a date by adding an integer to a baseline date. The integer can be negative to return a date that is earlier than the base date.

Input: number (int32), [baseline_date (date)]
Output: date
Examples. If mylink.myintcol contains the integer 18250, and mylink.mydatecol contains the date 1958–08–18, then the three following functions are equivalent, and return the date 2008–08–05:
```
DateFromDaysSince(18250,"1958-08-18")
DateFromDaysSince(mylink.myintcol,"1958-08-18")
DateFromDaysSince(mylink.myintcol,mylink.mydatecol)
```
If mylink.mynegintcol contains the integer -1, and mylink.mydatecol contains the date 1958–08–18, then the following three functions are equivalent, and return the date 1958–08–17:
```
DateFromDaysSince(-1,"1958-08-18")
DateFromDaysSince(mylink.mynegintcol,"1958-08-18")
DateFromDaysSince(mylink.mynegintcol,mylink.mydatecol)
```

DateFromComponents

Returns a date from the given years, months, and day of month given as three separate values.

Input: years (int32), months (int32), dayofmonth (int32)
Output: date
Examples. If mylink.yearcol contains the value 2010, mylink.monthcol contains the value 12, and mylink.dayofmonthcol contains the value 2, then the two following functions are equivalent, and return the date 2010–12–02.
```
DateFromComponents(2010, 12, 2)
DateFromComponents(mylink.yearcol, mylink.monthcol, mylink.dayofmonthcol)
```

DateFromJulianDay

Returns a date from the given julian day.

Input: julianday (uint32)
Output: date
Examples. If mylink.myjulcol contains the value 2454614, then the two following functions are equivalent, and return the date 2008–05–27.
```
DateFromJulianDay(2454614)
DateFromJulianDay(mylink.myjulcol)
```

DateOffsetByComponents

Returns the given date, with offsets applied from the given year offset, month offset, and day of month offset given as three separate values. The offset values can each be positive, zero, or negative.

Input: basedate (date), year_offset (int32), month_offset (int32), dayofmonth_offset (int32)
Output: date
Examples. If mylink.basedate contains 2011-08-18 and mylink.yearos contains the value 2, mylink.monthos contains the value 0, and mylink.dayofmonthosol contains the value 0, then the two following functions are equivalent, and return the date 2013–08–18.
```
DateOffsetByComponents("2011-08-18", 2, 0, 0)
DateOffsetByComponents(mylink.basedate, mylink.yearos, mylink.monthos, 
mylink.dayofmonthos)
```
If mylink.basedate contains 2011-08-18 and mylink.yearos contains the value -2, mylink.monthos contains the value 0, and mylink.dayofmonthosol contains the value 0, then the two following functions are equivalent, and return the date 2009–08–18.
```
DateOffsetByComponents("2011-08-18", -2, 0, 0)
DateOffsetByComponents(mylink.basedate, mylink.yearos, mylink.monthos, 
mylink.dayofmonthos)
```

DaysSinceFromDate

Returns the number of days from source date to the given date.

Input: given_date, source_date
Output: days_since (int32)
Examples. If mylink.mysourcedate contains the date 1958–08–18 and mylink.mygivendate contains the date 2008–08–18, then the two following functions are equivalent, and return the integer value 18263.
```
DaysSinceFromDate(mylink.mygivendate, mylink.mysourcedate)
DaysSinceFromDate("2008-08-18","1958-08-18")
```

DaysInMonth

Returns the number of days in the month in the given basedate.

Input: basedate (date)
Output: daysinmonth (int32)
Examples. If mylink.mysourcedate contains the date 1958–08–18, then the two following functions are equivalent, and return the integer value 31.
```
DaysInMonth(mylink.mysourcedate)
DaysInMonth("1958-08-18")
```

DaysInYear

Returns the number of days in the year in the given basedate.

Input: basedate (date)
Output: daysinyearh (int32)
Examples. If mylink.mysourcedate contains the date 2012–08–18, then the two following functions are equivalent, and return the integer value 366.
```
DaysInYear(mylink.mysourcedate)
DaysInYear("2012-08-18")
```
If mylink.mysourcedate contains the date 2011–08–18, then the two following functions are equivalent, and return the integer value 365.
```
DaysInYear(mylink.mysourcedate)
DaysInYear("2011-08-18")
```

DateOffsetByDays

Returns the given date, offset by the given number of days. The offset value can be positive, zero, or negative.

Input: basedate (date), dayoffset (int32)
Output: date
Examples. If mylink.basedate contains 2011-08-18 and mylink.dayoffset contains the value 2, then the two following functions are equivalent, and return the date 2011–08–20.
```
DateOffsetByDays("2011-08-18", 2)
DateOffsetByDays(mylink.basedate, mylink.dayoffset)
```
If mylink.basedate contains 2011-08-18 and mylink.dayoffset contains the value -31, then the two following functions are equivalent, and return the date 2011–07–18.
```
DateOffsetByDays("2011-08-18", -31)
DateOffsetByDays(mylink.basedate, mylink.dayoffset)
```

HoursFromTime

Returns the hour portion of a time.

Input: time
Output: hours (int8)
Examples. If mylink.mytime contains the time 22:30:00, then the following two functions are equivalent, and return the integer value 22.
```
HoursFromTime(mylink.mytime)
HoursFromTime("22:30:00")
```

JulianDayFromDate

Returns a julian day from the given date.

Input: date
Output: julianday (int32)
Examples. If mylink.mydate contains the date 2008–05–27, then the two following functions are equivalent, and return the value 2454614.
```
JulianDayFromDate("2008–05–27")
JulianDayFromDate(mylink.mydate)
```

MicroSecondsFromTime

Returns the microsecond portion of a time.

Input: time
Output: microseconds (int32)
Examples. If mylink.mytime contains the time 22:30:00.32, then the following function returns the value 320000:
```
MicroSecondsFromTime(mylink.mytime)
```

MidnightSecondsFromTime

Returns the number of seconds from midnight to the given time.

Input: time
Output: seconds (int8)
Examples. If mylink.mytime contains the time 00:30:52, then the two following functions are equivalent, and return the value 1852:
```
MidnightSecondsFromTime("00:30:52")
MidnightSecondsFromTime(mylink.mytime)
```

MinutesFromTime

Returns the minute portion of a time.

Input: time
Output: minutes (int8)
Examples. If mylink.mytime contains the time 22:30:52, then the two following functions are equivalent, and return the value 30:
```
MinutesFromTime("22:30:52")
MinutesFromTime(mylink.mytime)
```

MonthDayFromDate

Returns the day of the month from the given date.

Input: date
Output: day (int8)
Examples. If mylink.mydate contains the date 2008-08-18, then the two following functions are equivalent, and return the value 18:
```
MonthDayFromDate("2008-08-18")
MonthDayFromDate(mylink.mydate)
```

MonthFromDate

Returns the month number from the given date.

Input: date
Output: month_number (int8)
Examples. If mylink.mydate contains the date 2008-08-18, then the two following functions are equivalent, and return the value 8:
```
MonthFromDate("2008-08-18")
MonthDayDate(mylink.mydate)
```

NextWeekdayFromDate

Returns the date of the specified day of the week soonest after the source date. The day of the week is specified as the full name, for example, thursday, or a three-letter abbreviation, for example, thu.

Input: sourcedate (date), day_of_week (string)
Output: date
Examples. If mylink.mysourcedate contains the date 2008-08-18, then the two following functions are equivalent, and return the value 2008–08–21:
```
NextWeekdayFromDate("2008-08-18", "thursday")
NextWeekdayFromDate(mylink.mysourcedate, "thu")
```

NthWeekdayFromDate

Returns the date of the specified day of the week offset by the specified number of weeks from the source date. The day of the week is specified as the full name, for example, thursday, or a three-letter abbreviation, for example, thu. The offset can be positive, negative, or zero.

Input: basedate (date), day_of_week (string), week_offset (int32)
Output: date
Examples. If mylink.mydate contains the date 2009-08-18, then the two following functions are equivalent, and return the value 2009–08–20:
```
NthWeekdayFromDate("2009-08-18", "thursday", 1)
NthWeekdayFromDate(mylink.mydate, "thu", 1)
```
The first occurrence of Thursday is returned. In the proceeding example, the Thursday occurs in the same week as the date 2009-08-18. The date 2009-08-18 is a Tuesday.
If mylink.mydate contains the date 2009-08-18, then the two following functions are equivalent, and return the value 2009–08–06:
```
NthWeekdayFromDate("2009-08-18", "thursday", -2)
NthWeekdayFromDate(mylink.mydate, "thu", -2)
```
The occurrence of Thursday, that is two Thursdays past, is returned.

PreviousWeekdayFromDate

Returns the date of the specified day of the week most recent before the source date. The day of the week is specified as the full name, for example, thursday, or a three-letter abbreviation, for example, thu.

Input: sourcedate, day_of_week (string)
Output: date
Examples. If mylink.mysourcedate contains the date 2008-08-18, then the two following functions are equivalent, and return the value 2008–08–14:
```
PreviousWeekdayFromDate("2008-08-18", "thursday")
PreviousWeekdayFromDate(mylink.mysourcedate, "thu")
```

SecondsFromTime

Returns the seconds portion of a time.

Input: time
Output: seconds (dfloat)
Examples. If mylink.mytime contains the time 22:30:52, then the two following functions are equivalent, and return the value 52:
```
SecondsFromTime("22:30:52")
SecondsFromTime(mylink.mytime)
```

SecondsSinceFromTimestamp

Returns the number of seconds between two timestamps.

Input: timestamp, timestamp_base
Output: seconds (dfloat)
Examples. If mylink.mytimestamp contains the timestamp 2008–08–18 22:30:52, and mylink.mytimestamp_base contains the timestamp 2008–08–19 22:30:52, then the two following functions are equivalent, and return the value -86400:
```
SecondsSinceFromTimestamp("2008–08–18 22:30:52","2008–08–19 22:30:52")
SecondsSinceFromTimestamp(mylink.mytimestamp, mylink.mytimestamp_base)
```

TimeDate

Returns the system time and date as a formatted string.

Input: -
Output: system time and date (string)
Examples. If the job was run at 4.21 pm on June 20th 2008, then the following function returns the string "16:21:48 20 Jun 2008".
```
TimeDate()
```

TimeFromComponents

Returns a time from the given hours, minutes, seconds and microseconds given as four separate values.

Input: hours (int32), minutes (int32), seconds (int32), microseconds (int32)
Output: time
Examples. If mylink.hourcol contains the value 10, mylink.mincol contains the value 12, mylink.seccol contains the value 2, and mylink.mseccol contains 0, then the two following functions are equivalent, and return the time 10:12:02.0:
```
TimeFromComponents(10, 12, 2, 0)
TimeFromComponents(mylink.hourcol, mylink.mincol, mylink.seccol, mylink.mseccol)
```

TimeFromMidnightSeconds

Returns the time given the number of seconds since midnight.

Input: seconds (dfloat)
Output: time
Examples. If mylink.mymidnightseconds contains the value 240, then the two following functions are equivalent, and return the value 00:04:00:
```
TimeFromMidnightSeconds("240")
TimeFromMidnightSeconds(mylink.mymidnightseconds)
```

TimeOffsetByComponents

Returns the given time, with offsets applied from the given hour offset, minute offset, and second offset, each given as separate values. The seconds offset can include partial seconds.

Input: basetime (time), hour_offset (int32), minute_offset (int32), second_offset (dfloat)
Output: time
Examples. If mylink.basetime contains 14:05:29 and mylink.houros contains the value 2, mylink.minos contains the value 0, mylink.secos contains the value 20, then the two following functions are equivalent, and return the time 16:05:49.
```
TimeOffsetByComponents("14:05:29", 2, 0, 20)
TimeOffsetByComponents(mylink.basetime, mylink.houros, mylink.minos, mylink.secos)
```

TimeOffsetBySeconds

Returns the given time, with offsets applied from the given seconds offset. The seconds offset can include partial seconds.

Input: basetime (time), second_offset (dfloat)
Output: time
Examples. If mylink.basetime contains 14:05:29.30 and mylink.secos contains the value 2.5, then the two following functions are equivalent, and return the time 14:05:31.80:
```
TimeOffsetByComponents("14:05:29.30", 2.5)
TimeOffsetByComponents(mylink.basetime, mylink.secos)
```

TimestampFromDateTime

Returns a timestamp form the given date and time.

Input: date time
Output: timestamp
Examples. If mylink.mydate contains the date 2008–08–18 and mylink.mytime contains the time 22:30:52, then the two following functions are equivalent, and return the timestamp 2008–08–18 22:30:52:
```
TimestampFromDateTime("2008–08–18","22:30:52")
TimestampFromDateTime(mylink.mydate,mylink.mytime)
```

TimestampFromSecondsSince

Returns a timestamp derived from the number of seconds from the base timestamp.

Input: seconds (dfloat), [base_timestamp]
Output: timestamp
Examples. If mylink.myseconds contains the value 2563 and mylink.timestamp_base contains the timestamp 2008–08–18 22:30:52, then the two following functions are equivalent, and return the timestamp 2008–08–18 23:13:35:
```
TimestampFromSecondsSince("2563","2008–08–18 22:30:52")
TimestampFromSecondsSince(mylink.myseconds,mylink.timestamp_base)
```

TimestampFromTimet

Returns a timestamp from the given UNIX time_t value.

Input: timet (int32)
Output: timestamp
Examples. If mylink.mytimet contains the value 1234567890, then the two following functions are equivalent, and return the timestamp 2009–02–13 23:31:30:
```
TimestampFromTimet("1234567890")
TimestampFromTimet(mylink.mytimet)
```

TimestampOffsetByComponents

Returns the given timestamp, with offsets applied from the given year offset, month offset, day offset, hour offset, minute offset, and second offset, each given as separate values. The seconds offset can include partial seconds.

Input: basetimestamp (timestamp), year_offset (int32), month_offset (int32), dayofmonth_offset (int32), hour_offset (int32), minute_offset (int32), second_offset (dfloat)
Output: timestamp
Examples. If mylink.basetimestamp contains 2009-08-18 14:05:29 and mylink.yearos contains 0, mylink.monthos contains the value 2, mylink.dayos contains the value -4, mylink.houros contains the value 2, mylink.minos contains the value 0, mylink.secos contains the value 20, then the two following functions are equivalent, and return the timestamp 2009-10-14 16:05:49.
```
TimestampOffsetByComponents("2009-08-18 14:05:29", 0, 2, -4, 2, 0, 20)
TimestampOffsetByComponents(mylink.basetimestamp, mylink.houros, 
mylink.minos, mylink.secos)
```

TimestampOffsetBySeconds

Returns the given timestamp, with offsets applied from the given seconds offset. The seconds offset can include partial seconds.

Input: basetimestamp (timestamp), second_offset (dfloat)
Output: timestamp
Examples. If mylink.basetimestamp contains 2009-08-18 14:05:29 and mylink.secos contains the value 32760, then the two following functions are equivalent, and return the timestamp 2009-08-18 23:11:29:
```
TimeOffsetBySeconds("2009-08-18 14:05:29", 32760)
TimeOffsetBySeconds
(mylink.basetimestamp, mylink.secos)
```

TimetFromTimestamp

Returns a UNIX time_t value from the given timestamp.

Input: timestamp
Output: timet (int32)
Examples. If mylink.mytimestamp contains the value 2009–02–13 23:31:30, then the two following functions are equivalent, and return the value 1234567890:
```
TimestampFromTimet("2009–02–13 23:31:30")
TimestampFromTimet(mylink.mytimestamp)
```

WeekdayFromDate

Returns the day number of the week from the given date. Origin_day optionally specifies the day regarded as the first in the week and is Sunday by default.

Input: date, [origin_day]
Output: day (int8)
Examples. If mylink.mydate contains the date 2008-08-18, then the two following functions are equivalent, and return the value 1:
```
WeekdayFromDate("2008-08-18")
WeekdayFromDate(mylink.mydate)
```
If mylink.mydate contains the date 2008-08-18, and mylink.origin_day contains saturday, then the two following functions are equivalent, and return the value 2:
```
WeekdayFromDate("2008-08-18","saturday")
WeekdayFromDate(mylink.mydate,mylink.origin_day)
```

YeardayFromDate

Returns the day number in the year from the given date.

Input: date
Output: day (int16)
Examples. If mylink.mydate contains the date 2008-08-18, then the two following functions are equivalent, and return the value 231:
```
YeardayFromDate("2008-08-18")
YeardayFromDate(mylink.mydate)
```

YearFromDate

Returns the year from the given date.

Input: date
Output: year (int16)
Examples. If mylink.mydate contains the date 2008-08-18, then the two following functions are equivalent, and return the value 2008:
```
YearFromDate("2008-08-18")
YearFromDate(mylink.mydate)
```

YearweekFromDate

Returns the week number in the year from the given date

Input: date
Output: week (int16)
Examples. If mylink.mydate contains the date 2008-08-18, then the two following functions are equivalent, and return the value 33:
```
YearweekFromDate("2008-08-18")
YearweekFromDate(mylink.mydate)
```