advertisement

The transforms in this category manipulate date values:

Transform Description
date Formats a date
dateAdd Adds days, months, or years to a date
dateDay Returns the day part of a date, a number from 1 to 31
dateGtoJ Converts a Gregorian date to a Julian date
dateJtoG Converts a Julian date to a Gregorian date
dateJNYD Specifies the Julian New Year's Day for subsequent conversions
dateModifier Returns the modifier word from a date, such as "bef", "circa", etc.
dateMonth Returns the month part of a date, a number from 1 to 12
dateMonthAbbr Returns the month part of a date converted to an abbreviated name, "Jan", "Feb", etc.
dateMonthName Returns the month part of a date converted to a name, "January", "February", etc.
dateYear Returns the year part of a date with an optional argument to add or substract years
dateSubtract Subtracts days, months, or years from a date
dayOfWeek Returns the day of the week for a Gregorian date

date:f1:f2:f3

Formats a date value according to one of the given format parameters, "f1", "f2", or "f3".

Field Values

The field value must be a date recognized by ORA when it standardizes field values.

Date Format Parameters

Format parameters use keywords to indicate where to insert parts of the date.

f1 is a required parameter. If it is missing, the date value will not be transformed. If the date value has a year, month, and day, ORA uses f1 to format the value.

f2 is an optional parameter. If it is missing, it defaults to the f1 value. If the date value has a year and month, but no day, ORA uses f2 to format the value.

f3 is an optional parameter. If it is missing, it defaults to the f2 value. If the date value has a year, but no month and day, ORA uses f3 to format the value.

Format Parameter Keywords

The format specification may include the following keywords. The keywords are case-sensitive, so you must use the keywords below exactly as they appear. You can combine the keywords in any sequence. Any text in the format that does not match one of the keywords will be included as-is in the result.

dd
Replaced by a two-digit day number in the range 01 to 31. For days less than 10, the result will have a leading zero.
d
Replaced by a one- or two-digit day number. For days less than 10, the result will not have a leading zero.
mm
Replaced by a two-digit month number in the range 01 to 12. For months less than 10, the result will have a leading zero.
m
Replaced by a one- or two-digit month number. For months less than 10, the result will not have a leading zero.
Mmmm
Replaced by a mixed-case month name, "January", "February", etc.
Mmm
Replaced by a mixed-case month abbreviation, "Jan", "Feb", etc.
MMMM
Replaced by an upper-case month name, "JANUARY", "FEBRUARY", etc.
MMM
Replaced by an upper-case month abbreviation, "JAN", "FEB", etc.
mmmm
Replaced by an lower-case month name, "january", "february", etc.
mmm
Replaced by an lower-case month abbreviation, "jan", "feb", etc.
yyyy
Replaced by a four-digit year. For years less than 1000, the result will have a leading zero.
yyy
Replaced by a three- or four-digit year. For years less than 1000, the result will not have a leading zero.

Examples

  1. Format a date in year-month-day format where all the parts are digits:
    [Birth Date:date:yyyy-mm-dd]

    If a field named Birth Date has the value "12 May 1952", the result is "1952-05-12".

    If a field named Birth Date has the value "May 1952", the result is "1952-05-00".

    If a field named Birth Date has the value "1952", the result is "1952-00-00".

  2. Format a date showing only the date parts that are present in the field value:
    [Death Date:date:yyyy-mm-dd:yyyy-mm:yyyy]

    If a field named Death Date has the value "1977", the result is "1977".

  3. Format a date in "month day, year" format where the month is a mixed-case month name, not a number:
    [Death Date:date:Mmmm d, yyy:Mmmm, yyy:yyy]

    If a field named Death Date has the value "14 December 1977", the result is "December 14, 1977"".

    If a field named Death Date has the value "December 1977", the result is "December, 1977"".

    If a field named Death Date has the value "1977", the result is "1977".

Special Characters

If you want to use one of the keyword characters (d, m, M, or Y) in the format as a literal character, you must escape it with '\'. For example:

[Birth Date:date:\day\: d, \month\: m, \year\: yyy]

Note that ":" is the parameter delimiter in transforms and it must be escaped in addition to the date formatting keyword characters.

Calendar Warning

Please see the Date Manipulation Notes page for important information about date field values.

dateAdd:delta

Adds days, months, or years to the current value.

The input value must be a date with year, month, and day parts and must not include any modifier word such as "before", etc. The delta parameter must be one or more numbers followed by a suffix, "d" for days, "m" for months, or "y" for years. If a number has no suffix, "d" (days) is assumed.

The result is a date and it is formatted according to the current date format.

For example, if the "Date" field has the value "12 May 1953", the result of [Date:dateAdd:1d] is "13 May 1953".

You may specify multiple numbers separated by a space.

For example, if the "Date" field has the value "12 May 1953", the result of [Date:dateAdd:1y 1d] is "13 May 1954".

