PassiveSupport.Range (passive_support v0.8.4)

Helper functions for working with ranges.

Ranges have some interesting characteristics in Elixir. A range literal is the language's simplest representation of a Stream; the use case for them is rather limited compared to other languages; and as of version 1.12.0, it is the first data type in Elixir to make use of a ternary operator (..///3)

All of this can mean exactly one thing: Ranges are for lovers. And by virtue of that fact, this library maintainer's personal soft spot for the data type has to be categorical proof that he is, in fact, a lover.

This module defines a number of functions that help in determining the characteristics of a range, especially in terms of another range, as well as some functions that aid in manipulating ranges for various use cases — the existence of all of which, as of yet, are unproven. Nevertheless, if any of these hypothetical workflows are eventually found to be extant, these functions will all doubtlessly prove invaluable to whatever intrepid, frontier programmer is brave enough to address the challenging burdens, somehow lightened by these desperate grasps for relevance.

Link to this section Summary

Functions

adjacent?(arg1, arg2)

Returns true if either range begins immediately after the other. Returns false if the ranges have opposing polarities

first(arg)

Returns the first number of the range

includes?(range, point)

Returns true if other is a number that falls within range, or if other_range is fully contained within range, regardless of polarity. Returns false for all other values of other.

join(range_1, range_a)

If the provided ranges overlap or are adjacent, returns a new range spanning the entirety of both

last(arg)

Returns the last number of the range

max(arg)

Returns the larger end of the range

min(arg)

Returns the smaller end of the range

next_page(arg)

Returns a new range that immediately follows the range provided, with an equivalent size

overlaps?(arg1, arg2)

Returns true if either end of either range falls within the other. Returns false if the second argument is not a range, or if the ranges have opposing polarities.

prev_page(arg)

Returns a new range that immediately precedes the range provided, with an equivalent size

size(arg)

Returns the size of the range

Link to this section Functions

adjacent?(arg1, arg2)

(since 0.1.0)

Specs

adjacent?(Range.t(), Range.t()) :: boolean()

Returns true if either range begins immediately after the other. Returns false if the ranges have opposing polarities

Examples

iex> adjacent?(1..5, 6..10)
true
iex> adjacent?(6..10, 1..5)
true
iex> adjacent?(10..6, 5..1)
true
iex> adjacent?(5..1, 10..6)
true

iex> adjacent?(0..4, 6..10)
false
iex> adjacent?(6..10, 0..4)
false
iex> adjacent?(10..6, 1..5)
false

first(arg)

(since 0.1.0)

Specs

first(Range.t()) :: integer()

Returns the first number of the range

Examples

iex> first(0..5)
0
iex> first(5..0)
5

includes?(range, point)

(since 0.1.0)

Specs

includes?(Range.t(), any()) :: boolean()

Returns true if other is a number that falls within range, or if other_range is fully contained within range, regardless of polarity. Returns false for all other values of other.

Examples

iex> includes?(1..5, 3)
true
iex> includes?(1..5, 5)
true
iex> includes?(1..5, :math.pi)
true
iex> includes?(1..5, :no)
false
iex> includes?(1..5, nil)
false

iex> includes?(1..5, 2..4)
true
iex> includes?(1..5, 4..6)
false
iex> includes?(1..5, 0..2)
false

iex> includes?(5..1, 3)
true
iex> includes?(5..1, 2..4)
true
iex> includes?(5..1, 4..2)
true

join(range_1, range_a)

(since 0.1.0)

Specs

join(Range.t(), Range.t()) :: Range.t()

If the provided ranges overlap or are adjacent, returns a new range spanning the entirety of both

Examples

iex> join(1..5, 6..10)
1..10
iex> join(1..5, 4..8)
1..8
iex> join(10..20, 5..15)
5..20
iex> join(1..10, 2..8)
1..10

iex> join(1..2, 5..10)
** (ArgumentError) Cannot join 1..2 and 5..10

iex> join(1..5, 10..5)
** (ArgumentError) Cannot join 1..5 and 10..5//-1

last(arg)

(since 0.1.0)

Specs

last(Range.t()) :: integer()

Returns the last number of the range

Examples

iex> last(0..5)
5
iex> last(5..0)
0

max(arg)

(since 0.1.0)

Returns the larger end of the range

Examples

iex> max(0..5)
5
iex> max(5..0)
5

min(arg)

(since 0.1.0)

Returns the smaller end of the range

Examples

iex> min(0..5)
0
iex> min(5..0)
0

next_page(arg)

(since 0.1.0)

Specs

next_page(Range.t()) :: Range.t()

Returns a new range that immediately follows the range provided, with an equivalent size

Examples

iex> next_page(1..10)
11..20
iex> next_page(10..1)
0..-9

overlaps?(arg1, arg2)

(since 0.1.0)

Specs

overlaps?(Range.t(), Range.t()) :: boolean()

Returns true if either end of either range falls within the other. Returns false if the second argument is not a range, or if the ranges have opposing polarities.

Examples

iex> overlaps?(1..5, 4..6)
true
iex> overlaps?(4..6, 1..5)
true
iex> overlaps?(1..5, 6..7)
false

iex> overlaps?(1..5, 2..4)
true
iex> overlaps?(2..4, 1..5)
true

iex> overlaps?(5..1, 4..6)
false
iex> overlaps?(4..6, 5..1)
false
iex> overlaps?(1..5, 6..4)
false
iex> overlaps?(6..4, 1..5)
false
iex> overlaps?(6..4, 5..1)
true

prev_page(arg)

(since 0.1.0)

Specs

prev_page(Range.t()) :: Range.t()

Returns a new range that immediately precedes the range provided, with an equivalent size

Examples

iex> prev_page(1..10)
-9..0
iex> prev_page(10..1)
20..11

size(arg)

(since 0.1.0)

Specs

size(Range.t()) :: integer()

Returns the size of the range

Examples

iex> size(1..5)
5
iex> size(0..5)
6
iex> size(5..0)
6