C arrays of unknown size

This module is intended to be imported qualified.

import HsBindgen.Runtime.Prelude
import HsBindgen.Runtime.IncompleteArray qualified as IA

In example C code below, p1 points to the array xs as a whole, while p2 points to the first element of xs.

extern int xs[];
void foo () {
  int (*p1)[] = &xs;
  int *p2 = &(xs[0]);
}

Though the types of p1 and p2 differ, the values of the pointers (the address they point to) is the same. An array is just a block of contiguous memory storing array elements. p1 points to where xs starts, and p2 points to where the first element of xs starts, and these addresses are the same. In Haskell, the corresponding types for p1 and p2 respectively are Ptr (IncompleteArray CInt) and Ptr CInt respectively.

Functions like peekArray require a Ptr (IncompleteArray a) argument. If the user only has access to a Ptr a but they know that is pointing to the first element in an array, then they can use toPtr to convert the pointer before using peekArray on it. Conversely, if the user has access to a Ptr (IncompleteArray a) but they want to convert it to a Ptr a, then they can use toFirstElemPtr.

NOTE: with overloaded record dot syntax, syntax like .toFirstElemPtr is also supported.

Relevant functions in this module also support pointers of newtypes around IncompleteArray, hence the addition of Coercible constraints in many places. For example, we can use toPtr at an IncompleteArray type or we can use toPtr at a newtype around an IncompleteArray.

newtype A = A (IncompleteArray CInt)
toPtr @(IncompleteArray CInt) :: Ptr CInt -> Ptr (IncompleteArray CInt)
toPtr @A                      :: Ptr CInt -> Ptr A