When you specify multiple numbers, the changes are applied in the same sequence as the numbers in the parameter.

When a number is negative, the result is the same as subtracting the number of days, months, or years.

For example, if the "Date" field has the value "12 May 1953", the result of [Date:dateAdd:-3y] is "12 May 1950".

See the dateSubtract transform for another way to subtract values from a date.

Calendar Warning

Please see the Date Manipulation Notes page for important information about date field values.

dateAdd treats all dates as belonging to the Gregorian calendar.

When operating on Julian dates, the result will be correct except:

  1. when the interval spans the conversion from the Julian calendar to the Gregorian calendar,
  2. when the interval spans a year boundary and the starting day of the year is not January 1.

In the following examples, the Julian New Year's Day property is assumed to be March 25.

For example, in British North America 2 September 1752 (Julian) was followed by 14 September 1752 (Gregorian):

Input Date Transform Output Date Notes
2 Sep 1752 [Date:dateAdd:-1d] 1 Sep 1752 This is the correct result. Both dates are Julian.
2 Sep 1752 [Date:dateAdd:1d] 3 Sep 1752 This is an incorrect result. In British North America, 2 Sep 1752 was a Julian date, but there was no 3 Sep 1752. The next day was 14 Sep 1752, a Gregorian date.
2 Sep 1752 [Date:dateJtoG:dateAdd:1d] 14 Sep 1752 This is the correct result.

Also, in British North America before the change to the Gregorian calendar, the civil year changed on March 25:

Input Date Transform Output Date Notes
24 Mar 1751 [Date:dateAdd:-1d] 23 Sep 1751 This is the correct result.
24 Mar 1751 [Date:dateAdd:1d] 25 Sep 1751 This is an incorrect result. In British North America, "24 Mar 1751" was followed by "25 Mar 1752".
24 Mar 1751 [Date:dateJtoG:dateAdd:1d:dateGtoJ] 25 Mar 1752 This is the correct result.

dateDay

Returns the day part of a date, a number from 1 to 31. The input value must be a valid date with year, month, and day parts.

For example, if the "Date" field has the value "12 May 1953", the result of [Date:dateDay] is "12".

dateGtoJ

Gregorian to Julian

Given a date using the Gregorian calendar, dateGtoJ converts the date to the Julian calendar.

The input value must be a date with year, month, and day parts and must not include any modifier word such as "before", etc.

For example, if a field named Date has the value "15 OCT 1582", the result of [Date:dateGtoJ] is "5 OCT 1582".

Calendar Warning

Please see the Date Manipulation Notes page for important information about date field values.

ORA does not detect whether a date is a Gregorian date or Julian date. It's up to the user to decide based on the collection, time-period, etc.

Many locales did not use January 1 as the start of a new year when using the Julian calendar. When ORA converts the value, it uses the Julian New Year's Day property to determine the first day of the new year. If the Julian New Year's Day property is not correct for the locale of the current record, the dateGtoJ result will not be correct for some days of the year. See dateJNYD.

dateJtoG

Julian to Gregorian

Given a date using the Julian calendar, dateJtoG converts the date to the Gregorian calendar.

The input value must be a date with year, month, and day parts and must not include any modifier word such as "before", etc.

For example, if a field named Date has the value "5 OCT 1582", the result of [Date:dateJtoG] is "15 OCT 1582".

Calendar Warning

Please see the Date Manipulation Notes page for important information about date field values.

ORA does not detect whether a date is a Gregorian date or Julian date. It's up to the user to decide based on the collection, time-period, etc.

Many locales did not use January 1 as the start of a new year when using the Julian calendar. When ORA converts the value, it uses the Julian New Year's Day property to determine the first day of the new year. If the Julian New Year's Day property is not correct for the locale of the current record, the dateJtoG result will not be correct for some days of the year. See dateJNYD.

dateJNYD:first-month:first-day

Julian New Year's Day

The dateJNYD transform does not modify the input value. It sets a temporary value for the Julian New Year's Day property. The temporary new year's day value influences subsequent date conversions in the same template.

If the value passed to the transform is not empty, and if the parameters are valid, the dateJNYD transform returns an empty value but produces a true result.

If the value passed to the transform is empty, or if the parameters are not valid, the dateJNYD transform returns an empty value and produces a false result.

The field value passed to the transform does not have to be a date. The value is not processed by the transform. It is only required because the transform infrastructure requires a field and the value must not be empty because no transforms are processed if the initial field value is empty.

Example

Several countries shifted the first day of the new year to January 1 before adopting the Gregorian calendar. For example, Spain changed the new year date to January 1 as of January 1, 1556 and changed to the Gregorian calendar in October, 1582, with its last Julian date being October 4, 1582. To convert a Julian date in the range "1 JAN 1556" through "4 OCT 1882" to a Gregorian date, the Julian New Year's Date must be set to January 1. If your Julian New Year's Day preference is set to a different date, the dateJtoG transform will not return the correct value.

