Arrays

Kinds

There are four kinds of arrays:

Static Arrays

int[3] s;

Static arrays have a length fixed at compile time.

The total size of a static array cannot exceed 16Mb.

A static array with a dimension of 0 is allowed, but no space is allocated for it.

Static arrays are value types. They are passed to and returned by functions by value.

Dynamic Arrays

int[] a;

Dynamic arrays consist of a length and a pointer to the array data. Multiple dynamic arrays can share all or parts of the array data.

Pointer Arrays

int* p;

A pointer can manipulate a block of multiple contiguous values in memory. Accessing more than one value cannot be @safe as it requires pointer arithmetic. This is supported for interfacing with C and for specialized systems work. A pointer has no length associated with it, so there is no way for the compiler or runtime to do bounds checking, etc., on it.

Array Declarations

Declarations appear before the identifier being declared and read right to left, so:

int[] a;      // dynamic array of ints
int[4][3] b;  // array of 3 arrays of 4 ints each
int[][5] c;   // array of 5 dynamic arrays of ints.
int*[]*[3] d; // array of 3 pointers to dynamic arrays of pointers to ints
int[]* e;     // pointer to dynamic array of ints

Array Initializers & Literals

An ArrayInitializer initializes a dynamic or static array:

auto a1 = [1,2,3];  // type is int[], with elements 1, 2, and 3
auto a2 = [1u,2,3]; // type is uint[], with elements 1u, 2u, and 3u
int[2] a3 = [1,2];  // type is int[2], with elements 1, and 2

An array literal is an expression:

void f(int[] a);

f([1, 2]); // pass 2 elements
f([]); // pass an empty array

Array Comparison

For static and dynamic arrays:

• The .length property will give the number of elements in the array.
• The .ptr property will give a pointer to the first element in the array.
• a == b compares both the array lengths and array elements.
• a is b compares each .ptr and each .length. Note that this is deprecated for static arrays because those are value types, so checking identity should not compare the .ptr fields.

int[3] s = [1, 2, 3];
int[] a = [1, 2, 3];

assert(s.length == 3);
assert(a.length == 3);
assert(s == a);
assert(s.ptr != a.ptr); // here `a` is not a slice of `s`
assert(s !is a);

See also: RelExpression.

Array Assignment

There are two broad kinds of operations to do on dynamic arrays and pointer arrays - those affecting the handle to the array, and those affecting the contents of the array. Assignment only affects the handle for these types.

int* p;
int[3] s;
int[] a;

p = s.ptr; // p points to the first element of the array s.
assert(p !is null);
p = a.ptr;
assert(p is null);

// error, since the length of the array pointed to by p is unknown
//s = p;

//a = p;   // error, length unknown
a = s;     // a points to the elements of s
assert(a.ptr == s.ptr);

int[] b = [1, 2, 3];
a = b;     // a points to the same array as b does
assert(a.ptr == b.ptr);
assert(a is b);

A static array can be assigned from a dynamic array - the data is copied. The lengths must match:

int[3] s;
int[] a;

//s = [1, 2]; // error
s = [1, 2, 3]; // OK
//s = [1, 2, 3, 4]; // error

a = [4, 5, 6];
s = a; // OK
assert(s == a);
assert(s.ptr != a.ptr);

a = [1, 2];
//s = a; // RangeError, length mismatch

a = s;
assert(a.ptr == s.ptr);
//s = a; // RangeError, overlap

The dynamic array data must not overlap with the static array memory. See also Copying.

Indexing

Indexing allows access to an element of an array:

auto a = [1,2,3];
assert(a[0] == 1);
assert(a[2] == 3);
a[2] = 4;
assert(a[2] == 4);
assert(a == [1,2,4]);
//writeln(a[3]); // runtime error (unless bounds checks turned off)

int[2] b = [1,2];
assert(b[1] == 2);
//writeln(b[2]); // compile-time error, index out of bounds

See also IndexOperation.

Pointer Arithmetic

A pointer can also be indexed, but no bounds checks are done. Unlike arrays, a pointer value can also be used in certain arithmetic expressions to produce another pointer:

int[] a = [1,2,3];
int* p = a.ptr;

p[2] = 4;
assert(a[2] == 4);
writeln(p[3]); // undefined behaviour

