## 9.20. Range/Multirange Functions and Operators

 See [Section 8.17](rangetypes.html) for an overview of range types.

[Table 9.53](functions-range.html#RANGE-OPERATORS-TABLE) shows the specialized operators available for range types. [Table 9.54](functions-range.html#MULTIRANGE-OPERATORS-TABLE) shows the specialized operators available for multirange types. In addition to those, the usual comparison operators shown in [Table 9.1](functions-comparison.html#FUNCTIONS-COMPARISON-OP-TABLE) are available for range and multirange types. The comparison operators order first by the range lower bounds, and only if those are equal do they compare the upper bounds. The multirange operators compare each range until one is unequal. This does not usually result in a useful overall ordering, but the operators are provided to allow unique indexes to be constructed on ranges.

**Table 9.53. Range Operators**

|                                                                                                        Operator<br/><br/> Description<br/><br/> Example(s)                                                                                                        |
|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|                                                            `anyrange` `@>` `anyrange` → `boolean`<br/><br/> Does the first range contain the second?<br/><br/>`int4range(2,4) @> int4range(2,3)` → `t`                                                            |
|                                               `anyrange` `@>` `anyelement` → `boolean`<br/><br/> Does the range contain the element?<br/><br/>`'[2011-01-01,2011-03-01)'::tsrange @> '2011-01-10'::timestamp` → `t`                                               |
|                                                          `anyrange` `<@` `anyrange` → `boolean`<br/><br/> Is the first range contained by the second?<br/><br/>`int4range(2,4) <@ int4range(1,7)` → `t`                                                           |
|                                                                  `anyelement` `<@` `anyrange` → `boolean`<br/><br/> Is the element contained in the range?<br/><br/>`42 <@ int4range(1,7)` → `f`                                                                  |
|                                                 `anyrange` `&&` `anyrange` → `boolean`<br/><br/> Do the ranges overlap, that is, have any elements in common?<br/><br/>`int8range(3,7) && int8range(4,12)` → `t`                                                  |
|                                                      `anyrange` `<<` `anyrange` → `boolean`<br/><br/> Is the first range strictly left of the second?<br/><br/>`int8range(1,10) << int8range(100,110)` → `t`                                                      |
|                                                      `anyrange` `>>` `anyrange` → `boolean`<br/><br/> Is the first range strictly right of the second?<br/><br/>`int8range(50,60) >> int8range(20,30)` → `t`                                                      |
|                                                 `anyrange` `&<` `anyrange` → `boolean`<br/><br/> Does the first range not extend to the right of the second?<br/><br/>`int8range(1,20) &< int8range(18,20)` → `t`                                                 |
|                                                  `anyrange` `&>` `anyrange` → `boolean`<br/><br/> Does the first range not extend to the left of the second?<br/><br/>`int8range(7,20) &> int8range(5,10)` → `t`                                                  |
|                                                                `anyrange` `-|-` `anyrange` → `boolean`<br/><br/> Are the ranges adjacent?<br/><br/>`numrange(1.1,2.2) -|- numrange(2.2,3.3)` → `t`                                                                |
|         `anyrange` `+` `anyrange` → `anyrange`<br/><br/> Computes the union of the ranges. The ranges must overlap or be adjacent, so that the union is a single range (but see `range_merge()`).<br/><br/>`numrange(5,15) + numrange(10,20)` → `[5,20)`          |
|                                                        `anyrange` `*` `anyrange` → `anyrange`<br/><br/> Computes the intersection of the ranges.<br/><br/>`int8range(5,15) * int8range(10,20)` → `[10,15)`                                                        |
|`anyrange` `-` `anyrange` → `anyrange`<br/><br/> Computes the difference of the ranges. The second range must not be contained in the first in such a way that the difference would not be a single range.<br/><br/>`int8range(5,15) - int8range(10,20)` → `[5,10)`|

**Table 9.54. Multirange Operators**

|                                                                                              Operator<br/><br/> Description<br/><br/> Example(s)                                                                                              |
|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|                               `anymultirange` `@>` `anymultirange` → `boolean`<br/><br/> Does the first multirange contain the second?<br/><br/>`'{[2,4)}'::int4multirange @> '{[2,3)}'::int4multirange` → `t`                                |
|                                           `anymultirange` `@>` `anyrange` → `boolean`<br/><br/> Does the multirange contain the range?<br/><br/>`'{[2,4)}'::int4multirange @> int4range(2,3)` → `t`                                           |
|                            `anymultirange` `@>` `anyelement` → `boolean`<br/><br/> Does the multirange contain the element?<br/><br/>`'{[2011-01-01,2011-03-01)}'::tsmultirange @> '2011-01-10'::timestamp` → `t`                             |
|                                         `anyrange` `@>` `anymultirange` → `boolean`<br/><br/> Does the range contain the multirange?<br/><br/>`'[2,4)'::int4range @> '{[2,3)}'::int4multirange` → `t`                                         |
|                              `anymultirange` `<@` `anymultirange` → `boolean`<br/><br/> Is the first multirange contained by the second?<br/><br/>`'{[2,4)}'::int4multirange <@ '{[1,7)}'::int4multirange` → `t`                              |
|                                         `anymultirange` `<@` `anyrange` → `boolean`<br/><br/> Is the multirange contained by the range?<br/><br/>`'{[2,4)}'::int4multirange <@ int4range(1,7)` → `t`                                          |
|                                         `anyrange` `<@` `anymultirange` → `boolean`<br/><br/> Is the range contained by the multirange?<br/><br/>`int4range(2,4) <@ '{[1,7)}'::int4multirange` → `t`                                          |
|                                             `anyelement` `<@` `anymultirange` → `boolean`<br/><br/> Is the element contained by the multirange?<br/><br/>`42 <@ '{[1,7)}'::int4multirange` → `t`                                              |
|                     `anymultirange` `&&` `anymultirange` → `boolean`<br/><br/> Do the multiranges overlap, that is, have any elements in common?<br/><br/>`'{[3,7)}'::int8multirange && '{[4,12)}'::int8multirange` → `t`                     |
|                                          `anymultirange` `&&` `anyrange` → `boolean`<br/><br/> Does the multirange overlap the range?<br/><br/>`'{[3,7)}'::int8multirange && int8range(4,12)` → `t`                                           |
|                                          `anyrange` `&&` `anymultirange` → `boolean`<br/><br/> Does the range overlap the multirange?<br/><br/>`int8range(3,7) && '{[4,12)}'::int8multirange` → `t`                                           |
|                         `anymultirange` `<<` `anymultirange` → `boolean`<br/><br/> Is the first multirange strictly left of the second?<br/><br/>`'{[1,10)}'::int8multirange << '{[100,110)}'::int8multirange` → `t`                          |
|                                     `anymultirange` `<<` `anyrange` → `boolean`<br/><br/> Is the multirange strictly left of the range?<br/><br/>`'{[1,10)}'::int8multirange << int8range(100,110)` → `t`                                     |
|                                     `anyrange` `<<` `anymultirange` → `boolean`<br/><br/> Is the range strictly left of the multirange?<br/><br/>`int8range(1,10) << '{[100,110)}'::int8multirange` → `t`                                     |
|                         `anymultirange` `>>` `anymultirange` → `boolean`<br/><br/> Is the first multirange strictly right of the second?<br/><br/>`'{[50,60)}'::int8multirange >> '{[20,30)}'::int8multirange` → `t`                          |
|                                     `anymultirange` `>>` `anyrange` → `boolean`<br/><br/> Is the multirange strictly right of the range?<br/><br/>`'{[50,60)}'::int8multirange >> int8range(20,30)` → `t`                                     |
|                                     `anyrange` `>>` `anymultirange` → `boolean`<br/><br/> Is the range strictly right of the multirange?<br/><br/>`int8range(50,60) >> '{[20,30)}'::int8multirange` → `t`                                     |
|                    `anymultirange` `&<` `anymultirange` → `boolean`<br/><br/> Does the first multirange not extend to the right of the second?<br/><br/>`'{[1,20)}'::int8multirange &< '{[18,20)}'::int8multirange` → `t`                     |
|                                `anymultirange` `&<` `anyrange` → `boolean`<br/><br/> Does the multirange not extend to the right of the range?<br/><br/>`'{[1,20)}'::int8multirange &< int8range(18,20)` → `t`                                |
|                                `anyrange` `&<` `anymultirange` → `boolean`<br/><br/> Does the range not extend to the right of the multirange?<br/><br/>`int8range(1,20) &< '{[18,20)}'::int8multirange` → `t`                                |
|                     `anymultirange` `&>` `anymultirange` → `boolean`<br/><br/> Does the first multirange not extend to the left of the second?<br/><br/>`'{[7,20)}'::int8multirange &> '{[5,10)}'::int8multirange` → `t`                      |
|                                 `anymultirange` `&>` `anyrange` → `boolean`<br/><br/> Does the multirange not extend to the left of the range?<br/><br/>`'{[7,20)}'::int8multirange &> int8range(5,10)` → `t`                                 |
|                                 `anyrange` `&>` `anymultirange` → `boolean`<br/><br/> Does the range not extend to the left of the multirange?<br/><br/>`int8range(7,20) &> '{[5,10)}'::int8multirange` → `t`                                 |
|                                   `anymultirange` `-|-` `anymultirange` → `boolean`<br/><br/> Are the multiranges adjacent?<br/><br/>`'{[1.1,2.2)}'::nummultirange -|- '{[2.2,3.3)}'::nummultirange` → `t`                                    |
|                                      `anymultirange` `-|-` `anyrange` → `boolean`<br/><br/> Is the multirange adjacent to the range?<br/><br/>`'{[1.1,2.2)}'::nummultirange -|- numrange(2.2,3.3)` → `t`                                      |
|                                      `anyrange` `-|-` `anymultirange` → `boolean`<br/><br/> Is the range adjacent to the multirange?<br/><br/>`numrange(1.1,2.2) -|- '{[2.2,3.3)}'::nummultirange` → `t`                                      |
|`anymultirange` `+` `anymultirange` → `anymultirange`<br/><br/> Computes the union of the multiranges. The multiranges need not overlap or be adjacent.<br/><br/>`'{[5,10)}'::nummultirange + '{[15,20)}'::nummultirange` → `{[5,10), [15,20)}`|
|                        `anymultirange` `*` `anymultirange` → `anymultirange`<br/><br/> Computes the intersection of the multiranges.<br/><br/>`'{[5,15)}'::int8multirange * '{[10,20)}'::int8multirange` → `{[10,15)}`                        |
|                     `anymultirange` `-` `anymultirange` → `anymultirange`<br/><br/> Computes the difference of the multiranges.<br/><br/>`'{[5,20)}'::int8multirange - '{[10,15)}'::int8multirange` → `{[5,10), [15,20)}`                     |

 The left-of/right-of/adjacent operators always return false when an empty range or multirange is involved; that is, an empty range is not considered to be either before or after any other range.

 Elsewhere empty ranges and multiranges are treated as the additive identity: anything unioned with an empty value is itself. Anything minus an empty value is itself. An empty multirange has exactly the same points as an empty range. Every range contains the empty range. Every multirange contains as many empty ranges as you like.

 The range union and difference operators will fail if the resulting range would need to contain two disjoint sub-ranges, as such a range cannot be represented. There are separate operators for union and difference that take multirange parameters and return a multirange, and they do not fail even if their arguments are disjoint. So if you need a union or difference operation for ranges that may be disjoint, you can avoid errors by first casting your ranges to multiranges.

[Table 9.55](functions-range.html#RANGE-FUNCTIONS-TABLE) shows the functions available for use with range types. [Table 9.56](functions-range.html#MULTIRANGE-FUNCTIONS-TABLE) shows the functions available for use with multirange types.

**Table 9.55. Range Functions**

|                                                                               Function<br/><br/> Description<br/><br/> Example(s)                                                                               |
|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|      []() `lower` ( `anyrange` ) → `anyelement`<br/><br/> Extracts the lower bound of the range (`NULL` if the range is empty or the lower bound is infinite).<br/><br/>`lower(numrange(1.1,2.2))` → `1.1`      |
|      []() `upper` ( `anyrange` ) → `anyelement`<br/><br/> Extracts the upper bound of the range (`NULL` if the range is empty or the upper bound is infinite).<br/><br/>`upper(numrange(1.1,2.2))` → `2.2`      |
|                                               []() `isempty` ( `anyrange` ) → `boolean`<br/><br/> Is the range empty?<br/><br/>`isempty(numrange(1.1,2.2))` → `f`                                               |
|                                    []() `lower_inc` ( `anyrange` ) → `boolean`<br/><br/> Is the range's lower bound inclusive?<br/><br/>`lower_inc(numrange(1.1,2.2))` → `t`                                    |
|                                    []() `upper_inc` ( `anyrange` ) → `boolean`<br/><br/> Is the range's upper bound inclusive?<br/><br/>`upper_inc(numrange(1.1,2.2))` → `f`                                    |
|                                     []() `lower_inf` ( `anyrange` ) → `boolean`<br/><br/> Is the range's lower bound infinite?<br/><br/>`lower_inf('(,)'::daterange)` → `t`                                     |
|                                     []() `upper_inf` ( `anyrange` ) → `boolean`<br/><br/> Is the range's upper bound infinite?<br/><br/>`upper_inf('(,)'::daterange)` → `t`                                     |
|[]() `range_merge` ( `anyrange`, `anyrange` ) → `anyrange`<br/><br/> Computes the smallest range that includes both of the given ranges.<br/><br/>`range_merge('[1,2)'::int4range, '[3,4)'::int4range)` → `[1,4)`|

**Table 9.56. Multirange Functions**

|                                                                                                           Function<br/><br/> Description<br/><br/> Example(s)                                                                                                          |
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|                    []() `lower` ( `anymultirange` ) → `anyelement`<br/><br/> Extracts the lower bound of the multirange (`NULL` if the multirange is empty or the lower bound is infinite).<br/><br/>`lower('{[1.1,2.2)}'::nummultirange)` → `1.1`                     |
|                    []() `upper` ( `anymultirange` ) → `anyelement`<br/><br/> Extracts the upper bound of the multirange (`NULL` if the multirange is empty or the upper bound is infinite).<br/><br/>`upper('{[1.1,2.2)}'::nummultirange)` → `2.2`                     |
|                                                                []() `isempty` ( `anymultirange` ) → `boolean`<br/><br/> Is the multirange empty?<br/><br/>`isempty('{[1.1,2.2)}'::nummultirange)` → `f`                                                                |
|                                                     []() `lower_inc` ( `anymultirange` ) → `boolean`<br/><br/> Is the multirange's lower bound inclusive?<br/><br/>`lower_inc('{[1.1,2.2)}'::nummultirange)` → `t`                                                     |
|                                                     []() `upper_inc` ( `anymultirange` ) → `boolean`<br/><br/> Is the multirange's upper bound inclusive?<br/><br/>`upper_inc('{[1.1,2.2)}'::nummultirange)` → `f`                                                     |
|                                                        []() `lower_inf` ( `anymultirange` ) → `boolean`<br/><br/> Is the multirange's lower bound infinite?<br/><br/>`lower_inf('{(,)}'::datemultirange)` → `t`                                                        |
|                                                        []() `upper_inf` ( `anymultirange` ) → `boolean`<br/><br/> Is the multirange's upper bound infinite?<br/><br/>`upper_inf('{(,)}'::datemultirange)` → `t`                                                        |
|                                   []() `range_merge` ( `anymultirange` ) → `anyrange`<br/><br/> Computes the smallest range that includes the entire multirange.<br/><br/>`range_merge('{[1,2), [3,4)}'::int4multirange)` → `[1,4)`                                    |
|                                                []() `multirange` ( `anyrange` ) → `anymultirange`<br/><br/> Returns a multirange containing just the given range.<br/><br/>`multirange('[1,2)'::int4range)` → `{[1,2)}`                                                |
|[]() `unnest` ( `anymultirange` ) → `setof anyrange`<br/><br/> Expands a multirange into a set of ranges. The ranges are read out in storage order (ascending).<br/><br/>`unnest('{[1,2), [3,4)}'::int4multirange)` → ``<br/><br/>```<br/> [1,2)<br/> [3,4)<br/><br/>```|

 The `lower_inc`, `upper_inc`, `lower_inf`, and `upper_inf` functions all return false for an empty range or multirange.