Skip to content

std.algorithms: document public methods #4312

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 23, 2016
Merged

std.algorithms: document public methods #4312

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions std/algorithm/comparison.d
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1168,7 +1168,7 @@ size_t levenshteinDistance(alias equals = (a,b) => a == b, Range1, Range2)
assert(levenshteinDistance("cat"d, "rat"d) == 1);
}

// compat overload for alias this strings
/// ditto
size_t levenshteinDistance(alias equals = (a,b) => a == b, Range1, Range2)
(auto ref Range1 s, auto ref Range2 t)
if (isConvertibleToString!Range1 || isConvertibleToString!Range2)
Expand Down Expand Up @@ -1240,7 +1240,7 @@ levenshteinDistanceAndPath(alias equals = (a,b) => a == b, Range1, Range2)
assert(levenshteinDistance("kitten", "sitting") == 3);
}

// compat overload for alias this strings
/// ditto
Tuple!(size_t, EditOp[])
levenshteinDistanceAndPath(alias equals = (a,b) => a == b, Range1, Range2)
(auto ref Range1 s, auto ref Range2 t)
Expand Down
102 changes: 56 additions & 46 deletions std/algorithm/iteration.d
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1319,7 +1319,34 @@ private struct FilterBidiResult(alias pred, Range)
}
}

// group
/**
Groups consecutively equivalent elements into a single tuple of the element and
the number of its repetitions.

Similarly to $(D uniq), $(D group) produces a range that iterates over unique
consecutive elements of the given range. Each element of this range is a tuple
of the element and the number of times it is repeated in the original range.
Equivalence of elements is assessed by using the predicate $(D pred), which
defaults to $(D "a == b"). The predicate is passed to $(XREF functional,binaryFun),
and can either accept a string, or any callable that can be executed via
$(D pred(element, element)).

Params:
pred = Binary predicate for determining equivalence of two elements.
r = The $(XREF_PACK_NAMED range,primitives,isInputRange,input range) to
iterate over.

Returns: A range of elements of type $(D Tuple!(ElementType!R, uint)),
representing each consecutively unique element and its respective number of
occurrences in that run. This will be an input range if $(D R) is an input
range, and a forward range in all other cases.
*/
Group!(pred, Range) group(alias pred = "a == b", Range)(Range r)
{
return typeof(return)(r);
}

/// ditto
struct Group(alias pred, R) if (isInputRange!R)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be under the same docs as its factory function. Same goes for all of the public range structs.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

so /// ditto?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, and you should move it to under the factory function. No one should be using the struct directly, but since it's public we can't make it a static struct without deprecation cycles that are of questional value anyway.

{
import std.typecons : Rebindable, tuple, Tuple;
Expand All @@ -1344,12 +1371,14 @@ struct Group(alias pred, R) if (isInputRange!R)
private R _input;
private Tuple!(MutableE, uint) _current;

///
this(R input)
{
_input = input;
if (!_input.empty) popFront();
}

///
void popFront()
{
if (_input.empty)
Expand All @@ -1370,23 +1399,27 @@ struct Group(alias pred, R) if (isInputRange!R)

static if (isInfinite!R)
{
///
enum bool empty = false; // Propagate infiniteness.
}
else
{
///
@property bool empty()
{
return _current[1] == 0;
}
}

///
@property auto ref front()
{
assert(!empty);
return _current;
}

static if (isForwardRange!R) {
///
@property typeof(this) save() {
typeof(this) ret = this;
ret._input = this._input.save;
Expand All @@ -1396,33 +1429,6 @@ struct Group(alias pred, R) if (isInputRange!R)
}
}

/**
Groups consecutively equivalent elements into a single tuple of the element and
the number of its repetitions.

Similarly to $(D uniq), $(D group) produces a range that iterates over unique
consecutive elements of the given range. Each element of this range is a tuple
of the element and the number of times it is repeated in the original range.
Equivalence of elements is assessed by using the predicate $(D pred), which
defaults to $(D "a == b"). The predicate is passed to $(XREF functional,binaryFun),
and can either accept a string, or any callable that can be executed via
$(D pred(element, element)).

Params:
pred = Binary predicate for determining equivalence of two elements.
r = The $(XREF_PACK_NAMED range,primitives,isInputRange,input range) to
iterate over.

Returns: A range of elements of type $(D Tuple!(ElementType!R, uint)),
representing each consecutively unique element and its respective number of
occurrences in that run. This will be an input range if $(D R) is an input
range, and a forward range in all other cases.
*/
Group!(pred, Range) group(alias pred = "a == b", Range)(Range r)
{
return typeof(return)(r);
}

///
@safe unittest
{
Expand Down Expand Up @@ -4874,13 +4880,31 @@ private struct UniqResult(alias pred, Range)
}
}

// permutations
/**
Lazily computes all _permutations of $(D r) using $(WEB
en.wikipedia.org/wiki/Heap%27s_algorithm, Heap's algorithm).

Returns:
A forward range the elements of which are an $(XREF range,
indexed) view into $(D r).

See_Also:
$(XREF_PACK algorithm,sorting,nextPermutation).
*/
Permutations!Range permutations(Range)(Range r)
if (isRandomAccessRange!Range && hasLength!Range)
{
return typeof(return)(r);
}

/// ditto
struct Permutations(Range)
if (isRandomAccessRange!Range && hasLength!Range)
{
size_t[] indices, state;
Range r;

///
this(Range r)
{
import std.range : iota;
Expand All @@ -4892,14 +4916,17 @@ struct Permutations(Range)
empty = r.length == 0;
}

///
bool empty;

///
@property auto front()
{
import std.range : indexed;
return r.indexed(indices);
}

///
void popFront()
{
void next(int n)
Expand Down Expand Up @@ -4928,23 +4955,6 @@ struct Permutations(Range)
}
}

/**
Lazily computes all _permutations of $(D r) using $(WEB
en.wikipedia.org/wiki/Heap%27s_algorithm, Heap's algorithm).

Returns:
A forward range the elements of which are an $(XREF range,
indexed) view into $(D r).

See_Also:
$(XREF_PACK algorithm,sorting,nextPermutation).
*/
Permutations!Range permutations(Range)(Range r)
if (isRandomAccessRange!Range && hasLength!Range)
{
return typeof(return)(r);
}

///
unittest
{
Expand Down
7 changes: 4 additions & 3 deletions std/algorithm/mutation.d
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1667,7 +1667,7 @@ if (s != SwapStrategy.stable
return range;
}

// Ditto
/// Ditto
Range remove
(SwapStrategy s = SwapStrategy.stable, Range, Offset...)
(Range range, Offset offset)
Expand Down Expand Up @@ -2380,8 +2380,9 @@ unittest
swap(b1, b2);
}

// Not yet documented
void swap(T)(ref T lhs, ref T rhs) if (is(typeof(lhs.proxySwap(rhs))))
/// ditto
void swap(T)(ref T lhs, ref T rhs)
if (is(typeof(lhs.proxySwap(rhs))))
{
lhs.proxySwap(rhs);
}
Expand Down
Loading