assert(p == &a[0]);
p++; // point to a[1]
assert(*p == 2);

See AddExpression for details.

Slicing

Slicing an array means to specify a subarray of it. This is done by supplying two index expressions. The elements from the start index up until the end index are selected. Any item at the end index is not included.

An array slice does not copy the data, it is only another reference to it. Slicing produces a dynamic array.

int[3] a = [4, 5, 6]; // static array of 3 ints
int[] b;

b = a[1..3]; // a[1..3] is a 2 element dynamic array consisting of
             // a[1] and a[2]
assert(b == [5, 6]);
assert(b.ptr == a.ptr + 1);

a[2] = 3;
assert(b == [5, 3]);

b = b[1..2];
assert(b == [3]);

Expression[] is shorthand for a slice of the entire array.

Slicing is not only handy for referring to parts of other arrays, but for converting pointers into bounds-checked arrays:

int[10] a = [ 1,2,3,4,5,6,7,8,9,10 ];

int* p = &a[2];
writeln(p[7]);      // 10
writeln(p[8]);      // undefined behaviour

int[] b = p[0..8];  // convert pointer elements to dynamic array
assert(b is a[2..10]);
writeln(b);
writeln(b[7]);      // 10
//writeln(b[8]);    // runtime error (unless bounds checks turned off)

See also SliceOperation.

Array Length

When indexing or slicing a static or dynamic array, the symbol $ represents the length of the array.

int[4] foo;
int[] bar;

// These assignments are equivalent:
bar = foo;
bar = foo[];
bar = foo[0 .. 4];
bar = foo[0 .. $];
bar = foo[0 .. foo.length];
assert(bar.length == 4);

int* p = foo.ptr; // a pointer has no length property
bar = p[0 .. 4]; // OK
//bar = p[0 .. $]; // error, '$' is not defined, since p is not an array

int i;
//i = foo[0]+$; // error, '$' is not defined, out of scope of [ ]
i = bar[$-1]; // retrieves last element of the array

Array Copying

When the slice operator appears as the left-hand side of an assignment expression, it means that the contents of the array are the target of the assignment rather than a reference to the array. Array copying happens when the left-hand side is a slice, and the right-hand side is an array of or pointer to the same type.

int[3] s, t;
int[] a;

s = t;             // the 3 elements of t are copied into s
s[] = t;           // the 3 elements of t are copied into s
s[] = t[];         // the 3 elements of t are copied into s
s[1..2] = t[0..1]; // same as s[1] = t[0]
s[0..2] = t[1..3]; // same as s[0] = t[1], s[1] = t[2]
//s[0..4] = t[0..4]; // error, only 3 elements in s and t
//s[0..2] = t;       // error, operands have different lengths

a = [1, 2];
s[0..2] = a;
assert(s == [1, 2, 0]);

//a[] = s; // RangeError, lengths don't match
a[0..2] = s[1..3];
assert(a == [2, 0]);

Overlapping Copying

Overlapping copies are an error:

void main()
{
    int[3] s;

    s[0..2] = s[1..3]; // error, overlapping copy
    s[1..3] = s[0..2]; // error, overlapping copy
}

Disallowing overlapping makes it possible for more aggressive parallel code optimizations than possible with the serial semantics of C.

If overlapping is required, use std.algorithm.mutation.copy:

import std.algorithm;
int[] s = [1, 2, 3, 4];

copy(s[1..3], s[0..2]);
assert(s == [2, 3, 3, 4]);

Array Setting

If a slice operator appears as the left-hand side of an assignment expression, and the type of the right-hand side is the same as the element type of the left-hand side, then the array contents of the left-hand side are set to the right-hand side.

int[3] s;
int[] a;
int* p;

s[] = 3;
assert(s == [3, 3, 3]);

a = s;
a[] = 1;
assert(s == [1, 1, 1]);

p = s.ptr;
p[0..2] = 2;
assert(s == [2, 2, 1]);

Array Concatenation

The binary operator ~ is the cat operator. It is used to concatenate arrays:

int[] a = [1, 2];
assert(a ~ 3 == [1, 2, 3]); // concatenate array with a single value

