Quickly fork, edit online, and submit a pull request for this page.
Requires a signed-in GitHub account. This works well for small changes.
If you'd like to make larger changes you may want to consider using
a local clone.

std.algorithm.searching

This is a submodule of std.algorithm.
It contains generic searching algorithms.

all can also be used without a predicate, if its items can be
evaluated to true or false in a conditional statement. This can be a
convenient way to quickly evaluate that all of the elements of a range
are true.

any can also be used without a predicate, if its items can be
evaluated to true or false in a conditional statement. !any can be a
convenient way to quickly test that none of the elements of a range
evaluate to true.

Checks whether r has "balanced parentheses", i.e. all instances
of lPar are closed by corresponding instances of rPar. The
parameter maxNestingLevel controls the nesting level allowed. The
most common uses are the default or 0. In the latter case, no
nesting is allowed.

Parameters:

Range r

The range to check.

E lPar

The element corresponding with a left (opening) parenthesis.

E rPar

The element corresponding with a right (closing) parenthesis.

size_t maxNestingLevel

The maximum allowed nesting level.

Returns:

true if the given range has balanced parenthesis within the given maximum
nesting level; false otherwise.

A slice of r1 which contains the characters that both ranges start with,
if the first argument is a string; otherwise, the same as the result of
takeExactly(r1, n), where n is the number of elements in the common
prefix of both ranges.

The first version counts the number of elements x in r for
which pred(x, value) is true. pred defaults to
equality. Performs Ο(haystack.length) evaluations of pred.

The second version returns the number of times needle occurs in
haystack. Throws an exception if needle.empty, as the count
of the empty range in any range would be infinite. Overlapped counts
are not considered, for example count("aaa", "aa") is 1, not
2.

The third version counts the elements for which pred(x) is true. Performs Ο(haystack.length) evaluations of pred.

The fourth version counts the number of elements in a range. It is
an optimization for the third version: if the given range has the
length property the count is returned right away, otherwise
performs Ο(haystack.length) to walk the range.

Note
Regardless of the overload, count will not accept
infinite ranges for haystack.

Either a single element, or a
forward range
of elements, to be evaluated in turn against each
element in haystack under the given predicate.

Returns:

The number of elements which must be popped from the front of
haystack before reaching an element for which
startsWith!pred(haystack, needles) is true. If
startsWith!pred(haystack, needles) is not true for any element in
haystack, then -1 is returned.

The needles to check against, which may be single
elements, or bidirectional ranges of elements.

R2 withThis

The single element to check.

Returns:

0 if the needle(s) do not occur at the end of the given range;
otherwise the position of the matching needle, that is, 1 if the range ends
with withOneOfThese[0], 2 if it ends with withOneOfThese[1], and so
on.

In the case when no needle parameters are given, return true iff back of
doesThisStart fulfils predicate pred.

Finds the first occurrence of a forward range in another forward range.

Performs Ο(walkLength(haystack) * walkLength(needle)) comparisons in the
worst case. There are specializations that improve performance by taking
advantage of bidirectional range
or random access in the given ranges (where possible), depending on the statistics
of the two ranges' content.

Parameters:

pred

The predicate to use for comparing respective elements from the haystack
and the needle. Defaults to simple equality "a == b".

Finds two or more needles into a haystack. The predicate pred is used throughout to compare elements. By default, elements are
compared for equality.

Parameters:

pred

The predicate to use for comparing elements.

Range haystack

The target of the search. Must be an input range.
If any of needles is a range with elements comparable to
elements in haystack, then haystack must be a
forward range
such that the search can backtrack.

Ranges needles

One or more items to search for. Each of needles must
be either comparable to one element in haystack, or be itself a
forward range with elements comparable with elements in
haystack.

Returns:

A tuple containing haystack positioned to match one of the
needles and also the 1-based index of the matching element in needles (0 if none of needles matched, 1 if needles[0]
matched, 2 if needles[1] matched...). The first needle to be found
will be the one that matches. If multiple needles are found at the
same spot in the range, then the shortest one is the one which matches
(if multiple needles of the same length are found at the same spot (e.g
"a" and 'a'), then the left-most of them in the argument list
matches).

The relationship between haystack and needles simply means
that one can e.g. search for individual ints or arrays of ints in an array of ints. In addition, if elements are
individually comparable, searches of heterogeneous types are allowed
as well: a double[] can be searched for an int or a short[], and conversely a long can be searched for a float
or a double[]. This makes for efficient searches without the need
to coerce one side of the comparison into the other's side type.

The complexity of the search is Ο(haystack.length *
max(needles.length)). (For needles that are individual items, length
is considered to be 1.) The strategy used in searching several
subranges at once maximizes cache usage by moving in haystack as
few times as possible.

