{"id":1723,"date":"2018-10-17T15:09:40","date_gmt":"2018-10-17T15:09:40","guid":{"rendered":"http:\/\/dlang.org\/blog\/?p=1723"},"modified":"2021-10-08T11:02:14","modified_gmt":"2021-10-08T11:02:14","slug":"interfacing-d-with-c-arrays-part-1","status":"publish","type":"post","link":"https:\/\/dlang.org\/blog\/2018\/10\/17\/interfacing-d-with-c-arrays-part-1\/","title":{"rendered":"Interfacing D with C: Arrays Part 1"},"content":{"rendered":"

This post is part of an ongoing series<\/a> on working with both D and C in the same project. The previous post<\/a> showed how to compile and link C and D objects. This post is the first in a miniseries focused on arrays.<\/p>\n

When interacting with C APIs, it\u2019s almost a given that arrays are going to pop up in one way or another (perhaps most often as strings, a subject of a future article in the \u201cD and C\u201d series). Although D arrays are implemented in a manner that is not directly compatible with C, the fundamental building blocks are the same. This makes compatibility between the two relatively painless as long as the differences are not forgotten. This article is the first of a few exploring those differences.<\/p>\n

When using a C API from D, it\u2019s sometimes necessary to translate existing code from C to D. A new D program can benefit from existing examples of using the C API, and anyone porting a program from C that uses the API would do well to keep the initial port as close to the original as possible. It\u2019s on that basis that we\u2019re starting off with a look at the declaration and initialization syntax in both languages and how to translate between them. Subsequent posts in this series will cover multidimensional arrays, the anatomy of a D array, passing D arrays to and receiving C arrays from C functions, and how the GC fits into the picture.<\/p>\n

My original concept of covering this topic was much smaller in scope, my intent to brush over the boring details and assume that readers would know enough of the basics of C to derive the why from the what and the how. That was before I gave a D tutorial presentation to a group among whom only one person had any experience with C. I\u2019ve also become more aware that there are regular users of the D forums<\/a> who have never touched a line of C. As such, I\u2019ll be covering a lot more ground than I otherwise would have (hence a two-part article has morphed into at least three). I urge those for whom much of said ground is old hat not to get complacent in their skimming of the page! A comfortable experience with C is more apt than none at all to obscure some of the pitfalls I describe.<\/p>\n

Array declarations<\/h3>\n

Let\u2019s start with a simple declaration of a one-dimensional array:<\/p>\n

int c0[3];<\/pre>\n
This declaration allocates enough memory on the stack to hold three int<\/code> values. The values are stored contiguously in memory, one right after the other. c0<\/code> may or may not be initialized, depending on where it\u2019s declared. Global variables and static<\/code> local variables are default initialized to 0<\/code>, as the following C program demonstrates.<\/p>\n
definit.c<\/strong><\/p>\n
#include <stdio.h>\n\n\/\/ global (can also be declared static)\nint c1[3];\n\nvoid main(int argc, char** argv)\n{\n    static int c2[3];       \/\/ static local\n    int c3[3];              \/\/ non-static local\n\n    printf(\"one: %i %i %i\\n\", c1[0], c1[1], c1[2]);\n    printf(\"two: %i %i %i\\n\", c2[0], c2[1], c2[2]);\n    printf(\"three: %i %i %i\\n\", c3[0], c3[1], c3[2]);\n}<\/pre>\n
For me, this prints:<\/p>\n
one: 0 0 0\ntwo: 0 0 0\nthree: -1 8 0<\/pre>\n
The values for c3<\/code> just happened to be lying around at that memory location. Now for the equivalent D declaration:<\/p>\n
int[3] d0;<\/pre>\n
Try it online<\/a><\/em><\/p>\n
Here we can already find the first gotcha.<\/p>\n
A general rule of thumb in D is that C code pasted into a D source file should either work as it does in C or fail to compile. For a long while, C array declaration syntax fell into the former category and was a legal alternative to the D syntax. It has since been deprecated and subsequently removed from the language, meaning int d0[3]<\/code> will now cause the compiler to scold you:<\/p>\n
Error: instead of C-style syntax, use D-style int[3] d0<\/pre>\n
It may seem an arbitrary restriction, but it really isn\u2019t. At its core, it\u2019s about consistency at a couple of different levels.<\/p>\n
One is that we read declarations in D from right to left<\/a>. In the declaration of d0<\/code>, everything flows from right to left in the same order that we say it: \u201c(d0) is an (array of three) (integers)\u201d. The same is not true of the C-style declaration.<\/p>\n
Another is that the type of d0<\/code> is actually int[3]<\/code>. Consider the following pointer declarations:<\/p>\n
int* p0, p1;<\/pre>\n
The type of both p0<\/code> and p1<\/code> is int*<\/code> (in C, only p0<\/code> would be a pointer; p1<\/code> would simply be an int<\/code>). It\u2019s the same as all type declarations in D\u2014type on the left, symbol on the right. Now consider this:<\/p>\n
int d1[3], d2[3];\nint[3] d4, d5;<\/pre>\n
Having two different syntaxes for array declarations, with one that splits the type like an infinitive, sets the stage for the production of inconsistent and potentially confusing code. By making the C-style syntax illegal, consistency is enforced. Code readability is a key component of maintainability.<\/p>\n
Another difference between d0<\/code> and c0<\/code> is that the elements of d0<\/code> will be default initialized no matter where or how it\u2019s declared. Module scope, local scope, static local\u2026 it doesn\u2019t matter. Unless the compiler is told otherwise, variables in D are always default initialized to the predefined value specified by the init<\/code> property of each type<\/a>. Array elements are initialized to the init<\/code> property of the element type. As it happens, int.init == 0<\/code>. Translate definit.c<\/strong> to D and see it for yourself (open up run.dlang.io and give it a go<\/a>).<\/p>\n
When translating C to D, this default initialization business is a subtle gotcha. Consider this innocently contrived C snippet:<\/p>\n
\/\/ static variables are default initialized to 0 in C\nstatic float vertex[3];\nsome_func_that_expects_inited_vert(vertex);<\/pre>\n
A direct translation straight to D will not produce the expected result, as float.init == float.nan<\/code>, not 0.0f<\/code>!<\/p>\n
When translating between the two languages, always be aware of which C variables are not explicitly initialized, which are expected to be initialized, and the default initialization value for each of the basic types<\/a> in D. Failure to account for the subtleties may well lead to debugging sessions of the hair-pulling variety.<\/p>\n
Default initialization can easily be disabled in D with = void<\/code> in the declaration. This is particularly useful for arrays that are going to be loaded with values before they\u2019re read, or that contain elements with an init<\/code> value that isn\u2019t very useful as anything other than a marker of uninitialized variables.<\/p>\n
float[16] matrix = void;\nsetIdentity(matrix);<\/pre>\n
On a side note, the purpose of default initialization is not to provide a convenient default value, but to make uninitialized variables stand out (a fact you may come to appreciate in a future debugging session). A common mistake is to assume that types like float<\/code> and char<\/code>, with their \u201cnot a number\u201d (float.nan<\/code>) and invalid UTF\u20138 (0xFF<\/code>) initializers, are the oddball outliers. Not so. Those values are great markers of uninitialized memory because they aren\u2019t useful for much else. It\u2019s the integer types (and bool<\/code>) that break the pattern. For these types, the entire range of values has potential meaning, so there\u2019s no single value that universally shouts \u201cHey! I\u2019m uninitialized!\u201d. As such, integer and bool<\/code> variables are often left with their default initializer since 0<\/code> and false<\/code> are frequently the values one would pick for explicit initialization for those types. Floating point and character values, however, should generally be explicitly initialized or assigned to as soon as possible.<\/p>\n
Explicit array initialization<\/h3>\n
C allows arrays to be explicitly initialized in different ways:<\/p>\n
int ci0[3] = {0, 1, 2};  \/\/ [0, 1, 2]\nint ci1[3] = {1};        \/\/ [1, 0, 0]\nint ci2[]  = {0, 1, 2};  \/\/ [0, 1, 2]\nint ci3[3] = {[2] = 2, [0] = 1}; \/\/ [1, 0, 2]\nint ci4[]  = {[2] = 2, [0] = 1}; \/\/ [1, 0, 2]<\/pre>\n
What we can see here is:<\/p>\n