int[] b = a ~ [3, 4];
assert(b == [1, 2, 3, 4]); // concatenate two arrays

Many languages overload the + operator for concatenation. This confusingly leads to a dilemma - does:

"10" + 3 + 4

produce the number 17, the string "1034" or the string "107" as the result? It isn't obvious, and the language designers wind up carefully writing rules to disambiguate it - rules that get incorrectly implemented, overlooked, forgotten, and ignored. It's much better to have + mean addition, and a separate operator to be array concatenation.

Concatenation always creates a copy of its operands, even if one of the operands is a 0 length array, so:

auto b = [7];
auto a = b;      // a refers to b
assert(a is b);

a = b ~ []; // a refers to a copy of b
assert(a !is b);
assert(a == b);

See also: is operator.

Array Appending

Similarly, the ~= operator means append, as in:

a ~= b; // a becomes the concatenation of a and b

Appending does not always create a copy, see setting dynamic array length for details.

Vector Operations

Many array operations can be expressed at a high level rather than as a loop. For example, the loop:

T[] a, b;
...
for (size_t i = 0; i < a.length; i++)
    a[i] = b[i] + 4;

assigns to the elements of a the elements of b with 4 added to each. This can also be expressed in vector notation as:

T[] a, b;
...
a[] = b[] + 4;

A vector operation is indicated by the slice operator appearing as the left-hand side of an assignment or an op-assignment expression. The right-hand side can be certain combinations of:

• An array SliceOperation of the same length and type as the left-hand side
• A scalar expression of the same element type as the left-hand side

The following operations are supported:

• Unary: -, ~
• Add: +, -
• Mul: *, /, %,
• Bitwise: ^, &, |
• Pow: ^^

int[3] a = 0;
int[] b = [1, 2, 3];

a[] += 10 - (b[] ^^ 2);
assert(a == [9, 6, 1]);

The slice on the left and any slices on the right must not overlap. All operands are evaluated exactly once, even if the array slice has zero elements in it.

If the element type defines matching overloaded operators, those methods must be pure nothrow @nogc.

The order in which the array elements are computed is implementation defined, and may even occur in parallel. An application must not depend on this order.

Implementation Note: Many vector operations are expected to take advantage of any vector math instructions available on the target computer.

Rectangular Arrays

Experienced FORTRAN numerics programmers know that multidimensional "rectangular" arrays for things like matrix operations are much faster than trying to access them via pointers to pointers resulting from "array of pointers to array" semantics. For example, the D syntax:

double[][] matrix;

declares matrix as an array of pointers to arrays. (Dynamic arrays are implemented as pointers to the array data.) Since the arrays can have varying sizes (being dynamically sized), this is sometimes called "jagged" arrays. Even worse for optimizing the code, the array rows can sometimes point to each other! Fortunately, D static arrays, while using the same syntax, are implemented as a fixed rectangular layout in a contiguous block of memory:

import std.stdio : writeln;

double[6][3] matrix = 0; // Sets all elements to 0.

void main()
{
    writeln(matrix); // [[0, 0, 0, 0, 0, 0], [0, 0, 0, 0, 0, 0], [0, 0, 0, 0, 0, 0]]
}

Note that dimensions and indices appear in opposite orders. Dimensions in the declaration are read right to left whereas indices are read left to right:

import std.stdio : writeln;

void main()
{
    double[6][3] matrix = 0;
    matrix[2][5] = 3.14; // Assignment to bottom right element.
    writeln(matrix); // [[0, 0, 0, 0, 0, 0], [0, 0, 0, 0, 0, 0], [0, 0, 0, 0, 0, 3.14]]

    static assert(!__traits(compiles, matrix[5][2])); // Array index out of bounds.
}

More information can be found at Dlang Wiki - Dense Multidimensional Arrays.

Array Properties

Static array properties are:

void foo(int, int, int) { /* ... */ }

int[3] ia = [1, 2, 3];
foo(ia.tupleof); // same as `foo(1, 2, 3);`

float[3] fa;
//fa = ia; // error
fa.tupleof = ia.tupleof;
assert(fa == [1F, 2F, 3F]);

Dynamic array properties are:

Examples:

int* p;
int[3] s;
int[] a;

