begriffs open source - ai-pg/blob - full-docs/txt/functions-range.txt

   1
   2 9.20. Range/Multirange Functions and Operators #
   3
   4    See Section 8.17 for an overview of range types.
   5
   6    Table 9.58 shows the specialized operators available for range types.
   7    Table 9.59 shows the specialized operators available for multirange
   8    types. In addition to those, the usual comparison operators shown in
   9    Table 9.1 are available for range and multirange types. The comparison
  10    operators order first by the range lower bounds, and only if those are
  11    equal do they compare the upper bounds. The multirange operators
  12    compare each range until one is unequal. This does not usually result
  13    in a useful overall ordering, but the operators are provided to allow
  14    unique indexes to be constructed on ranges.
  15
  16    Table 9.58. Range Operators
  17
  18    Operator
  19
  20    Description
  21
  22    Example(s)
  23
  24    anyrange @> anyrange → boolean
  25
  26    Does the first range contain the second?
  27
  28    int4range(2,4) @> int4range(2,3) → t
  29
  30    anyrange @> anyelement → boolean
  31
  32    Does the range contain the element?
  33
  34    '[2011-01-01,2011-03-01)'::tsrange @> '2011-01-10'::timestamp → t
  35
  36    anyrange <@ anyrange → boolean
  37
  38    Is the first range contained by the second?
  39
  40    int4range(2,4) <@ int4range(1,7) → t
  41
  42    anyelement <@ anyrange → boolean
  43
  44    Is the element contained in the range?
  45
  46    42 <@ int4range(1,7) → f
  47
  48    anyrange && anyrange → boolean
  49
  50    Do the ranges overlap, that is, have any elements in common?
  51
  52    int8range(3,7) && int8range(4,12) → t
  53
  54    anyrange << anyrange → boolean
  55
  56    Is the first range strictly left of the second?
  57
  58    int8range(1,10) << int8range(100,110) → t
  59
  60    anyrange >> anyrange → boolean
  61
  62    Is the first range strictly right of the second?
  63
  64    int8range(50,60) >> int8range(20,30) → t
  65
  66    anyrange &< anyrange → boolean
  67
  68    Does the first range not extend to the right of the second?
  69
  70    int8range(1,20) &< int8range(18,20) → t
  71
  72    anyrange &> anyrange → boolean
  73
  74    Does the first range not extend to the left of the second?
  75
  76    int8range(7,20) &> int8range(5,10) → t
  77
  78    anyrange -|- anyrange → boolean
  79
  80    Are the ranges adjacent?
  81
  82    numrange(1.1,2.2) -|- numrange(2.2,3.3) → t
  83
  84    anyrange + anyrange → anyrange
  85
  86    Computes the union of the ranges. The ranges must overlap or be
  87    adjacent, so that the union is a single range (but see range_merge()).
  88
  89    numrange(5,15) + numrange(10,20) → [5,20)
  90
  91    anyrange * anyrange → anyrange
  92
  93    Computes the intersection of the ranges.
  94
  95    int8range(5,15) * int8range(10,20) → [10,15)
  96
  97    anyrange - anyrange → anyrange
  98
  99    Computes the difference of the ranges. The second range must not be
 100    contained in the first in such a way that the difference would not be a
 101    single range.
 102
 103    int8range(5,15) - int8range(10,20) → [5,10)
 104
 105    Table 9.59. Multirange Operators
 106
 107    Operator
 108
 109    Description
 110
 111    Example(s)
 112
 113    anymultirange @> anymultirange → boolean
 114
 115    Does the first multirange contain the second?
 116
 117    '{[2,4)}'::int4multirange @> '{[2,3)}'::int4multirange → t
 118
 119    anymultirange @> anyrange → boolean
 120
 121    Does the multirange contain the range?
 122
 123    '{[2,4)}'::int4multirange @> int4range(2,3) → t
 124
 125    anymultirange @> anyelement → boolean
 126
 127    Does the multirange contain the element?
 128
 129    '{[2011-01-01,2011-03-01)}'::tsmultirange @> '2011-01-10'::timestamp →
 130    t
 131
 132    anyrange @> anymultirange → boolean
 133
 134    Does the range contain the multirange?
 135
 136    '[2,4)'::int4range @> '{[2,3)}'::int4multirange → t
 137
 138    anymultirange <@ anymultirange → boolean
 139
 140    Is the first multirange contained by the second?
 141
 142    '{[2,4)}'::int4multirange <@ '{[1,7)}'::int4multirange → t
 143
 144    anymultirange <@ anyrange → boolean
 145
 146    Is the multirange contained by the range?
 147
 148    '{[2,4)}'::int4multirange <@ int4range(1,7) → t
 149
 150    anyrange <@ anymultirange → boolean
 151
 152    Is the range contained by the multirange?
 153
 154    int4range(2,4) <@ '{[1,7)}'::int4multirange → t
 155
 156    anyelement <@ anymultirange → boolean
 157
 158    Is the element contained by the multirange?
 159
 160    4 <@ '{[1,7)}'::int4multirange → t
 161
 162    anymultirange && anymultirange → boolean
 163
 164    Do the multiranges overlap, that is, have any elements in common?
 165
 166    '{[3,7)}'::int8multirange && '{[4,12)}'::int8multirange → t
 167
 168    anymultirange && anyrange → boolean
 169
 170    Does the multirange overlap the range?
 171
 172    '{[3,7)}'::int8multirange && int8range(4,12) → t
 173
 174    anyrange && anymultirange → boolean
 175
 176    Does the range overlap the multirange?
 177
 178    int8range(3,7) && '{[4,12)}'::int8multirange → t
 179
 180    anymultirange << anymultirange → boolean
 181
 182    Is the first multirange strictly left of the second?
 183
 184    '{[1,10)}'::int8multirange << '{[100,110)}'::int8multirange → t
 185
 186    anymultirange << anyrange → boolean
 187
 188    Is the multirange strictly left of the range?
 189
 190    '{[1,10)}'::int8multirange << int8range(100,110) → t
 191
 192    anyrange << anymultirange → boolean
 193
 194    Is the range strictly left of the multirange?
 195
 196    int8range(1,10) << '{[100,110)}'::int8multirange → t
 197
 198    anymultirange >> anymultirange → boolean
 199
 200    Is the first multirange strictly right of the second?
 201
 202    '{[50,60)}'::int8multirange >> '{[20,30)}'::int8multirange → t
 203
 204    anymultirange >> anyrange → boolean
 205
 206    Is the multirange strictly right of the range?
 207
 208    '{[50,60)}'::int8multirange >> int8range(20,30) → t
 209
 210    anyrange >> anymultirange → boolean
 211
 212    Is the range strictly right of the multirange?
 213
 214    int8range(50,60) >> '{[20,30)}'::int8multirange → t
 215
 216    anymultirange &< anymultirange → boolean
 217
 218    Does the first multirange not extend to the right of the second?
 219
 220    '{[1,20)}'::int8multirange &< '{[18,20)}'::int8multirange → t
 221
 222    anymultirange &< anyrange → boolean
 223
 224    Does the multirange not extend to the right of the range?
 225
 226    '{[1,20)}'::int8multirange &< int8range(18,20) → t
 227
 228    anyrange &< anymultirange → boolean
 229
 230    Does the range not extend to the right of the multirange?
 231
 232    int8range(1,20) &< '{[18,20)}'::int8multirange → t
 233
 234    anymultirange &> anymultirange → boolean
 235
 236    Does the first multirange not extend to the left of the second?
 237
 238    '{[7,20)}'::int8multirange &> '{[5,10)}'::int8multirange → t
 239
 240    anymultirange &> anyrange → boolean
 241
 242    Does the multirange not extend to the left of the range?
 243
 244    '{[7,20)}'::int8multirange &> int8range(5,10) → t
 245
 246    anyrange &> anymultirange → boolean
 247
 248    Does the range not extend to the left of the multirange?
 249
 250    int8range(7,20) &> '{[5,10)}'::int8multirange → t
 251
 252    anymultirange -|- anymultirange → boolean
 253
 254    Are the multiranges adjacent?
 255
 256    '{[1.1,2.2)}'::nummultirange -|- '{[2.2,3.3)}'::nummultirange → t
 257
 258    anymultirange -|- anyrange → boolean
 259
 260    Is the multirange adjacent to the range?
 261
 262    '{[1.1,2.2)}'::nummultirange -|- numrange(2.2,3.3) → t
 263
 264    anyrange -|- anymultirange → boolean
 265
 266    Is the range adjacent to the multirange?
 267
 268    numrange(1.1,2.2) -|- '{[2.2,3.3)}'::nummultirange → t
 269
 270    anymultirange + anymultirange → anymultirange
 271
 272    Computes the union of the multiranges. The multiranges need not overlap
 273    or be adjacent.
 274
 275    '{[5,10)}'::nummultirange + '{[15,20)}'::nummultirange → {[5,10),
 276    [15,20)}
 277
 278    anymultirange * anymultirange → anymultirange
 279
 280    Computes the intersection of the multiranges.
 281
 282    '{[5,15)}'::int8multirange * '{[10,20)}'::int8multirange → {[10,15)}
 283
 284    anymultirange - anymultirange → anymultirange
 285
 286    Computes the difference of the multiranges.
 287
 288    '{[5,20)}'::int8multirange - '{[10,15)}'::int8multirange → {[5,10),
 289    [15,20)}
 290
 291    The left-of/right-of/adjacent operators always return false when an
 292    empty range or multirange is involved; that is, an empty range is not
 293    considered to be either before or after any other range.
 294
 295    Elsewhere empty ranges and multiranges are treated as the additive
 296    identity: anything unioned with an empty value is itself. Anything
 297    minus an empty value is itself. An empty multirange has exactly the
 298    same points as an empty range. Every range contains the empty range.
 299    Every multirange contains as many empty ranges as you like.
 300
 301    The range union and difference operators will fail if the resulting
 302    range would need to contain two disjoint sub-ranges, as such a range
 303    cannot be represented. There are separate operators for union and
 304    difference that take multirange parameters and return a multirange, and
 305    they do not fail even if their arguments are disjoint. So if you need a
 306    union or difference operation for ranges that may be disjoint, you can
 307    avoid errors by first casting your ranges to multiranges.
 308
 309    Table 9.60 shows the functions available for use with range types.
 310    Table 9.61 shows the functions available for use with multirange types.
 311
 312    Table 9.60. Range Functions
 313
 314    Function
 315
 316    Description
 317
 318    Example(s)
 319
 320    lower ( anyrange ) → anyelement
 321
 322    Extracts the lower bound of the range (NULL if the range is empty or
 323    has no lower bound).
 324
 325    lower(numrange(1.1,2.2)) → 1.1
 326
 327    upper ( anyrange ) → anyelement
 328
 329    Extracts the upper bound of the range (NULL if the range is empty or
 330    has no upper bound).
 331
 332    upper(numrange(1.1,2.2)) → 2.2
 333
 334    isempty ( anyrange ) → boolean
 335
 336    Is the range empty?
 337
 338    isempty(numrange(1.1,2.2)) → f
 339
 340    lower_inc ( anyrange ) → boolean
 341
 342    Is the range's lower bound inclusive?
 343
 344    lower_inc(numrange(1.1,2.2)) → t
 345
 346    upper_inc ( anyrange ) → boolean
 347
 348    Is the range's upper bound inclusive?
 349
 350    upper_inc(numrange(1.1,2.2)) → f
 351
 352    lower_inf ( anyrange ) → boolean
 353
 354    Does the range have no lower bound? (A lower bound of -Infinity returns
 355    false.)
 356
 357    lower_inf('(,)'::daterange) → t
 358
 359    upper_inf ( anyrange ) → boolean
 360
 361    Does the range have no upper bound? (An upper bound of Infinity returns
 362    false.)
 363
 364    upper_inf('(,)'::daterange) → t
 365
 366    range_merge ( anyrange, anyrange ) → anyrange
 367
 368    Computes the smallest range that includes both of the given ranges.
 369
 370    range_merge('[1,2)'::int4range, '[3,4)'::int4range) → [1,4)
 371
 372    Table 9.61. Multirange Functions
 373
 374    Function
 375
 376    Description
 377
 378    Example(s)
 379
 380    lower ( anymultirange ) → anyelement
 381
 382    Extracts the lower bound of the multirange (NULL if the multirange is
 383    empty or has no lower bound).
 384
 385    lower('{[1.1,2.2)}'::nummultirange) → 1.1
 386
 387    upper ( anymultirange ) → anyelement
 388
 389    Extracts the upper bound of the multirange (NULL if the multirange is
 390    empty or has no upper bound).
 391
 392    upper('{[1.1,2.2)}'::nummultirange) → 2.2
 393
 394    isempty ( anymultirange ) → boolean
 395
 396    Is the multirange empty?
 397
 398    isempty('{[1.1,2.2)}'::nummultirange) → f
 399
 400    lower_inc ( anymultirange ) → boolean
 401
 402    Is the multirange's lower bound inclusive?
 403
 404    lower_inc('{[1.1,2.2)}'::nummultirange) → t
 405
 406    upper_inc ( anymultirange ) → boolean
 407
 408    Is the multirange's upper bound inclusive?
 409
 410    upper_inc('{[1.1,2.2)}'::nummultirange) → f
 411
 412    lower_inf ( anymultirange ) → boolean
 413
 414    Does the multirange have no lower bound? (A lower bound of -Infinity
 415    returns false.)
 416
 417    lower_inf('{(,)}'::datemultirange) → t
 418
 419    upper_inf ( anymultirange ) → boolean
 420
 421    Does the multirange have no upper bound? (An upper bound of Infinity
 422    returns false.)
 423
 424    upper_inf('{(,)}'::datemultirange) → t
 425
 426    range_merge ( anymultirange ) → anyrange
 427
 428    Computes the smallest range that includes the entire multirange.
 429
 430    range_merge('{[1,2), [3,4)}'::int4multirange) → [1,4)
 431
 432    multirange ( anyrange ) → anymultirange
 433
 434    Returns a multirange containing just the given range.
 435
 436    multirange('[1,2)'::int4range) → {[1,2)}
 437
 438    unnest ( anymultirange ) → setof anyrange
 439
 440    Expands a multirange into a set of ranges in ascending order.
 441
 442    unnest('{[1,2), [3,4)}'::int4multirange) →
 443  [1,2)
 444  [3,4)
 445
 446    The lower_inc, upper_inc, lower_inf, and upper_inf functions all return
 447    false for an empty range or multirange.