Returns the 1-based index of the first needle found in haystack. If no
needle is found, then 0 is returned.

So, if used directly in the condition of an if statement or loop, the result
will be true if one of the needles is found and false if none are
found, whereas if the result is used elsewhere, it can either be cast to
bool for the same effect or used to get which needle was found first
without having to deal with the tuple that LREF find returns for the
same operation.

These functions find the first occurrence of needle in haystack and then
split haystack as follows.

findSplit returns a tuple result containing three ranges. result[0]
is the portion of haystack before needle, result[1] is the portion of
haystack that matches needle, and result[2] is the portion of haystack
after the match. If needle was not found, result[0] comprehends haystack
entirely and result[1] and result[2] are empty.

findSplitBefore returns a tuple result containing two ranges. result[0] is
the portion of haystack before needle, and result[1] is the balance of
haystack starting with the match. If needle was not found, result[0]
comprehends haystack entirely and result[1] is empty.

findSplitAfter returns a tuple result containing two ranges.
result[0] is the portion of haystack up to and including the
match, and result[1] is the balance of haystack starting
after the match. If needle was not found, result[0] is empty
and result[1] is haystack.

In all cases, the concatenation of the returned ranges spans the
entire haystack.

If haystack is a random-access range, all three components of the tuple have
the same type as haystack. Otherwise, haystack must be a
forward range and
the type of result[0] and result[1] is the same as std.range.takeExactly.

Parameters:

pred

Predicate to use for comparing needle against haystack.

R1 haystack

The range to search.

R2 needle

What to look for.

Returns:

A sub-type of Tuple!() of the split portions of haystack (see above for
details). This sub-type of Tuple!() has opCast defined for bool. This
opCast returns true when the separating needle was found
(!result[1].empty) and false otherwise. This enables the convenient idiom
shown in the following example.

Computes the minimum (respectively maximum) of range along with its number of
occurrences. Formally, the minimum is a value x in range such that pred(a, x) is false for all values a in range. Conversely, the maximum is
a value x in range such that pred(x, a) is false for all values a
in range (note the swapped arguments to pred).

These functions may be used for computing arbitrary extrema by choosing pred
appropriately. For corrrect functioning, pred must be a strict partial order,
i.e. transitive (if pred(a, b) && pred(b, c) then pred(a, c)) and
irreflexive (pred(a, a) is false). The trichotomy property of
inequality is not required: these algoritms consider elements a and b equal
(for the purpose of counting) if pred puts them in the same equivalence class,
i.e. !pred(a, b) && !pred(b, a).

Parameters:

pred

The ordering predicate to use to determine the extremum (minimum
or maximum).

Computes a subrange of range starting at the first occurrence of range's
minimum (respectively maximum) and with the same ending as range, or the
empty range if range itself is empty.

Formally, the minimum is a value x in range such that pred(a, x) is
false for all values a in range. Conversely, the maximum is a value x in
range such that pred(x, a) is false for all values a in range (note
the swapped arguments to pred).

These functions may be used for computing arbitrary extrema by choosing pred
appropriately. For corrrect functioning, pred must be a strict partial order,
i.e. transitive (if pred(a, b) && pred(b, c) then pred(a, c)) and
irreflexive (pred(a, a) is false).

Parameters:

pred

The ordering predicate to use to determine the extremum (minimum or
maximum) element.

The position of the minimum (respectively maximum) element of forward
rangerange, i.e. a subrange of range starting at the position of its
smallest (respectively largest) element and with the same ending as range.

Checks whether the given
input range starts with (one
of) the given needle(s) or, if no needles are given,
if its front element fulfils predicate pred.

Parameters:

pred

Predicate to use in comparing the elements of the haystack and the
needle(s). Mandatory if no needles are given.

Range doesThisStart

The input range to check.

Needles withOneOfThese

The needles against which the range is to be checked,
which may be individual elements or input ranges of elements.

R2 withThis

The single needle to check, which may be either a single element
or an input range of elements.

Returns:

0 if the needle(s) do not occur at the beginning of the given range;
otherwise the position of the matching needle, that is, 1 if the range starts
with withOneOfThese[0], 2 if it starts with withOneOfThese[1], and so
on.

In the case where doesThisStart starts with multiple of the ranges or
elements in withOneOfThese, then the shortest one matches (if there are
two which match which are of the same length (e.g. "a" and 'a'), then
the left-most of them in the argument
list matches).

In the case when no needle parameters are given, return true iff front of
doesThisStart fulfils predicate pred.

Determines whether the element for which the given predicate is
true should be included in the resulting range (No.openRight), or
not (Yes.openRight).

Returns:

An input range that
iterates over the original range's elements, but ends when the specified
predicate becomes true. If the original range is a
forward range or
higher, this range will be a forward range.