size_t len;
//len = p.length;   // error, pointer has no length property
enum sl = s.length; // compile time constant
static assert(sl == 3);

len = a.length; // runtime value
assert(len == 0);

//a = p.dup; // error, length not known
a = s.dup;   // allocates an array of 3 elements, copies
             // elements of `s` into it
assert(a == s[]);
assert(a.ptr != s.ptr);

int[] b = a.dup; // allocates a new array of `a.length` elements, copies
                 // elements of `a` into it
assert(b !is a); // b is an independent copy of a

.ptr Property

The .ptr property will give a pointer to the first element in a static or dynamic array. It may be a dangling pointer if the array length is zero. For this reason, .ptr is not accessible in @safe code.

A dynamic array's .ptr is default-initialized to null.

An array with zero length may have a non-null .ptr. That can occur:

• From slicing a dynamic array a with zero-width: a[$..$].
• For a zero-length static array.

int[] a;
assert(a.ptr is null);

int[0] z;
assert(z.ptr !is null);

Setting Dynamic Array Length

The .length property of a dynamic array can be set as the left-hand side of an = operator:

array.length = 7;

This causes the array to be reallocated in place, and the existing contents copied over to the new array. If the new array length is shorter, the array is not reallocated, and no data is copied. It is equivalent to slicing the array:

array = array[0..7];

If the new array length is longer, the array is reallocated if necessary, preserving the existing elements. The new elements are filled out with the default initializer.

Growing an Array

To maximize efficiency, the runtime always tries to resize the array in place to avoid extra copying. It will do a copy if the new size is larger and either:

• The array was not allocated by the GC.
• There is no spare capacity for the array.
• Resizing in place would overwrite valid data still accessible in another slice.

char[] a = new char[20];
char[] b = a[0..10];
char[] c = a[10..20];
char[] d = a;

b.length = 15; // always reallocates because extending in place would
               // overwrite other data in a.
b[11] = 'x';   // a[11] and c[1] are not affected
assert(a[11] == char.init);

d.length = 1;
assert(d.ptr == a.ptr); // unchanged

d.length = 20; // also reallocates, because doing this will overwrite a and c
assert(d.ptr != a.ptr);

c.length = 12; // may reallocate in place if space allows, because nothing
               // was allocated after c.
c[5] = 'y';    // may affect contents of a, but not b or d because those
               // were reallocated.

a.length = 25; // This always reallocates because if c extended in place,
               // then extending a would overwrite c.  If c didn't
               // reallocate in place, it means there was not enough space,
               // which will still be true for a.
a[15] = 'z';   // does not affect c, because either a or c has reallocated.

To guarantee copying behavior, use the .dup property to ensure a unique array that can be resized.

Resizing a dynamic array is a relatively expensive operation. So, while the following method of filling an array:

void fun()
{
    int[] array;
    while (1)
    {
        import core.stdc.stdio : getchar;
        auto c = getchar;
        if (!c)
            break;
        ++array.length;
        array[array.length - 1] = c;
    }
}

void fun()
{
    int[] array;
    array.length = 100;        // guess
    int i;
    for (i = 0; ; i++)
    {
        import core.stdc.stdio : getchar;
        auto c = getchar;
        if (!c)
            break;
        if (i == array.length)
            array.length *= 2;
        array[i] = c;
    }
    array.length = i;
}

Base selection of the initial size on expected common use cases, which can be determined by instrumenting the code, or simply using good judgement. For example, when gathering user input from the console - it's unlikely to be longer than 80.

capacity and reserve

The capacity property gives the maximum length a dynamic array can grow to without reallocating. The spare capacity for an array a is a.capacity - a.length. The capacity for a slice is zero:

• If it does not point to GC-allocated dynamic array memory.
• By default, when an element has been stored after the slice.

int[] a;
assert(a.capacity == 0);
a.length = 3; // may allocate spare capacity too
assert(a.capacity >= 3);

auto b = a[1..3];
assert(b.capacity >= 2); // either a or b can append into any spare capacity
b = a[0..2];
assert(b.capacity == 0);

The reserve function requests a minimum capacity for an array. It returns the new capacity, which may be more than requested. Any spare capacity can be used by the append operator or .length assignment.

