Menu

- Learn
- Documentation
  - Language Reference
  - Library Reference
  - Command-line Reference
  - Feature Overview
  - Articles
- Packages
- Community
  - Blog
  - Orgs using D
  - Twitter
  - Forums
  - IRC
  - Wiki
  - GitHub
  - Issues
  - Foundation
  - Donate
- Resources
  - Books
  - Tutorials
  - Tools
  - Editors
  - IDEs
  - Visual D
  - Acknowledgments
  - D Style
  - Glossary
  - Sitemap

Search
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 a local clone.

# std.array

Functions and types that manipulate built-in arrays and associative arrays.
This module provides all kinds of functions to create, manipulate or convert arrays:

Function Name | Description
--- | ---
array | Returns a copy of the input in a newly allocated dynamic array.
appender | Returns a new Appender or RefAppender initialized with a given array.
assocArray | Returns a newly allocated associative array from a range of key/value tuples.
byPair | Construct a range iterating over an associative array by key/value tuples.
insertInPlace | Inserts into an existing array at a given position.
join | Concatenates a range of ranges into one array.
minimallyInitializedArray | Returns a new array of type T.
replace | Returns a new array with all occurrences of a certain subrange replaced.
replaceFirst | Returns a new array with the first occurrence of a certain subrange replaced.
replaceInPlace | Replaces all occurrences of a certain subrange and puts the result into a given array.
replaceInto | Replaces all occurrences of a certain subrange and puts the result into an output range.
replaceLast | Returns a new array with the last occurrence of a certain subrange replaced.
replaceSlice | Returns a new array with a given slice replaced.
replicate | Creates a new array out of several copies of an input array or range.
sameHead | Checks if the initial segments of two arrays refer to the same place in memory.
sameTail | Checks if the final segments of two arrays refer to the same place in memory.
split | Eagerly split a range or string into an array.
uninitializedArray | Returns a new array of type T without initializing its elements.

License:
Boost License 1.0.
Authors:
Andrei Alexandrescu and Jonathan M Davis

Source: std/array.d

ForeachType!Range[] `array`(Range)(Range `r`)
if (isIterable!Range && !isNarrowString!Range && !isInfinite!Range);
  Allocates an `array` and initializes it with copies of the elements of range `r`.
  Narrow strings are handled as a special case in an overload.
  Parameters:

  Range `r` | range (or aggregate with opApply function) whose elements are copied into the allocated `array`

  Returns:
  allocated and initialized `array`
  Examples:

      auto a = array([1, 2, 3, 4, 5][]);
      assert(a == [ 1, 2, 3, 4, 5 ]);

@trusted ElementType!String[] `array`(String)(scope String `str`)
if (isNarrowString!String);
  Convert a narrow string to an `array` type that fully supports random access. This is handled as a special case and always returns an `array` of dchar
  Parameters:

  String `str` | isNarrowString to be converted to an `array` of dchar

  Returns:
  a dchar[], const(dchar)[], or immutable(dchar)[] depending on the constness of the input.
auto `assocArray`(Range)(Range `r`)
if (isInputRange!Range);
  Returns a newly allocated associative array from a range of key/value tuples.
  Parameters:

  Range `r` | An input range of tuples of keys and values.

  Returns:
  A newly allocated associative array out of elements of the input range, which must be a range of tuples (Key, Value). Returns a `null` associative array reference when given an empty range.

  Duplicates: Associative arrays have unique keys. If `r` contains duplicate keys, then the result will contain the value of the last pair for that key in `r`.

  See Also:
  std.typecons.Tuple, std.range.zip
  Examples:

      import std.range;
      import std.typecons;
      auto a = assocArray(zip([0, 1, 2], ["a", "b", "c"])); // aka zipMap
      assert(is(typeof(a) == string[int]));
      assert(a == [0:"a", 1:"b", 2:"c"]);

      auto b = assocArray([ tuple("foo", "bar"), tuple("baz", "quux") ]);
      assert(is(typeof(b) == string[string]));
      assert(b == ["foo":"bar", "baz":"quux"]);

auto `byPair`(Key, Value)(Value[Key] `aa`);
  Construct a range iterating over an associative array by key/value tuples.
  Parameters:

  Value[Key] `aa` | The associative array to iterate over.

  Returns:
  A forward range of Tuple's of key and value pairs from the given associative array.
  Examples:

      import std.typecons : tuple, Tuple;
      import std.algorithm.sorting : sort;

      auto aa = ["a": 1, "b": 2, "c": 3];
      Tuple!(string, int)[] pairs;

      // Iteration over key/value pairs.
      foreach (pair; aa.byPair)
      {
          pairs ~= pair;
      }

      // Iteration order is implementation-dependent, so we should sort it to get
      // a fixed order.
      sort(pairs);
      assert(pairs == [
          tuple("a", 1),
          tuple("b", 2),
          tuple("c", 3)
      ]);

