When a C function expects to take an array as an argument, the corresponding parameter is declared as a pointer. Take the following example:

#include <stdio.h>
void printThreeInts(int *ints) {
  int i;
  for(i=0; i<3; ++i)
    printf("%i
", ints[i]);
}

It's common practice in C to require an array length to be passed along with the array pointer in functions that have array parameters. In this case, a length parameter is omitted since the expected length of the array is in the name of the function, a practice that, while dangerous and error-prone, isn't exactly uncommon.

C programmers really have to be on their toes, but that means D programmers also have to pay close attention when interacting with C. It's so easy to get used to the safety of D's arrays and forget that calling C functions often requires extra vigilance. Any array you pass to this function must have at least three elements. What happens when you pass a shorter array depends entirely on what exists in the memory locations beyond the end of the array at the time the function is called.

There are two ways to call printThreeInts that require no copying or conversions. One is to use a cast, something that is not recommended. The other, recommended, way is to use the .ptr property common to all arrays:

extern(C) @nogc nothrow void printThreeInts(int*);
void main() {
  int[] ints = [1, 2, 3];
  printThreeInts(cast(int*)ints);
  printThreeInts(ints.ptr);
}

Knowing that a D array is a data structure that contains a length and a pointer, it may appear baffling that we can legally cast it to a pointer. Consider this:

struct IntArray {
  size_t length;
  int* ptr;
}
auto ia = IntArray(ints.length, ints.ptr);
auto pi = cast(int*)ia;

If you were to insert this at the end of main and try to compile, the compiler would rightly complain that you can't cast ia of type IntArray to int*. But that's because your IntArray type doesn't have the privileges given to built-in arrays.

When we cast our ints array to int*, the compiler is smart enough to pick up on the fact that all we really want to do is substitute ints.ptr in place of the cast. That's essentially what it does. Often, new D programmers tend to use the cast, probably because that's the sort of thing they're used to in other languages, and there is some existing D code out there that does that. Veteran D programmers tend to prefer using the .ptr property directly. Not only is it fewer characters to type and makes it clear exactly what's going on, but there's no room for getting the type wrong. Using the cast, you could inadvertently do something like cast away immutable or const. Always prefer passing the .ptr.

If you save the previous C example as $LEARNINGD/Chapter09/threeints/arrc.c and the D example as arr.d in the same directory, you can compile with the following commands. Using DMD with the default Digital Mars linker:

dmc -c arrc.c
dmd arr.d arrc.obj

Using DMD with the Microsoft linker (be sure to use the x64 Native Tools Command Prompt shortcut in the Visual Studio installation directories):

cl /c arrc.c
dmd -m64 arr.d arrc.obj

Using DMD on platforms other than Windows:

gcc -c arrc.c
dmd arr.d arrc.o

void printThreeInts(int[] arr) {
  assert(arr.length >= 3);
  printThreeInts(arr.ptr);
}

When a C function takes a pointer parameter to which it intends to write data, it's important that the destination array has enough space to hold all of the elements it will be assigned. For example, this function writes three integers to an int array:

void storeThreeInts(int *ints) {
  int i;
  for(i=0; i<3; ++i)
    ints[i] = i+100;
}

With the appropriate binding, we can call it like so:

auto threeInts = new int[3];
storeThreeInts(threeInts.ptr);
writeln(threeInts);

Here, we've used a dynamic array allocated to hold three elements, but it could be a static array as well. As long as the array has enough space allocated to hold at least three elements, we're good.

Sometimes, a C function takes a pointer-to-a-pointer, such as int**, to represent either a single array or an array of arrays. How to handle this depends on the context. Let's first consider the case of a pointer to an array. The following C function takes an array of int arrays and prints the members of each:

void printIntArrays(size_t count, int **arrays, size_t *sizes) {
  size_t i, j;
  for(i=0; i<count; ++i) {
    printf("Array #%d:
", i + 1);
      for(j=0; j<sizes[i]; ++j)
        printf("	%i
", arrays[i][j]);
  }
}

The first parameter, count, is necessary for the function to know how many arrays it has to work with. The second parameter is the array of arrays, and the third is an array containing the size of each int array. The prototype for a static D binding is:

extern(C) @nogc nothrow 
void printIntArrays(size_t, int**,size_t*);

Though it may seem odd, it's possible to pass a single array to this function. Let's look at that case first, since less work needs to be done than when we pass an array of arrays:

auto fourInts = [10, 20, 30, 40];
auto fourIntsSize = fourInts.length;
auto pfi = fourInts.ptr;
printIntArrays(1, &pfi, &fourIntsSize);

The highlighted lines are important here. It's not possible to take the address of either .length or .ptr. The only way to get the pointers we need is to first assign them to temporary variables and take the addresses of those. Still, this is easy compared to what we have to do for an array of arrays:

auto intArrays = [[10, 20, 30], [1, 3, 5, 7, 9], [100, 101]];
auto ptrs = new int*[3];
auto sizes = new size_t[](intArrays.length);
foreach(i, ia; intArrays) {
  ptrs[i] = ia.ptr;
  sizes[i] = ia.length;
}
printIntArrays(intArrays.length, ptrs.ptr, sizes.ptr);

The two highlighted lines show that we have to allocate two arrays for this case. It's not possible to cast a D rectangular array to a C pointer-to-a-pointer.

In a different context, a function might always expect a pointer-to-a-pointer to actually be a pointer to a single array, rather than to multiple arrays, perhaps to assign the array variable a new address. For example, the following function takes an int** and reassigns the pointer to a local static array. It then returns the size of the local array so that the calling code knows how many elements it's pointing to:

size_t getIntList(int** parray) {
  static int localArray[3] = {10, 20, 30};
  *parray = localArray;
  return 3;
}

Given what we've seen so far, your first instinct might be to try this:

int*[] ipa = new int*[](1);
auto size = getIntList(ipa.ptr);

Since an array of pointers is just like any other array, it makes sense that we should be able to allocate an array of them large enough to hold the number of elements the function wants to write to it. This is no different than what we did for the storeThreeInts example. We know we're getting one array element, so we allocate space to hold one element.

If you think about it, the allocation is wasteful. There's no reason to allocate space on the GC heap to hold any C array pointers. If we're worried about the contents of the array changing out from under us on the C side, or perhaps the original array address becoming invalid, allocating space to store the pointer buys us nothing. We would need to allocate space for the elements, then copy them all over to guarantee we can hang on to them for as long as we want. So we can do away with the allocation and just do this:

int* pi;
auto size = getIntList(&pi);

Now we can take this pointer and slice it to get a D array:

auto intList = pi[0 .. size];

At this point, we still haven't allocated any GC memory. If we want, we can call .dup on the array to allocate space for a new array and copy all the elements over, or we can just work with the slice directly. If you don't want to modify the original elements, or to manually manage their lifetime, or if you're concerned about something happening to them on the C side, just go for the .dup.

We know that D strings are also D arrays, so it's reasonable to expect that they behave the same when interacting with C. To a large extent, they do. However, the compiler does give string literals some special treatment that normal arrays just don't get. Try to compile and run the following program and see what happens:

void main() {
  import core.stdc.stdio : puts;
  puts("Giving a D string literal to a C function.");
}

Here, we are calling the standard C library function puts with a D string literal as an argument. puts is not a D wrapper, but a direct binding to the C function. It takes a C string, const char*, as an argument. So, what gives? How does this compile and run?

The compiler treats string literals specially. A string literal is implicitly convertible to a const or immutable pointer to char. This is true of function parameters and variable declarations. The same does not hold for regular array literals, nor is it true of string variables:

void main() {
  import core.stdc.stdio : puts;
  auto str = "Giving a D string to a C function.";
  puts(str);
}

This will fail to compile. From what we've seen so far about passing D arrays to C, we know we can work around this:

puts(str.ptr);

In this particular case, this works and causes no harm, but it isn't a general-purpose solution. This is another point where D strings differ from other array types.

There's no getting around the fact that C strings are expected to be null-terminated, meaning the last character in the string should be '' (or 0). The D compiler will let you pass D string literals directly to C functions because all string literals in D are null-terminated. This feature exists specifically to make them directly compatible with C. However, D does not require all strings to be null-terminated. Strings received from external sources, such as files or network packets, are not guaranteed to have a trailing ''; they will only have one if they've been initialized with a literal. For that reason, the compiler does not allow string variables to be implicitly converted to C-style strings, treating them just like any other array.

In this specific case, we know that str was assigned a literal, so we know that it is null-terminated. In the general case, however, when we cannot guarantee the original source of a string variable was a literal, we need to turn to the Phobos function std.string.toStringz.

We've already seen this function and its cousin, std.utf.toUTF16z, in the loader module presented earlier in the chapter. Given a string str, toStringz ensures that it is null-terminated. This usually means that a new string is allocated with space for the null-terminator. The UTF variations perform the same task, while also converting the input to the appropriately UTF-encoded string type.

When implementing a function that accepts a D string and hands it off to a C function, you should always use toStringz or, if the C API requires it, one of the UTF versions, before passing the string on to C. If you don't, then you've not only allowed the potential for a crash, you've also opened a pretty big security hole. Even if you think you're 100% sure that the function will only take literals, perhaps because it's private to the module and you completely control the types of strings it gets, you should still use toStringz.

Another thing to watch out for is what the C function does with any strings you give it. I have actually seen someone recommend that a C function declared to take a char* be translated to D to accept a const(char)* instead, solely to make it easier to pass a D string to it. When using a binding that you didn't create, always familiarize yourself with the original C API before you get started. You certainly don't want a C function to attempt to modify your immutable(char)[] strings in D. Nothing good can come of that. If you do need to pass a string to a C function that will be modified, just dup it to a variable of type char[] and then pass that on to the C function. Note that there's no guarantee that duping a string will preserve the null-terminator in the copy.

auto s = "Dup me!";
char[] cstr = s.dup ~ '';
modifyString(cstr.ptr);

If the C function is treating the string as a buffer and doesn't need to read it first, just do as you would with any array; allocate an array of characters large enough to hold the output, then pass it on:

auto cstr = new char[1024];
writeToBuffer(cstr.length, cstr.ptr);

Sometimes, such a function might be documented to require that the array contain the null-terminator, even though it's empty. In that case, keep in mind that the .init value of a char is 0xFF, not 0, so you'll have to set the value yourself.