int[] array;
const size_t cap = array.reserve(10); // request
assert(cap >= 10); // allocated may be more than request
assert(array.ptr != null);
assert(array.length == 0);

int[] copy = array;
assert(copy.capacity == cap); // array and copy have same capacity
array ~= [1, 2, 3, 4, 5]; // grow in place
assert(cap == array.capacity); // array memory was not reallocated
assert(copy.ptr == array.ptr);
assert(copy.capacity == 0);
copy ~= 0; // allocates a new array
assert(copy.ptr != array.ptr);
assert(array[0] == 1);

Above, copy's length remains zero but it points to the same memory allocated by the reserve call. Because array is then appended to, copy.ptr + 0 no longer points to unused memory - instead that is the address of array[0]. So copy.capacity will be zero to prevent any appending to copy from overwriting elements in array.

When an array with spare capacity has its length reduced, or is assigned a slice of itself that ends before the previous last element, the capacity will be zero.

The @system function assumeSafeAppend allows the capacity to be regained, but care must be taken not to overwrite immutable elements that may exist in another slice.

int[] a = [1, 2, 3];
a.length--;
assert(a.capacity == 0);
a.assumeSafeAppend();
assert(a.capacity >= 3);

Functions as Array Properties

See Uniform Function Call Syntax (UFCS).

Array Bounds Checking

It is an error to index an array with an index that is less than 0 or greater than or equal to the array length. If an index is out of bounds, an ArrayIndexError is thrown if detected at runtime, and an error is raised if detected at compile time. A program may not rely on array bounds checking happening, for example, the following program is incorrect:

void main()
{
    import core.exception;
    try
    {
        auto array = [1, 2];
        for (auto i = 0; ; i++)
        {
            array[i] = 5;
        }
    }
    catch (ArrayIndexError)
    {
        // terminate loop
    }
}

void main()
{
    auto array = [1, 2];
    for (auto i = 0; i < array.length; i++)
    {
        array[i] = 5;
    }
}

Implementation Note: Compilers should attempt to detect array bounds errors at compile time, for example:

int[3] foo;
int x = foo[3]; // error, out of bounds

Insertion of array bounds checking code at runtime should be turned on and off with a compile time switch.

See also Safe Functions.

Disabling Array Bounds Checking

Insertion of array bounds checking code at runtime may be turned off with a compiler switch -boundscheck.

If the bounds check in @system or @trusted code is disabled, the code correctness must still be guaranteed by the code author.

On the other hand, disabling the bounds check in @safe code will break the guaranteed memory safety by compiler. It's not recommended unless motivated by speed measurements.

Array Initialization

Default Initialization

• Pointers are initialized to null.
• Static array contents are initialized to the default initializer for the array element type.
• Dynamic arrays are initialized to having 0 elements and a null .ptr.
• Associative arrays are initialized to having 0 elements.

Length Initialization

The new expression can be used to allocate a dynamic array with a specified length by specifying its type and then using the (size) syntax:

int[] i = new int[](5);
i = new int[5]; // same allocation, alternate syntax
assert(i.length == 5);

int[][] j = new int[][](10, 5);
assert(j.length == 10);
assert(j[0].length == 5);

See NewExpression for details.

Void Initialization

Void initialization happens when the Initializer for an array is void. What it means is that no initialization is done, i.e. the contents of the array will be undefined. This is most useful as an efficiency optimization. Void initializations are an advanced technique and should only be used when profiling indicates that it matters.

To void initialise the elements of a dynamic array use std.array.uninitializedArray.

Array Initializers

ArrayInitializer:
    [ ArrayElementInitializersopt ]

ArrayElementInitializers:
    ArrayElementInitializer
    ArrayElementInitializer ,
    ArrayElementInitializer , ArrayElementInitializers

ArrayElementInitializer:
    NonVoidInitializer
    AssignExpression : NonVoidInitializer

An ArrayInitializer is a list of array element values enclosed in [ ]. The values can be optionally preceded by an index and a :. If an index is not supplied, it is set to the previous index plus 1, or 0 if it is the first value. Any missing elements will be initialized to the default value of the element type.

int[3] a = [ 1:2, 3 ]; // a[0] = 0, a[1] = 2, a[2] = 3

assert(a == [0, 2, 3]);