nothrow @system auto `uninitializedArray`(T, I...)(I `sizes`)
if (isDynamicArray!T && allSatisfy!(isIntegral, I) && hasIndirections!(ElementEncodingType!T));
  Returns a new array of type T allocated on the garbage collected heap without initializing its elements. This can be a useful optimization if every element will be immediately initialized. T may be a multidimensional array. In this case `sizes` may be specified for any number of dimensions from 0 to the number in T.
  `uninitializedArray` is nothrow and weakly pure.
  `uninitializedArray` is @system if the uninitialized element type has pointers.
nothrow @trusted auto `uninitializedArray`(T, I...)(I `sizes`)
if (isDynamicArray!T && allSatisfy!(isIntegral, I) && !hasIndirections!(ElementEncodingType!T));
  Examples:

      double[] arr = uninitializedArray!(double[])(100);
      assert(arr.length == 100);

      double[][] matrix = uninitializedArray!(double[][])(42, 31);
      assert(matrix.length == 42);
      assert(matrix[0].length == 31);

      char*[] ptrs = uninitializedArray!(char*[])(100);
      assert(ptrs.length == 100);

nothrow @trusted auto `minimallyInitializedArray`(T, I...)(I `sizes`)
if (isDynamicArray!T && allSatisfy!(isIntegral, I));
  Returns a new array of type T allocated on the garbage collected heap.
  Partial initialization is done for types with indirections, for preservation of memory safety. Note that elements will only be initialized to 0, but not necessarily the element type's .init.
  `minimallyInitializedArray` is nothrow and weakly pure.
void `insertInPlace`(T, U...)(ref T[] `array`, size_t `pos`, U `stuff`)
if (!isSomeString!(T[]) && allSatisfy!(isInputRangeOrConvertible!T, U) && U.length > 0);
void `insertInPlace`(T, U...)(ref T[] `array`, size_t `pos`, U `stuff`)
if (isSomeString!(T[]) && allSatisfy!(isCharOrStringOrDcharRange, U));
  Inserts `stuff` (which must be an input range or any number of implicitly convertible items) in `array` at position `pos`.
  Parameters:

  T[] `array` | The `array` that `stuff` will be inserted into.
  size_t `pos` | The position in `array` to insert the `stuff`.
  U `stuff` | An input range, or any number of implicitly convertible items to insert into `array`.

  Examples:

      int[] a = [ 1, 2, 3, 4 ];
      a.insertInPlace(2, [ 1, 2 ]);
      assert(a == [ 1, 2, 1, 2, 3, 4 ]);
      a.insertInPlace(3, 10u, 11);
      assert(a == [ 1, 2, 1, 10, 11, 2, 3, 4]);

pure nothrow @safe bool `sameHead`(T)(in T[] `lhs`, in T[] `rhs`);
  Returns whether the fronts of `lhs` and `rhs` both refer to the same place in memory, making one of the arrays a slice of the other which starts at index 0.
  Examples:

      auto a = [1, 2, 3, 4, 5];
      auto b = a[0 .. 2];

      assert(a.sameHead(b));

pure nothrow @trusted bool `sameTail`(T)(in T[] `lhs`, in T[] `rhs`);
  Returns whether the backs of `lhs` and `rhs` both refer to the same place in memory, making one of the arrays a slice of the other which end at index $.
  Examples:

      auto a = [1, 2, 3, 4, 5];
      auto b = a[3..$];

      assert(a.sameTail(b));

ElementEncodingType!S[] `replicate`(S)(S `s`, size_t `n`)
if (isDynamicArray!S);
ElementType!S[] `replicate`(S)(S `s`, size_t `n`)
if (isInputRange!S && !isDynamicArray!S);
  Parameters:

  S `s` | an input range or a dynamic array
  size_t `n` | number of times to repeat `s`

  Returns:
  An array that consists of `s` repeated `n` times. This function allocates, fills, and returns a new array.
  See Also:
  For a lazy version, refer to std.range.repeat.
  Examples:

      auto a = "abc";
      auto s = replicate(a, 3);

      assert(s == "abcabcabc");

      auto b = [1, 2, 3];
      auto c = replicate(b, 3);

      assert(c == [1, 2, 3, 1, 2, 3, 1, 2, 3]);

      auto d = replicate(b, 0);

      assert(d == []);

