Menu
Search

API Documentation

version 2.108.0

overview

View source code
Display the source code in std/range/package.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.

std.range.Zip/zip - multiple declarations

Function zip

Iterate several ranges in lockstep. The element type is a proxy tuple that allows accessing the current element in the nth range by using e[n].

auto zip(Ranges...) (
  Ranges ranges
)
if (Ranges.length && allSatisfy!(isInputRange, Ranges));

auto zip(Ranges...) (
  StoppingPolicy sp,
  Ranges ranges
)
if (Ranges.length && allSatisfy!(isInputRange, Ranges));

zip is similar to lockstep, but lockstep doesn't bundle its elements and uses the opApply protocol. lockstep allows reference access to the elements in foreach iterations.

Parameters

NameDescription
sp controls what zip will do if the ranges are different lengths
ranges the ranges to zip together

Returns

At minimum, an input range. Zip offers the lowest range facilities of all components, e.g. it offers random access iff all ranges offer random access, and also offers mutation and swapping if all ranges offer it. Due to this, Zip is extremely powerful because it allows manipulating several ranges in lockstep.

Throws

An Exception if all of the ranges are not the same length and sp is set to StoppingPolicy.requireSameLength.

Limitations

The @nogc and nothrow attributes cannot be inferred for the Zip struct because StoppingPolicy can vary at runtime. This limitation is not shared by the anonymous range returned by the zip function when not given an explicit StoppingPolicy as an argument.

Example

import std.algorithm.comparison : equal;
import std.algorithm.iteration : map;

// pairwise sum
auto arr = only(0, 1, 2);
auto part1 = zip(arr, arr.dropOne).map!"a[0] + a[1]";
assert(part1.equal(only(1, 3)));

Example

import std.conv : to;

int[] a = [ 1, 2, 3 ];
string[] b = [ "a", "b", "c" ];
string[] result;

foreach (tup; zip(a, b))
{
    result ~= tup[0].to!string ~ tup[1];
}

writeln(result); // ["1a", "2b", "3c"]

size_t idx = 0;
// unpacking tuple elements with foreach
foreach (e1, e2; zip(a, b))
{
    writeln(e1); // a[idx]
    writeln(e2); // b[idx]
    ++idx;
}

Example

zip is powerful - the following code sorts two arrays in parallel: 

import std.algorithm.sorting : sort;

int[] a = [ 1, 2, 3 ];
string[] b = [ "a", "c", "b" ];
zip(a, b).sort!((t1, t2) => t1[0] > t2[0]);

writeln(a); // [3, 2, 1]
// b is sorted according to a's sorting
writeln(b); // ["b", "c", "a"]

Struct Zip

Iterate several ranges in lockstep. The element type is a proxy tuple that allows accessing the current element in the nth range by using e[n].

struct Zip(Ranges...)
  
if (Ranges.length && allSatisfy!(isInputRange, Ranges));

zip is similar to lockstep, but lockstep doesn't bundle its elements and uses the opApply protocol. lockstep allows reference access to the elements in foreach iterations.

Constructors

NameDescription
this (rs, s) Builds an object. Usually this is invoked indirectly by using the zip function.

Properties

NameTypeDescription
back[get] ElementTypeReturns the rightmost element.
back[set] ElementTypeReturns the current iterated element.
front[get] ElementTypeReturns the current iterated element.
front[set] ElementTypeSets the front of all iterated ranges.
length[get] autoReturns the length of this range. Defined only if all ranges define length.
save[get] Zip

Methods

NameDescription
moveAt (n) Destructively reads the nth element in the composite range. Defined if all ranges offer random access.
moveBack () Moves out the back.
moveFront () Moves out the front.
opIndex (n) Returns the nth element in the composite range. Defined if all ranges offer random access.
opIndexAssign (v, n) Assigns to the nth element in the composite range. Defined if all ranges offer random access.
opSlice (from, to) Returns a slice of the range. Defined only if all range define slicing.
popBack () Calls popBack for all controlled ranges.
popFront () Advances to the next element in all controlled ranges.

Aliases

NameDescription
opDollar Returns the length of this range. Defined only if all ranges define length.

Parameters

NameDescription
sp controls what zip will do if the ranges are different lengths
ranges the ranges to zip together

Returns

At minimum, an input range. Zip offers the lowest range facilities of all components, e.g. it offers random access iff all ranges offer random access, and also offers mutation and swapping if all ranges offer it. Due to this, Zip is extremely powerful because it allows manipulating several ranges in lockstep.

Throws

An Exception if all of the ranges are not the same length and sp is set to StoppingPolicy.requireSameLength.

Limitations

The @nogc and nothrow attributes cannot be inferred for the Zip struct because StoppingPolicy can vary at runtime. This limitation is not shared by the anonymous range returned by the zip function when not given an explicit StoppingPolicy as an argument.

Example

import std.algorithm.comparison : equal;
import std.algorithm.iteration : map;

// pairwise sum
auto arr = only(0, 1, 2);
auto part1 = zip(arr, arr.dropOne).map!"a[0] + a[1]";
assert(part1.equal(only(1, 3)));

Example

import std.conv : to;

int[] a = [ 1, 2, 3 ];
string[] b = [ "a", "b", "c" ];
string[] result;

foreach (tup; zip(a, b))
{
    result ~= tup[0].to!string ~ tup[1];
}

writeln(result); // ["1a", "2b", "3c"]

size_t idx = 0;
// unpacking tuple elements with foreach
foreach (e1, e2; zip(a, b))
{
    writeln(e1); // a[idx]
    writeln(e2); // b[idx]
    ++idx;
}

Example

zip is powerful - the following code sorts two arrays in parallel: 

import std.algorithm.sorting : sort;

int[] a = [ 1, 2, 3 ];
string[] b = [ "a", "c", "b" ];
zip(a, b).sort!((t1, t2) => t1[0] > t2[0]);

writeln(a); // [3, 2, 1]
// b is sorted according to a's sorting
writeln(b); // ["b", "c", "a"]

Authors

Andrei Alexandrescu, David Simcha, Jonathan M Davis, and Jack Stouffer. Credit for some of the ideas in building this module goes to Leonardo Maffi.

License

Boost License 1.0.