For this example, assume that the Julian New Year's Day preference is set to "March 25". Also assume that date was recorded in Spain.

Input Date Transform Output Date Notes
10 Mar 1556 [Date:dateJtoG] 20 Mar 1557 This is not the correct result given the assumptions described above.
10 Mar 1556 [Date:dateJNYD:1:1][Date:dateJtoG] 20 Mar 1556 This is the correct result given the assumptions described above.

Calendar Warning

Please see the Date Manipulation Notes page for important information about date field values.

dateModifier

Returns the modifier word part of a date, a value such as "bef", "before", "aft", "after", "ca", "circa", etc. The input value must be a valid date.

For example, if the "Date" field has the value "after 12 May 1953", the result of [Date:datemodifier] is "after".

dateMonth

Returns the month part of a date, a number from 1 to 12. The input value must be a valid date with year and month parts.

For example, if the "Date" field has the value "25 June 1949", the result of [Date:dateMonth] is "6".

dateMonthAbbr

Returns the month part of a date as a month name abbreviation, "Jan", "Feb", etc. The input value must be a valid date with year and month parts.

For example, if the "Date" field has the value "25 June 1949", the result of [Date:dateMonthAbbr] is "Jun".

dateMonthName

Returns the month part of a date as a month name, "January", "February", etc. The input value must be a valid date with year and month parts.

For example, if the "Date" field has the value "25 June 1949", the result of [Date:dateMonthName] is "June".

dateSubtract:delta

Subtracts days, months, or years from the current value.

The input value must be a date with year, month, and day parts and must not include any modifier word such as "before", etc. The delta parameter must be one or more numbers followed by a suffix, "d" for days, "m" for months, or "y" for years. If a number has no suffix, "d" (days) is assumed.

The result is a date and it is formatted according to the current date format.

For example, if the "Date" field has the value "12 May 1953", the result of [Date:dateSubtract:1d] is "11 May 1953".

You may specify multiple numbers separated by a space.

For example, if the "Date" field has the value "12 May 1953", the result of [Date:dateSubtract:1y 1d] is "11 May 1953".

When you specify multiple numbers, the changes are applied in the same sequence as the numbers in the parameter.

When a number is negative, the result is the same as adding the number of days, months, or years.

For example, if the "Date" field has the value "12 May 1953", the result of [Date:dateSubtract:-3y] is "12 May 1956".

See the dateAdd transform for another way to add values to a date.

Calendar Warning

Please see the Date Manipulation Notes page for important information about date field values.

dateSubtract treats all dates as belonging to the Gregorian calendar. Please see the dateAdd transform for a discussion of the issues related to calculating dates that span the Julian-to-Gregorian calendar change.

dateYear:delta

Returns the year part of a date. The input value must be a valid date.

The delta parameter is optional. If specified, it must be a number, and negative numbers must be preceded by "-". Positive numbers may be preceded by "+", but that is not required.

For example, if the "Date" field has the value "12 May 1953", the result of [Date:dateYear] is "1953" and the result of [Date:dateYear:-1] is "1952".

The delta parameter is useful when creating query parameters for URLs to search a repository and you want to specify a range of years before and after the actual year.

dayOfWeek:version

Returns the day of the week for a Gregorian date. The current value must be a date with year, month, and day parts and must not include any modifier word such as "before", etc.

  • If version is "short", "s", or not specified, the result will be an abbreviated day name, "Sun", "Mon", "Tue", etc.

    For example, if the "Date" field has the value "12 May 1953", the result of [Date:dayofweek] is "Tue". The result of [Date:dayofweek:s] is also "Tue"

  • If version is "long" or "l", the result will be the full day name, "Sunday", "Monday", "Tuesday", etc.

    For example, if the "Date" field has the value "12 May 1953", the result of [Date:dayofweek:l] is "Tuesday".

    The actual short and long day names and abbreviations are determined by your browser's current locale settings.

  • If version is "number" or "n", the result will be the day of the week number, as a digit, where Sunday is 0 (zero), Monday is 1 (one), etc.

    For example, if the "Date" field has the value "12 May 1953", the result of [Date:dayofweek:n] is "2".

Calendar Warning

dayOfWeek treats all dates as belonging to the Gregorian calendar. The result will NOT be correct for Julian dates.

For example, the Julian date 2 September 1752 was a Wednesday. dayOfWeek will return Saturday, which is correct for a Gregorian calendar date, but incorrect for a Julian calendar date. You may determine the day of week for a Julian date by converting the date to Gregorian first.

For example, if the "Date" field has the value 2 SEP 1752, the result of [Date:dateJtoG:dayofweek:long] is "Wednesday".

Date Range

ORA's date manipulation transforms support dates from 1 January 0001 to dates well into the future. ORA's date manipulation transforms do not support BCE (BC) dates.

On This Page