pure @safe S[] `split`(S)(S `s`)
if (isSomeString!S);
  Eagerly `split` the string `s` into an array of words, using whitespace as delimiter. Runs of whitespace are merged together (no empty words are produced).
  @safe, pure and CTFE-able.
  Parameters:

  S `s` | the string to `split`

  See Also:
  std.algorithm.iteration.splitter for a version that splits using any separator.
  std.regex.splitter for a version that splits using a regular expression defined separator.
  Examples:

      assert(split("hello world") == ["hello","world"]);
      assert(split("192.168.0.1", ".") == ["192", "168", "0", "1"]);

      auto a = split([1, 2, 3, 4, 5, 1, 2, 3, 4, 5], [2, 3]);
      assert(a == [[1], [4, 5, 1], [4, 5]]);

auto `split`(Range, Separator)(Range `range`, Separator `sep`)
if (isForwardRange!Range && is(typeof(ElementType!Range.init == Separator.init)));
auto `split`(Range, Separator)(Range `range`, Separator `sep`)
if (isForwardRange!Range && isForwardRange!Separator && is(typeof(ElementType!Range.init == ElementType!Separator.init)));
auto `split`(alias isTerminator, Range)(Range `range`)
if (isForwardRange!Range && is(typeof(unaryFun!isTerminator(`range`.front))));
  Eagerly splits `range` into an array, using `sep` as the delimiter.
  The range must be a forward range. The separator can be a value of the same type as the elements in `range` or it can be another forward range.

  Example: If `range` is a string, `sep` can be a char or another string. The return type will be an array of strings. If `range` is an int array, `sep` can be an int or another int array. The return type will be an array of int arrays.

  Parameters:

  Range `range` | a forward range.
  Separator `sep` | a value of the same type as the elements of `range` or another forward `range`.

  Returns:
  An array containing the divided parts of `range`.
  See Also:
  std.algorithm.iteration.splitter for the lazy version of this function.
ElementEncodingType!(ElementType!RoR)[] `join`(RoR, R)(RoR `ror`, scope R `sep`)
if (isInputRange!RoR && isInputRange!(Unqual!(ElementType!RoR)) && isInputRange!R && is(Unqual!(ElementType!(ElementType!RoR)) == Unqual!(ElementType!R)));
ElementEncodingType!(ElementType!RoR)[] `join`(RoR, E)(RoR `ror`, scope E `sep`)
if (isInputRange!RoR && isInputRange!(Unqual!(ElementType!RoR)) && is(E : ElementType!(ElementType!RoR)));
ElementEncodingType!(ElementType!RoR)[] `join`(RoR)(RoR `ror`)
if (isInputRange!RoR && isInputRange!(Unqual!(ElementType!RoR)));
  Eagerly concatenates all of the ranges in `ror` together (with the GC) into one array using `sep` as the separator if present.
  Parameters:

  RoR `ror` | An input range of input ranges
  R `sep` | An input range, or a single element, to `join` the ranges on

  Returns:
  An array of elements
  See Also:
  For a lazy version, see std.algorithm.iteration.joiner
  Examples:

      assert(join(["hello", "silly", "world"], " ") == "hello silly world");
      assert(join(["hello", "silly", "world"]) == "hellosillyworld");

      assert(join([[1, 2, 3], [4, 5]], [72, 73]) == [1, 2, 3, 72, 73, 4, 5]);
      assert(join([[1, 2, 3], [4, 5]]) == [1, 2, 3, 4, 5]);

      const string[] arr = ["apple", "banana"];
      assert(arr.join(",") == "apple,banana");
      assert(arr.join() == "applebanana");

E[] `replace`(E, R1, R2)(E[] `subject`, R1 `from`, R2 `to`)
if (isDynamicArray!(E[]) && isForwardRange!R1 && isForwardRange!R2 && (hasLength!R2 || isSomeString!R2));
void `replaceInto`(E, Sink, R1, R2)(Sink `sink`, E[] `subject`, R1 `from`, R2 `to`)
if (isOutputRange!(Sink, E) && isDynamicArray!(E[]) && isForwardRange!R1 && isForwardRange!R2 && (hasLength!R2 || isSomeString!R2));
  Replace occurrences of `from` with `to` in `subject` in a new array. If `sink` is defined, then output the new array into `sink`.
  Parameters:

  Sink `sink` | an output range
  E[] `subject` | the array `to` scan
  R1 `from` | the item `to` `replace`
  R2 `to` | the item `to` `replace` all instances of `from` with

  Returns:
  If `sink` isn't defined, a new array without changing the contents of `subject`, or the original array if no match is found.
  Examples:

      assert("Hello Wörld".replace("o Wö", "o Wo") == "Hello World");
      assert("Hello Wörld".replace("l", "h") == "Hehho Wörhd");

  Examples:

      auto arr = [1, 2, 3, 4, 5];
      auto from = [2, 3];
      auto to = [4, 6];
      auto sink = appender!(int[])();

      replaceInto(sink, arr, from, to);

      assert(sink.data == [1, 4, 6, 4, 5]);

