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
) 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
Name | Description |
---|---|
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
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"