Files
swift-collections/Sources/TrailingElementsModule/TrailingElementsModule.docc/TrailingElementsModule.md
T
Karoy Lorentey 80878519f2 [doc] Fix most issues reported by docc
DocC keeps changing its link syntax. The latest iteration appears to have trouble dealing with `Self`-taking or `Self`-returning methods, so change our API to replace `Self` with a direct mention of the concrete type. ¯\\\_(ツ)\_/¯

That said, the new compiler also found a large number of mismatching parameter names, and that was really helpful.
2026-03-09 14:14:51 -07:00

4.5 KiB

TrailingElementsModule

Overview

This module provides types that manage values consisting of a fixed-size header plus variable-size storage that follows that header in memory. The types are similar in design to the ManagedBuffer type in the standard library, but are non-copyable types that eliminate the need for reference counting and heap allocation.

The TrailingArray type can be used for types consisting of a header after which there are some (dynamic) number of elements. For example, we could have a Coordinates type that is followed by Point elements:

struct Point {
  var x: Int
  var y: Int
}

struct Coordinates {
  var numPoints: Int
  // Points will follow in memory
}

To use TrailingArray, the Coordinates type must conform to the TrailingElements protocol, specifying the type of the trailing elements (Point) and the number of trailing elements (numPoints), like this:

extension Coordinates: TrailingElements {
    typealias Element = Point
    var trailingCount: Int { numPoints }
}

Now, we can create an intrusive managed buffer. The easiest way is to do so on the heap:

var coords = TrailingArray(header: Coordinates(numPoints: 3)) { outputSpan in 
  outputSpan.append(Point(x: 1, y: 2))
  outputSpan.append(Point(x: 2, y: 3))
  outputSpan.append(Point(x: 3, y: 4))
}

Subscripting an TrailingArray provides access to the elements. One can also use the TrailingArray.elements or TrailingArray.mutableElements properties to get a Span or MutableSpan over the elements, respectively. Once the coords value is no longer used, the buffer will be deallocated.

print(coords[0])    // displays Point(x: 1, y: 2)

Stack allocation

If heap allocation is not acceptable, use the static method TrailingArray.withTemporaryValue to produce a temporary instance of TrailingArray that can be used within the given body closure, like this:

TrailingArray.withTemporaryValue(header: Coordinates(numPoints: 3), repeating: Point(x: 0, y: 0)) { coords in
    coords[0] = Point(x: 1, y: 2)
    coords[1] = Point(x: 2, y: 3)
    coords[2] = Point(x: 3, y: 4)

    // operate on coords
}

Interoperability with unsafe C APIs

TrailingArray provides facilities for working with the underlying unsafe pointers, which can be useful when interoperating with C APIs. TrailingArray can take ownership of a heap-allocated pointer to its Header type (such as one might get back from a C API api) using init(consuming:):

init(consuming pointer: UnsafeMutablePointer<Header>)

or give up its pointer to hand off to C with leakStorage:

consuming func leakStorage() -> UnsafeMutablePointer<Header>

Unsafe pointers can be accessed via the withUnsafeMutablePointer* family of methods to access a pointer to the header, the trailing elements, or both.

Flexible array members

One of the uses for this module is to work with C types that involve flexible array members, which are described via an incomplete array at the end of a struct. Here is the C equivalent to the Coordinates structure shown above:

struct coordinates_t {
  unsigned num_points;
  struct point_t points[];
};

The C coordinates_t type can extended to conform to the TrailingElements protocol, allowing it to be used directly with TrailingArray:

extension coordinates_t: TrailingElements {
    typealias Element = point_t
    var trailingCount: Int { num_points }
}

This provides safer access patterns for C flexible array members, introducing safe memory ownership and bounds-safety checking.

TrailingPadding

This module also provides a lower-level primitive called TrailingPadding that references heap- or stack-allocated data with a particular type (also called the Header type) but whose allocation is larger than the size of the header itself. The API is roughly similar to that of TrailingArray, but it has no notion of what data might follow the Header instance. Instead, its initializer takes a "total size" for the allocation size, leaving the size calculation to the user:

var padded = TrailingPadding(header: SomeType(), totalSize: getSizeOfSomeTypeWithPadding())

Topics

Structures

  • TrailingArray
  • TrailingPadding

Protocols

  • TrailingElements