This is most handy when the array indices are given by enums:

enum Color { red, blue, green }

int[Color.max + 1] value =
  [ Color.blue :6,
    Color.green:2,
    Color.red  :5 ];

assert(value == [5, 6, 2]);

Any indices must be known at compile-time. Note that if the array type is not specified and every element has an index, it will be inferred as an associative array literal.

int n = 4;
auto aa = [0:1, 3:n]; // associative array `int[int]`

int[] a = [1, 3:n, 5];
assert(a == [1, 0, 0, n, 5]);

//int[] e = [n:2]; // error, n not known at compile-time

Static Initialization of Statically Allocated Arrays

All elements of a static array can be initialized to a specific value with:

int[4] a = 42; // set all elements of a to 42

assert(a == [42, 42, 42, 42]);

These arrays are statically allocated when they appear in global scope. Otherwise, they need to be marked with const or static storage classes to make them statically allocated arrays.

Special Array Types

Strings

A string is an array of immutable (read-only) characters. String literals essentially are an easy way to write character array literals.

char[] arr;
//arr = "abc";          // error, cannot implicitly convert expression `"abc"` of type `string` to `char[]`
arr = "abc".dup;        // ok, allocates mutable copy

string str1 = "abc";    // ok, same types
//str1 = arr;           // error, cannot implicitly convert expression `arr` of type `char[]` to `string`
str1 = arr.idup;        // ok, allocates an immutable copy of elements
assert(str1 == "abc");

string str2 = str1;     // ok, mutable slice of same immutable array contents

The name string is aliased to immutable(char)[]. The type immutable(char)[] represents an array of immutable chars. However, the reference to the string is mutable.

immutable(char)[] s = "foo";
s[0] = 'a';  // error, s[0] is immutable
s = "bar";   // ok, s itself is not immutable

If the reference to the string needs to be immutable as well, it can be declared immutable char[] or immutable string:

immutable char[] s = "foo";
s[0] = 'a';  // error, s refers to immutable data
s = "bar";   // error, s is immutable

Strings can be copied, compared, concatenated, and appended:

string s1;
immutable s2 = "ello";
s1 = s2;
s1 = "h" ~ s1;
if (s1 > "farro")
    s1 ~= " there";

assert(s1 == "hello there");

with array semantics. Any generated temporaries get cleaned up by the garbage collector (or by using alloca()). Not only that, this works with any array not just a special String array.

String Literal Types

The type of a string literal is determined by the semantic phase of compilation. The type is determined by implicit conversion rules. If there are two equally applicable implicit conversions, the result is an error. To disambiguate these cases, a cast or a postfix of c, w or d can be used:

cast(immutable(wchar)[]) "abc" // this is an array of wchar characters
"abc"w                         // so is this

String literals that do not have a postfix character and that have not been cast can be implicitly converted between string, wstring, and dstring (see below) as necessary.

void fun()
{
    char c;
    wchar w;
    dchar d;

    c = 'b';     // c is assigned the character 'b'
    w = 'b';     // w is assigned the wchar character 'b'
    //w = 'bc';  // error - only one wchar character at a time
    w = "b"[0];  // w is assigned the wchar character 'b'
    w = "\r"[0]; // w is assigned the carriage return wchar character
    d = 'd';     // d is assigned the character 'd'
}

Strings and Unicode

String data is encoded as follows:

Note that built-in comparison operators operate on a code unit basis. The end result for valid strings is the same as that of code point for code point comparison as long as both strings are in the same normalization form. Since normalization is a costly operation not suitable for language primitives it's assumed to be enforced by the user.

The standard library lends a hand for comparing strings with mixed encodings (by transparently decoding, see std.algorithm.cmp), case-insensitive comparison and normalization.

Last but not least, a desired string sorting order differs by culture and language and is usually nothing like code point for code point comparison. The natural order of strings is obtained by applying the Unicode collation algorithm that should be implemented in the standard library.

Character Pointers and C strings

A pointer to a character can be generated:

string str = "abcd";
immutable(char)* p = &str[3]; // pointer to 4th element
assert(*p == 'd');
p = str.ptr; // pointer to 1st element
assert(*p == 'a');

