FHIRPath Function: difference

{:.stu}

Returns the number of boundaries crossed for the specified precision between the input value and the value arguments. If the input value is after the value argument, the result is negative. The result of this operation is always an integer; any fractional boundaries are dropped. {:.stu}

For input and value types of date values, the precision argument must be one of: year, month, week, or day. {:.stu}

For input and value types of datetime values, the precision argument must be one of: year, month, week, day, hour, minute, second, or millisecond. {:.stu}

For input and value types of time values, the precision argument must be one of: hour, minute, second, or millisecond. {:.stu}

If the input value or value argument are of less precision than the specified precision, the result is empty. {:.stu}

For calculations involving weeks, Sunday is considered to be the first day of the week for the purposes of determining the number of boundaries crossed. {:.stu}

When computing the difference between datetime values with different timezone offsets, implementations should normalize the timezone when a precision of hour, minute, second, or millisecond is requested. {:.stu}

If either the input or value argument is empty, the result is empty. {:.stu}

The following examples illustrate the behavior of the difference function: {:.stu}

@2025-01-02.difference(@2025-01-07, 'week') // 1 - crossed a week boundary (Sunday)
@2025-01-01.difference(@2025-09-01, 'year') // 0 - baby is 9 months old, but born this year
@2024-12-01.difference(@2025-09-01, 'year') // 1 - baby is 10 months old, but born last year

{:.stu}

Summary

• Category: Date and Time Interval Functions
• Section: 5.11.2
• Return Type: Integer
• Empty Input Result: empty
• Errors on Multiple Input: true

Description

Returns the number of boundaries crossed for the specified precision between the input value and the value arguments. If the input value is after the value argument, the result is negative. The result of this operation is always an integer; any fractional boundaries are dropped.

Arguments

• value: Date | DateTime | Time - The value to compare with the input
• precision: identifier - The precision for the difference calculation

Type Mapping

• n/a

Example

@2025-01-02.difference(@2025-01-07, 'week') // 1 - crossed a week boundary (Sunday)
@2025-01-01.difference(@2025-09-01, 'year') // 0 - baby is 9 months old, but born this year
@2024-12-01.difference(@2025-09-01, 'year') // 1 - baby is 10 months old, but born last year