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

std.algorithm.mutation

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

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.

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 bringToFront function treats strings at the code unit
level and it is not concerned with Unicode character integrity.
bringToFront is designed as a function for moving elements
in ranges, not as a string function.

Performs Ο(max(front.length, back.length)) evaluations of swap.

Preconditions
Either front and back are disjoint, or back is
reachable from front and front is not reachable from 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 arr[0 .. 4] above. In
the example below, r2 is a right subrange of r1.

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 [ "abc",
"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 [
"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
[ "abc", "aBc", "b" ] would be the correct result). Such
algorithms are called stable. If the ordering algorithm may swap
equivalent elements discretionarily, the ordering is called unstable.

Yet another class of algorithms may choose an intermediate tradeoff by
being stable only on a well-defined subrange of the range. There is no
established terminology for such behavior; this library calls it semistable.

Generally, the stable ordering strategy may be more costly in
time and/or space than the other two because it imposes additional
constraints. Similarly, semistable may be costlier than unstable. As (semi-)stability is not needed very often, the ordering
algorithms in this module parameterized by SwapStrategy all
choose SwapStrategy.unstable as the default.

Note that remove does not change the length of the original range directly;
instead, it returns the shortened range. If its return value is not assigned to
the original range, the original range will retain its original length, though
its contents will have changed:

The element at offset 1 has been removed and the rest of the elements have
shifted up to fill its place, however, the original array remains of the same
length. This is because all functions in std.algorithm only change content, not topology. The value 8 is repeated because move was
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 remove. In that case,
elements at the respective indices are all removed. The indices must
be passed in increasing order, otherwise an exception occurs.

(Note that all indices refer to slots in the original array, not
in the array as it is being progressively shortened.) Finally, any
combination of integral offsets and tuples composed of two integral
offsets can be passed in.

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. 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 SwapStrategy.unstable to remove.

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, 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 remove works on bidirectional ranges that have assignable
lvalue elements. The moving strategy is (listed from fastest to slowest):

If s == SwapStrategy.unstable && isRandomAccessRange!Range &&
hasLength!Range && hasLvalueElements!Range, then elements are moved from the
end of the range into the slots to be filled. In this case, the absolute
minimum of moves is performed.

Otherwise, if 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 range.popFront.

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.

Parameters:

s

a SwapStrategy to determine if the original order needs to be preserved

Reduces the length of the
bidirectional rangerange 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 s = SwapStrategy.stable (the default),
elements are moved progressively to front such that their relative
order is preserved. Returns the filtered range.

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 ba\u0301d ("bád") will result in d\u0301ab ("d́ab") instead of
da\u0301b ("dáb").

The strip group of functions allow stripping of either leading, trailing,
or both leading and trailing elements.

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 strip and stripRight functions require the range to
be a BidirectionalRangerange.

All of these functions come in two varieties: one takes a target element,
where the range will be stripped as long as this element can be found.
The other takes a lambda predicate, where the range will be stripped as
long as the predicate returns true.

Swaps all elements of r1 with successive elements in r2.
Returns a tuple containing the remainder portions of r1 and 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.

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, fill and
uninitializedFill are equivalent).

Parameters:

Range range

An
input range
that exposes references to its elements and has assignable
elements