mirror of
https://github.com/dlang/phobos.git
synced 2025-05-04 17:11:26 +03:00
Group documentation in std.algorithm.searching + small fixes
This commit is contained in:
Sebastian Wilzbach
parent
31cf21bb86
commit
ba7af41793
1 changed files with 70 additions and 109 deletions
|
|
@ -748,7 +748,8 @@ if (isInputRange!R && !isInfinite!R)
|
|||
`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.
|
||||
`haystack`, then `-1` is returned. If only `pred` is provided,
|
||||
`pred(haystack)` is tested for each element.
|
||||
|
||||
See_Also: $(REF indexOf, std,string)
|
||||
+/
|
||||
|
|
@ -898,18 +899,7 @@ if (isInputRange!R &&
|
|||
assert(countUntil("hello world", "world", 'l') == 2);
|
||||
}
|
||||
|
||||
/++
|
||||
Similar to the previous overload of `countUntil`, except that this one
|
||||
evaluates only the predicate `pred`.
|
||||
|
||||
Params:
|
||||
pred = Predicate to when to stop counting.
|
||||
haystack = An
|
||||
$(REF_ALTTEXT input range, isInputRange, std,range,primitives) of
|
||||
elements to be counted.
|
||||
Returns: The number of elements which must be popped from `haystack`
|
||||
before `pred(haystack.front)` is `true`.
|
||||
+/
|
||||
/// ditto
|
||||
ptrdiff_t countUntil(alias pred, R)(R haystack)
|
||||
if (isInputRange!R &&
|
||||
is(typeof(unaryFun!pred(haystack.front)) : bool))
|
||||
|
|
@ -1457,35 +1447,51 @@ private auto extremum(alias selector = "a < b", Range,
|
|||
|
||||
// find
|
||||
/**
|
||||
Finds an individual element in an input range. Elements of $(D
|
||||
haystack) are compared with `needle` by using predicate $(D
|
||||
pred). Performs $(BIGOH walkLength(haystack)) evaluations of $(D
|
||||
pred).
|
||||
Finds an individual element in an $(REF_ALTTEXT input range, isInputRange, std,range,primitives).
|
||||
Elements of `haystack` are compared with `needle` by using predicate
|
||||
`pred` with `pred(haystack.front, needle)`.
|
||||
`find` performs $(BIGOH walkLength(haystack)) evaluations of `pred`.
|
||||
|
||||
To _find the last occurrence of `needle` in `haystack`, call $(D
|
||||
find(retro(haystack), needle)). See $(REF retro, std,range).
|
||||
To _find the last occurrence of `needle` in a
|
||||
$(REF_ALTTEXT bidirectional, isBidirectionalRange, std,range,primitives) `haystack`,
|
||||
call `find(retro(haystack), needle)`. See $(REF retro, std,range).
|
||||
|
||||
If no `needle` is provided, `pred(haystack.front)` will be evaluated on each
|
||||
element of the input range.
|
||||
|
||||
If `input` is a $(REF_ALTTEXT forward range, isForwardRange, std,range,primitives),
|
||||
`needle` can be a $(REF_ALTTEXT forward range, isForwardRange, std,range,primitives) too.
|
||||
In this case `startsWith!pred(haystack, needle)` is evaluated on each evaluation.
|
||||
|
||||
Note:
|
||||
`find` behaves similar to `dropWhile` in other languages.
|
||||
|
||||
Complexity:
|
||||
`find` performs $(BIGOH walkLength(haystack)) evaluations of `pred`.
|
||||
There are specializations that improve performance by taking
|
||||
advantage of $(REF_ALTTEXT bidirectional, isBidirectionalRange, std,range,primitives)
|
||||
or $(REF_ALTTEXT random access, isRandomAccess, std,range,primitives)
|
||||
ranges (where possible).
|
||||
|
||||
Params:
|
||||
|
||||
pred = The predicate for comparing each element with the needle, defaulting to
|
||||
`"a == b"`.
|
||||
The negated predicate `"a != b"` can be used to search instead for the first
|
||||
element $(I not) matching the needle.
|
||||
pred = The predicate for comparing each element with the needle, defaulting to equality `"a == b"`.
|
||||
The negated predicate `"a != b"` can be used to search instead for the first
|
||||
element $(I not) matching the needle.
|
||||
|
||||
haystack = The $(REF_ALTTEXT input range, isInputRange, std,range,primitives)
|
||||
searched in.
|
||||
haystack = The $(REF_ALTTEXT input range, isInputRange, std,range,primitives)
|
||||
searched in.
|
||||
|
||||
needle = The element searched for.
|
||||
needle = The element searched for.
|
||||
|
||||
Returns:
|
||||
|
||||
`haystack` advanced such that the front element is the one searched for;
|
||||
that is, until `binaryFun!pred(haystack.front, needle)` is `true`. If no
|
||||
such position exists, returns an empty `haystack`.
|
||||
`haystack` advanced such that the front element is the one searched for;
|
||||
that is, until `binaryFun!pred(haystack.front, needle)` is `true`. If no
|
||||
such position exists, returns an empty `haystack`.
|
||||
|
||||
See_Also:
|
||||
$(HTTP sgi.com/tech/stl/_find.html, STL's _find)
|
||||
*/
|
||||
See_ALso: $(LREF findAdjacent), $(LREF findAmong), $(LREF findSkip), $(LREF findSplit), $(LREF startsWith)
|
||||
*/
|
||||
InputRange find(alias pred = "a == b", InputRange, Element)(InputRange haystack, scope Element needle)
|
||||
if (isInputRange!InputRange &&
|
||||
is (typeof(binaryFun!pred(haystack.front, needle)) : bool))
|
||||
|
|
@ -1760,35 +1766,7 @@ if (isInputRange!InputRange &&
|
|||
assert([x].find(x).empty == false);
|
||||
}
|
||||
|
||||
/**
|
||||
Advances the input range `haystack` by calling `haystack.popFront`
|
||||
until either `pred(haystack.front)`, or $(D
|
||||
haystack.empty). Performs $(BIGOH haystack.length) evaluations of $(D
|
||||
pred).
|
||||
|
||||
To _find the last element of a
|
||||
$(REF_ALTTEXT bidirectional, isBidirectionalRange, std,range,primitives) `haystack` satisfying
|
||||
`pred`, call `find!(pred)(retro(haystack))`. See $(REF retro, std,range).
|
||||
|
||||
`find` behaves similar to `dropWhile` in other languages.
|
||||
|
||||
Params:
|
||||
|
||||
pred = The predicate for determining if a given element is the one being
|
||||
searched for.
|
||||
|
||||
haystack = The $(REF_ALTTEXT input range, isInputRange, std,range,primitives) to
|
||||
search in.
|
||||
|
||||
Returns:
|
||||
|
||||
`haystack` advanced such that the front element is the one searched for;
|
||||
that is, until `binaryFun!pred(haystack.front, needle)` is `true`. If no
|
||||
such position exists, returns an empty `haystack`.
|
||||
|
||||
See_Also:
|
||||
$(HTTP sgi.com/tech/stl/find_if.html, STL's find_if)
|
||||
*/
|
||||
/// ditto
|
||||
InputRange find(alias pred, InputRange)(InputRange haystack)
|
||||
if (isInputRange!InputRange)
|
||||
{
|
||||
|
|
@ -1842,31 +1820,7 @@ if (isInputRange!InputRange)
|
|||
assert(find!(a=>a%4 == 0)("日本語") == "本語");
|
||||
}
|
||||
|
||||
/**
|
||||
Finds the first occurrence of a forward range in another forward range.
|
||||
|
||||
Performs $(BIGOH walkLength(haystack) * walkLength(needle)) comparisons in the
|
||||
worst case. There are specializations that improve performance by taking
|
||||
advantage of $(REF_ALTTEXT bidirectional range, isBidirectionalRange, std,range,primitives)
|
||||
or random access in the given ranges (where possible), depending on the statistics
|
||||
of the two ranges' content.
|
||||
|
||||
Params:
|
||||
|
||||
pred = The predicate to use for comparing respective elements from the haystack
|
||||
and the needle. Defaults to simple equality `"a == b"`.
|
||||
|
||||
haystack = The $(REF_ALTTEXT forward range, isForwardRange, std,range,primitives)
|
||||
searched in.
|
||||
|
||||
needle = The $(REF_ALTTEXT forward range, isForwardRange, std,range,primitives)
|
||||
searched for.
|
||||
|
||||
Returns:
|
||||
|
||||
`haystack` advanced such that `needle` is a prefix of it (if no
|
||||
such position exists, returns `haystack` advanced to termination).
|
||||
*/
|
||||
/// ditto
|
||||
R1 find(alias pred = "a == b", R1, R2)(R1 haystack, scope R2 needle)
|
||||
if (isForwardRange!R1 && isForwardRange!R2
|
||||
&& is(typeof(binaryFun!pred(haystack.front, needle.front)) : bool))
|
||||
|
|
@ -2664,8 +2618,7 @@ Returns:
|
|||
`seq` advanced to the first matching element, or until empty if there are no
|
||||
matching elements.
|
||||
|
||||
See_Also:
|
||||
$(HTTP sgi.com/tech/stl/find_first_of.html, STL's find_first_of)
|
||||
See_Also: $(LREF find), $(REF std,algorithm,comparison,among)
|
||||
*/
|
||||
InputRange findAmong(alias pred = "a == b", InputRange, ForwardRange)(
|
||||
InputRange seq, ForwardRange choices)
|
||||
|
|
@ -2700,6 +2653,11 @@ if (isInputRange!InputRange && isForwardRange!ForwardRange)
|
|||
* Finds `needle` in `haystack` and positions `haystack`
|
||||
* right after the first occurrence of `needle`.
|
||||
*
|
||||
* If no needle is provided, the `haystack` is advanced as long as `pred`
|
||||
* evaluates to `true`.
|
||||
* Similarly, the haystack is positioned so as `pred` evaluates to `false` for
|
||||
* `haystack.front`.
|
||||
*
|
||||
* Params:
|
||||
* haystack = The
|
||||
* $(REF_ALTTEXT forward range, isForwardRange, std,range,primitives) to search
|
||||
|
|
@ -2711,7 +2669,10 @@ if (isInputRange!InputRange && isForwardRange!ForwardRange)
|
|||
*
|
||||
* Returns: `true` if the needle was found, in which case `haystack` is
|
||||
* positioned after the end of the first occurrence of `needle`; otherwise
|
||||
* `false`, leaving `haystack` untouched.
|
||||
* `false`, leaving `haystack` untouched. If no needle is provided, it returns
|
||||
* the number of times `pred(haystack.front)` returned true.
|
||||
*
|
||||
* See_Also: $(LREF find)
|
||||
*/
|
||||
bool findSkip(alias pred = "a == b", R1, R2)(ref R1 haystack, R2 needle)
|
||||
if (isForwardRange!R1 && isForwardRange!R2
|
||||
|
|
@ -2742,18 +2703,7 @@ if (isForwardRange!R1 && isForwardRange!R2
|
|||
assert(findSkip(s, "def") && s.empty);
|
||||
}
|
||||
|
||||
/**
|
||||
* Advances the `haystack` as long as `pred` evaluates to `true`.
|
||||
* The haystack is positioned so as pred evaluates to false for haystack.front.
|
||||
*
|
||||
* Params:
|
||||
* haystack = The
|
||||
* $(REF_ALTTEXT forward range, isForwardRange, std,range,primitives) to search
|
||||
* in.
|
||||
* pred = Custom predicate for comparison of haystack and needle
|
||||
*
|
||||
* Returns: The number of times `pred(haystack.front)` returned true.
|
||||
*/
|
||||
/// ditto
|
||||
size_t findSkip(alias pred, R1)(ref R1 haystack)
|
||||
if (isForwardRange!R1 && ifTestable!(typeof(haystack.front), unaryFun!pred))
|
||||
{
|
||||
|
|
@ -2827,6 +2777,8 @@ 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.
|
||||
|
||||
See_Also: $(LREF find)
|
||||
*/
|
||||
auto findSplit(alias pred = "a == b", R1, R2)(R1 haystack, R2 needle)
|
||||
if (isForwardRange!R1 && isForwardRange!R2)
|
||||
|
|
@ -3192,6 +3144,8 @@ Returns: The minimum, respectively maximum element of a range together with the
|
|||
number it occurs in the range.
|
||||
|
||||
Throws: `Exception` if `range.empty`.
|
||||
|
||||
See_Also: $(REF min, std,algorithm,comparison), $(LREF minIndex), $(LREF minElement), $(LREF minPos)
|
||||
*/
|
||||
Tuple!(ElementType!Range, size_t)
|
||||
minCount(alias pred = "a < b", Range)(Range range)
|
||||
|
|
@ -3398,7 +3352,9 @@ Params:
|
|||
Returns: The minimal element of the passed-in range.
|
||||
|
||||
See_Also:
|
||||
$(REF min, std,algorithm,comparison)
|
||||
|
||||
$(LREF maxElement), $(REF min, std,algorithm,comparison), $(LREF minCount),
|
||||
$(LREF minIndex), $(LREF minPos)
|
||||
*/
|
||||
auto minElement(alias map, Range)(Range r)
|
||||
if (isInputRange!Range && !isInfinite!Range)
|
||||
|
|
@ -3511,8 +3467,11 @@ Params:
|
|||
|
||||
Returns: The maximal element of the passed-in range.
|
||||
|
||||
|
||||
See_Also:
|
||||
$(REF max, std,algorithm,comparison)
|
||||
|
||||
$(LREF minElement), $(REF max, std,algorithm,comparison), $(LREF maxCount),
|
||||
$(LREF maxIndex), $(LREF maxPos)
|
||||
*/
|
||||
auto maxElement(alias map, Range)(Range r)
|
||||
if (isInputRange!Range && !isInfinite!Range)
|
||||
|
|
@ -3637,6 +3596,8 @@ Returns: The position of the minimum (respectively maximum) element of forward
|
|||
range `range`, i.e. a subrange of `range` starting at the position of its
|
||||
smallest (respectively largest) element and with the same ending as `range`.
|
||||
|
||||
See_Also:
|
||||
$(REF max, std,algorithm,comparison), $(LREF minCount), $(LREF minIndex), $(LREF minElement)
|
||||
*/
|
||||
Range minPos(alias pred = "a < b", Range)(Range range)
|
||||
if (isForwardRange!Range && !isInfinite!Range &&
|
||||
|
|
@ -3738,15 +3699,15 @@ Params:
|
|||
range = The $(REF_ALTTEXT input range, isInputRange, std,range,primitives)
|
||||
to search.
|
||||
|
||||
Complexity: O(n)
|
||||
Exactly `n - 1` comparisons are needed.
|
||||
Complexity: $(BIGOH range.length)
|
||||
Exactly `range.length - 1` comparisons are needed.
|
||||
|
||||
Returns:
|
||||
The index of the first encounter of the minimum element in `range`. If the
|
||||
`range` is empty, -1 is returned.
|
||||
|
||||
See_Also:
|
||||
$(REF min, std,algorithm,comparison), $(LREF minCount), $(LREF minElement), $(LREF minPos)
|
||||
$(LREF maxIndex), $(REF min, std,algorithm,comparison), $(LREF minCount), $(LREF minElement), $(LREF minPos)
|
||||
*/
|
||||
sizediff_t minIndex(alias pred = "a < b", Range)(Range range)
|
||||
if (isForwardRange!Range && !isInfinite!Range &&
|
||||
|
|
@ -3852,8 +3813,8 @@ if (isForwardRange!Range && !isInfinite!Range &&
|
|||
/**
|
||||
Computes the index of the first occurrence of `range`'s maximum element.
|
||||
|
||||
Complexity: O(n)
|
||||
Exactly `n - 1` comparisons are needed.
|
||||
Complexity: $(BIGOH range)
|
||||
Exactly `range.length - 1` comparisons are needed.
|
||||
|
||||
Params:
|
||||
pred = The ordering predicate to use to determine the maximum element.
|
||||
|
|
@ -3864,7 +3825,7 @@ Returns:
|
|||
`range` is empty, -1 is returned.
|
||||
|
||||
See_Also:
|
||||
$(REF max, std,algorithm,comparison), $(LREF maxCount), $(LREF maxElement), $(LREF maxPos)
|
||||
$(LREF minIndex), $(REF max, std,algorithm,comparison), $(LREF maxCount), $(LREF maxElement), $(LREF maxPos)
|
||||
*/
|
||||
sizediff_t maxIndex(alias pred = "a < b", Range)(Range range)
|
||||
if (isInputRange!Range && !isInfinite!Range &&
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue