As its name suggests, this function takes two dates as arguments and returns the difference as a number of years, months and days. It is not the same as combining the results of the MonthsBetween and DaysBetween functions together with the YearsBetween function.

The simplest form takes only the starting date and ending date as arguments, and returns a string with the years, months and days between these two dates. The years, months and days parts are separated from each other by a pipe symbol – |.

As usual, the operation is best explained by way of an example. Here are two scripts and some XpressDox code that demonstrate the various aspects of the function.

«Script(Phrase,Value,Name)»«&Value&» «Value(&Name&)»«Plural(&Value&,’’,’s’)»«ScriptEnd()»
«Script(YMDBetween,StartDate,EndDate)»
«SetVr(‘ymd’,YearsMonthsDaysBetween(&EndDate&,&StartDate&))»
«::ry,SubstringBefore(::gymd,’|’)»
«::rm,SubstringAfter(::gymd,’|’)->SubstringBefore(^,’|’)»
«::rd,SubstringAfterLast(::gymd,’|’)»
The period starting on «FormatDate(&StartDate&,’MMMM d, yyyy’)» and ending on «FormatDate(&EndDate&,’MMMM d, yyyy’)» is: «Phrase(::gy,’year’)», «Phrase(::gm,’month’)», and «Phrase(::gd,’day’)»
«ScriptEnd()»
«YMDBetween(BeginDate,EndDate)»
The value returned by the function with fewest arguments: «GetV(‘ymd’)»
The number of years only: «YearsMonthsDaysBetween(EndDate,BeginDate,’Y’)»
The number of months only: «YearsMonthsDaysBetween(EndDate,BeginDate,’M’)»
The number of days only: «YearsMonthsDaysBetween(EndDate,BeginDate,’d’)»

Remember that ::r is the shortcut for SetVr and ::g is the shortcut for GetV. Have a look at Using and storing variables.