|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > Date and Time Calculation > DTO. - Date Time Operations > Date & Time Calculations |
MiniRobotLanguage (MRL)
DTO.AddYears Command
Add or Subtract Years from a Specific Date
Intention
The DTO.AddYears command is used to perform date calculations by adding or subtracting a specified number of years from a given date. This is particularly useful for calculating future dates like anniversaries, contract expirations, or multi-year projections.
The command correctly handles leap years. For instance, if you add one year to February 29th of a leap year, the result will correctly be February 28th of the following year. To subtract years, simply provide a negative number.
Syntax
DTO.AddYears|date|years|[format]|[$$RES]
Parameter Explanation
date - The starting date string (e.g., "29.02.2024").
years - The number of years to add. Use a negative value (e.g., -5) to subtract years.
format - (Optional) A format mask for both the input `date` and the output string. If omitted, a standard format ("DD.MM.YYYY") is used.
$$RES - (Optional) The variable to receive the newly calculated date string.
Example
'**********************************************
' DTO.AddYears - Sample
'**********************************************
'
' --- Sample 1: Calculate a 5-year anniversary ---
$$DAA = "15.08.2023"
DTO.AddYears|$$DAA|5||$$RES
MBX.5 years after $$DAA is $$RES ' Result: 15.08.2028
'
' --- Sample 2: Handle a leap day ---
$$DAB = "29.02.2024"
DTO.AddYears|$$DAB|1||$$RES
MBX.1 year after $$DAB is $$RES ' Result: 28.02.2025
'
' --- Sample 3: Subtract years with a custom format ---
$$DAC = "2030-01-01"
$$FMT = "YYYY-MM-DD"
DTO.AddYears|$$DAC|-10|$$FMT|$$RES
MBX.10 years before $$DAC was $$RES ' Result: 2020-01-01
ENR.
Remarks
If the `format` parameter is provided, it is used for both parsing the input date and formatting the output date. If it is omitted, the command attempts to parse a standard format and returns the result in the same standard format.
Limitations:
A valid date string must be provided. An invalid date will cause an error.
See also:
• DTC. - Date and Time Calculation