Search
View source code
Display the source code in std/algorithm/mutation.d from which this page was generated on github.
Report a bug
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 local clone.

# Module `std.algorithm.mutation`

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

Cheat Sheet
Function Name Description
`bringToFront` 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]`.
`copy` Copies a range to another. If `a = [1, 2, 3]` and `b = new int`, then `copy(a, b)` leaves `b = [1, 2, 3, 0, 0]` and returns `b[3 .. \$]`.
`fill` Fills a range with a pattern, e.g., if `a = new int`, then `fill(a, 4)` leaves `a = [4, 4, 4]` and `fill(a, [3, 4])` leaves `a = [3, 4, 3]`.
`initializeAll` If `a = [1.2, 3.4]`, then `initializeAll(a)` leaves `a = [double.init, double.init]`.
`move` `move(a, b)` moves `a` into `b`. `move(a)` reads `a` destructively when necessary.
`moveEmplace` Similar to `move` but assumes `target` is uninitialized.
`moveAll` Moves all elements from one range to another.
`moveEmplaceAll` Similar to `moveAll` but assumes all elements in `target` are uninitialized.
`moveSome` Moves as many elements as possible from one range to another.
`moveEmplaceSome` Similar to `moveSome` but assumes all elements in `target` are uninitialized.
`remove` Removes elements from a range in-place, and returns the shortened range.
`reverse` If `a = [1, 2, 3]`, `reverse(a)` changes it to `[3, 2, 1]`.
`strip` Strips all leading and trailing elements equal to a value, or that satisfy a predicate. If `a = [1, 1, 0, 1, 1]`, then `strip(a, 1)` and `strip!(e => e == 1)(a)` returns ``.
`stripLeft` Strips all leading elements equal to a value, or that satisfy a predicate. If `a = [1, 1, 0, 1, 1]`, then `stripLeft(a, 1)` and `stripLeft!(e => e == 1)(a)` returns `[0, 1, 1]`.
`stripRight` Strips all trailing elements equal to a value, or that satisfy a predicate. If `a = [1, 1, 0, 1, 1]`, then `stripRight(a, 1)` and `stripRight!(e => e == 1)(a)` returns `[1, 1, 0]`.
`swap` Swaps two values.
`swapAt` Swaps two values by indices.
`swapRanges` Swaps all elements of two ranges.
`uninitializedFill` Fills a range (assumed uninitialized) with a value.

## Functions

NameDescription
``` bringToFront(front, back) ``` `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.
``` copy(source, target) ``` Copies the content of `source` into `target` and returns the remaining (unfilled) part of `target`.
``` fill(range, value) ``` Assigns `value` to each element of input range `range`.
``` initializeAll(range) ``` Initializes all elements of `range` with their `.init` value. Assumes that the elements of the range are uninitialized.
``` move(source, target) ``` Moves `source` into `target`, via a destructive copy when necessary.
``` moveAll(src, tgt) ``` Calls `move(a, b)` for each element `a` in `src` and the corresponding element `b` in `tgt`, in increasing order.
``` moveEmplace(source, target) ``` Similar to `move` but assumes `target` is uninitialized. This is more efficient because `source` can be blitted over `target` without destroying or initializing it first.
``` moveEmplaceAll(src, tgt) ``` Similar to `moveAll` but assumes all elements in `tgt` are uninitialized. Uses `moveEmplace` to move elements from `src` over elements from `tgt`.
``` moveEmplaceSome(src, tgt) ``` Same as `moveSome` but assumes all elements in `tgt` are uninitialized. Uses `moveEmplace` to move elements from `src` over elements from `tgt`.
``` moveSome(src, tgt) ``` Calls `move(a, b)` for each element `a` in `src` and the corresponding element `b` in `tgt`, in increasing order, stopping when either range has been exhausted.
``` remove(range, offset) ``` Eliminates elements at given offsets from `range` and returns the shortened range.
``` remove(range) ``` Reduces the length of the bidirectional range `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 `s = SwapStrategy.stable` (the default), elements are moved progressively to front such that their relative order is preserved. Returns the filtered range.
``` reverse(r) ``` Reverses `r` in-place. Performs `r.length / 2` evaluations of `swap`. UTF sequences consisting of multiple code units are preserved properly.
``` strip(range, element) ``` The strip group of functions allow stripping of either leading, trailing, or both leading and trailing elements.
``` stripLeft(range, element) ``` The strip group of functions allow stripping of either leading, trailing, or both leading and trailing elements.
``` stripRight(range, element) ``` The strip group of functions allow stripping of either leading, trailing, or both leading and trailing elements.
``` swap(lhs, rhs) ``` 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.
``` swapAt(r, i1, i2) ``` Swaps two elements in-place of a range `r`, specified by their indices `i1` and `i2`.
``` swapRanges(r1, r2) ``` 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.
``` uninitializedFill(range, 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, `fill` and uninitializedFill are equivalent).

## Enums

NameDescription
``` SwapStrategy ``` 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.