Only string literals are zero-terminated in D. In general, when transferring a pointer to string data to C, append a terminating '\0':

string str = "ab";
assert(str.ptr[2] == '\0'); // OK
str ~= "cd";
// str is no longer zero-terminated
str ~= "\0";
assert(str[4] == '\0'); // OK
str.length = 2;
// str is no longer correctly zero-terminated
assert(str.ptr[2] != '\0');

Example: printf

core.stdc.stdio.printf is a C function and is not part of D. printf() will print C strings, which are 0 terminated. There are two ways to use printf() with D strings. The first is to add a terminating 0:

str ~= "\0";
printf("the string is '%s'\n", str.ptr);

import std.string;
printf("the string is '%s'\n", std.string.toStringz(str));

String literals already have a 0 appended to them, so can be used directly:

printf("the string is '%s'\n", "string literal".ptr);

So, why does the first string literal to printf not need the .ptr? The first parameter is prototyped as a const(char)*, and a string literal can be implicitly converted to a const(char)*. The rest of the arguments to printf, however, are variadic (specified by ...), and a string literal typed immutable(char)[] cannot be passed to variadic parameters.

The second way is to use the precision specifier. The length comes first, followed by the pointer:

printf("the string is '%.*s'\n", cast(int)str.length, str.ptr);

The best way is to use std.stdio.writefln, which can handle D strings:

import std.stdio;
writefln("the string is '%s'", str);

Void Arrays

There are special types of array with void element type which can hold arrays of any kind. Void arrays are used for low-level operations where some kind of array data is being handled, but the exact type of the array elements are unimportant. The .length of a void array is the length of the data in bytes, rather than the number of elements in its original type. Array indices in slicing operations are interpreted as byte indices. A void array cannot be indexed.

Arrays of any type can be implicitly converted to a (tail qualified) void array - the compiler inserts the appropriate calculations so that the .length of the resulting array's size is in bytes rather than number of elements. Void arrays cannot be converted back to the original type without using an array cast, and it is an error to convert to an array type whose element size does not evenly divide the length of the void array.

void main()
{
    int[] data1 = [1,2,3];

    void[] arr = data1;            // OK, int[] implicit converts to void[].
    assert(data1.length == 3);
    assert(arr.length == 12);      // length is implicitly converted to bytes.

    arr[0..4] = [5];               // Assign first 4 bytes to 1 int element
    assert(data1 == [5,2,3]);

    arr ~= [6];                    // Append the 4 bytes of an int
    //data1 = arr;                 // Error: void[] does not implicitly
                                   // convert to int[].
    int[] data2 = cast(int[]) arr; // OK, can convert with explicit cast.
    assert(data2 is arr);          // both point to the same set of bytes
    assert(data2 == [5,2,3,6]);
}

void main()
{
    void[] arr = new void[12];
    long[] bad = cast(long[]) arr; // Runtime error: long.sizeof == 8, which
                                   // does not divide arr.length, which is 12
                                   // bytes.
}

Void arrays can be static arrays if their length is known at compile-time. The length is specified in bytes:

void main()
{
    byte[2] x;
    int[2] y;

    void[2] a = x; // OK, lengths match
    void[2] b = y; // Error: int[2] is 8 bytes long, doesn't fit in 2 bytes.
}

While it may seem that void arrays are just fancy syntax for ubyte[], there is a subtle distinction. The garbage collector generally will not scan ubyte[] arrays for pointers, ubyte[] being presumed to contain only pure byte data, not pointers. However, it will scan void[] arrays for pointers, since such an array may have been implicitly converted from an array of pointers or an array of elements that contain pointers. Allocating an array that contains pointers as ubyte[] may run the risk of the GC collecting live memory if these pointers are the only remaining references to their targets.

Implicit Conversions

A pointer T* can be implicitly converted to one of the following:

• void*

A static array T[dim] can be implicitly converted to one of the following (U is a base class of T):

• T[]
• const(U)[]
• const(U[])
• void[]

A dynamic array T[] can be implicitly converted to one of the following (U is a base class of T):

• const(U)[]
• const(U[])
• void[]

Array literals can also be implicitly converted to static array types. See Array Literals for details.

String literals can also be implicitly converted to static array types and character pointer types. See String Literals for details.