Numerical Ranges

This chapter describes range and logrange objects that are useful abstaction of numerical loops, intervals, discrete sets, (log)lines and linear spaces. The module for numerical ranges is not exposed, only the contructors are visible from the MAD environment and thus, numerical ranges must be handled directly by their methods. Note that range and logrange have value semantic like number.

Constructors

The constructors for range and logrange are directly available from the MAD environment, except for the special case of the concatenation operator applied to two or three number, which is part of the language definition as a MAD-NG extension. The logrange behave as a the range but they work on logarithmic scale. All constructor functions adjust the value of step to ensure stable sizes and iterators across platforms (see the method adjust for details).

start..stop

start..stop..step

The concatenation operator applied to two or three numbers creates a range and does not perform any adjustment of step. The default step for the first form is one.

range([start_, ] stop, step_)

Return a range object starting at start, ending at stop (included), with increments of size step. Default: start_ = 1, step_ = 1.

nrange([start_, ] stop, size_)

Return a range object starting at start, ending at stop (included), with size increments. Default: start_ = 1, size_ = 100.

logrange([start_, ] stop, step_)

Return a logrange object starting at start, ending at stop (included), with increments of size step. Default: start_ = 1, step_ = 1.

nlogrange([start_, ] stop, size_)

Return a logrange object starting at start, ending at stop (included), with size increments. Default: start_ = 1, size_ = 100.

torange(str)

Return a range decoded from the string str containing a literal numerical ranges of the form "a..b" or "a..b..c" where a, b and c are literal numbers.

Empty Ranges

Empty ranges of size zero can be created by fulfilling the constraints start > stop and step > 0 or start < stop and step < 0 in range constructor.

Singleton Ranges

Singleton ranges of size one can be created by fulfilling the constraints step > stop-start for start < stop and step < stop-start for stop < start in range constructor or size == 1 in nrange constructor. In this latter case, step will be set to step = huge * sign(stop-start).

Constant Ranges

Constant ranges of infinite size can be created by fulfilling the constraints start == stop and step == 0 in range constructor or size == inf in nrange constructor. The user must satify the constraint start == stop in both constructors to show its intention.

Attributes

rng.start

rng.logstart

The component start of the range and the logrange on a linear scale.

rng.stop

rng.logstop

The component stop of the range and the logrange on a linear scale.

rng.step

rng.logstep

The component step of the range and the logrange on a linear scale, which may slighlty differ from the value provided to the constructors due to adjustment.

Functions

is_range(a)

is_logrange(a)

Return true if a is respectively a range or a logrange, false otherwise. These functions are only available from the module MAD.typeid.

isa_range(a)

Return true if a is a range or a logrange (i.e. is-a range), false otherwise. This function is only available from the module MAD.typeid.

Methods

Unless specified, the object rng that owns the methods represents either a range or a logrange.

rng:is_empty()

Return false if rng contains at least one value, true otherwise.

rng:same()

Return rng itself. This method is the identity for objects with value semantic.

rng:copy()

Return rng itself. This method is the identity for objects with value semantic.

rng:ranges()

Return the values of start, stop and step, fully characterising the range rng.

rng:size()

Return the number of values contained by the range rng, i.e. its size that is the number of steps plus one.

rng:value(x)

Return the interpolated value at x, i.e. interpreting the range rng as a (log)line with equation start + x * step.

rng:get(x)

Return rng:value(x) if the result is inside the range’s bounds, nil otherwise.

rng:last()

Return the last value inside the bounds of the range rng, nil otherwise.

rng:adjust()

Return a range with a step adjusted.

The internal quantity step is adjusted if the computed size is close to an integer by \(\pm10^{-12}\). Then the following properties should hold even for rational binary numbers given a consistent input for start, stop, step and size:

• #range(start, stop, step)               == size

• nrange(start, stop, size):step()        == step

• range (start, stop, step):value(size-1) == stop

The maximum adjustment is step = step * (1-eps)^2, beyond this value it is the user reponsibility to provide better inputs.

rng:bounds()

Return the values of start, last (as computed by rng:last()) and step (made positive) characterising the boundaries of the range rng, i.e. interpreted as an interval, nil otherwise.

rng:overlap(rng2)

Return true if rng and rng2 overlap, i.e. have intersecting bounds, false otherwise.

rng:reverse()

Return a range which is the reverse of the range rng, i.e. swap start and stop, and reverse step.

rng:log()

Return a logrange built by converting the range rng to logarithmic scale.

rng:unm()

Return a range with all components start, stop and step negated.

rng:add(num)

Return a range with start and stop shifted by num.

rng:sub(num)

Return a range with start and stop shifted by -num.

rng:mul(num)

Return a range with stop and step scaled by num.

rng:div(num)

Return a range with stop and step scaled by 1/num.

rng:tostring()

Return a string encoding the range rng into a literal numerical ranges of the form "a..b" or "a..b..c" where a, b and c are literal numbers.

rng:totable()

Return a table filled with #rng values computed by rng:value(). Note that ranges are objects with a very small memory footprint while the generated tables can be huge.

Operators

#rng

Return the number of values contained by the range rng, i.e. it is equivalent to rng:size().

rng[n]

Return the value at index n contained by the range rng, i.e. it is equivalent to rng:get(round(n-1)).

-rng

Equivalent to rng:unm().

rng + num

num + rng

Equivalent to rng:add(num).

rng - num

Equivalent to rng:sub(num).

num - rng

Equivalent to rng:unm():add(num).

num * rng

rng * num

Equivalent to rng:mul(num).

rng / num

Equivalent to rng:div(num).

rng == rng2

Return true if rng and rng2 are of same king, have equal start and stop, and their step are within one eps from each other, false otherwise.

Iterators

ipairs(rng)

Return an ipairs iterator suitable for generic for loops. The generated values are those returned by rng:value(i).