View source code
Display the source code in std/algorithm/mutation.d from which this page was generated on github.
Report a bug
If you spot a problem with this page, click here to create a Bugzilla issue.
Improve this page
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.

Function std.algorithm.mutation.bringToFront

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.

size_t bringToFront(InputRange, ForwardRange) (
  InputRange front,
  ForwardRange back
)
if (isInputRange!InputRange && isForwardRange!ForwardRange);

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.

The bringToFront function 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.

Preconditions

Either front and back are disjoint, or back is reachable from front and front is not reachable from back.

Parameters

NameDescription
front an input range
back a forward range

Returns

The number of elements brought to the front, i.e., the length of back.

See Also

STL's rotate

Example

The simplest use of bringToFront is for rotating elements in a buffer. For example:

auto arr = [4, 5, 6, 7, 1, 2, 3];
auto p = bringToFront(arr[0 .. 4], arr[4 .. $]);
writeln(p); // arr.length - 4
writeln(arr); // [1, 2, 3, 4, 5, 6, 7]

Example

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.

import std.algorithm.comparison : equal;
import std.container : SList;
import std.range.primitives : popFrontN;

auto list = SList!(int)(4, 5, 6, 7, 1, 2, 3);
auto r1 = list[];
auto r2 = list[]; popFrontN(r2, 4);
assert(equal(r2, [ 1, 2, 3 ]));
bringToFront(r1, r2);
assert(equal(list[], [ 1, 2, 3, 4, 5, 6, 7 ]));

Example

Elements can be swapped across ranges of different types:

import std.algorithm.comparison : equal;
import std.container : SList;

auto list = SList!(int)(4, 5, 6, 7);
auto vec = [ 1, 2, 3 ];
bringToFront(list[], vec);
assert(equal(list[], [ 1, 2, 3, 4 ]));
assert(equal(vec, [ 5, 6, 7 ]));

Example

Unicode integrity is not preserved:

import std.string : representation;
auto ar = representation("a".dup);
auto br = representation("รง".dup);

bringToFront(ar, br);

auto a = cast(char[]) ar;
auto b = cast(char[]) br;

// Illegal UTF-8
writeln(a); // "\303"
// Illegal UTF-8
writeln(b); // "\247a"

Authors

Andrei Alexandrescu

License

Boost License 1.0.