T[] `replace`(T, Range)(T[] `subject`, size_t `from`, size_t `to`, Range `stuff`)
if (isInputRange!Range && (is(ElementType!Range : T) || isSomeString!(T[]) && is(ElementType!Range : dchar)));
  Replaces elements `from` array with indices ranging `from` `from` (inclusive) `to` `to` (exclusive) with the range `stuff`.
  Parameters:

  T[] `subject` | the array `to` scan
  size_t `from` | the starting index
  size_t `to` | the ending index
  Range `stuff` | the items `to` `replace` in-between `from` and `to`

  Returns:
  A new array without changing the contents of `subject`.
  Examples:

      auto a = [ 1, 2, 3, 4 ];
      auto b = a.replace(1, 3, [ 9, 9, 9 ]);
      assert(a == [ 1, 2, 3, 4 ]);
      assert(b == [ 1, 9, 9, 9, 4 ]);

void `replaceInPlace`(T, Range)(ref T[] `array`, size_t `from`, size_t `to`, Range `stuff`)
if (is(typeof(replace(`array`, `from`, `to`, `stuff`))));
  Replaces elements `from` `array` with indices ranging `from` `from` (inclusive) `to` `to` (exclusive) with the range `stuff`. Expands or shrinks the `array` as needed.
  Examples:

      int[] a = [1, 4, 5];
      replaceInPlace(a, 1u, 2u, [2, 3, 4]);
      assert(a == [1, 2, 3, 4, 5]);
      replaceInPlace(a, 1u, 2u, cast(int[])[]);
      assert(a == [1, 3, 4, 5]);
      replaceInPlace(a, 1u, 3u, a[2 .. 4]);
      assert(a == [1, 4, 5, 5]);

E[] `replaceFirst`(E, R1, R2)(E[] `subject`, R1 `from`, R2 `to`)
if (isDynamicArray!(E[]) && isForwardRange!R1 && is(typeof(appender!(E[])().put(`from`[0..1]))) && isForwardRange!R2 && is(typeof(appender!(E[])().put(`to`[0..1]))));
  Replaces the first occurrence of `from` with `to` in `subject`.
  Parameters:

  E[] `subject` | the array `to` scan
  R1 `from` | the item `to` replace
  R2 `to` | the item `to` replace `from` with

  Returns:
  A new array without changing the contents of `subject`, or the original array if no match is found.
  Examples:

      auto a = [1, 2, 2, 3, 4, 5];
      auto b = a.replaceFirst([2], [1337]);
      assert(b == [1, 1337, 2, 3, 4, 5]);

      auto s = "This is a foo foo list";
      auto r = s.replaceFirst("foo", "silly");
      assert(r == "This is a silly foo list");

E[] `replaceLast`(E, R1, R2)(E[] `subject`, R1 `from`, R2 `to`)
if (isDynamicArray!(E[]) && isForwardRange!R1 && is(typeof(appender!(E[])().put(`from`[0..1]))) && isForwardRange!R2 && is(typeof(appender!(E[])().put(`to`[0..1]))));
  Replaces the last occurrence of `from` with `to` in `subject`.
  Parameters:

  E[] `subject` | the array `to` scan
  R1 `from` | the item `to` replace
  R2 `to` | the item `to` replace `from` with

  Returns:
  A new array without changing the contents of `subject`, or the original array if no match is found.
  Examples:

      auto a = [1, 2, 2, 3, 4, 5];
      auto b = a.replaceLast([2], [1337]);
      assert(b == [1, 2, 1337, 3, 4, 5]);

      auto s = "This is a foo foo list";
      auto r = s.replaceLast("foo", "silly");
      assert(r == "This is a foo silly list", r);

inout(T)[] `replaceSlice`(T)(inout(T)[] `s`, in T[] `slice`, in T[] `replacement`);
  Returns a new array that is `s` with `slice` replaced by `replacement`[].
  Examples:

      auto a = [1, 2, 3, 4, 5];
      auto b = replaceSlice(a, a[1 .. 4], [0, 0, 0]);

      assert(b == [1, 0, 0, 0, 5]);

