mirrors/phobos
1
0
Fork 0
mirror of https://github.com/dlang/phobos.git synced 2025-05-07 03:27:03 +03:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge pull request #1635 from kiith-sa/patch-7

Browse source 
DDoc: Doc improvements for std.algorithm (see extended description)
This commit is contained in:
monarch dodra 2013-10-16 06:04:15 -07:00
commit d122aa0cb0
1 changed files with 72 additions and 31 deletions
Download patch file Download diff file Expand all files Collapse all files

103
std/algorithm.d
View file

@ -43,7 +43,10 @@ Implements algorithms oriented mainly towards processing of
sequences. Some functions are semantic equivalents or supersets of sequences. Some functions are semantic equivalents or supersets of
those found in the $(D $(LESS)_algorithm$(GREATER)) header in $(WEB those found in the $(D $(LESS)_algorithm$(GREATER)) header in $(WEB
sgi.com/tech/stl/, Alexander Stepanov's Standard Template Library) for sgi.com/tech/stl/, Alexander Stepanov's Standard Template Library) for
C++. C++. Sequences processed by these functions define range-based interfaces.
$(LINK2 std_range.html, Reference on ranges)$(BR)
$(LINK2 http://ddili.org/ders/d.en/ranges.html, Tutorial on ranges)
Many functions in this module are parameterized with a function or a Many functions in this module are parameterized with a function or a
$(GLOSSARY predicate). The predicate may be passed either as a $(GLOSSARY predicate). The predicate may be passed either as a
@ -1924,12 +1927,15 @@ unittest
// swap // swap
/** /**
Swaps $(D lhs) and $(D rhs). See also $(XREF exception, pointsTo). Swaps $(D lhs) and $(D rhs).
Preconditions: Preconditions:
$(D !pointsTo(lhs, lhs) && !pointsTo(lhs, rhs) && !pointsTo(rhs, lhs) $(D !pointsTo(lhs, lhs) && !pointsTo(lhs, rhs) && !pointsTo(rhs, lhs)
&& !pointsTo(rhs, rhs)) && !pointsTo(rhs, rhs))
See_Also:
$(XREF exception, pointsTo)
*/ */
void swap(T)(ref T lhs, ref T rhs) @trusted pure nothrow void swap(T)(ref T lhs, ref T rhs) @trusted pure nothrow
if (isMutable!T && !is(typeof(T.init.proxySwap(T.init)))) if (isMutable!T && !is(typeof(T.init.proxySwap(T.init))))
@ -3607,10 +3613,10 @@ assert(r == [ 1, 2, 3, 4, 5 ]);
Finds an individual element in an input range. Elements of $(D Finds an individual element in an input range. Elements of $(D
haystack) are compared with $(D needle) by using predicate $(D haystack) are compared with $(D needle) by using predicate $(D
pred). Performs $(BIGOH walkLength(haystack)) evaluations of $(D pred). Performs $(BIGOH walkLength(haystack)) evaluations of $(D
pred). See also $(WEB sgi.com/tech/stl/_find.html, STL's _find). pred).
To _find the last occurence of $(D needle) in $(D haystack), call $(D To _find the last occurence of $(D needle) in $(D haystack), call $(D
find(retro(haystack), needle)). See also $(XREF range, retro). find(retro(haystack), needle)). See $(XREF range, retro).
Params: Params:
@ -3645,6 +3651,9 @@ assert(!find(a, 2).empty); // found
string[] s = [ "Hello", "world", "!" ]; string[] s = [ "Hello", "world", "!" ];
assert(!find!("toLower(a) == b")(s, "hello").empty); assert(!find!("toLower(a) == b")(s, "hello").empty);
---- ----
See_Also:
$(WEB sgi.com/tech/stl/_find.html, STL's _find)
*/ */
R find(alias pred = "a == b", R, E)(R haystack, E needle) R find(alias pred = "a == b", R, E)(R haystack, E needle)
@ -4277,10 +4286,10 @@ unittest
Advances the input range $(D haystack) by calling $(D haystack.popFront) Advances the input range $(D haystack) by calling $(D haystack.popFront)
until either $(D pred(haystack.front)), or $(D until either $(D pred(haystack.front)), or $(D
haystack.empty). Performs $(BIGOH haystack.length) evaluations of $(D haystack.empty). Performs $(BIGOH haystack.length) evaluations of $(D
pred). See also $(WEB sgi.com/tech/stl/find_if.html, STL's find_if). pred).
To find the last element of a bidirectional $(D haystack) satisfying To find the last element of a bidirectional $(D haystack) satisfying
$(D pred), call $(D find!(pred)(retro(haystack))). See also $(XREF $(D pred), call $(D find!(pred)(retro(haystack))). See $(XREF
range, retro). range, retro).
Example: Example:
@ -4292,6 +4301,9 @@ assert(find!("a > 2")(arr) == [ 3, 4, 1 ]);
bool pred(int x) { return x + 1 > 1.5; } bool pred(int x) { return x + 1 > 1.5; }
assert(find!(pred)(arr) == arr); assert(find!(pred)(arr) == arr);
---- ----
See_Also:
$(WEB sgi.com/tech/stl/find_if.html, STL's find_if)
*/ */
Range find(alias pred, Range)(Range haystack) if (isInputRange!(Range)) Range find(alias pred, Range)(Range haystack) if (isInputRange!(Range))
{ {
@ -5692,8 +5704,7 @@ unittest
/** /**
Advances $(D r) until it finds the first two adjacent elements $(D a), Advances $(D r) until it finds the first two adjacent elements $(D a),
$(D b) that satisfy $(D pred(a, b)). Performs $(BIGOH r.length) $(D b) that satisfy $(D pred(a, b)). Performs $(BIGOH r.length)
evaluations of $(D pred). See also $(WEB evaluations of $(D pred).
sgi.com/tech/stl/adjacent_find.html, STL's adjacent_find).
Example: Example:
---- ----
@ -5702,6 +5713,9 @@ auto r = findAdjacent(a);
assert(r == [ 10, 10, 9, 8, 8, 7, 8, 9 ]); assert(r == [ 10, 10, 9, 8, 8, 7, 8, 9 ]);
p = findAdjacent!("a < b")(a); p = findAdjacent!("a < b")(a);
assert(p == [ 7, 8, 9 ]); assert(p == [ 7, 8, 9 ]);
See_Also:
$(WEB sgi.com/tech/stl/adjacent_find.html, STL's adjacent_find)
---- ----
*/ */
Range findAdjacent(alias pred = "a == b", Range)(Range r) Range findAdjacent(alias pred = "a == b", Range)(Range r)
@ -5749,8 +5763,7 @@ unittest
Advances $(D seq) by calling $(D seq.popFront) until either $(D Advances $(D seq) by calling $(D seq.popFront) until either $(D
find!(pred)(choices, seq.front)) is $(D true), or $(D seq) becomes find!(pred)(choices, seq.front)) is $(D true), or $(D seq) becomes
empty. Performs $(BIGOH seq.length * choices.length) evaluations of empty. Performs $(BIGOH seq.length * choices.length) evaluations of
$(D pred). See also $(WEB sgi.com/tech/stl/find_first_of.html, STL's $(D pred).
find_first_of).
Example: Example:
---- ----
@ -5758,6 +5771,9 @@ int[] a = [ -1, 0, 1, 2, 3, 4, 5 ];
int[] b = [ 3, 1, 2 ]; int[] b = [ 3, 1, 2 ];
assert(findAmong(a, b) == a[2 .. $]); assert(findAmong(a, b) == a[2 .. $]);
---- ----
See_Also:
$(WEB sgi.com/tech/stl/find_first_of.html, STL's find_first_of)
*/ */
Range1 findAmong(alias pred = "a == b", Range1, Range2)( Range1 findAmong(alias pred = "a == b", Range1, Range2)(
Range1 seq, Range2 choices) Range1 seq, Range2 choices)
@ -5960,8 +5976,7 @@ Returns $(D true) if and only if the two ranges compare equal element
for element, according to binary predicate $(D pred). The ranges may for element, according to binary predicate $(D pred). The ranges may
have different element types, as long as $(D pred(a, b)) evaluates to have different element types, as long as $(D pred(a, b)) evaluates to
$(D bool) for $(D a) in $(D r1) and $(D b) in $(D r2). Performs $(D bool) for $(D a) in $(D r1) and $(D b) in $(D r2). Performs
$(BIGOH min(r1.length, r2.length)) evaluations of $(D pred). See also $(BIGOH min(r1.length, r2.length)) evaluations of $(D pred).
$(WEB sgi.com/tech/stl/_equal.html, STL's _equal).
Example: Example:
---- ----
@ -5978,6 +5993,9 @@ assert(equal(a, b));
double[] c = [ 1.005, 2, 4, 3]; double[] c = [ 1.005, 2, 4, 3];
assert(equal!(approxEqual)(b, c)); assert(equal!(approxEqual)(b, c));
---- ----
See_Also:
$(WEB sgi.com/tech/stl/_equal.html, STL's _equal)
*/ */
bool equal(Range1, Range2)(Range1 r1, Range2 r2) bool equal(Range1, Range2)(Range1 r1, Range2 r2)
if (isInputRange!Range1 && isInputRange!Range2 if (isInputRange!Range1 && isInputRange!Range2
@ -6552,8 +6570,7 @@ Sequentially compares elements in $(D r1) and $(D r2) in lockstep, and
stops at the first mismatch (according to $(D pred), by default stops at the first mismatch (according to $(D pred), by default
equality). Returns a tuple with the reduced ranges that start with the equality). Returns a tuple with the reduced ranges that start with the
two mismatched values. Performs $(BIGOH min(r1.length, r2.length)) two mismatched values. Performs $(BIGOH min(r1.length, r2.length))
evaluations of $(D pred). See also $(WEB evaluations of $(D pred).
sgi.com/tech/stl/_mismatch.html, STL's _mismatch).
Example: Example:
---- ----
@ -6563,6 +6580,9 @@ auto m = mismatch(x, y);
assert(m[0] == x[3 .. $]); assert(m[0] == x[3 .. $]);
assert(m[1] == y[3 .. $]); assert(m[1] == y[3 .. $]);
---- ----
See_Also:
$(WEB sgi.com/tech/stl/_mismatch.html, STL's _mismatch)
*/ */
Tuple!(Range1, Range2) Tuple!(Range1, Range2)
@ -6824,11 +6844,7 @@ unittest
// copy // copy
/** /**
Copies the content of $(D source) into $(D target) and returns the Copies the content of $(D source) into $(D target) and returns the
remaining (unfilled) part of $(D target). See also $(WEB remaining (unfilled) part of $(D target).
sgi.com/tech/stl/_copy.html, STL's _copy). If a behavior similar to
$(WEB sgi.com/tech/stl/copy_backward.html, STL's copy_backward) is
needed, use $(D copy(retro(source), retro(target))). See also $(XREF
range, retro).
Example: Example:
---- ----
@ -6853,16 +6869,30 @@ auto d = copy(a, b);
To copy at most $(D n) elements from range $(D a) to range $(D b), you To copy at most $(D n) elements from range $(D a) to range $(D b), you
may want to use $(D copy(take(a, n), b)). To copy those elements from may want to use $(D copy(take(a, n), b)). To copy those elements from
range $(D a) that satisfy predicate $(D pred) to range $(D b), you may range $(D a) that satisfy predicate $(D pred) to range $(D b), you may
want to use $(D copy(filter!(pred)(a), b)). want to use $(D copy(a.filter!(pred), b)).
Example: Example:
---- ----
int[] a = [ 1, 5, 8, 9, 10, 1, 2, 0 ]; int[] a = [ 1, 5, 8, 9, 10, 1, 2, 0 ];
auto b = new int[a.length]; auto b = new int[a.length];
auto c = copy(filter!("(a & 1) == 1")(a), b); auto c = copy(a.filter!(a => (a & 1) == 1), b);
assert(b[0 .. $ - c.length] == [ 1, 5, 9, 1 ]); assert(b[0 .. $ - c.length] == [ 1, 5, 9, 1 ]);
---- ----
$(XREF range, retro) can be used to achieve behavior similar to
$(WEB sgi.com/tech/stl/copy_backward.html, STL's copy_backward').
Example:
----
import std.algorithm, std.range;
int[] src = [1, 2, 4];
int[] dst = [0, 0, 0, 0, 0];
copy(src.retro, dst.retro);
assert(dst == [0, 0, 1, 2, 4]);
----
See_Also:
$(WEB sgi.com/tech/stl/_copy.html, STL's _copy)
*/ */
Range2 copy(Range1, Range2)(Range1 source, Range2 target) Range2 copy(Range1, Range2)(Range1 source, Range2 target)
if (isInputRange!Range1 && isOutputRange!(Range2, ElementType!Range1)) if (isInputRange!Range1 && isOutputRange!(Range2, ElementType!Range1))
@ -6999,13 +7029,16 @@ unittest
// reverse // reverse
/** /**
Reverses $(D r) in-place. Performs $(D r.length / 2) evaluations of $(D Reverses $(D r) in-place. Performs $(D r.length / 2) evaluations of $(D
swap). See also $(WEB sgi.com/tech/stl/_reverse.html, STL's _reverse). swap).
Example: Example:
---- ----
int[] arr = [ 1, 2, 3 ]; int[] arr = [ 1, 2, 3 ];
reverse(arr); reverse(arr);
assert(arr == [ 3, 2, 1 ]); assert(arr == [ 3, 2, 1 ]);
See_Also:
$(WEB sgi.com/tech/stl/_reverse.html, STL's _reverse)
---- ----
*/ */
void reverse(Range)(Range r) void reverse(Range)(Range r)
@ -7278,7 +7311,7 @@ assert(equal(vec, [ 5, 6, 7 ]));
---- ----
Performs $(BIGOH max(front.length, back.length)) evaluations of $(D Performs $(BIGOH max(front.length, back.length)) evaluations of $(D
swap). See also $(WEB sgi.com/tech/stl/_rotate.html, STL's rotate). swap).
Preconditions: Preconditions:
@ -7290,6 +7323,9 @@ Returns:
The number of elements brought to the front, i.e., the length of $(D The number of elements brought to the front, i.e., the length of $(D
back). back).
See_Also:
$(WEB sgi.com/tech/stl/_rotate.html, STL's rotate)
*/ */
size_t bringToFront(Range1, Range2)(Range1 front, Range2 back) size_t bringToFront(Range1, Range2)(Range1 front, Range2 back)
if (isInputRange!Range1 && isForwardRange!Range2) if (isInputRange!Range1 && isForwardRange!Range2)
@ -7870,9 +7906,6 @@ swap). The unstable version computes the minimum possible evaluations
of $(D swap) (roughly half of those performed by the semistable of $(D swap) (roughly half of those performed by the semistable
version). version).
See also STL's $(WEB sgi.com/tech/stl/_partition.html, _partition) and
$(WEB sgi.com/tech/stl/stable_partition.html, stable_partition).
Returns: Returns:
The right part of $(D r) after partitioning. The right part of $(D r) after partitioning.
@ -7918,6 +7951,10 @@ r = partition!(fun, SwapStrategy.semistable)(arr);
// Now arr is [4 5 6 7 8 9 10 2 3 1] and r points to 2 // Now arr is [4 5 6 7 8 9 10 2 3 1] and r points to 2
assert(arr == [4, 5, 6, 7, 8, 9, 10, 2, 3, 1] && r == arr[7 .. $]); assert(arr == [4, 5, 6, 7, 8, 9, 10, 2, 3, 1] && r == arr[7 .. $]);
---- ----
See_Also:
STL's $(WEB sgi.com/tech/stl/_partition.html, _partition)$(BR)
STL's $(WEB sgi.com/tech/stl/stable_partition.html, stable_partition)
*/ */
Range partition(alias predicate, Range partition(alias predicate,
SwapStrategy ss = SwapStrategy.unstable, Range)(Range r) SwapStrategy ss = SwapStrategy.unstable, Range)(Range r)
@ -8192,8 +8229,7 @@ and all elements $(D e2) from $(D r[nth]) to $(D r[r.length]) satisfy
$(D !less(e2, r[nth])). Effectively, it finds the nth smallest $(D !less(e2, r[nth])). Effectively, it finds the nth smallest
(according to $(D less)) elements in $(D r). Performs an expected (according to $(D less)) elements in $(D r). Performs an expected
$(BIGOH r.length) (if unstable) or $(BIGOH r.length * log(r.length)) $(BIGOH r.length) (if unstable) or $(BIGOH r.length * log(r.length))
(if stable) evaluations of $(D less) and $(D swap). See also $(WEB (if stable) evaluations of $(D less) and $(D swap).
sgi.com/tech/stl/nth_element.html, STL's nth_element).
If $(D n >= r.length), the algorithm has no effect. If $(D n >= r.length), the algorithm has no effect.
@ -8208,6 +8244,9 @@ topN!("a < b")(v, n);
assert(v[n] == 9); assert(v[n] == 9);
---- ----
See_Also:
$(WEB sgi.com/tech/stl/nth_element.html, STL's nth_element)
BUGS: BUGS:
Stable topN has not been implemented yet. Stable topN has not been implemented yet.
@ -8347,8 +8386,8 @@ unittest
Sorts a random-access range according to the predicate $(D less). Performs Sorts a random-access range according to the predicate $(D less). Performs
$(BIGOH r.length * log(r.length)) (if unstable) or $(BIGOH r.length * $(BIGOH r.length * log(r.length)) (if unstable) or $(BIGOH r.length *
log(r.length) * log(r.length)) (if stable) evaluations of $(D less) log(r.length) * log(r.length)) (if stable) evaluations of $(D less)
and $(D swap). See also STL's $(WEB sgi.com/tech/stl/_sort.html, _sort) and $(D swap).
and $(WEB sgi.com/tech/stl/stable_sort.html, stable_sort).
$(D sort) returns a $(XREF range, SortedRange) over the original range, which $(D sort) returns a $(XREF range, SortedRange) over the original range, which
functions that can take advantage of sorted data can then use to know that the functions that can take advantage of sorted data can then use to know that the
@ -8358,7 +8397,9 @@ but other functions won't know that the original range has been sorted, whereas
they $(I can) know that $(XREF range, SortedRange) has been sorted. they $(I can) know that $(XREF range, SortedRange) has been sorted.
See_Also: See_Also:
$(XREF range, assumeSorted) $(XREF range, assumeSorted)$(BR)
STL's $(WEB sgi.com/tech/stl/_sort.html, _sort)$(BR)
$(WEB sgi.com/tech/stl/stable_sort.html, stable_sort)
Remark: Stable sort is implementated as Timsort, the original code at Remark: Stable sort is implementated as Timsort, the original code at
$(WEB github.com/Xinok/XSort, XSort) by Xinok, public domain. $(WEB github.com/Xinok/XSort, XSort) by Xinok, public domain.