csquery v1.0.0 CSQuery.Range View Source

An AWS CloudSearch structured query syntax representation of ranges that may be inclusive or exclusive, open or closed, and may be constructed of integers, floats, DateTime.t/0 values, or (in some cases) strings.

A brief note about notation: { and } denote exclusive range bounds; [ and ] denote inclusive range bounds.

Inclusive or Exclusive Ranges

Ranges that are inclusive cover the entire range, including the boundaries of the range. These are typical of Elixir Range.t/0 values. The Elixir range 1..10 is all integers from 1 through 10. CSQuery.Range values may be lower-bound exclusive, upper-bound exclusive, or both-bound exclusive.

  • [1,10]: lower- and upper-bound inclusive. Integers 1 through 10.
  • {1,10}: lower- and upper-bound exclusive; Integers 2 through 9.
  • {1,10]: lower-bound exclusive, upper-bound inclusive. Integers 2 through 10.
  • [1,10}: lower-bound inclusive, upper-bound exclusive. Integers 1 through 9.

Open or Closed Ranges

An open range is one that omits either the upper or lower bound. Representationally, an omitted bound must be described as exclusive.

  • {,10]: Open range for integers up to 10.
  • [10,}: Open range for integers 10 or larger.

Logically, a fully open range ({,}) is possible, but is meaningless in the context of a search, so a CSQuery.OpenRangeError will be thrown.

iex> new({nil, nil})
** (CSQuery.OpenRangeError) CSQuery.Range types may not be open on both upper and lower bounds.

iex> new(%{})
** (CSQuery.OpenRangeError) CSQuery.Range types may not be open on both upper and lower bounds.

Range Types

Elixir range values are restricted to integers. CloudSearch ranges may be:

  • Integers:

    iex> new({1, 10}) |> to_value
    "[1,10]"
  • Floats:

    iex> new({:math.pi(), :math.pi() * 2}) |> to_value
    "[3.141592653589793,6.283185307179586]"
  • Mixed numbers:

    iex> new({1, :math.pi() * 2}) |> to_value
    "[1,6.283185307179586]"
  • Timestamps

    iex> start = %DateTime{
    ...>  year: 2018, month: 7, day: 21,
    ...>  hour: 17, minute: 55, second: 0,
    ...>  time_zone: "America/Toronto", zone_abbr: "EST",
    ...>  utc_offset: -14_400, std_offset: 0
    ...> }
    iex> finish = %DateTime{
    ...>  year: 2018, month: 7, day: 21,
    ...>  hour: 19, minute: 55, second: 0,
    ...>  time_zone: "America/Toronto", zone_abbr: "EST",
    ...>  utc_offset: -14_400, std_offset: 0
    ...> }
    iex> new({start, finish}) |> to_value
    "['2018-07-21T17:55:00-04:00','2018-07-21T19:55:00-04:00']"
  • Strings

    iex> new({"a", "z"}) |> to_value
    "['a','z']"

integers, floats, timestamps, or strings.

CSQuery.Range construction looks for compatible types (integers and floats may be mixed, but neither timestamps nor strings may be mixed with other types), and a CSQuery.RangeValueTypeError will be thrown if incompatible types are found.

iex> new(%{first: 3, last: "z"})
** (CSQuery.RangeValueTypeError) CSQuery.Range types must be compatible (numbers, dates, and strings may not be mixed).

iex> new(%{first: DateTime.utc_now(), last: "z"})
** (CSQuery.RangeValueTypeError) CSQuery.Range types must be compatible (numbers, dates, and strings may not be mixed).

Link to this section Summary

Types

t()

Supported values for CSQuery.Range values

Link to this section Types

Link to this type t() View Source
t() :: %CSQuery.Range{
  first: value(),
  first?: value(),
  last: value(),
  last?: value()
}
Link to this type value() View Source
value() :: nil | integer() | float() | DateTime.t() | String.t()

Supported values for CSQuery.Range values.

Link to this section Functions

Link to this function new(value) View Source
new(Range.t()) :: t()
new({nil | number(), nil | number()}) :: t() | no_return()
new({nil | String.t(), nil | String.t()}) :: t() | no_return()
new({nil | DateTime.t(), nil | DateTime.t()}) :: t() | no_return()
new(map()) :: t() | no_return()

Create a new CSQuery.Range value.