mirrors/phobos
1
0
Fork 0
mirror of https://github.com/dlang/phobos.git synced 2025-04-29 22:50:38 +03:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge pull request #5970 from wilzbach/markdownify-algorithm

Browse source 
Markdownify std.algorithm
merged-on-behalf-of: Jack Stouffer <jack@jackstouffer.com>
This commit is contained in:
The Dlang Bot 2018-01-03 15:44:56 +01:00 • committed by GitHub
commit db2d2413b4
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
7 changed files with 652 additions and 660 deletions
Download patch file Download diff file Expand all files Collapse all files

148
std/algorithm/comparison.d
View file

@ -8,41 +8,41 @@ $(BOOKTABLE Cheat Sheet,
$(TR $(TH Function Name) $(TH Description))
$(T2 among,
Checks if a value is among a set of values, e.g.
$(D if (v.among(1, 2, 3)) // `v` is 1, 2 or 3))
`if (v.among(1, 2, 3)) // `v` is 1, 2 or 3`)
$(T2 castSwitch,
$(D (new A()).castSwitch((A a)=>1,(B b)=>2)) returns $(D 1).)
`(new A()).castSwitch((A a)=>1,(B b)=>2)` returns `1`.)
$(T2 clamp,
$(D clamp(1, 3, 6)) returns $(D 3). $(D clamp(4, 3, 6)) returns $(D 4).)
`clamp(1, 3, 6)` returns `3`. `clamp(4, 3, 6)` returns `4`.)
$(T2 cmp,
$(D cmp("abc", "abcd")) is $(D -1), $(D cmp("abc", "aba")) is $(D 1),
and $(D cmp("abc", "abc")) is $(D 0).)
`cmp("abc", "abcd")` is `-1`, `cmp("abc", "aba")` is `1`,
and `cmp("abc", "abc")` is `0`.)
$(T2 either,
Return first parameter $(D p) that passes an $(D if (p)) test, e.g.
$(D either(0, 42, 43)) returns $(D 42).)
Return first parameter `p` that passes an `if (p)` test, e.g.
`either(0, 42, 43)` returns `42`.)
$(T2 equal,
Compares ranges for element-by-element equality, e.g.
$(D equal([1, 2, 3], [1.0, 2.0, 3.0])) returns $(D true).)
`equal([1, 2, 3], [1.0, 2.0, 3.0])` returns `true`.)
$(T2 isPermutation,
$(D isPermutation([1, 2], [2, 1])) returns $(D true).)
`isPermutation([1, 2], [2, 1])` returns `true`.)
$(T2 isSameLength,
$(D isSameLength([1, 2, 3], [4, 5, 6])) returns $(D true).)
`isSameLength([1, 2, 3], [4, 5, 6])` returns `true`.)
$(T2 levenshteinDistance,
$(D levenshteinDistance("kitten", "sitting")) returns $(D 3) by using
`levenshteinDistance("kitten", "sitting")` returns `3` by using
the $(LINK2 https://en.wikipedia.org/wiki/Levenshtein_distance,
Levenshtein distance _algorithm).)
$(T2 levenshteinDistanceAndPath,
$(D levenshteinDistanceAndPath("kitten", "sitting")) returns
$(D tuple(3, "snnnsni")) by using the
`levenshteinDistanceAndPath("kitten", "sitting")` returns
`tuple(3, "snnnsni")` by using the
$(LINK2 https://en.wikipedia.org/wiki/Levenshtein_distance,
Levenshtein distance _algorithm).)
$(T2 max,
$(D max(3, 4, 2)) returns $(D 4).)
`max(3, 4, 2)` returns `4`.)
$(T2 min,
$(D min(3, 4, 2)) returns $(D 2).)
`min(3, 4, 2)` returns `2`.)
$(T2 mismatch,
$(D mismatch("oh hi", "ohayo")) returns $(D tuple(" hi", "ayo")).)
`mismatch("oh hi", "ohayo")` returns `tuple(" hi", "ayo")`.)
$(T2 predSwitch,
$(D 2.predSwitch(1, "one", 2, "two", 3, "three")) returns $(D "two").)
`2.predSwitch(1, "one", 2, "two", 3, "three")` returns `"two"`.)
)
Copyright: Andrei Alexandrescu 2008-.
@ -67,9 +67,9 @@ import std.meta : allSatisfy;
import std.typecons; // : tuple, Tuple, Flag, Yes;
/**
Find $(D value) _among $(D values), returning the 1-based index
of the first matching value in $(D values), or $(D 0) if $(D value)
is not _among $(D values). The predicate $(D pred) is used to
Find `value` _among `values`, returning the 1-based index
of the first matching value in `values`, or `0` if `value`
is not _among `values`. The predicate `pred` is used to
compare values, and uses equality by default.
Params:
@ -130,7 +130,7 @@ if (isExpressionTuple!values)
}
/**
Alternatively, $(D values) can be passed at compile-time, allowing for a more
Alternatively, `values` can be passed at compile-time, allowing for a more
efficient search, but one that only supports matching on equality:
*/
@safe unittest
@ -214,19 +214,19 @@ private template indexOfFirstOvershadowingChoiceOnLast(choices...)
Executes and returns one of a collection of handlers based on the type of the
switch object.
The first choice that $(D switchObject) can be casted to the type
of argument it accepts will be called with $(D switchObject) casted to that
type, and the value it'll return will be returned by $(D castSwitch).
The first choice that `switchObject` can be casted to the type
of argument it accepts will be called with `switchObject` casted to that
type, and the value it'll return will be returned by `castSwitch`.
If a choice's return type is void, the choice must throw an exception, unless
all the choices are void. In that case, castSwitch itself will return void.
Throws: If none of the choice matches, a $(D SwitchError) will be thrown. $(D
Throws: If none of the choice matches, a `SwitchError` will be thrown. $(D
SwitchError) will also be thrown if not all the choices are void and a void
choice was executed without throwing anything.
Params:
choices = The $(D choices) needs to be composed of function or delegate
choices = The `choices` needs to be composed of function or delegate
handlers that accept one argument. There can also be a choice that
accepts zero arguments. That choice will be invoked if the $(D
switchObject) is null.
@ -235,7 +235,7 @@ Params:
Returns:
The value of the selected choice.
Note: $(D castSwitch) can only be used with object types.
Note: `castSwitch` can only be used with object types.
*/
auto castSwitch(choices...)(Object switchObject)
{
@ -517,7 +517,7 @@ auto castSwitch(choices...)(Object switchObject)
/** Clamps a value into the given bounds.
This functions is equivalent to $(D max(lower, min(upper,val))).
This functions is equivalent to `max(lower, min(upper,val))`.
Params:
val = The value to _clamp.
@ -525,7 +525,7 @@ Params:
upper = The _upper bound of the _clamp.
Returns:
Returns $(D val), if it is between $(D lower) and $(D upper).
Returns `val`, if it is between `lower` and `upper`.
Otherwise returns the nearest of the two.
*/
@ -582,15 +582,15 @@ do
/**********************************
Performs three-way lexicographical comparison on two
$(REF_ALTTEXT input ranges, isInputRange, std,range,primitives)
according to predicate $(D pred). Iterating $(D r1) and $(D r2) in
lockstep, $(D cmp) compares each element $(D e1) of $(D r1) with the
corresponding element $(D e2) in $(D r2). If one of the ranges has been
finished, $(D cmp) returns a negative value if $(D r1) has fewer
elements than $(D r2), a positive value if $(D r1) has more elements
than $(D r2), and $(D 0) if the ranges have the same number of
according to predicate `pred`. Iterating `r1` and `r2` in
lockstep, `cmp` compares each element `e1` of `r1` with the
corresponding element `e2` in `r2`. If one of the ranges has been
finished, `cmp` returns a negative value if `r1` has fewer
elements than `r2`, a positive value if `r1` has more elements
than `r2`, and `0` if the ranges have the same number of
elements.
If the ranges are strings, $(D cmp) performs UTF decoding
If the ranges are strings, `cmp` performs UTF decoding
appropriately and compares the ranges one code point at a time.
Params:
@ -600,9 +600,9 @@ Params:
Returns:
0 if both ranges compare equal. -1 if the first differing element of $(D
r1) is less than the corresponding element of $(D r2) according to $(D
pred). 1 if the first differing element of $(D r2) is less than the
corresponding element of $(D r1) according to $(D pred).
r1) is less than the corresponding element of `r2` according to $(D
pred). 1 if the first differing element of `r2` is less than the
corresponding element of `r1` according to `pred`.
*/
int cmp(alias pred = "a < b", R1, R2)(R1 r1, R2 r2)
@ -726,8 +726,8 @@ if (isInputRange!R1 && isInputRange!R2)
// equal
/**
Compares two ranges for equality, as defined by predicate $(D pred)
(which is $(D ==) by default).
Compares two ranges for equality, as defined by predicate `pred`
(which is `==` by default).
*/
template equal(alias pred = "a == b")
{
@ -738,17 +738,17 @@ template equal(alias pred = "a == b")
/++
Compares two ranges for equality. The ranges may have
different element types, as long as $(D pred(r1.front, r2.front))
evaluates to $(D bool).
Performs $(BIGOH min(r1.length, r2.length)) evaluations of $(D pred).
different element types, as long as `pred(r1.front, r2.front)`
evaluates to `bool`.
Performs $(BIGOH min(r1.length, r2.length)) evaluations of `pred`.
Params:
r1 = The first range to be compared.
r2 = The second range to be compared.
Returns:
$(D true) if and only if the two ranges compare _equal element
for element, according to binary predicate $(D pred).
`true` if and only if the two ranges compare _equal element
for element, according to binary predicate `pred`.
See_Also:
$(HTTP sgi.com/tech/stl/_equal.html, STL's _equal)
@ -844,9 +844,9 @@ template equal(alias pred = "a == b")
}
/++
Tip: $(D equal) can itself be used as a predicate to other functions.
Tip: `equal` can itself be used as a predicate to other functions.
This can be very useful when the element type of a range is itself a
range. In particular, $(D equal) can be its own predicate, allowing
range. In particular, `equal` can be its own predicate, allowing
range of range (of range...) comparisons.
+/
@safe unittest
@ -983,10 +983,10 @@ if (T.length >= 1)
/**
Encodes $(HTTP realityinteractive.com/rgrzywinski/archives/000249.html,
edit operations) necessary to transform one sequence into
another. Given sequences $(D s) (source) and $(D t) (target), a
sequence of $(D EditOp) encodes the steps that need to be taken to
convert $(D s) into $(D t). For example, if $(D s = "cat") and $(D
"cars"), the minimal sequence that transforms $(D s) into $(D t) is:
another. Given sequences `s` (source) and `t` (target), a
sequence of `EditOp` encodes the steps that need to be taken to
convert `s` into `t`. For example, if `s = "cat"` and $(D
"cars"), the minimal sequence that transforms `s` into `t` is:
skip two characters, replace 't' with 'r', and insert an 's'. Working
with edit operations is useful in applications such as spell-checkers
(to find the closest word to a given misspelled word), approximate
@ -1193,9 +1193,9 @@ private:
/**
Returns the $(HTTP wikipedia.org/wiki/Levenshtein_distance, Levenshtein
distance) between $(D s) and $(D t). The Levenshtein distance computes
the minimal amount of edit operations necessary to transform $(D s)
into $(D t). Performs $(BIGOH s.length * t.length) evaluations of $(D
distance) between `s` and `t`. The Levenshtein distance computes
the minimal amount of edit operations necessary to transform `s`
into `t`. Performs $(BIGOH s.length * t.length) evaluations of $(D
equals) and occupies $(BIGOH s.length * t.length) storage.
Params:
@ -1305,8 +1305,8 @@ if (isConvertibleToString!Range1 || isConvertibleToString!Range2)
}
/**
Returns the Levenshtein distance and the edit path between $(D s) and
$(D t).
Returns the Levenshtein distance and the edit path between `s` and
`t`.
Params:
equals = The binary predicate to compare the elements of the two ranges.
@ -1555,11 +1555,11 @@ if (T.length >= 2)
// mismatch
/**
Sequentially compares elements in $(D r1) and $(D r2) in lockstep, and
stops at the first mismatch (according to $(D pred), by default
Sequentially compares elements in `r1` and `r2` in lockstep, and
stops at the first mismatch (according to `pred`, by default
equality). Returns a tuple with the reduced ranges that start with the
two mismatched values. Performs $(BIGOH min(r1.length, r2.length))
evaluations of $(D pred).
evaluations of `pred`.
See_Also:
$(HTTP sgi.com/tech/stl/_mismatch.html, STL's _mismatch)
@ -1598,9 +1598,9 @@ if (isInputRange!(Range1) && isInputRange!(Range2))
Returns one of a collection of expressions based on the value of the switch
expression.
$(D choices) needs to be composed of pairs of test expressions and return
expressions. Each test-expression is compared with $(D switchExpression) using
$(D pred)($(D switchExpression) is the first argument) and if that yields true
`choices` needs to be composed of pairs of test expressions and return
expressions. Each test-expression is compared with `switchExpression` using
`pred`(`switchExpression` is the first argument) and if that yields true
- the return expression is returned.
Both the test and the return expressions are lazily evaluated.
@ -1622,7 +1622,7 @@ made the predicate yield true, or the default return expression if no test
expression matched.
Throws: If there is no default return expression and the predicate does not
yield true with any test expression - $(D SwitchError) is thrown. $(D
yield true with any test expression - `SwitchError` is thrown. $(D
SwitchError) is also thrown if a void return expression was executed without
throwing anything.
*/
@ -1734,7 +1734,7 @@ auto predSwitch(alias pred = "a == b", T, R ...)(T switchExpression, lazy R choi
/**
Checks if the two ranges have the same number of elements. This function is
optimized to always take advantage of the $(D length) member of either range
optimized to always take advantage of the `length` member of either range
if it exists.
If both ranges have a length member, this function is $(BIGOH 1). Otherwise,
@ -1745,7 +1745,7 @@ Params:
r2 = a finite $(REF_ALTTEXT input range, isInputRange, std,range,primitives)
Returns:
$(D true) if both ranges have the same length, $(D false) otherwise.
`true` if both ranges have the same length, `false` otherwise.
*/
bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2)
if (isInputRange!Range1 &&
@ -1867,27 +1867,27 @@ alias AllocateGC = Flag!"allocateGC";
/**
Checks if both ranges are permutations of each other.
This function can allocate if the $(D Yes.allocateGC) flag is passed. This has
the benefit of have better complexity than the $(D Yes.allocateGC) option. However,
This function can allocate if the `Yes.allocateGC` flag is passed. This has
the benefit of have better complexity than the `Yes.allocateGC` option. However,
this option is only available for ranges whose equality can be determined via each
element's $(D toHash) method. If customized equality is needed, then the $(D pred)
element's `toHash` method. If customized equality is needed, then the `pred`
template parameter can be passed, and the function will automatically switch to
the non-allocating algorithm. See $(REF binaryFun, std,functional) for more details on
how to define $(D pred).
how to define `pred`.
Non-allocating forward range option: $(BIGOH n^2)
Non-allocating forward range option with custom $(D pred): $(BIGOH n^2)
Non-allocating forward range option with custom `pred`: $(BIGOH n^2)
Allocating forward range option: amortized $(BIGOH r1.length) + $(BIGOH r2.length)
Params:
pred = an optional parameter to change how equality is defined
allocate_gc = $(D Yes.allocateGC)/$(D No.allocateGC)
allocate_gc = `Yes.allocateGC`/`No.allocateGC`
r1 = A finite $(REF_ALTTEXT forward range, isForwardRange, std,range,primitives)
r2 = A finite $(REF_ALTTEXT forward range, isForwardRange, std,range,primitives)
Returns:
$(D true) if all of the elements in $(D r1) appear the same number of times in $(D r2).
Otherwise, returns $(D false).
`true` if all of the elements in `r1` appear the same number of times in `r2`.
Otherwise, returns `false`.
*/
bool isPermutation(AllocateGC allocate_gc, Range1, Range2)

318
std/algorithm/iteration.d
View file

@ -7,48 +7,48 @@ $(SCRIPT inhibitQuickIndex = 1;)
$(BOOKTABLE Cheat Sheet,
$(TR $(TH Function Name) $(TH Description))
$(T2 cache,
Eagerly evaluates and caches another range's $(D front).)
Eagerly evaluates and caches another range's `front`.)
$(T2 cacheBidirectional,
As above, but also provides $(D back) and $(D popBack).)
As above, but also provides `back` and `popBack`.)
$(T2 chunkBy,
$(D chunkBy!((a,b) => a[1] == b[1])([[1, 1], [1, 2], [2, 2], [2, 1]]))
`chunkBy!((a,b) => a[1] == b[1])([[1, 1], [1, 2], [2, 2], [2, 1]])`
returns a range containing 3 subranges: the first with just
$(D [1, 1]); the second with the elements $(D [1, 2]) and $(D [2, 2]);
and the third with just $(D [2, 1]).)
`[1, 1]`; the second with the elements `[1, 2]` and `[2, 2]`;
and the third with just `[2, 1]`.)
$(T2 cumulativeFold,
$(D cumulativeFold!((a, b) => a + b)([1, 2, 3, 4])) returns a
`cumulativeFold!((a, b) => a + b)([1, 2, 3, 4])` returns a
lazily-evaluated range containing the successive reduced values `1`,
`3`, `6`, `10`.)
$(T2 each,
$(D each!writeln([1, 2, 3])) eagerly prints the numbers $(D 1), $(D 2)
and $(D 3) on their own lines.)
`each!writeln([1, 2, 3])` eagerly prints the numbers `1`, `2`
and `3` on their own lines.)
$(T2 filter,
$(D filter!(a => a > 0)([1, -1, 2, 0, -3])) iterates over elements $(D 1)
and $(D 2).)
`filter!(a => a > 0)([1, -1, 2, 0, -3])` iterates over elements `1`
and `2`.)
$(T2 filterBidirectional,
Similar to $(D filter), but also provides $(D back) and $(D popBack) at
Similar to `filter`, but also provides `back` and `popBack` at
a small increase in cost.)
$(T2 fold,
$(D fold!((a, b) => a + b)([1, 2, 3, 4])) returns $(D 10).)
`fold!((a, b) => a + b)([1, 2, 3, 4])` returns `10`.)
$(T2 group,
$(D group([5, 2, 2, 3, 3])) returns a range containing the tuples
$(D tuple(5, 1)), $(D tuple(2, 2)), and $(D tuple(3, 2)).)
`group([5, 2, 2, 3, 3])` returns a range containing the tuples
`tuple(5, 1)`, `tuple(2, 2)`, and `tuple(3, 2)`.)
$(T2 joiner,
$(D joiner(["hello", "world!"], "; ")) returns a range that iterates
over the characters $(D "hello; world!"). No new string is created -
`joiner(["hello", "world!"], "; ")` returns a range that iterates
over the characters `"hello; world!"`. No new string is created -
the existing inputs are iterated.)
$(T2 map,
$(D map!(a => a * 2)([1, 2, 3])) lazily returns a range with the numbers
$(D 2), $(D 4), $(D 6).)
`map!(a => a * 2)([1, 2, 3])` lazily returns a range with the numbers
`2`, `4`, `6`.)
$(T2 permutations,
Lazily computes all permutations using Heap's algorithm.)
$(T2 reduce,
$(D reduce!((a, b) => a + b)([1, 2, 3, 4])) returns $(D 10).
`reduce!((a, b) => a + b)([1, 2, 3, 4])` returns `10`.
This is the old implementation of `fold`.)
$(T2 splitter,
Lazily splits a range by a separator.)
$(T2 sum,
Same as $(D fold), but specialized for accurate summation.)
Same as `fold`, but specialized for accurate summation.)
$(T2 uniq,
Iterates over the unique elements in a range, which is assumed sorted.)
)
@ -117,29 +117,29 @@ if (fun.length >= 1)
}
/++
$(D cache) eagerly evaluates $(D front) of $(D range)
on each construction or call to $(D popFront),
`cache` eagerly evaluates `front` of `range`
on each construction or call to `popFront`,
to store the result in a _cache.
The result is then directly returned when $(D front) is called,
The result is then directly returned when `front` is called,
rather than re-evaluated.
This can be a useful function to place in a chain, after functions
that have expensive evaluation, as a lazy alternative to $(REF array, std,array).
In particular, it can be placed after a call to $(D map), or before a call
to $(D filter).
In particular, it can be placed after a call to `map`, or before a call
to `filter`.
$(D cache) may provide
`cache` may provide
$(REF_ALTTEXT bidirectional _range, isBidirectionalRange, std,_range,primitives)
iteration if needed, but since this comes at an increased cost, it must be explicitly requested via the
call to $(D cacheBidirectional). Furthermore, a bidirectional _cache will
call to `cacheBidirectional`. Furthermore, a bidirectional _cache will
evaluate the "center" element twice, when there is only one element left in
the _range.
$(D cache) does not provide random access primitives,
as $(D cache) would be unable to _cache the random accesses.
If $(D Range) provides slicing primitives,
then $(D cache) will provide the same slicing primitives,
but $(D hasSlicing!Cache) will not yield true (as the $(REF hasSlicing, std,_range,primitives)
`cache` does not provide random access primitives,
as `cache` would be unable to _cache the random accesses.
If `Range` provides slicing primitives,
then `cache` will provide the same slicing primitives,
but `hasSlicing!Cache` will not yield true (as the $(REF hasSlicing, std,_range,primitives)
trait also checks for random access).
Params:
@ -204,14 +204,14 @@ if (isBidirectionalRange!Range)
}
/++
Tip: $(D cache) is eager when evaluating elements. If calling front on the
Tip: `cache` is eager when evaluating elements. If calling front on the
underlying _range has a side effect, it will be observable before calling
front on the actual cached _range.
Furthermore, care should be taken composing $(D cache) with $(REF take, std,_range).
By placing $(D take) before $(D cache), then $(D cache) will be "aware"
Furthermore, care should be taken composing `cache` with $(REF take, std,_range).
By placing `take` before `cache`, then `cache` will be "aware"
of when the _range ends, and correctly stop caching elements when needed.
If calling front has no side effect though, placing $(D take) after $(D cache)
If calling front has no side effect though, placing `take` after `cache`
may yield a faster _range.
Either way, the resulting ranges will be equivalent, but maybe not at the
@ -440,12 +440,12 @@ private struct _Cache(R, bool bidir)
}
/**
$(D auto map(Range)(Range r) if (isInputRange!(Unqual!Range));)
`auto map(Range)(Range r) if (isInputRange!(Unqual!Range));`
Implements the homonym function (also known as $(D transform)) present
in many languages of functional flavor. The call $(D map!(fun)(range))
returns a range of which elements are obtained by applying $(D fun(a))
left to right for all elements $(D a) in $(D range). The original ranges are
Implements the homonym function (also known as `transform`) present
in many languages of functional flavor. The call `map!(fun)(range)`
returns a range of which elements are obtained by applying `fun(a)`
left to right for all elements `a` in `range`. The original ranges are
not changed. Evaluation is done lazily.
Params:
@ -454,7 +454,7 @@ Params:
Returns:
a range with each fun applied to all the elements. If there is more than one
fun, the element type will be $(D Tuple) containing one element for each fun.
fun, the element type will be `Tuple` containing one element for each fun.
See_Also:
$(HTTP en.wikipedia.org/wiki/Map_(higher-order_function), Map (higher-order function))
@ -508,8 +508,8 @@ if (fun.length >= 1)
}
/**
Multiple functions can be passed to $(D map). In that case, the
element type of $(D map) is a tuple containing one element for each
Multiple functions can be passed to `map`. In that case, the
element type of `map` is a tuple containing one element for each
function.
*/
@safe unittest
@ -527,7 +527,7 @@ function.
}
/**
You may alias $(D map) with some function(s) to a symbol and use
You may alias `map` with some function(s) to a symbol and use
it separately:
*/
@safe unittest
@ -844,14 +844,14 @@ private struct MapResult(alias fun, Range)
// each
/**
Eagerly iterates over $(D r) and calls $(D pred) over _each element.
Eagerly iterates over `r` and calls `pred` over _each element.
If no predicate is specified, $(D each) will default to doing nothing
but consuming the entire range. $(D .front) will be evaluated, but this
If no predicate is specified, `each` will default to doing nothing
but consuming the entire range. `.front` will be evaluated, but this
can be avoided by explicitly specifying a predicate lambda with a
$(D lazy) parameter.
`lazy` parameter.
$(D each) also supports $(D opApply)-based iterators, so it will work
`each` also supports `opApply`-based iterators, so it will work
with e.g. $(REF parallel, std,parallelism).
Params:
@ -1081,19 +1081,19 @@ public:
// filter
/**
$(D auto filter(Range)(Range rs) if (isInputRange!(Unqual!Range));)
`auto filter(Range)(Range rs) if (isInputRange!(Unqual!Range));`
Implements the higher order _filter function. The predicate is passed to
$(REF unaryFun, std,functional), and can either accept a string, or any callable
that can be executed via $(D pred(element)).
that can be executed via `pred(element)`.
Params:
predicate = Function to apply to each element of range
range = Input range of elements
Returns:
$(D filter!(predicate)(range)) returns a new range containing only elements $(D x) in $(D range) for
which $(D predicate(x)) returns $(D true).
`filter!(predicate)(range)` returns a new range containing only elements `x` in `range` for
which `predicate(x)` returns `true`.
See_Also:
$(HTTP en.wikipedia.org/wiki/Filter_(higher-order_function), Filter (higher-order function))
@ -1299,9 +1299,9 @@ private struct FilterResult(alias pred, Range)
}
/**
* $(D auto filterBidirectional(Range)(Range r) if (isBidirectionalRange!(Unqual!Range));)
* `auto filterBidirectional(Range)(Range r) if (isBidirectionalRange!(Unqual!Range));`
*
* Similar to $(D filter), except it defines a
* Similar to `filter`, except it defines a
* $(REF_ALTTEXT bidirectional range, isBidirectionalRange, std,range,primitives).
* There is a speed disadvantage - the constructor spends time
* finding the last element in the range that satisfies the filtering
@ -1310,14 +1310,14 @@ private struct FilterResult(alias pred, Range)
* $(REF retro, std,range) can be applied against the filtered range.
*
* The predicate is passed to $(REF unaryFun, std,functional), and can either
* accept a string, or any callable that can be executed via $(D pred(element)).
* accept a string, or any callable that can be executed via `pred(element)`.
*
* Params:
* pred = Function to apply to each element of range
* r = Bidirectional range of elements
*
* Returns:
* a new range containing only the elements in r for which pred returns $(D true).
* a new range containing only the elements in r for which pred returns `true`.
*/
template filterBidirectional(alias pred)
{
@ -1398,22 +1398,22 @@ private struct FilterBidiResult(alias pred, Range)
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
Similarly to `uniq`, `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 $(REF binaryFun, std,functional),
Equivalence of elements is assessed by using the predicate `pred`, which
defaults to `"a == b"`. The predicate is passed to $(REF binaryFun, std,functional),
and can either accept a string, or any callable that can be executed via
$(D pred(element, element)).
`pred(element, element)`.
Params:
pred = Binary predicate for determining equivalence of two elements.
r = The $(REF_ALTTEXT input range, isInputRange, std,range,primitives) to
iterate over.
Returns: A range of elements of type $(D Tuple!(ElementType!R, uint)),
Returns: A range of elements of type `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
occurrences in that run. This will be an input range if `R` is an input
range, and a forward range in all other cases.
See_Also: $(LREF chunkBy), which chunks an input range into subranges
@ -1886,17 +1886,17 @@ if (isForwardRange!Range)
* In other languages this is often called `partitionBy`, `groupBy`
* or `sliceWhen`.
*
* Equivalence is defined by the predicate $(D pred), which can be either
* Equivalence is defined by the predicate `pred`, which can be either
* binary, which is passed to $(REF binaryFun, std,functional), or unary, which is
* passed to $(REF unaryFun, std,functional). In the binary form, two _range elements
* $(D a) and $(D b) are considered equivalent if $(D pred(a,b)) is true. In
* unary form, two elements are considered equivalent if $(D pred(a) == pred(b))
* `a` and `b` are considered equivalent if `pred(a,b)` is true. In
* unary form, two elements are considered equivalent if `pred(a) == pred(b)`
* is true.
*
* This predicate must be an equivalence relation, that is, it must be
* reflexive ($(D pred(x,x)) is always true), symmetric
* ($(D pred(x,y) == pred(y,x))), and transitive ($(D pred(x,y) && pred(y,z))
* implies $(D pred(x,z))). If this is not the case, the range returned by
* reflexive (`pred(x,x)` is always true), symmetric
* (`pred(x,y) == pred(y,x)`), and transitive (`pred(x,y) && pred(y,z)`
* implies `pred(x,z)`). If this is not the case, the range returned by
* chunkBy may assert at runtime or behave erratically.
*
* Params:
@ -2128,7 +2128,7 @@ Params:
Returns:
A range of elements in the joined range. This will be a forward range if
both outer and inner ranges of $(D RoR) are forward ranges; otherwise it will
both outer and inner ranges of `RoR` are forward ranges; otherwise it will
be only an input range.
See_also:
@ -2726,20 +2726,20 @@ if (isInputRange!RoR && isInputRange!(ElementType!RoR))
}
/++
Implements the homonym function (also known as $(D accumulate), $(D
compress), $(D inject), or $(D foldl)) present in various programming
Implements the homonym function (also known as `accumulate`, $(D
compress), `inject`, or `foldl`) present in various programming
languages of functional flavor. There is also $(LREF fold) which does
the same thing but with the opposite parameter order.
The call $(D reduce!(fun)(seed, range)) first assigns $(D seed) to
an internal variable $(D result), also called the accumulator.
Then, for each element $(D x) in $(D range), $(D result = fun(result, x))
gets evaluated. Finally, $(D result) is returned.
The one-argument version $(D reduce!(fun)(range))
The call `reduce!(fun)(seed, range)` first assigns `seed` to
an internal variable `result`, also called the accumulator.
Then, for each element `x` in `range`, `result = fun(result, x)`
gets evaluated. Finally, `result` is returned.
The one-argument version `reduce!(fun)(range)`
works similarly, but it uses the first element of the range as the
seed (the range must be non-empty).
Returns:
the accumulated $(D result)
the accumulated `result`
Params:
fun = one or more functions
@ -2751,7 +2751,7 @@ See_Also:
and without the need to use $(LREF tuple) for multiple seeds. This makes it easier
to use in UFCS chains.
$(LREF sum) is similar to $(D reduce!((a, b) => a + b)) that offers
$(LREF sum) is similar to `reduce!((a, b) => a + b)` that offers
pairwise summing of floating point numbers.
+/
template reduce(fun...)
@ -2764,20 +2764,20 @@ if (fun.length >= 1)
import std.typecons : tuple, isTuple;
/++
No-seed version. The first element of $(D r) is used as the seed's value.
No-seed version. The first element of `r` is used as the seed's value.
For each function $(D f) in $(D fun), the corresponding
seed type $(D S) is $(D Unqual!(typeof(f(e, e)))), where $(D e) is an
element of $(D r): $(D ElementType!R) for ranges,
and $(D ForeachType!R) otherwise.
For each function `f` in `fun`, the corresponding
seed type `S` is `Unqual!(typeof(f(e, e)))`, where `e` is an
element of `r`: `ElementType!R` for ranges,
and `ForeachType!R` otherwise.
Once S has been determined, then $(D S s = e;) and $(D s = f(s, e);)
Once S has been determined, then `S s = e;` and `s = f(s, e);`
must both be legal.
If $(D r) is empty, an $(D Exception) is thrown.
If `r` is empty, an `Exception` is thrown.
Params:
r = an iterable value as defined by $(D isIterable)
r = an iterable value as defined by `isIterable`
Returns:
the final result of the accumulator applied to the iterable
@ -2804,19 +2804,19 @@ if (fun.length >= 1)
}
/++
Seed version. The seed should be a single value if $(D fun) is a
single function. If $(D fun) is multiple functions, then $(D seed)
should be a $(REF Tuple, std,typecons), with one field per function in $(D f).
Seed version. The seed should be a single value if `fun` is a
single function. If `fun` is multiple functions, then `seed`
should be a $(REF Tuple, std,typecons), with one field per function in `f`.
For convenience, if the seed is const, or has qualified fields, then
$(D reduce) will operate on an unqualified copy. If this happens
then the returned type will not perfectly match $(D S).
`reduce` will operate on an unqualified copy. If this happens
then the returned type will not perfectly match `S`.
Use $(D fold) instead of $(D reduce) to use the seed version in a UFCS chain.
Use `fold` instead of `reduce` to use the seed version in a UFCS chain.
Params:
seed = the initial value of the accumulator
r = an iterable value as defined by $(D isIterable)
r = an iterable value as defined by `isIterable`
Returns:
the final result of the accumulator applied to the iterable
@ -2891,8 +2891,8 @@ if (fun.length >= 1)
}
/**
Many aggregate range operations turn out to be solved with $(D reduce)
quickly and easily. The example below illustrates $(D reduce)'s
Many aggregate range operations turn out to be solved with `reduce`
quickly and easily. The example below illustrates `reduce`'s
remarkable power and flexibility.
*/
@safe unittest
@ -2945,8 +2945,8 @@ remarkable power and flexibility.
/**
Sometimes it is very useful to compute multiple aggregates in one pass.
One advantage is that the computation is faster because the looping overhead
is shared. That's why $(D reduce) accepts multiple functions.
If two or more functions are passed, $(D reduce) returns a
is shared. That's why `reduce` accepts multiple functions.
If two or more functions are passed, `reduce` returns a
$(REF Tuple, std,typecons) object with one member per passed-in function.
The number of seeds must be correspondingly increased.
*/
@ -3187,23 +3187,23 @@ private template ReduceSeedType(E)
/++
Implements the homonym function (also known as $(D accumulate), $(D
compress), $(D inject), or $(D foldl)) present in various programming
languages of functional flavor. The call $(D fold!(fun)(range, seed))
first assigns $(D seed) to an internal variable $(D result),
also called the accumulator. Then, for each element $(D x) in $(D
range), $(D result = fun(result, x)) gets evaluated. Finally, $(D
result) is returned. The one-argument version $(D fold!(fun)(range))
Implements the homonym function (also known as `accumulate`, $(D
compress), `inject`, or `foldl`) present in various programming
languages of functional flavor. The call `fold!(fun)(range, seed)`
first assigns `seed` to an internal variable `result`,
also called the accumulator. Then, for each element `x` in $(D
range), `result = fun(result, x)` gets evaluated. Finally, $(D
result) is returned. The one-argument version `fold!(fun)(range)`
works similarly, but it uses the first element of the range as the
seed (the range must be non-empty).
Returns:
the accumulated $(D result)
the accumulated `result`
See_Also:
$(HTTP en.wikipedia.org/wiki/Fold_(higher-order_function), Fold (higher-order function))
$(LREF sum) is similar to $(D fold!((a, b) => a + b)) that offers
$(LREF sum) is similar to `fold!((a, b) => a + b)` that offers
precise summing of floating point numbers.
This is functionally equivalent to $(LREF reduce) with the argument order reversed,
@ -3265,12 +3265,12 @@ if (fun.length >= 1)
/++
Similar to `fold`, but returns a range containing the successive reduced values.
The call $(D cumulativeFold!(fun)(range, seed)) first assigns `seed` to an
The call `cumulativeFold!(fun)(range, seed)` first assigns `seed` to an
internal variable `result`, also called the accumulator.
The returned range contains the values $(D result = fun(result, x)) lazily
The returned range contains the values `result = fun(result, x)` lazily
evaluated for each element `x` in `range`. Finally, the last element has the
same value as $(D fold!(fun)(seed, range)).
The one-argument version $(D cumulativeFold!(fun)(range)) works similarly, but
same value as `fold!(fun)(seed, range)`.
The one-argument version `cumulativeFold!(fun)(range)` works similarly, but
it returns the first element unchanged and uses it as seed for the next
elements.
This function is also known as
@ -3299,9 +3299,9 @@ if (fun.length >= 1)
/++
No-seed version. The first element of `r` is used as the seed's value.
For each function `f` in `fun`, the corresponding seed type `S` is
$(D Unqual!(typeof(f(e, e)))), where `e` is an element of `r`:
`Unqual!(typeof(f(e, e)))`, where `e` is an element of `r`:
`ElementType!R`.
Once `S` has been determined, then $(D S s = e;) and $(D s = f(s, e);) must
Once `S` has been determined, then `S s = e;` and `s = f(s, e);` must
both be legal.
Params:
@ -3657,33 +3657,33 @@ any narrow string type or sliceable range type, but is most popular with string
types.
Two adjacent separators are considered to surround an empty element in
the split range. Use $(D filter!(a => !a.empty)) on the result to compress
the split range. Use `filter!(a => !a.empty)` on the result to compress
empty elements.
The predicate is passed to $(REF binaryFun, std,functional), and can either accept
a string, or any callable that can be executed via $(D pred(element, s)).
a string, or any callable that can be executed via `pred(element, s)`.
If the empty range is given, the result is an empty range. If a range with
one separator is given, the result is a range with two empty elements.
If splitting a string on whitespace and token compression is desired,
consider using $(D splitter) without specifying a separator (see fourth overload
consider using `splitter` without specifying a separator (see fourth overload
below).
Params:
pred = The predicate for comparing each element with the separator,
defaulting to $(D "a == b").
defaulting to `"a == b"`.
r = The $(REF_ALTTEXT input range, isInputRange, std,range,primitives) to be
split. Must support slicing and $(D .length).
split. Must support slicing and `.length`.
s = The element to be treated as the separator between range segments to be
split.
Constraints:
The predicate $(D pred) needs to accept an element of $(D r) and the
separator $(D s).
The predicate `pred` needs to accept an element of `r` and the
separator `s`.
Returns:
An input range of the subranges of elements between separators. If $(D r)
An input range of the subranges of elements between separators. If `r`
is a $(REF_ALTTEXT forward range, isForwardRange, std,range,primitives)
or $(REF_ALTTEXT bidirectional range, isBidirectionalRange, std,range,primitives),
the returned range will be likewise.
@ -3965,33 +3965,33 @@ if (is(typeof(binaryFun!pred(r.front, s)) : bool)
}
/**
Similar to the previous overload of $(D splitter), except this one uses another
Similar to the previous overload of `splitter`, except this one uses another
range as a separator. This can be used with any narrow string type or sliceable
range type, but is most popular with string types. The predicate is passed to
$(REF binaryFun, std,functional), and can either accept a string, or any callable
that can be executed via $(D pred(r.front, s.front)).
that can be executed via `pred(r.front, s.front)`.
Two adjacent separators are considered to surround an empty element in
the split range. Use $(D filter!(a => !a.empty)) on the result to compress
the split range. Use `filter!(a => !a.empty)` on the result to compress
empty elements.
Unlike the previous overload of $(D splitter), this one will not return a
Unlike the previous overload of `splitter`, this one will not return a
bidirectional range.
Params:
pred = The predicate for comparing each element with the separator,
defaulting to $(D "a == b").
defaulting to `"a == b"`.
r = The $(REF_ALTTEXT input range, isInputRange, std,range,primitives) to be
split.
s = The $(REF_ALTTEXT forward range, isForwardRange, std,range,primitives) to
be treated as the separator between segments of $(D r) to be split.
be treated as the separator between segments of `r` to be split.
Constraints:
The predicate $(D pred) needs to accept an element of $(D r) and an
element of $(D s).
The predicate `pred` needs to accept an element of `r` and an
element of `s`.
Returns:
An input range of the subranges of elements between separators. If $(D r)
An input range of the subranges of elements between separators. If `r`
is a forward range, the returned range will be a forward range.
See_Also: $(REF _splitter, std,regex) for a version that splits using a regular
@ -4236,13 +4236,13 @@ if (is(typeof(binaryFun!pred(r.front, s.front)) : bool)
/**
Similar to the previous overload of $(D splitter), except this one does not use a separator.
Similar to the previous overload of `splitter`, except this one does not use a separator.
Instead, the predicate is an unary function on the input range's element type.
The $(D isTerminator) predicate is passed to $(REF unaryFun, std,functional) and can
either accept a string, or any callable that can be executed via $(D pred(element, s)).
The `isTerminator` predicate is passed to $(REF unaryFun, std,functional) and can
either accept a string, or any callable that can be executed via `pred(element, s)`.
Two adjacent separators are considered to surround an empty element in
the split range. Use $(D filter!(a => !a.empty)) on the result to compress
the split range. Use `filter!(a => !a.empty)` on the result to compress
empty elements.
Params:
@ -4251,10 +4251,10 @@ Params:
be split.
Constraints:
The predicate $(D isTerminator) needs to accept an element of $(D input).
The predicate `isTerminator` needs to accept an element of `input`.
Returns:
An input range of the subranges of elements between separators. If $(D input)
An input range of the subranges of elements between separators. If `input`
is a forward range or $(REF_ALTTEXT bidirectional range, isBidirectionalRange, std,range,primitives),
the returned range will be likewise.
@ -4494,10 +4494,10 @@ private struct SplitterResult(alias isTerminator, Range)
}
/++
Lazily splits the string $(D s) into words, using whitespace as the delimiter.
Lazily splits the string `s` into words, using whitespace as the delimiter.
This function is string specific and, contrary to
$(D splitter!(std.uni.isWhite)), runs of whitespace will be merged together
`splitter!(std.uni.isWhite)`, runs of whitespace will be merged together
(no empty tokens will be produced).
Params:
@ -4688,43 +4688,43 @@ if (isSomeChar!C)
// sum
/**
Sums elements of $(D r), which must be a finite
Sums elements of `r`, which must be a finite
$(REF_ALTTEXT input range, isInputRange, std,range,primitives). Although
conceptually $(D sum(r)) is equivalent to $(LREF fold)!((a, b) => a +
b)(r, 0), $(D sum) uses specialized algorithms to maximize accuracy,
conceptually `sum(r)` is equivalent to $(LREF fold)!((a, b) => a +
b)(r, 0), `sum` uses specialized algorithms to maximize accuracy,
as follows.
$(UL
$(LI If $(D $(REF ElementType, std,range,primitives)!R) is a floating-point
type and $(D R) is a
$(LI If `$(REF ElementType, std,range,primitives)!R` is a floating-point
type and `R` is a
$(REF_ALTTEXT random-access range, isRandomAccessRange, std,range,primitives) with
length and slicing, then $(D sum) uses the
length and slicing, then `sum` uses the
$(HTTP en.wikipedia.org/wiki/Pairwise_summation, pairwise summation)
algorithm.)
$(LI If $(D ElementType!R) is a floating-point type and $(D R) is a
$(LI If `ElementType!R` is a floating-point type and `R` is a
finite input range (but not a random-access range with slicing), then
$(D sum) uses the $(HTTP en.wikipedia.org/wiki/Kahan_summation,
`sum` uses the $(HTTP en.wikipedia.org/wiki/Kahan_summation,
Kahan summation) algorithm.)
$(LI In all other cases, a simple element by element addition is done.)
)
For floating point inputs, calculations are made in
$(DDLINK spec/type, Types, $(D real))
precision for $(D real) inputs and in $(D double) precision otherwise
(Note this is a special case that deviates from $(D fold)'s behavior,
which would have kept $(D float) precision for a $(D float) range).
$(DDLINK spec/type, Types, `real`)
precision for `real` inputs and in `double` precision otherwise
(Note this is a special case that deviates from `fold`'s behavior,
which would have kept `float` precision for a `float` range).
For all other types, the calculations are done in the same type obtained
from from adding two elements of the range, which may be a different
type from the elements themselves (for example, in case of
$(DDSUBLINK spec/type,integer-promotions, integral promotion)).
A seed may be passed to $(D sum). Not only will this seed be used as an initial
A seed may be passed to `sum`. Not only will this seed be used as an initial
value, but its type will override all the above, and determine the algorithm
and precision used for summation.
Note that these specialized summing algorithms execute more primitive operations
than vanilla summation. Therefore, if in certain cases maximum speed is required
at expense of precision, one can use $(D fold!((a, b) => a + b)(r, 0)), which
at expense of precision, one can use `fold!((a, b) => a + b)(r, 0)`, which
is not specialized for summation.
Params:
@ -5115,10 +5115,10 @@ if (isInputRange!R &&
Lazily iterates unique consecutive elements of the given range (functionality
akin to the $(HTTP wikipedia.org/wiki/_Uniq, _uniq) system
utility). Equivalence of elements is assessed by using the predicate
$(D pred), by default $(D "a == b"). The predicate is passed to
`pred`, by default `"a == b"`. The predicate is passed to
$(REF binaryFun, std,functional), and can either accept a string, or any callable
that can be executed via $(D pred(element, element)). If the given range is
bidirectional, $(D uniq) also yields a
that can be executed via `pred(element, element)`. If the given range is
bidirectional, `uniq` also yields a
$(REF_ALTTEXT bidirectional range, isBidirectionalRange, std,range,primitives).
Params:
@ -5128,7 +5128,7 @@ Params:
Returns:
An $(REF_ALTTEXT input range, isInputRange, std,range,primitives) of
consecutively unique elements in the original range. If $(D r) is also a
consecutively unique elements in the original range. If `r` is also a
forward range or bidirectional range, the returned range will be likewise.
*/
auto uniq(alias pred = "a == b", Range)(Range r)
@ -5261,12 +5261,12 @@ private struct UniqResult(alias pred, Range)
}
/**
Lazily computes all _permutations of $(D r) using $(HTTP
Lazily computes all _permutations of `r` using $(HTTP
en.wikipedia.org/wiki/Heap%27s_algorithm, Heap's algorithm).
Returns:
A $(REF_ALTTEXT forward range, isForwardRange, std,range,primitives)
the elements of which are an $(REF indexed, std,range) view into $(D r).
the elements of which are an $(REF indexed, std,range) view into `r`.
See_Also:
$(REF nextPermutation, std,algorithm,sorting).

182
std/algorithm/mutation.d
View file

@ -7,53 +7,53 @@ $(SCRIPT inhibitQuickIndex = 1;)
$(BOOKTABLE Cheat Sheet,
$(TR $(TH Function Name) $(TH Description))
$(T2 bringToFront,
If $(D a = [1, 2, 3]) and $(D b = [4, 5, 6, 7]),
$(D bringToFront(a, b)) leaves $(D a = [4, 5, 6]) and
$(D b = [7, 1, 2, 3]).)
If `a = [1, 2, 3]` and `b = [4, 5, 6, 7]`,
`bringToFront(a, b)` leaves `a = [4, 5, 6]` and
`b = [7, 1, 2, 3]`.)
$(T2 copy,
Copies a range to another. If
$(D a = [1, 2, 3]) and $(D b = new int[5]), then $(D copy(a, b))
leaves $(D b = [1, 2, 3, 0, 0]) and returns $(D b[3 .. $]).)
`a = [1, 2, 3]` and `b = new int[5]`, then `copy(a, b)`
leaves `b = [1, 2, 3, 0, 0]` and returns `b[3 .. $]`.)
$(T2 fill,
Fills a range with a pattern,
e.g., if $(D a = new int[3]), then $(D fill(a, 4))
leaves $(D a = [4, 4, 4]) and $(D fill(a, [3, 4])) leaves
$(D a = [3, 4, 3]).)
e.g., if `a = new int[3]`, then `fill(a, 4)`
leaves `a = [4, 4, 4]` and `fill(a, [3, 4])` leaves
`a = [3, 4, 3]`.)
$(T2 initializeAll,
If $(D a = [1.2, 3.4]), then $(D initializeAll(a)) leaves
$(D a = [double.init, double.init]).)
If `a = [1.2, 3.4]`, then `initializeAll(a)` leaves
`a = [double.init, double.init]`.)
$(T2 move,
$(D move(a, b)) moves $(D a) into $(D b). $(D move(a)) reads $(D a)
`move(a, b)` moves `a` into `b`. `move(a)` reads `a`
destructively when necessary.)
$(T2 moveEmplace,
Similar to $(D move) but assumes `target` is uninitialized.)
Similar to `move` but assumes `target` is uninitialized.)
$(T2 moveAll,
Moves all elements from one range to another.)
$(T2 moveEmplaceAll,
Similar to $(D moveAll) but assumes all elements in `target` are uninitialized.)
Similar to `moveAll` but assumes all elements in `target` are uninitialized.)
$(T2 moveSome,
Moves as many elements as possible from one range to another.)
$(T2 moveEmplaceSome,
Similar to $(D moveSome) but assumes all elements in `target` are uninitialized.)
Similar to `moveSome` but assumes all elements in `target` are uninitialized.)
$(T2 remove,
Removes elements from a range in-place, and returns the shortened
range.)
$(T2 reverse,
If $(D a = [1, 2, 3]), $(D reverse(a)) changes it to $(D [3, 2, 1]).)
If `a = [1, 2, 3]`, `reverse(a)` changes it to `[3, 2, 1]`.)
$(T2 strip,
Strips all leading and trailing elements equal to a value, or that
satisfy a predicate.
If $(D a = [1, 1, 0, 1, 1]), then $(D strip(a, 1)) and
$(D strip!(e => e == 1)(a)) returns $(D [0]).)
If `a = [1, 1, 0, 1, 1]`, then `strip(a, 1)` and
`strip!(e => e == 1)(a)` returns `[0]`.)
$(T2 stripLeft,
Strips all leading elements equal to a value, or that satisfy a
predicate. If $(D a = [1, 1, 0, 1, 1]), then $(D stripLeft(a, 1)) and
$(D stripLeft!(e => e == 1)(a)) returns $(D [0, 1, 1]).)
predicate. If `a = [1, 1, 0, 1, 1]`, then `stripLeft(a, 1)` and
`stripLeft!(e => e == 1)(a)` returns `[0, 1, 1]`.)
$(T2 stripRight,
Strips all trailing elements equal to a value, or that satisfy a
predicate.
If $(D a = [1, 1, 0, 1, 1]), then $(D stripRight(a, 1)) and
$(D stripRight!(e => e == 1)(a)) returns $(D [1, 1, 0]).)
If `a = [1, 1, 0, 1, 1]`, then `stripRight(a, 1)` and
`stripRight!(e => e == 1)(a)` returns `[1, 1, 0]`.)
$(T2 swap,
Swaps two values.)
$(T2 swapAt,
@ -84,21 +84,21 @@ import std.typecons; // : tuple, Tuple;
// bringToFront
/**
The $(D bringToFront) function has considerable flexibility and
The `bringToFront` function has considerable flexibility and
usefulness. It can rotate elements in one buffer left or right, swap
buffers of equal length, and even move elements across disjoint
buffers of different types and different lengths.
$(D bringToFront) takes two ranges $(D front) and $(D back), which may
be of different types. Considering the concatenation of $(D front) and
$(D back) one unified range, $(D bringToFront) rotates that unified
range such that all elements in $(D back) are brought to the beginning
of the unified range. The relative ordering of elements in $(D front)
and $(D back), respectively, remains unchanged.
`bringToFront` takes two ranges `front` and `back`, which may
be of different types. Considering the concatenation of `front` and
`back` one unified range, `bringToFront` rotates that unified
range such that all elements in `back` are brought to the beginning
of the unified range. The relative ordering of elements in `front`
and `back`, respectively, remains unchanged.
The $(D bringToFront) function treats strings at the code unit
The `bringToFront` function treats strings at the code unit
level and it is not concerned with Unicode character integrity.
$(D bringToFront) is designed as a function for moving elements
`bringToFront` is designed as a function for moving elements
in ranges, not as a string function.
Performs $(BIGOH max(front.length, back.length)) evaluations of $(D
@ -106,8 +106,8 @@ swap).
Preconditions:
Either $(D front) and $(D back) are disjoint, or $(D back) is
reachable from $(D front) and $(D front) is not reachable from $(D
Either `front` and `back` are disjoint, or `back` is
reachable from `front` and `front` is not reachable from $(D
back).
Params:
@ -115,7 +115,7 @@ Params:
back = a $(REF_ALTTEXT forward range, isForwardRange, std,range,primitives)
Returns:
The number of elements brought to the front, i.e., the length of $(D back).
The number of elements brought to the front, i.e., the length of `back`.
See_Also:
$(HTTP sgi.com/tech/stl/_rotate.html, STL's rotate)
@ -146,7 +146,7 @@ if (isInputRange!InputRange && isForwardRange!ForwardRange)
}
/**
The simplest use of $(D bringToFront) is for rotating elements in a
The simplest use of `bringToFront` is for rotating elements in a
buffer. For example:
*/
@safe unittest
@ -158,10 +158,10 @@ buffer. For example:
}
/**
The $(D front) range may actually "step over" the $(D back)
The `front` range may actually "step over" the `back`
range. This is very useful with forward ranges that cannot compute
comfortably right-bounded subranges like $(D arr[0 .. 4]) above. In
the example below, $(D r2) is a right subrange of $(D r1).
comfortably right-bounded subranges like `arr[0 .. 4]` above. In
the example below, `r2` is a right subrange of `r1`.
*/
@safe unittest
{
@ -351,11 +351,11 @@ private enum bool areCopyCompatibleArrays(T1, T2) =
// copy
/**
Copies the content of $(D source) into $(D target) and returns the
remaining (unfilled) part of $(D target).
Copies the content of `source` into `target` and returns the
remaining (unfilled) part of `target`.
Preconditions: $(D target) shall have enough room to accommodate
the entirety of $(D source).
Preconditions: `target` shall have enough room to accommodate
the entirety of `source`.
Params:
source = an $(REF_ALTTEXT input range, isInputRange, std,range,primitives)
@ -446,7 +446,7 @@ range elements, different types of ranges are accepted:
}
/**
To _copy at most $(D n) elements from a range, you may want to use
To _copy at most `n` elements from a range, you may want to use
$(REF take, std,range):
*/
@safe unittest
@ -539,7 +539,7 @@ $(HTTP sgi.com/tech/stl/copy_backward.html, STL's copy_backward'):
}
/**
Assigns $(D value) to each element of input _range $(D range).
Assigns `value` to each element of input _range `range`.
Params:
range = An
@ -713,9 +713,9 @@ if ((isInputRange!Range && is(typeof(range.front = value)) ||
}
/**
Fills $(D range) with a pattern copied from $(D filler). The length of
$(D range) does not have to be a multiple of the length of $(D
filler). If $(D filler) is empty, an exception is thrown.
Fills `range` with a pattern copied from `filler`. The length of
`range` does not have to be a multiple of the length of $(D
filler). If `filler` is empty, an exception is thrown.
Params:
range = An $(REF_ALTTEXT input _range, isInputRange, std,_range,primitives)
@ -832,7 +832,7 @@ if (isInputRange!InputRange
}
/**
Initializes all elements of $(D range) with their $(D .init) value.
Initializes all elements of `range` with their `.init` value.
Assumes that the elements of the range are uninitialized.
Params:
@ -1447,9 +1447,9 @@ Params:
src = An $(REF_ALTTEXT input range, isInputRange, std,range,primitives) with
movable elements.
tgt = An $(REF_ALTTEXT input range, isInputRange, std,range,primitives) with
elements that elements from $(D src) can be moved into.
elements that elements from `src` can be moved into.
Returns: The leftover portion of $(D tgt) after all elements from $(D src) have
Returns: The leftover portion of `tgt` after all elements from `src` have
been moved.
*/
InputRange2 moveAll(InputRange1, InputRange2)(InputRange1 src, InputRange2 tgt)
@ -1554,7 +1554,7 @@ Params:
src = An $(REF_ALTTEXT input range, isInputRange, std,range,primitives) with
movable elements.
tgt = An $(REF_ALTTEXT input range, isInputRange, std,range,primitives) with
elements that elements from $(D src) can be moved into.
elements that elements from `src` can be moved into.
Returns: The leftover portions of the two ranges after one or the other of the
ranges have been exhausted.
@ -1624,15 +1624,15 @@ Defines the swapping strategy for algorithms that need to swap
elements in a range (such as partition and sort). The strategy
concerns the swapping of elements that are not the core concern of the
algorithm. For example, consider an algorithm that sorts $(D [ "abc",
"b", "aBc" ]) according to $(D toUpper(a) < toUpper(b)). That
algorithm might choose to swap the two equivalent strings $(D "abc")
and $(D "aBc"). That does not affect the sorting since both $(D [
"abc", "aBc", "b" ]) and $(D [ "aBc", "abc", "b" ]) are valid
"b", "aBc" ]) according to `toUpper(a) < toUpper(b)`. That
algorithm might choose to swap the two equivalent strings `"abc"`
and `"aBc"`. That does not affect the sorting since both `$D(
"abc", "aBc", "b" ]) and `[ "aBc", "abc", "b" ]` are valid
outcomes.
Some situations require that the algorithm must NOT ever change the
relative ordering of equivalent elements (in the example above, only
$(D [ "abc", "aBc", "b" ]) would be the correct result). Such
`[ "abc", "aBc", "b" ]` would be the correct result). Such
algorithms are called $(B stable). If the ordering algorithm may swap
equivalent elements discretionarily, the ordering is called $(B
unstable).
@ -1642,12 +1642,12 @@ being stable only on a well-defined subrange of the range. There is no
established terminology for such behavior; this library calls it $(B
semistable).
Generally, the $(D stable) ordering strategy may be more costly in
Generally, the `stable` ordering strategy may be more costly in
time and/or space than the other two because it imposes additional
constraints. Similarly, $(D semistable) may be costlier than $(D
constraints. Similarly, `semistable` may be costlier than $(D
unstable). As (semi-)stability is not needed very often, the ordering
algorithms in this module parameterized by $(D SwapStrategy) all
choose $(D SwapStrategy.unstable) as the default.
algorithms in this module parameterized by `SwapStrategy` all
choose `SwapStrategy.unstable` as the default.
*/
enum SwapStrategy
@ -1730,7 +1730,7 @@ invoked to rearrange elements, and on integers `move` simply copies the source
to the destination. To replace `a` with the effect of the removal, simply
assign the slice returned by `remove` to it, as shown in the first example.
Multiple indices can be passed into $(D remove). In that case,
Multiple indices can be passed into `remove`. In that case,
elements at the respective indices are all removed. The indices must
be passed in increasing order, otherwise an exception occurs.
@ -1752,25 +1752,25 @@ assert(remove(a, 1, tuple(3, 5), 9) == [ 0, 2, 5, 6, 7, 8, 10 ]);
In this case, the slots at positions 1, 3, 4, and 9 are removed from
the array. The tuple passes in a range closed to the left and open to
the right (consistent with built-in slices), e.g. $(D tuple(3, 5))
means indices $(D 3) and $(D 4) but not $(D 5).
the right (consistent with built-in slices), e.g. `tuple(3, 5)`
means indices `3` and `4` but not `5`.
If the need is to remove some elements in the range but the order of
the remaining elements does not have to be preserved, you may want to
pass $(D SwapStrategy.unstable) to $(D remove).
pass `SwapStrategy.unstable` to `remove`.
----
int[] a = [ 0, 1, 2, 3 ];
assert(remove!(SwapStrategy.unstable)(a, 1) == [ 0, 3, 2 ]);
----
In the case above, the element at slot $(D 1) is removed, but replaced
In the case above, the element at slot `1` is removed, but replaced
with the last element of the range. Taking advantage of the relaxation
of the stability requirement, $(D remove) moved elements from the end
of the stability requirement, `remove` moved elements from the end
of the array over the slots to be removed. This way there is less data
movement to be done which improves the execution time of the function.
The function $(D remove) works on bidirectional ranges that have assignable
The function `remove` works on bidirectional ranges that have assignable
lvalue elements. The moving strategy is (listed from fastest to slowest):
$(UL $(LI If $(D s == SwapStrategy.unstable && isRandomAccessRange!Range &&
hasLength!Range && hasLvalueElements!Range), then elements are moved from the
@ -1779,8 +1779,8 @@ minimum of moves is performed.) $(LI Otherwise, if $(D s ==
SwapStrategy.unstable && isBidirectionalRange!Range && hasLength!Range
&& hasLvalueElements!Range), then elements are still moved from the
end of the range, but time is spent on advancing between slots by repeated
calls to $(D range.popFront).) $(LI Otherwise, elements are moved
incrementally towards the front of $(D range); a given element is never
calls to `range.popFront`.) $(LI Otherwise, elements are moved
incrementally towards the front of `range`; a given element is never
moved several times, but more elements are moved than in the previous
cases.))
@ -2021,10 +2021,10 @@ if (s == SwapStrategy.stable
/**
Reduces the length of the
$(REF_ALTTEXT bidirectional range, isBidirectionalRange, std,_range,primitives) $(D range) by removing
elements that satisfy $(D pred). If $(D s = SwapStrategy.unstable),
$(REF_ALTTEXT bidirectional range, isBidirectionalRange, std,_range,primitives) `range` by removing
elements that satisfy `pred`. If `s = SwapStrategy.unstable`,
elements are moved from the right end of the range over the elements
to eliminate. If $(D s = SwapStrategy.stable) (the default),
to eliminate. If `s = SwapStrategy.stable` (the default),
elements are moved progressively to front such that their relative
order is preserved. Returns the filtered range.
@ -2032,7 +2032,7 @@ Params:
range = a bidirectional ranges with lvalue elements
Returns:
the range with all of the elements where $(D pred) is $(D true)
the range with all of the elements where `pred` is `true`
removed
*/
Range remove(alias pred, SwapStrategy s = SwapStrategy.stable, Range)
@ -2181,7 +2181,7 @@ if (isBidirectionalRange!Range
// reverse
/**
Reverses $(D r) in-place. Performs $(D r.length / 2) evaluations of $(D
Reverses `r` in-place. Performs `r.length / 2` evaluations of $(D
swap).
Params:
r = a $(REF_ALTTEXT bidirectional range, isBidirectionalRange, std,range,primitives)
@ -2240,18 +2240,18 @@ if (isRandomAccessRange!Range && hasLength!Range)
}
/**
Reverses $(D r) in-place, where $(D r) is a narrow string (having
elements of type $(D char) or $(D wchar)). UTF sequences consisting of
Reverses `r` in-place, where `r` is a narrow string (having
elements of type `char` or `wchar`). UTF sequences consisting of
multiple code units are preserved properly.
Params:
s = a narrow string
Bugs:
When passing a sting with unicode modifiers on characters, such as $(D \u0301),
When passing a sting with unicode modifiers on characters, such as `\u0301`,
this function will not properly keep the position of the modifier. For example,
reversing $(D ba\u0301d) ("bád") will result in d\u0301ab ("d́ab") instead of
$(D da\u0301b) ("dáb").
reversing `ba\u0301d` ("bád") will result in d\u0301ab ("d́ab") instead of
`da\u0301b` ("dáb").
*/
void reverse(Char)(Char[] s)
if (isNarrowString!(Char[]) && !is(Char == const) && !is(Char == immutable))
@ -2307,12 +2307,12 @@ if (isNarrowString!(Char[]) && !is(Char == const) && !is(Char == immutable))
The strip group of functions allow stripping of either leading, trailing,
or both leading and trailing elements.
The $(D stripLeft) function will strip the $(D front) of the range,
the $(D stripRight) function will strip the $(D back) of the range,
while the $(D strip) function will strip both the $(D front) and $(D back)
The `stripLeft` function will strip the `front` of the range,
the `stripRight` function will strip the `back` of the range,
while the `strip` function will strip both the `front` and `back`
of the range.
Note that the $(D strip) and $(D stripRight) functions require the range to
Note that the `strip` and `stripRight` functions require the range to
be a $(LREF BidirectionalRange) range.
All of these functions come in two varieties: one takes a target element,
@ -2445,18 +2445,18 @@ if (isBidirectionalRange!Range && is(typeof(pred(range.back)) : bool))
// swap
/**
Swaps $(D lhs) and $(D rhs). The instances $(D lhs) and $(D rhs) are moved in
memory, without ever calling $(D opAssign), nor any other function. $(D T)
Swaps `lhs` and `rhs`. The instances `lhs` and `rhs` are moved in
memory, without ever calling `opAssign`, nor any other function. `T`
need not be assignable at all to be swapped.
If $(D lhs) and $(D rhs) reference the same instance, then nothing is done.
If `lhs` and `rhs` reference the same instance, then nothing is done.
$(D lhs) and $(D rhs) must be mutable. If $(D T) is a struct or union, then
`lhs` and `rhs` must be mutable. If `T` is a struct or union, then
its fields must also all be (recursively) mutable.
Params:
lhs = Data to be swapped with $(D rhs).
rhs = Data to be swapped with $(D lhs).
lhs = Data to be swapped with `rhs`.
rhs = Data to be swapped with `lhs`.
*/
void swap(T)(ref T lhs, ref T rhs) @trusted pure nothrow @nogc
if (isBlitAssignable!T && !is(typeof(lhs.proxySwap(rhs))))
@ -2820,8 +2820,8 @@ if (isInputRange!R1 && isInputRange!R2)
// swapRanges
/**
Swaps all elements of $(D r1) with successive elements in $(D r2).
Returns a tuple containing the remainder portions of $(D r1) and $(D
Swaps all elements of `r1` with successive elements in `r2`.
Returns a tuple containing the remainder portions of `r1` and $(D
r2) that were not swapped (one of them will be empty). The ranges may
be of different types but must have the same element type and support
swapping.
@ -2860,7 +2860,7 @@ if (hasSwappableElements!InputRange1 && hasSwappableElements!InputRange2
}
/**
Initializes each element of $(D range) with $(D value).
Initializes each element of `range` with `value`.
Assumes that the elements of the range are uninitialized.
This is of interest for structs that
define copy constructors (for all other types, $(LREF fill) and

8
std/algorithm/package.d
View file

@ -152,12 +152,12 @@ Many functions in this package are parameterized with a $(GLOSSARY predicate).
The predicate may be any suitable callable type
(a function, a delegate, a $(GLOSSARY functor), or a lambda), or a
compile-time string. The string may consist of $(B any) legal D
expression that uses the symbol $(D a) (for unary functions) or the
symbols $(D a) and $(D b) (for binary functions). These names will NOT
expression that uses the symbol `a` (for unary functions) or the
symbols `a` and `b` (for binary functions). These names will NOT
interfere with other homonym symbols in user code because they are
evaluated in a different context. The default for all binary
comparison predicates is $(D "a == b") for unordered operations and
$(D "a < b") for ordered operations.
comparison predicates is `"a == b"` for unordered operations and
`"a < b"` for ordered operations.
Example:

353
std/algorithm/searching.d
View file

@ -7,58 +7,58 @@ $(SCRIPT inhibitQuickIndex = 1;)
$(BOOKTABLE Cheat Sheet,
$(TR $(TH Function Name) $(TH Description))
$(T2 all,
$(D all!"a > 0"([1, 2, 3, 4])) returns $(D true) because all elements
`all!"a > 0"([1, 2, 3, 4])` returns `true` because all elements
are positive)
$(T2 any,
$(D any!"a > 0"([1, 2, -3, -4])) returns $(D true) because at least one
`any!"a > 0"([1, 2, -3, -4])` returns `true` because at least one
element is positive)
$(T2 balancedParens,
$(D balancedParens("((1 + 1) / 2)")) returns $(D true) because the
`balancedParens("((1 + 1) / 2)")` returns `true` because the
string has balanced parentheses.)
$(T2 boyerMooreFinder,
$(D find("hello world", boyerMooreFinder("or"))) returns $(D "orld")
`find("hello world", boyerMooreFinder("or"))` returns `"orld"`
using the $(LINK2 https://en.wikipedia.org/wiki/Boyer%E2%80%93Moore_string_search_algorithm,
Boyer-Moore _algorithm).)
$(T2 canFind,
$(D canFind("hello world", "or")) returns $(D true).)
`canFind("hello world", "or")` returns `true`.)
$(T2 count,
Counts elements that are equal to a specified value or satisfy a
predicate. $(D count([1, 2, 1], 1)) returns $(D 2) and
$(D count!"a < 0"([1, -3, 0])) returns $(D 1).)
predicate. `count([1, 2, 1], 1)` returns `2` and
`count!"a < 0"([1, -3, 0])` returns `1`.)
$(T2 countUntil,
$(D countUntil(a, b)) returns the number of steps taken in $(D a) to
reach $(D b); for example, $(D countUntil("hello!", "o")) returns
$(D 4).)
`countUntil(a, b)` returns the number of steps taken in `a` to
reach `b`; for example, `countUntil("hello!", "o")` returns
`4`.)
$(T2 commonPrefix,
$(D commonPrefix("parakeet", "parachute")) returns $(D "para").)
`commonPrefix("parakeet", "parachute")` returns `"para"`.)
$(T2 endsWith,
$(D endsWith("rocks", "ks")) returns $(D true).)
`endsWith("rocks", "ks")` returns `true`.)
$(T2 find,
$(D find("hello world", "or")) returns $(D "orld") using linear search.
`find("hello world", "or")` returns `"orld"` using linear search.
(For binary search refer to $(REF sortedRange, std,range).))
$(T2 findAdjacent,
$(D findAdjacent([1, 2, 3, 3, 4])) returns the subrange starting with
two equal adjacent elements, i.e. $(D [3, 3, 4]).)
`findAdjacent([1, 2, 3, 3, 4])` returns the subrange starting with
two equal adjacent elements, i.e. `[3, 3, 4]`.)
$(T2 findAmong,
$(D findAmong("abcd", "qcx")) returns $(D "cd") because $(D 'c') is
among $(D "qcx").)
`findAmong("abcd", "qcx")` returns `"cd"` because `'c'` is
among `"qcx"`.)
$(T2 findSkip,
If $(D a = "abcde"), then $(D findSkip(a, "x")) returns $(D false) and
leaves $(D a) unchanged, whereas $(D findSkip(a, "c")) advances $(D a)
to $(D "de") and returns $(D true).)
If `a = "abcde"`, then `findSkip(a, "x")` returns `false` and
leaves `a` unchanged, whereas `findSkip(a, "c")` advances `a`
to `"de"` and returns `true`.)
$(T2 findSplit,
$(D findSplit("abcdefg", "de")) returns the three ranges $(D "abc"),
$(D "de"), and $(D "fg").)
`findSplit("abcdefg", "de")` returns the three ranges `"abc"`,
`"de"`, and `"fg"`.)
$(T2 findSplitAfter,
$(D findSplitAfter("abcdefg", "de")) returns the two ranges
$(D "abcde") and $(D "fg").)
`findSplitAfter("abcdefg", "de")` returns the two ranges
`"abcde"` and `"fg"`.)
$(T2 findSplitBefore,
$(D findSplitBefore("abcdefg", "de")) returns the two ranges $(D "abc")
and $(D "defg").)
`findSplitBefore("abcdefg", "de")` returns the two ranges `"abc"`
and `"defg"`.)
$(T2 minCount,
$(D minCount([2, 1, 1, 4, 1])) returns $(D tuple(1, 3)).)
`minCount([2, 1, 1, 4, 1])` returns `tuple(1, 3)`.)
$(T2 maxCount,
$(D maxCount([2, 4, 1, 4, 1])) returns $(D tuple(4, 2)).)
`maxCount([2, 4, 1, 4, 1])` returns `tuple(4, 2)`.)
$(T2 minElement,
Selects the minimal element of a range.
`minElement([3, 4, 1, 2])` returns `1`.)
@ -72,22 +72,22 @@ $(T2 maxIndex,
Index of the maximal element of a range.
`maxElement([3, 4, 1, 2])` returns `1`.)
$(T2 minPos,
$(D minPos([2, 3, 1, 3, 4, 1])) returns the subrange $(D [1, 3, 4, 1]),
`minPos([2, 3, 1, 3, 4, 1])` returns the subrange `[1, 3, 4, 1]`,
i.e., positions the range at the first occurrence of its minimal
element.)
$(T2 maxPos,
$(D maxPos([2, 3, 1, 3, 4, 1])) returns the subrange $(D [4, 1]),
`maxPos([2, 3, 1, 3, 4, 1])` returns the subrange `[4, 1]`,
i.e., positions the range at the first occurrence of its maximal
element.)
$(T2 mismatch,
$(D mismatch("parakeet", "parachute")) returns the two ranges
$(D "keet") and $(D "chute").)
`mismatch("parakeet", "parachute")` returns the two ranges
`"keet"` and `"chute"`.)
$(T2 skipOver,
Assume $(D a = "blah"). Then $(D skipOver(a, "bi")) leaves $(D a)
unchanged and returns $(D false), whereas $(D skipOver(a, "bl"))
advances $(D a) to refer to $(D "ah") and returns $(D true).)
Assume `a = "blah"`. Then `skipOver(a, "bi")` leaves `a`
unchanged and returns `false`, whereas `skipOver(a, "bl")`
advances `a` to refer to `"ah"` and returns `true`.)
$(T2 startsWith,
$(D startsWith("hello, world", "hello")) returns $(D true).)
`startsWith("hello, world", "hello")` returns `true`.)
$(T2 until,
Lazily iterates a range until a specific value is found.)
)
@ -113,14 +113,14 @@ import std.traits;
import std.typecons; // : Tuple, Flag, Yes, No;
/++
Checks if $(I _all) of the elements verify $(D pred).
Checks if $(I _all) of the elements verify `pred`.
+/
template all(alias pred = "a")
{
/++
Returns $(D true) if and only if $(I _all) values $(D v) found in the
input _range $(D range) satisfy the predicate $(D pred).
Performs (at most) $(BIGOH range.length) evaluations of $(D pred).
Returns `true` if and only if $(I _all) values `v` found in the
input _range `range` satisfy the predicate `pred`.
Performs (at most) $(BIGOH range.length) evaluations of `pred`.
+/
bool all(Range)(Range range)
if (isInputRange!Range && is(typeof(unaryFun!pred(range.front))))
@ -139,7 +139,7 @@ template all(alias pred = "a")
}
/++
$(D all) can also be used without a predicate, if its items can be
`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 $(I _all) of the elements of a range
are true.
@ -157,17 +157,17 @@ are true.
}
/++
Checks if $(I _any) of the elements verifies $(D pred).
$(D !any) can be used to verify that $(I none) of the elements verify
$(D pred).
Checks if $(I _any) of the elements verifies `pred`.
`!any` can be used to verify that $(I none) of the elements verify
`pred`.
This is sometimes called `exists` in other languages.
+/
template any(alias pred = "a")
{
/++
Returns $(D true) if and only if $(I _any) value $(D v) found in the
input _range $(D range) satisfies the predicate $(D pred).
Performs (at most) $(BIGOH range.length) evaluations of $(D pred).
Returns `true` if and only if $(I _any) value `v` found in the
input _range `range` satisfies the predicate `pred`.
Performs (at most) $(BIGOH range.length) evaluations of `pred`.
+/
bool any(Range)(Range range)
if (isInputRange!Range && is(typeof(unaryFun!pred(range.front))))
@ -185,8 +185,8 @@ template any(alias pred = "a")
}
/++
$(D any) can also be used without a predicate, if its items can be
evaluated to true or false in a conditional statement. $(D !any) can be a
`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 $(I none) of the elements of a range
evaluate to true.
+/
@ -212,10 +212,10 @@ evaluate to true.
// balancedParens
/**
Checks whether $(D r) has "balanced parentheses", i.e. all instances
of $(D lPar) are closed by corresponding instances of $(D rPar). The
parameter $(D maxNestingLevel) controls the nesting level allowed. The
most common uses are the default or $(D 0). In the latter case, no
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.
Params:
@ -263,18 +263,18 @@ if (isInputRange!(Range) && is(typeof(r.front == lPar)))
}
/**
* Sets up Boyer-Moore matching for use with $(D find) below.
* Sets up Boyer-Moore matching for use with `find` below.
* By default, elements are compared for equality.
*
* $(D BoyerMooreFinder) allocates GC memory.
* `BoyerMooreFinder` allocates GC memory.
*
* Params:
* pred = Predicate used to compare elements.
* needle = A random-access range with length and slicing.
*
* Returns:
* An instance of $(D BoyerMooreFinder) that can be used with $(D find()) to
* invoke the Boyer-Moore matching algorithm for finding of $(D needle) in a
* An instance of `BoyerMooreFinder` that can be used with `find()` to
* invoke the Boyer-Moore matching algorithm for finding of `needle` in a
* given haystack.
*/
struct BoyerMooreFinder(alias pred, Range)
@ -407,7 +407,7 @@ Returns the common prefix of two ranges.
Params:
pred = The predicate to use in comparing elements for commonality. Defaults
to equality $(D "a == b").
to equality `"a == b"`.
r1 = A $(REF_ALTTEXT forward range, isForwardRange, std,range,primitives) of
elements.
@ -416,9 +416,9 @@ Params:
elements.
Returns:
A slice of $(D r1) which contains the characters that both ranges start with,
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
$(D takeExactly(r1, n)), where $(D n) is the number of elements in the common
`takeExactly(r1, n)`, where `n` is the number of elements in the common
prefix of both ranges.
See_Also:
@ -591,26 +591,26 @@ if (isNarrowString!R1 && isNarrowString!R2)
// count
/**
The first version counts the number of elements $(D x) in $(D r) for
which $(D pred(x, value)) is $(D true). $(D pred) defaults to
equality. Performs $(BIGOH haystack.length) evaluations of $(D pred).
The first version counts the number of elements `x` in `r` for
which `pred(x, value)` is `true`. `pred` defaults to
equality. Performs $(BIGOH haystack.length) evaluations of `pred`.
The second version returns the number of times $(D needle) occurs in
$(D haystack). Throws an exception if $(D needle.empty), as the _count
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 $(D count("aaa", "aa")) is $(D 1), not
$(D 2).
are not considered, for example `count("aaa", "aa")` is `1`, not
`2`.
The third version counts the elements for which $(D pred(x)) is $(D
true). Performs $(BIGOH haystack.length) evaluations of $(D pred).
The third version counts the elements for which `pred(x)` is $(D
true). Performs $(BIGOH 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 $(BIGOH haystack.length) to walk the range.
Note: Regardless of the overload, $(D count) will not accept
infinite ranges for $(D haystack).
Note: Regardless of the overload, `count` will not accept
infinite ranges for `haystack`.
Params:
pred = The predicate to evaluate.
@ -732,7 +732,7 @@ if (isInputRange!R && !isInfinite!R)
/++
Counts elements in the given
$(REF_ALTTEXT forward range, isForwardRange, std,range,primitives)
until the given predicate is true for one of the given $(D needles).
until the given predicate is true for one of the given `needles`.
Params:
pred = The predicate for determining when to stop counting.
@ -742,13 +742,13 @@ if (isInputRange!R && !isInfinite!R)
needles = Either a single element, or a
$(REF_ALTTEXT forward range, isForwardRange, std,range,primitives)
of elements, to be evaluated in turn against each
element in $(D haystack) under the given predicate.
element in `haystack` under the given predicate.
Returns: The number of elements which must be popped from the front of
$(D haystack) before reaching an element for which
$(D startsWith!pred(haystack, needles)) is $(D true). If
$(D startsWith!pred(haystack, needles)) is not $(D true) for any element in
$(D haystack), then $(D -1) is returned.
`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.
See_Also: $(REF indexOf, std,string)
+/
@ -899,16 +899,16 @@ if (isInputRange!R &&
}
/++
Similar to the previous overload of $(D countUntil), except that this one
evaluates only the predicate $(D pred).
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 $(D haystack)
before $(D pred(haystack.front)) is $(D true).
Returns: The number of elements which must be popped from `haystack`
before `pred(haystack.front)` is `true`.
+/
ptrdiff_t countUntil(alias pred, R)(R haystack)
if (isInputRange!R &&
@ -995,7 +995,7 @@ if (isInputRange!R &&
/**
Checks if the given range ends with (one of) the given needle(s).
The reciprocal of $(D startsWith).
The reciprocal of `startsWith`.
Params:
pred = The predicate to use for comparing elements between the range and
@ -1013,11 +1013,11 @@ Params:
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 $(D withOneOfThese[0]), 2 if it ends with $(D withOneOfThese[1]), and so
with `withOneOfThese[0]`, 2 if it ends with `withOneOfThese[1]`, and so
on.
In the case when no needle parameters are given, return $(D true) iff back of
$(D doesThisStart) fulfils predicate $(D pred).
In the case when no needle parameters are given, return `true` iff back of
`doesThisStart` fulfils predicate `pred`.
*/
uint endsWith(alias pred = "a == b", Range, Needles...)(Range doesThisEnd, Needles withOneOfThese)
if (isBidirectionalRange!Range && Needles.length > 1 &&
@ -1458,18 +1458,18 @@ private auto extremum(alias selector = "a < b", Range,
// find
/**
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 `needle` by using predicate $(D
pred). Performs $(BIGOH walkLength(haystack)) evaluations of $(D
pred).
To _find the last occurrence of $(D needle) in $(D haystack), call $(D
To _find the last occurrence of `needle` in `haystack`, call $(D
find(retro(haystack), needle)). See $(REF retro, std,range).
Params:
pred = The predicate for comparing each element with the needle, defaulting to
$(D "a == b").
The negated predicate $(D "a != b") can be used to search instead for the first
`"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)
@ -1477,16 +1477,11 @@ searched in.
needle = The element searched for.
Constraints:
$(D isInputRange!InputRange && is(typeof(binaryFun!pred(haystack.front, needle)
: bool)))
Returns:
$(D haystack) advanced such that the front element is the one searched for;
that is, until $(D binaryFun!pred(haystack.front, needle)) is $(D true). If no
such position exists, returns an empty $(D 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)
@ -1766,14 +1761,14 @@ if (isInputRange!InputRange &&
}
/**
Advances the input range $(D haystack) by calling $(D haystack.popFront)
until either $(D pred(haystack.front)), or $(D
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) $(D haystack) satisfying
$(D pred), call $(D find!(pred)(retro(haystack))). See $(REF retro, std,range).
$(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.
@ -1787,9 +1782,9 @@ search in.
Returns:
$(D haystack) advanced such that the front element is the one searched for;
that is, until $(D binaryFun!pred(haystack.front, needle)) is $(D true). If no
such position exists, returns an empty $(D 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_if.html, STL's find_if)
@ -1859,7 +1854,7 @@ 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 $(D "a == b").
and the needle. Defaults to simple equality `"a == b"`.
haystack = The $(REF_ALTTEXT forward range, isForwardRange, std,range,primitives)
searched in.
@ -1869,8 +1864,8 @@ searched for.
Returns:
$(D haystack) advanced such that $(D needle) is a prefix of it (if no
such position exists, returns $(D haystack) advanced to termination).
`haystack` advanced such that `needle` is a prefix of it (if no
such position exists, returns `haystack` advanced to termination).
*/
R1 find(alias pred = "a == b", R1, R2)(R1 haystack, scope R2 needle)
if (isForwardRange!R1 && isForwardRange!R2
@ -2279,7 +2274,7 @@ private R1 simpleMindedFind(alias pred, R1, R2)(R1 haystack, scope R2 needle)
}
/**
Finds two or more $(D needles) into a $(D haystack). The predicate $(D
Finds two or more `needles` into a `haystack`. The predicate $(D
pred) is used throughout to compare elements. By default, elements are
compared for equality.
@ -2288,41 +2283,41 @@ Params:
pred = The predicate to use for comparing elements.
haystack = The target of the search. Must be an input range.
If any of $(D needles) is a range with elements comparable to
elements in $(D haystack), then $(D haystack) must be a
If any of `needles` is a range with elements comparable to
elements in `haystack`, then `haystack` must be a
$(REF_ALTTEXT forward range, isForwardRange, std,range,primitives)
such that the search can backtrack.
needles = One or more items to search for. Each of $(D needles) must
be either comparable to one element in $(D haystack), or be itself a
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
$(D haystack).
`haystack`.
Returns:
A tuple containing $(D haystack) positioned to match one of the
A tuple containing `haystack` positioned to match one of the
needles and also the 1-based index of the matching element in $(D
needles) (0 if none of $(D needles) matched, 1 if $(D needles[0])
matched, 2 if $(D needles[1]) matched...). The first needle to be found
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
$(D "a") and $(D 'a')), then the left-most of them in the argument list
`"a"` and `'a'`), then the left-most of them in the argument list
matches).
The relationship between $(D haystack) and $(D needles) simply means
that one can e.g. search for individual $(D int)s or arrays of $(D
int)s in an array of $(D int)s. In addition, if elements are
The relationship between `haystack` and `needles` simply means
that one can e.g. search for individual `int`s or arrays of $(D
int)s in an array of `int`s. In addition, if elements are
individually comparable, searches of heterogeneous types are allowed
as well: a $(D double[]) can be searched for an $(D int) or a $(D
short[]), and conversely a $(D long) can be searched for a $(D float)
or a $(D double[]). This makes for efficient searches without the need
as well: a `double[]` can be searched for an `int` or a $(D
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 $(BIGOH 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 $(D haystack) as
subranges at once maximizes cache usage by moving in `haystack` as
few times as possible.
*/
Tuple!(Range, size_t) find(alias pred = "a == b", Range, Ranges...)
@ -2428,7 +2423,7 @@ if (Ranges.length > 1 && is(typeof(startsWith!pred(haystack, needles))))
}
/**
* Finds $(D needle) in $(D haystack) efficiently using the
* Finds `needle` in `haystack` efficiently using the
* $(LINK2 https://en.wikipedia.org/wiki/Boyer%E2%80%93Moore_string_search_algorithm,
* Boyer-Moore) method.
*
@ -2437,8 +2432,8 @@ if (Ranges.length > 1 && is(typeof(startsWith!pred(haystack, needles))))
* needle = A $(LREF BoyerMooreFinder).
*
* Returns:
* $(D haystack) advanced such that $(D needle) is a prefix of it (if no
* such position exists, returns $(D haystack) advanced to termination).
* `haystack` advanced such that `needle` is a prefix of it (if no
* such position exists, returns `haystack` advanced to termination).
*/
RandomAccessRange find(RandomAccessRange, alias pred, InputRange)(
RandomAccessRange haystack, scope BoyerMooreFinder!(pred, InputRange) needle)
@ -2490,9 +2485,9 @@ template canFind(alias pred="a == b")
import std.meta : allSatisfy;
/++
Returns $(D true) if and only if any value $(D v) found in the
input range $(D range) satisfies the predicate $(D pred).
Performs (at most) $(BIGOH haystack.length) evaluations of $(D pred).
Returns `true` if and only if any value `v` found in the
input range `range` satisfies the predicate `pred`.
Performs (at most) $(BIGOH haystack.length) evaluations of `pred`.
+/
bool canFind(Range)(Range haystack)
if (is(typeof(find!pred(haystack))))
@ -2501,8 +2496,8 @@ template canFind(alias pred="a == b")
}
/++
Returns $(D true) if and only if $(D needle) can be found in $(D
range). Performs $(BIGOH haystack.length) evaluations of $(D pred).
Returns `true` if and only if `needle` can be found in $(D
range). Performs $(BIGOH haystack.length) evaluations of `pred`.
+/
bool canFind(Range, Element)(Range haystack, scope Element needle)
if (is(typeof(find!pred(haystack, needle))))
@ -2511,14 +2506,14 @@ template canFind(alias pred="a == b")
}
/++
Returns the 1-based index of the first needle found in $(D haystack). If no
needle is found, then $(D 0) is returned.
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 $(D true) if one of the needles is found and $(D false) if none are
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
$(D bool) for the same effect or used to get which needle was found first
without having to deal with the tuple that $(D LREF find) returns for the
`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.
+/
size_t canFind(Range, Ranges...)(Range haystack, scope Ranges needles)
@ -2579,9 +2574,9 @@ template canFind(alias pred="a == b")
// findAdjacent
/**
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)
evaluations of $(D pred).
Advances `r` until it finds the first two adjacent elements `a`,
`b` that satisfy `pred(a, b)`. Performs $(BIGOH r.length)
evaluations of `pred`.
Params:
pred = The predicate to satisfy.
@ -2589,8 +2584,8 @@ Params:
search in.
Returns:
$(D r) advanced to the first occurrence of two adjacent elements that satisfy
the given predicate. If there are no such two elements, returns $(D r) advanced
`r` advanced to the first occurrence of two adjacent elements that satisfy
the given predicate. If there are no such two elements, returns `r` advanced
until empty.
See_Also:
@ -2654,9 +2649,9 @@ if (isForwardRange!(Range))
/**
Searches the given range for an element that matches one of the given choices.
Advances $(D seq) by calling $(D seq.popFront) until either
$(D find!(pred)(choices, seq.front)) is $(D true), or $(D seq) becomes empty.
Performs $(BIGOH seq.length * choices.length) evaluations of $(D pred).
Advances `seq` by calling `seq.popFront` until either
`find!(pred)(choices, seq.front)` is `true`, or `seq` becomes empty.
Performs $(BIGOH seq.length * choices.length) evaluations of `pred`.
Params:
pred = The predicate to use for determining a match.
@ -2666,7 +2661,7 @@ Params:
of possible choices.
Returns:
$(D seq) advanced to the first matching element, or until empty if there are no
`seq` advanced to the first matching element, or until empty if there are no
matching elements.
See_Also:
@ -2702,8 +2697,8 @@ if (isInputRange!InputRange && isForwardRange!ForwardRange)
// findSkip
/**
* Finds $(D needle) in $(D haystack) and positions $(D haystack)
* right after the first occurrence of $(D needle).
* Finds `needle` in `haystack` and positions `haystack`
* right after the first occurrence of `needle`.
*
* Params:
* haystack = The
@ -2714,9 +2709,9 @@ if (isInputRange!InputRange && isForwardRange!ForwardRange)
* for.
* pred = Custom predicate for comparison of haystack and needle
*
* Returns: $(D true) if the needle was found, in which case $(D haystack) is
* positioned after the end of the first occurrence of $(D needle); otherwise
* $(D false), leaving $(D haystack) untouched.
* 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.
*/
bool findSkip(alias pred = "a == b", R1, R2)(ref R1 haystack, R2 needle)
if (isForwardRange!R1 && isForwardRange!R2
@ -3177,16 +3172,16 @@ if (isForwardRange!R1 && isForwardRange!R2)
Computes the minimum (respectively maximum) of `range` along with its number of
occurrences. Formally, the minimum is a value `x` in `range` such that $(D
pred(a, x)) is `false` for all values `a` in `range`. Conversely, the maximum is
a value `x` in `range` such that $(D pred(x, a)) is `false` for all values `a`
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 $(D pred(a, b) && pred(b, c)) then $(D pred(a, c))) and
irreflexive ($(D pred(a, a)) is `false`). The $(LUCKY trichotomy property of
i.e. transitive (if `pred(a, b) && pred(b, c)` then `pred(a, c)`) and
irreflexive (`pred(a, a)` is `false`). The $(LUCKY 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. $(D !pred(a, b) && !pred(b, a)).
i.e. `!pred(a, b) && !pred(b, a)`.
Params:
pred = The ordering predicate to use to determine the extremum (minimum
@ -3623,15 +3618,15 @@ 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 $(D pred(a, x)) is
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 $(D pred(x, a)) is `false` for all values `a` in `range` (note
`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 $(D pred(a, b) && pred(b, c)) then $(D pred(a, c))) and
irreflexive ($(D pred(a, a)) is `false`).
i.e. transitive (if `pred(a, b) && pred(b, c)` then `pred(a, c)`) and
irreflexive (`pred(a, a)` is `false`).
Params:
pred = The ordering predicate to use to determine the extremum (minimum or
@ -3950,7 +3945,7 @@ Do nothing if there is no match.
Params:
pred = The predicate that determines whether elements from each respective
range match. Defaults to equality $(D "a == b").
range match. Defaults to equality `"a == b"`.
*/
template skipOver(alias pred = "a == b")
{
@ -3958,13 +3953,13 @@ template skipOver(alias pred = "a == b")
r1 = The $(REF_ALTTEXT forward range, isForwardRange, std,range,primitives) to
move forward.
r2 = The $(REF_ALTTEXT input range, isInputRange, std,range,primitives)
representing the initial segment of $(D r1) to skip over.
representing the initial segment of `r1` to skip over.
e = The element to match.
Returns:
true if the initial segment of $(D r1) matches $(D r2) or $(D pred) evaluates to true,
and $(D r1) has been advanced to the point past this segment; otherwise false, and
$(D r1) is left in its original position.
true if the initial segment of `r1` matches `r2` or `pred` evaluates to true,
and `r1` has been advanced to the point past this segment; otherwise false, and
`r1` is left in its original position.
*/
bool skipOver(R1, R2)(ref R1 r1, R2 r2)
if (is(typeof(binaryFun!pred(r1.front, r2.front))) &&
@ -4097,7 +4092,7 @@ template skipOver(alias pred = "a == b")
Checks whether the given
$(REF_ALTTEXT input range, isInputRange, std,range,primitives) starts with (one
of) the given needle(s) or, if no needles are given,
if its front element fulfils predicate $(D pred).
if its front element fulfils predicate `pred`.
Params:
@ -4116,17 +4111,17 @@ 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 $(D withOneOfThese[0]), 2 if it starts with $(D withOneOfThese[1]), and so
with `withOneOfThese[0]`, 2 if it starts with `withOneOfThese[1]`, and so
on.
In the case where $(D doesThisStart) starts with multiple of the ranges or
elements in $(D withOneOfThese), then the shortest one matches (if there are
two which match which are of the same length (e.g. $(D "a") and $(D 'a')), then
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 $(D true) iff front of
$(D doesThisStart) fulfils predicate $(D pred).
In the case when no needle parameters are given, return `true` iff front of
`doesThisStart` fulfils predicate `pred`.
*/
uint startsWith(alias pred = "a == b", Range, Needles...)(Range doesThisStart, Needles withOneOfThese)
if (isInputRange!Range && Needles.length > 1 &&
@ -4427,8 +4422,8 @@ if (isInputRange!R &&
}
/* (Not yet documented.)
Consume all elements from $(D r) that are equal to one of the elements
$(D es).
Consume all elements from `r` that are equal to one of the elements
`es`.
*/
private void skipAll(alias pred = "a == b", R, Es...)(ref R r, Es es)
//if (is(typeof(binaryFun!pred(r1.front, es[0]))))
@ -4457,17 +4452,17 @@ private void skipAll(alias pred = "a == b", R, Es...)(ref R r, Es es)
/**
Interval option specifier for `until` (below) and others.
If set to $(D OpenRight.yes), then the interval is open to the right
If set to `OpenRight.yes`, then the interval is open to the right
(last element is not included).
Otherwise if set to $(D OpenRight.no), then the interval is closed to the right
Otherwise if set to `OpenRight.no`, then the interval is closed to the right
(last element included).
*/
alias OpenRight = Flag!"openRight";
/**
Lazily iterates $(D range) _until the element $(D e) for which
$(D pred(e, sentinel)) is true.
Lazily iterates `range` _until the element `e` for which
`pred(e, sentinel)` is true.
This is similar to `takeWhile` in other languages.
@ -4477,8 +4472,8 @@ Params:
to iterate over.
sentinel = The element to stop at.
openRight = Determines whether the element for which the given predicate is
true should be included in the resulting range ($(D No.openRight)), or
not ($(D Yes.openRight)).
true should be included in the resulting range (`No.openRight`), or
not (`Yes.openRight`).
Returns:
An $(REF_ALTTEXT input _range, isInputRange, std,_range,primitives) that

72
std/algorithm/setops.d
View file

@ -557,9 +557,9 @@ pure @safe nothrow @nogc unittest
// largestPartialIntersection
/**
Given a range of sorted $(REF_ALTTEXT forward ranges, isForwardRange, std,range,primitives)
$(D ror), copies to $(D tgt) the elements that are common to most ranges, along with their number
of occurrences. All ranges in $(D ror) are assumed to be sorted by $(D
less). Only the most frequent $(D tgt.length) elements are returned.
`ror`, copies to `tgt` the elements that are common to most ranges, along with their number
of occurrences. All ranges in `ror` are assumed to be sorted by $(D
less). Only the most frequent `tgt.length` elements are returned.
Params:
less = The predicate the ranges are sorted by.
@ -567,27 +567,27 @@ Params:
tgt = The target range to copy common elements to.
sorted = Whether the elements copied should be in sorted order.
The function $(D largestPartialIntersection) is useful for
The function `largestPartialIntersection` is useful for
e.g. searching an $(LINK2 https://en.wikipedia.org/wiki/Inverted_index,
inverted index) for the documents most
likely to contain some terms of interest. The complexity of the search
is $(BIGOH n * log(tgt.length)), where $(D n) is the sum of lengths of
is $(BIGOH n * log(tgt.length)), where `n` is the sum of lengths of
all input ranges. This approach is faster than keeping an associative
array of the occurrences and then selecting its top items, and also
requires less memory ($(D largestPartialIntersection) builds its
result directly in $(D tgt) and requires no extra memory).
requires less memory (`largestPartialIntersection` builds its
result directly in `tgt` and requires no extra memory).
If at least one of the ranges is a multiset, then all occurences
of a duplicate element are taken into account. The result is
equivalent to merging all ranges and picking the most frequent
$(D tgt.length) elements.
`tgt.length` elements.
Warning: Because $(D largestPartialIntersection) does not allocate
extra memory, it will leave $(D ror) modified. Namely, $(D
largestPartialIntersection) assumes ownership of $(D ror) and
Warning: Because `largestPartialIntersection` does not allocate
extra memory, it will leave `ror` modified. Namely, $(D
largestPartialIntersection) assumes ownership of `ror` and
discretionarily swaps and advances elements of it. If you want $(D
ror) to preserve its contents after the call, you may want to pass a
duplicate to $(D largestPartialIntersection) (and perhaps cache the
duplicate to `largestPartialIntersection` (and perhaps cache the
duplicate in between calls).
*/
void largestPartialIntersection
@ -652,13 +652,13 @@ import std.algorithm.sorting : SortOutput; // FIXME
// largestPartialIntersectionWeighted
/**
Similar to $(D largestPartialIntersection), but associates a weight
Similar to `largestPartialIntersection`, but associates a weight
with each distinct element in the intersection.
If at least one of the ranges is a multiset, then all occurences
of a duplicate element are taken into account. The result
is equivalent to merging all input ranges and picking the highest
$(D tgt.length), weight-based ranking elements.
`tgt.length`, weight-based ranking elements.
Params:
less = The predicate the ranges are sorted by.
@ -798,15 +798,15 @@ void largestPartialIntersectionWeighted
Merges multiple sets. The input sets are passed as a
range of ranges and each is assumed to be sorted by $(D
less). Computation is done lazily, one union element at a time. The
complexity of one $(D popFront) operation is $(BIGOH
log(ror.length)). However, the length of $(D ror) decreases as ranges
complexity of one `popFront` operation is $(BIGOH
log(ror.length)). However, the length of `ror` decreases as ranges
in it are exhausted, so the complexity of a full pass through $(D
MultiwayMerge) is dependent on the distribution of the lengths of ranges
contained within $(D ror). If all ranges have the same length $(D n)
contained within `ror`. If all ranges have the same length `n`
(worst case scenario), the complexity of a full pass through $(D
MultiwayMerge) is $(BIGOH n * ror.length * log(ror.length)), i.e., $(D
log(ror.length)) times worse than just spanning all ranges in
turn. The output comes sorted (unstably) by $(D less).
turn. The output comes sorted (unstably) by `less`.
The length of the resulting range is the sum of all lengths of
the ranges passed as input. This means that all elements (duplicates
@ -824,11 +824,11 @@ Params:
Returns:
A range of the union of the ranges in `ror`.
Warning: Because $(D MultiwayMerge) does not allocate extra memory, it
will leave $(D ror) modified. Namely, $(D MultiwayMerge) assumes ownership
of $(D ror) and discretionarily swaps and advances elements of it. If
you want $(D ror) to preserve its contents after the call, you may
want to pass a duplicate to $(D MultiwayMerge) (and perhaps cache the
Warning: Because `MultiwayMerge` does not allocate extra memory, it
will leave `ror` modified. Namely, `MultiwayMerge` assumes ownership
of `ror` and discretionarily swaps and advances elements of it. If
you want `ror` to preserve its contents after the call, you may
want to pass a duplicate to `MultiwayMerge` (and perhaps cache the
duplicate in between calls).
*/
struct MultiwayMerge(alias less, RangeOfRanges)
@ -983,13 +983,13 @@ auto multiwayUnion(alias less = "a < b", RangeOfRanges)(RangeOfRanges ror)
}
/**
Lazily computes the difference of $(D r1) and $(D r2). The two ranges
are assumed to be sorted by $(D less). The element types of the two
Lazily computes the difference of `r1` and `r2`. The two ranges
are assumed to be sorted by `less`. The element types of the two
ranges must have a common type.
In the case of multisets, considering that element `a` appears `x`
times in $(D r1) and `y` times and $(D r2), the number of occurences
times in `r1` and `y` times and `r2`, the number of occurences
of `a` in the resulting range is going to be `x-y` if x > y or 0 othwerise.
Params:
@ -1108,7 +1108,7 @@ SetDifference!(less, R1, R2) setDifference(alias less = "a < b", R1, R2)
/**
Lazily computes the intersection of two or more input ranges $(D
ranges). The ranges are assumed to be sorted by $(D less). The element
ranges). The ranges are assumed to be sorted by `less`. The element
types of the ranges must have a common type.
In the case of multisets, the range with the minimum number of
@ -1274,20 +1274,20 @@ if (Rs.length >= 2 && allSatisfy!(isInputRange, Rs) &&
}
/**
Lazily computes the symmetric difference of $(D r1) and $(D r2),
i.e. the elements that are present in exactly one of $(D r1) and $(D
r2). The two ranges are assumed to be sorted by $(D less), and the
output is also sorted by $(D less). The element types of the two
Lazily computes the symmetric difference of `r1` and `r2`,
i.e. the elements that are present in exactly one of `r1` and $(D
r2). The two ranges are assumed to be sorted by `less`, and the
output is also sorted by `less`. The element types of the two
ranges must have a common type.
If both ranges are sets (without duplicated elements), the resulting
range is going to be a set. If at least one of the ranges is a multiset,
the number of occurences of an element `x` in the resulting range is `abs(a-b)`
where `a` is the number of occurences of `x` in $(D r1), `b` is the number of
occurences of `x` in $(D r2), and `abs` is the absolute value.
where `a` is the number of occurences of `x` in `r1`, `b` is the number of
occurences of `x` in `r2`, and `abs` is the absolute value.
If both arguments are ranges of L-values of the same type then
$(D SetSymmetricDifference) will also be a range of L-values of
`SetSymmetricDifference` will also be a range of L-values of
that type.
Params:
@ -1435,8 +1435,8 @@ TODO: once SetUnion got deprecated we can provide the usual definition
(= merge + filter after uniqs)
See: https://github.com/dlang/phobos/pull/4249
/**
Lazily computes the union of two or more ranges $(D rs). The ranges
are assumed to be sorted by $(D less). Elements in the output are
Lazily computes the union of two or more ranges `rs`. The ranges
are assumed to be sorted by `less`. Elements in the output are
unique. The element types of all ranges must have a common type.
Params:

231
std/algorithm/sorting.d
View file

@ -7,23 +7,23 @@ $(SCRIPT inhibitQuickIndex = 1;)
$(BOOKTABLE Cheat Sheet,
$(TR $(TH Function Name) $(TH Description))
$(T2 completeSort,
If $(D a = [10, 20, 30]) and $(D b = [40, 6, 15]), then
$(D completeSort(a, b)) leaves $(D a = [6, 10, 15]) and $(D b = [20,
If `a = [10, 20, 30]` and `b = [40, 6, 15]`, then
`completeSort(a, b)` leaves `a = [6, 10, 15]` and `b = [20$D(
30, 40]).
The range $(D a) must be sorted prior to the call, and as a result the
combination $(D $(REF chain, std,range)(a, b)) is sorted.)
The range `a` must be sorted prior to the call, and as a result the
combination `$(REF chain, std,range)(a, b)` is sorted.)
$(T2 isPartitioned,
$(D isPartitioned!"a < 0"([-1, -2, 1, 0, 2])) returns $(D true) because
the predicate is $(D true) for a portion of the range and $(D false)
`isPartitioned!"a < 0"([-1, -2, 1, 0, 2])` returns `true` because
the predicate is `true` for a portion of the range and `false`
afterwards.)
$(T2 isSorted,
$(D isSorted([1, 1, 2, 3])) returns $(D true).)
`isSorted([1, 1, 2, 3])` returns `true`.)
$(T2 isStrictlyMonotonic,
$(D isStrictlyMonotonic([1, 1, 2, 3])) returns $(D false).)
`isStrictlyMonotonic([1, 1, 2, 3])` returns `false`.)
$(T2 ordered,
$(D ordered(1, 1, 2, 3)) returns $(D true).)
`ordered(1, 1, 2, 3)` returns `true`.)
$(T2 strictlyOrdered,
$(D strictlyOrdered(1, 1, 2, 3)) returns $(D false).)
`strictlyOrdered(1, 1, 2, 3)` returns `false`.)
$(T2 makeIndex,
Creates a separate index for a range.)
$(T2 merge,
@ -37,9 +37,9 @@ $(T2 nextPermutation,
Computes the next lexicographically greater permutation of a range
in-place.)
$(T2 partialSort,
If $(D a = [5, 4, 3, 2, 1]), then $(D partialSort(a, 3)) leaves
$(D a[0 .. 3] = [1, 2, 3]).
The other elements of $(D a) are left in an unspecified order.)
If `a = [5, 4, 3, 2, 1]`, then `partialSort(a, 3)` leaves
`a[0 .. 3] = [1, 2, 3]`.
The other elements of `a` are left in an unspecified order.)
$(T2 partition,
Partitions a range according to a unary predicate.)
$(T2 partition3,
@ -88,21 +88,21 @@ import std.traits;
Specifies whether the output of certain algorithm is desired in sorted
format.
If set to $(D SortOutput.no), the output should not be sorted.
If set to `SortOutput.no`, the output should not be sorted.
Otherwise if set to $(D SortOutput.yes), the output should be sorted.
Otherwise if set to `SortOutput.yes`, the output should be sorted.
*/
alias SortOutput = Flag!"sortOutput";
// completeSort
/**
Sorts the random-access range $(D chain(lhs, rhs)) according to
predicate $(D less). The left-hand side of the range $(D lhs) is
assumed to be already sorted; $(D rhs) is assumed to be unsorted. The
exact strategy chosen depends on the relative sizes of $(D lhs) and
$(D rhs). Performs $(BIGOH lhs.length + rhs.length * log(rhs.length))
Sorts the random-access range `chain(lhs, rhs)` according to
predicate `less`. The left-hand side of the range `lhs` is
assumed to be already sorted; `rhs` is assumed to be unsorted. The
exact strategy chosen depends on the relative sizes of `lhs` and
`rhs`. Performs $(BIGOH lhs.length + rhs.length * log(rhs.length))
(best case) to $(BIGOH (lhs.length + rhs.length) * log(lhs.length +
rhs.length)) (worst-case) evaluations of $(D swap).
rhs.length)) (worst-case) evaluations of `swap`.
Params:
less = The predicate to sort by.
@ -143,8 +143,8 @@ if (hasLength!(RandomAccessRange2) && hasSlicing!(RandomAccessRange2))
// isSorted
/**
Checks whether a $(REF_ALTTEXT forward range, isForwardRange, std,range,primitives)
is sorted according to the comparison operation $(D less). Performs $(BIGOH r.length)
evaluations of $(D less).
is sorted according to the comparison operation `less`. Performs $(BIGOH r.length)
evaluations of `less`.
Unlike `isSorted`, `isStrictlyMonotonic` does not allow for equal values,
i.e. values for which both `less(a, b)` and `less(b, a)` are false.
@ -291,16 +291,16 @@ if (isForwardRange!Range)
}
/**
Like $(D isSorted), returns $(D true) if the given $(D values) are ordered
according to the comparison operation $(D less). Unlike $(D isSorted), takes values
Like `isSorted`, returns `true` if the given `values` are ordered
according to the comparison operation `less`. Unlike `isSorted`, takes values
directly instead of structured in a range.
$(D ordered) allows repeated values, e.g. $(D ordered(1, 1, 2)) is $(D true). To verify
that the values are ordered strictly monotonically, use $(D strictlyOrdered);
$(D strictlyOrdered(1, 1, 2)) is $(D false).
`ordered` allows repeated values, e.g. `ordered(1, 1, 2)` is `true`. To verify
that the values are ordered strictly monotonically, use `strictlyOrdered`;
`strictlyOrdered(1, 1, 2)` is `false`.
With either function, the predicate must be a strict ordering. For example,
using $(D "a <= b") instead of $(D "a < b") is incorrect and will cause failed
using `"a <= b"` instead of `"a < b"` is incorrect and will cause failed
assertions.
Params:
@ -308,8 +308,8 @@ Params:
less = The comparison predicate
Returns:
$(D true) if the values are ordered; $(D ordered) allows for duplicates,
$(D strictlyOrdered) does not.
`true` if the values are ordered; `ordered` allows for duplicates,
`strictlyOrdered` does not.
*/
bool ordered(alias less = "a < b", T...)(T values)
@ -366,15 +366,15 @@ if (is(typeof(ordered!less(values))))
// partition
/**
Partitions a range in two using the given $(D predicate).
Specifically, reorders the range $(D r = [left, right$(RPAREN)) using $(D swap)
such that all elements $(D i) for which $(D predicate(i)) is $(D true) come
before all elements $(D j) for which $(D predicate(j)) returns $(D false).
Partitions a range in two using the given `predicate`.
Specifically, reorders the range `r = [left, right$(RPAREN)` using `swap`
such that all elements `i` for which `predicate(i)` is `true` come
before all elements `j` for which `predicate(j)` returns `false`.
Performs $(BIGOH r.length) (if unstable or semistable) or $(BIGOH
r.length * log(r.length)) (if stable) evaluations of $(D less) and $(D
r.length * log(r.length)) (if stable) evaluations of `less` and $(D
swap). The unstable version computes the minimum possible evaluations
of $(D swap) (roughly half of those performed by the semistable
of `swap` (roughly half of those performed by the semistable
version).
Params:
@ -384,13 +384,13 @@ Params:
Returns:
The right part of $(D r) after partitioning.
The right part of `r` after partitioning.
If $(D ss == SwapStrategy.stable), $(D partition) preserves the relative
ordering of all elements $(D a), $(D b) in $(D r) for which $(D predicate(a) ==
predicate(b)). If $(D ss == SwapStrategy.semistable), $(D partition) preserves
the relative ordering of all elements $(D a), $(D b) in the left part of $(D r)
for which $(D predicate(a) == predicate(b)).
If `ss == SwapStrategy.stable`, `partition` preserves the relative
ordering of all elements `a`, `b` in `r` for which `predicate(a) =$D(
predicate(b)). If `ss == SwapStrategy.semistable`, `partition` preserves
the relative ordering of all elements `a`, `b` in the left part of `r`
for which `predicate(a) == predicate(b)`.
See_Also:
STL's $(HTTP sgi.com/tech/stl/_partition.html, _partition)$(BR)
@ -576,17 +576,17 @@ if (ss != SwapStrategy.stable && isInputRange!Range && hasSwappableElements!Rang
Partitions `r` around `pivot` using comparison function `less`, algorithm akin
to $(LINK2 https://en.wikipedia.org/wiki/Quicksort#Hoare_partition_scheme,
Hoare partition). Specifically, permutes elements of `r` and returns
an index $(D k < r.length) such that:
an index `k < r.length` such that:
$(UL
$(LI `r[pivot]` is swapped to `r[k]`)
$(LI All elements `e` in subrange $(D r[0 .. k]) satisfy $(D !less(r[k], e))
$(LI All elements `e` in subrange `r[0 .. k]` satisfy `!less(r[k], e)`
(i.e. `r[k]` is greater than or equal to each element to its left according to
predicate `less`))
$(LI All elements `e` in subrange $(D r[0 .. k]) satisfy $(D !less(e,
$(LI All elements `e` in subrange `r[0 .. k]` satisfy `!less(e$D(
r[k])) (i.e. `r[k]` is less than or equal to each element to its right
according to predicate `less`)))
@ -773,7 +773,7 @@ if (isRandomAccessRange!Range && hasLength!Range && hasSlicing!Range)
Params:
pred = The predicate that the range should be partitioned by.
r = The range to check.
Returns: $(D true) if $(D r) is partitioned according to predicate $(D pred).
Returns: `true` if `r` is partitioned according to predicate `pred`.
*/
bool isPartitioned(alias pred, Range)(Range r)
if (isForwardRange!(Range))
@ -799,13 +799,13 @@ if (isForwardRange!(Range))
// partition3
/**
Rearranges elements in $(D r) in three adjacent ranges and returns
them. The first and leftmost range only contains elements in $(D r)
less than $(D pivot). The second and middle range only contains
elements in $(D r) that are equal to $(D pivot). Finally, the third
and rightmost range only contains elements in $(D r) that are greater
than $(D pivot). The less-than test is defined by the binary function
$(D less).
Rearranges elements in `r` in three adjacent ranges and returns
them. The first and leftmost range only contains elements in `r`
less than `pivot`. The second and middle range only contains
elements in `r` that are equal to `pivot`. Finally, the third
and rightmost range only contains elements in `r` that are greater
than `pivot`. The less-than test is defined by the binary function
`less`.
Params:
less = The predicate to use for the rearrangement.
@ -817,7 +817,7 @@ Returns:
A $(REF Tuple, std,typecons) of the three resulting ranges. These ranges are
slices of the original range.
BUGS: stable $(D partition3) has not been implemented yet.
BUGS: stable `partition3` has not been implemented yet.
*/
auto partition3(alias less = "a < b", SwapStrategy ss = SwapStrategy.unstable, Range, E)
(Range r, E pivot)
@ -916,7 +916,7 @@ if (ss == SwapStrategy.unstable && isRandomAccessRange!Range
// makeIndex
/**
Computes an index for $(D r) based on the comparison $(D less). The
Computes an index for `r` based on the comparison `less`. The
index is a sorted array of pointers or indices into the original
range. This technique is similar to sorting, but it is more flexible
because (1) it allows "sorting" of immutable collections, (2) allows
@ -926,15 +926,15 @@ and (4) may be faster when dealing with large objects. However, using
an index may also be slower under certain circumstances due to the
extra indirection, and is always larger than a sorting-based solution
because it needs space for the index in addition to the original
collection. The complexity is the same as $(D sort)'s.
collection. The complexity is the same as `sort`'s.
The first overload of $(D makeIndex) writes to a range containing
The first overload of `makeIndex` writes to a range containing
pointers, and the second writes to a range containing offsets. The
first overload requires $(D Range) to be a
first overload requires `Range` to be a
$(REF_ALTTEXT forward range, isForwardRange, std,range,primitives), and the
latter requires it to be a random-access range.
$(D makeIndex) overwrites its second argument with the result, but
`makeIndex` overwrites its second argument with the result, but
never reallocates it.
Params:
@ -943,11 +943,11 @@ Params:
r = The range to index.
index = The resulting index.
Returns: The pointer-based version returns a $(D SortedRange) wrapper
over index, of type $(D SortedRange!(RangeIndex, (a, b) =>
Returns: The pointer-based version returns a `SortedRange` wrapper
over index, of type `SortedRange!(RangeIndex, (a, b) =$D(
binaryFun!less(*a, *b))) thus reflecting the ordering of the
index. The index-based version returns $(D void) because the ordering
relation involves not only $(D index) but also $(D r).
index. The index-based version returns `void` because the ordering
relation involves not only `index` but also `r`.
Throws: If the second argument's length is less than that of the range
indexed, an exception is thrown.
@ -1440,18 +1440,15 @@ private template validPredicates(E, less...)
}
/**
$(D auto multiSort(Range)(Range r)
if (validPredicates!(ElementType!Range, less));)
Sorts a range by multiple keys. The call $(D multiSort!("a.id < b.id",
"a.date > b.date")(r)) sorts the range $(D r) by $(D id) ascending,
and sorts elements that have the same $(D id) by $(D date)
"a.date > b.date")(r)) sorts the range `r` by `id` ascending,
and sorts elements that have the same `id` by `date`
descending. Such a call is equivalent to $(D sort!"a.id != b.id ? a.id
< b.id : a.date > b.date"(r)), but $(D multiSort) is faster because it
< b.id : a.date > b.date"(r)), but `multiSort` is faster because it
does fewer comparisons (in addition to being more convenient).
Returns:
The initial range wrapped as a $(D SortedRange) with its predicates
The initial range wrapped as a `SortedRange` with its predicates
converted to an equivalent single predicate.
*/
template multiSort(less...) //if (less.length > 1)
@ -1799,14 +1796,14 @@ private void sort5(alias lt, Range)(Range r)
// sort
/**
Sorts a random-access range according to the predicate $(D less). Performs
$(BIGOH r.length * log(r.length)) evaluations of $(D less). If `less` involves
Sorts a random-access range according to the predicate `less`. Performs
$(BIGOH r.length * log(r.length)) evaluations of `less`. If `less` involves
expensive computations on the _sort key, it may be worthwhile to use
$(LREF schwartzSort) instead.
Stable sorting requires $(D hasAssignableElements!Range) to be true.
Stable sorting requires `hasAssignableElements!Range` to be true.
$(D sort) returns a $(REF SortedRange, std,range) over the original range,
`sort` returns a $(REF SortedRange, std,range) over the original range,
allowing functions that can take advantage of sorted data to know that the
range is sorted and adjust accordingly. The $(REF SortedRange, std,range) is a
wrapper around the original range, so both it and the original range are sorted.
@ -1815,14 +1812,14 @@ they $(I can) know that $(REF SortedRange, std,range) has been sorted.
Preconditions:
The predicate is expected to satisfy certain rules in order for $(D sort) to
The predicate is expected to satisfy certain rules in order for `sort` to
behave as expected - otherwise, the program may fail on certain inputs (but not
others) when not compiled in release mode, due to the cursory $(D assumeSorted)
check. Specifically, $(D sort) expects $(D less(a,b) && less(b,c)) to imply
$(D less(a,c)) (transitivity), and, conversely, $(D !less(a,b) && !less(b,c)) to
imply $(D !less(a,c)). Note that the default predicate ($(D "a < b")) does not
others) when not compiled in release mode, due to the cursory `assumeSorted`
check. Specifically, `sort` expects `less(a,b) && less(b,c)` to imply
`less(a,c)` (transitivity), and, conversely, `!less(a,b) && !less(b,c)` to
imply `!less(a,c)`. Note that the default predicate (`"a < b"`) does not
always satisfy these conditions for floating point types, because the expression
will always be $(D false) when either $(D a) or $(D b) is NaN.
will always be `false` when either `a` or `b` is NaN.
Use $(REF cmp, std,math) instead.
Params:
@ -1830,8 +1827,8 @@ Params:
ss = The swapping strategy to use.
r = The range to sort.
Returns: The initial range wrapped as a $(D SortedRange) with the predicate
$(D binaryFun!less).
Returns: The initial range wrapped as a `SortedRange` with the predicate
`binaryFun!less`.
Algorithms: $(HTTP en.wikipedia.org/wiki/Introsort, Introsort) is used for unstable sorting and
$(HTTP en.wikipedia.org/wiki/Timsort, Timsort) is used for stable sorting.
@ -2882,14 +2879,14 @@ sort!((a, b) => hashFun(a) < hashFun(b))(array);
schwartzSort!(hashFun, "a < b")(array);
----
The $(D schwartzSort) function might require less temporary data and
The `schwartzSort` function might require less temporary data and
be faster than the Perl idiom or the decorate-sort-undecorate idiom
present in Python and Lisp. This is because sorting is done in-place
and only minimal extra data (one array of transformed elements) is
created.
To check whether an array was sorted and benefit of the speedup of
Schwartz sorting, a function $(D schwartzIsSorted) is not provided
Schwartz sorting, a function `schwartzIsSorted` is not provided
because the effect can be achieved by calling $(D
isSorted!less(map!transform(r))).
@ -2899,8 +2896,8 @@ Params:
ss = The swapping strategy to use.
r = The range to sort.
Returns: The initial range wrapped as a $(D SortedRange) with the
predicate $(D (a, b) => binaryFun!less(transform(a),
Returns: The initial range wrapped as a `SortedRange` with the
predicate `(a, b) => binaryFun!less(transform(a)$D(
transform(b))).
*/
SortedRange!(R, ((a, b) => binaryFun!less(unaryFun!transform(a),
@ -3018,11 +3015,11 @@ if (isRandomAccessRange!R && hasLength!R)
// partialSort
/**
Reorders the random-access range $(D r) such that the range $(D r[0
.. mid]) is the same as if the entire $(D r) were sorted, and leaves
the range $(D r[mid .. r.length]) in no particular order. Performs
$(BIGOH r.length * log(mid)) evaluations of $(D pred). The
implementation simply calls $(D topN!(less, ss)(r, n)) and then $(D
Reorders the random-access range `r` such that the range `r[$D(
.. mid]) is the same as if the entire `r` were sorted, and leaves
the range `r[mid .. r.length]` in no particular order. Performs
$(BIGOH r.length * log(mid)) evaluations of `pred`. The
implementation simply calls `topN!(less, ss)(r, n)` and then $(D
sort!(less, ss)(r[0 .. n])).
Params:
@ -3077,17 +3074,17 @@ if (isRandomAccessRange!(Range1) && hasLength!Range1 &&
// topN
/**
Reorders the range $(D r) using $(D swap) such that $(D r[nth]) refers
Reorders the range `r` using `swap` such that `r[nth]` refers
to the element that would fall there if the range were fully
sorted. In addition, it also partitions $(D r) such that all elements
$(D e1) from $(D r[0]) to $(D r[nth]) satisfy $(D !less(r[nth], e1)),
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
(according to $(D less)) elements in $(D r). Performs an expected
sorted. In addition, it also partitions `r` such that all elements
`e1` from `r[0]` to `r[nth]` satisfy `!less(r[nth], e1)`,
and all elements `e2` from `r[nth]` to `r[r.length]` satisfy
`!less(e2, r[nth])`. Effectively, it finds the nth smallest
(according to `less`) elements in `r`. Performs an expected
$(BIGOH r.length) (if unstable) or $(BIGOH r.length * log(r.length))
(if stable) evaluations of $(D less) and $(D swap).
(if stable) evaluations of `less` and `swap`.
If $(D n >= r.length), the algorithm has no effect and returns
If `n >= r.length`, the algorithm has no effect and returns
`r[0 .. r.length]`.
Params:
@ -3668,11 +3665,11 @@ if (isRandomAccessRange!(Range1) && hasLength!Range1 &&
}
/**
Copies the top $(D n) elements of the
$(REF_ALTTEXT input range, isInputRange, std,range,primitives) $(D source) into the
random-access range $(D target), where $(D n =
target.length). Elements of $(D source) are not touched. If $(D
sorted) is $(D true), the target is sorted. Otherwise, the target
Copies the top `n` elements of the
$(REF_ALTTEXT input range, isInputRange, std,range,primitives) `source` into the
random-access range `target`, where `n $D(
target.length). Elements of `source` are not touched. If $(D
sorted) is `true`, the target is sorted. Otherwise, the target
respects the $(HTTP en.wikipedia.org/wiki/Binary_heap, heap property).
Params:
@ -3735,7 +3732,7 @@ Similar to $(LREF topN), except that the range is not modified.
Params:
less = A binary predicate that defines the ordering of range elements.
Defaults to $(D a < b).
Defaults to `a < b`.
ss = $(RED (Not implemented yet.)) Specify the swapping strategy.
r = A
$(REF_ALTTEXT random-access range, isRandomAccessRange, std,range,primitives)
@ -3743,13 +3740,13 @@ Params:
index = A
$(REF_ALTTEXT random-access range, isRandomAccessRange, std,range,primitives)
with assignable elements to build the index in. The length of this range
determines how many top elements to index in $(D r).
determines how many top elements to index in `r`.
This index range can either have integral elements, in which case the
constructed index will consist of zero-based numerical indices into
$(D r); or it can have pointers to the element type of $(D r), in which
`r`; or it can have pointers to the element type of `r`, in which
case the constructed index will be pointers to the top elements in
$(D r).
`r`.
sorted = Determines whether to sort the index by the elements they refer
to.
@ -3852,7 +3849,7 @@ Private for the time being.
Computes the median of 2 to 5 arbitrary indexes in random-access range `r`
using hand-written specialized algorithms. The indexes must be distinct (if not,
behavior is implementation-defined). The function also partitions the elements
involved around the median, e.g. $(D medianOf(r, a, b, c)) not only fills `r[b]`
involved around the median, e.g. `medianOf(r, a, b, c)` not only fills `r[b]`
with the median of `r[a]`, `r[b]`, and `r[c]`, but also puts the minimum in
`r[a]` and the maximum in `r[c]`.
@ -3861,9 +3858,9 @@ less = The comparison predicate used, modeled as a
$(LINK2 https://en.wikipedia.org/wiki/Weak_ordering#Strict_weak_orderings, strict weak ordering)
(irreflexive, antisymmetric, transitive, and implying a transitive equivalence).
flag = Used only for even values of `T.length`. If `No.leanRight`, the median
"leans left", meaning $(D medianOf(r, a, b, c, d)) puts the lower median of the
"leans left", meaning `medianOf(r, a, b, c, d)` puts the lower median of the
four in `r[b]`, the minimum in `r[a]`, and the two others in `r[c]` and `r[d]`.
Conversely, $(D median!("a < b", Yes.leanRight)(r, a, b, c, d)) puts the upper
Conversely, `median!("a < b", Yes.leanRight)(r, a, b, c, d)` puts the upper
median of the four in `r[c]`, the maximum in `r[d]`, and the two others in
`r[a]` and `r[b]`.
r = The range containing the indexes.
@ -4025,16 +4022,16 @@ if (isRandomAccessRange!Range && hasLength!Range &&
// nextPermutation
/**
* Permutes $(D range) in-place to the next lexicographically greater
* Permutes `range` in-place to the next lexicographically greater
* permutation.
*
* The predicate $(D less) defines the lexicographical ordering to be used on
* The predicate `less` defines the lexicographical ordering to be used on
* the range.
*
* If the range is currently the lexicographically greatest permutation, it is
* permuted back to the least permutation and false is returned. Otherwise,
* true is returned. One can thus generate all permutations of a range by
* sorting it according to $(D less), which produces the lexicographically
* sorting it according to `less`, which produces the lexicographically
* least permutation, and then calling nextPermutation until it returns false.
* This is guaranteed to generate all distinct permutations of the range
* exactly once. If there are $(I N) elements in the range and all of them are
@ -4252,10 +4249,10 @@ if (isBidirectionalRange!BidirectionalRange &&
// nextEvenPermutation
/**
* Permutes $(D range) in-place to the next lexicographically greater $(I even)
* Permutes `range` in-place to the next lexicographically greater $(I even)
* permutation.
*
* The predicate $(D less) defines the lexicographical ordering to be used on
* The predicate `less` defines the lexicographical ordering to be used on
* the range.
*
* An even permutation is one which is produced by swapping an even number of