struct `Appender`(A) if (isDynamicArray!A);
  Implements an output range that appends data to an array. This is recommended over array ~= data when appending many elements because it is more efficient. `Appender` maintains its own array metadata locally, so it can avoid global locking for each append where capacity is non-zero.
  See Also:
  appender
  Examples:

      auto app = appender!string();
      string b = "abcdefg";
      foreach (char c; b)
          app.put(c);
      assert(app.data == "abcdefg");

      int[] a = [ 1, 2 ];
      auto app2 = appender(a);
      app2.put(3);
      app2.put([ 4, 5, 6 ]);
      assert(app2.data == [ 1, 2, 3, 4, 5, 6 ]);

  pure nothrow @trusted this(A `arr`);
    Constructs an Appender with a given array. Note that this does not copy the data. If the array has a larger capacity as determined by `arr`.capacity, it will be used by the appender. After initializing an appender on an array, appending to the original array will reallocate.
  pure nothrow @safe void `reserve`(size_t `newCapacity`);
    Reserve at least `newCapacity` elements for appending. Note that more elements may be reserved than requested. If `newCapacity` <= capacity, then nothing is done.
  const pure nothrow @property @safe size_t `capacity`();
    Returns the `capacity` of the array (the maximum number of elements the managed array can accommodate before triggering a reallocation). If any appending will reallocate, `capacity` returns 0.
  inout pure nothrow @property @trusted inout(ElementEncodingType!A)[] `data`();
    Returns the managed array.
  void `put`(U)(U `item`)
  if (canPutItem!U);
    Appends `item` to the managed array.
  void `put`(Range)(Range `items`)
  if (canPutRange!Range);
    Appends an entire range to the managed array.
  void `opOpAssign`(string op : "~", U)(U `rhs`)
  if (__traits(compiles, put(`rhs`)));
    Appends `rhs` to the managed array.
    Parameters:

    U `rhs` | Element or range.

  pure nothrow @trusted void `clear`();
    Clears the managed array. This allows the elements of the array to be reused for appending.

    Note: `clear` is disabled for immutable or const element types, due to the possibility that Appender might overwrite immutable data.

  pure @trusted void `shrinkTo`(size_t `newlength`);
    Shrinks the managed array to the given length.
    Throws:
    Exception if `newlength` is greater than the current array length.

    Note: `shrinkTo` is disabled for immutable or const element types.

struct `RefAppender`(A) if (isDynamicArray!A);
  A version of Appender that can update an array in-place. It forwards all calls to an underlying appender implementation. Any calls made to the appender also update the pointer to the original array passed in.

  Tip: Use the arrayPtr overload of appender for construction with type-inference.

  this(A* `arr`);
    Constructs a RefAppender with a given array reference. This does not copy the data. If the array has a larger capacity as determined by `arr`.capacity, it will be used by the appender.

    Note: Do not use built-in appending (i.e. ~=) on the original array until you are done with the appender, because subsequent calls to the appender will reallocate the array data without those appends.

    Parameters:

    A* `arr` | Pointer to an array. Must not be null.

  void `opDispatch`(string fn, Args...)(Args `args`)
  if (__traits(compiles, (Appender!A a) => mixin("a." ~ fn ~ "(`args`)")));
    Wraps remaining Appender methods such as put.
    Parameters:

    fn | Method name to call.
    Args `args` | Arguments to pass to the method.

  void `opOpAssign`(string op : "~", U)(U `rhs`)
  if (__traits(compiles, (Appender!A a) { a.put(`rhs`); } ));
    Appends `rhs` to the managed array.
    Parameters:

    U `rhs` | Element or range.

  const @property size_t `capacity`();
    Returns the `capacity` of the array (the maximum number of elements the managed array can accommodate before triggering a reallocation). If any appending will reallocate, `capacity` returns 0.
  inout @property inout(ElementEncodingType!A)[] `data`();
    Returns the managed array.
Appender!A `appender`(A)()
if (isDynamicArray!A);
Appender!(E[]) `appender`(A : E[], E)(auto ref A `array`);
  Convenience function that returns an Appender instance, optionally initialized with `array`.
RefAppender!(E[]) `appender`(P : E[]*, E)(P `arrayPtr`);
  Convenience function that returns a RefAppender instance initialized with `arrayPtr`. Don't use `null` for the array pointer, use the other version of `appender` instead.

Copyright © 1999-2017 by the D Language Foundation | Page generated by Ddoc on Wed May 31 23:36:02 2017