SortedRange

Represents a sorted range. In addition to the regular range primitives, supports additional operations that take advantage of the ordering, such as merge and binary search. To obtain a SortedRange from an unsorted range r, use std.algorithm.sorting.sort which sorts r in place and returns the corresponding SortedRange. To construct a SortedRange from a range r that is known to be already sorted, use assumeSorted.

Members

Functions

contains
bool contains(V value)

Returns true if and only if value can be found in range, which is assumed to be sorted. Performs O(log(r.length)) evaluations of pred.

equalRange
auto equalRange(V value)

Returns the subrange containing all elements e for which both pred(e, value) and pred(value, e) evaluate to false (e.g., if pred is "less than", returns the portion of the range with elements equal to value). Uses a classic binary search with interval halving until it finds a value that satisfies the condition, then uses SearchPolicy.gallopBackwards to find the left boundary and SearchPolicy.gallop to find the right boundary. These policies are justified by the fact that the two boundaries are likely to be near the first found value (i.e., equal ranges are relatively small). Completes the entire search in O(log(n)) time.

groupBy
auto groupBy()

Returns a range of subranges of elements that are equivalent according to the sorting relation.

lowerBound
auto lowerBound(V value)

This function uses a search with policy sp to find the largest left subrange on which pred(x, value) is true for all x (e.g., if pred is "less than", returns the portion of the range with elements strictly smaller than value). The search schedule and its complexity are documented in SearchPolicy.

opBinaryRight
bool opBinaryRight(V value)

Like contains, but the value is specified before the range.

opIndex
auto ref opIndex(size_t i)
opSlice
auto opSlice(size_t a, size_t b)
popBack
void popBack()
popFront
void popFront()

Range primitives.

release
auto release()

Releases the controlled range and returns it.

trisect
auto trisect(V value)

Returns a tuple r such that r[0] is the same as the result of lowerBound(value), r[1] is the same as the result of equalRange(value), and r[2] is the same as the result of upperBound(value). The call is faster than computing all three separately. Uses a search schedule similar to equalRange. Completes the entire search in O(log(n)) time.

upperBound
auto upperBound(V value)

This function searches with policy sp to find the largest right subrange on which pred(value, x) is true for all x (e.g., if pred is "less than", returns the portion of the range with elements strictly greater than value). The search schedule and its complexity are documented in SearchPolicy.

Properties

back
auto ref back [@property getter]

Range primitives.

empty
bool empty [@property getter]
front
auto ref front [@property getter]
save
auto save [@property getter]

Range primitives.

Examples

import std.algorithm.sorting : sort;
auto a = [ 1, 2, 3, 42, 52, 64 ];
auto r = assumeSorted(a);
assert(r.contains(3));
assert(!(32 in r));
auto r1 = sort!"a > b"(a);
assert(3 in r1);
assert(!r1.contains(32));
assert(r1.release() == [ 64, 52, 42, 3, 2, 1 ]);

SortedRange could accept ranges weaker than random-access, but it is unable to provide interesting functionality for them. Therefore, SortedRange is currently restricted to random-access ranges.

No copy of the original range is ever made. If the underlying range is changed concurrently with its corresponding SortedRange in ways that break its sorted-ness, SortedRange will work erratically.

import std.algorithm.mutation : swap;
auto a = [ 1, 2, 3, 42, 52, 64 ];
auto r = assumeSorted(a);
assert(r.contains(42));
swap(a[3], a[5]);         // illegal to break sortedness of original range
assert(!r.contains(42));  // passes although it shouldn't

SortedRange can be searched with predicates that do not take two elements of the underlying range as arguments.

This is useful, if a range of structs is sorted by a member and you want to search in that range by only providing a value for that member.

import std.algorithm.comparison : equal;
static struct S { int i; }
static bool byI(A, B)(A a, B b)
{
    static if (is(A == S))
        return a.i < b;
    else
        return a < b.i;
}
auto r = assumeSorted!byI([S(1), S(2), S(3)]);
auto lessThanTwo = r.lowerBound(2);
assert(equal(lessThanTwo, [S(1)]));

Meta