api-types-cpp
is a library providing ergonomic C++ types for data structures used at API (FIDL / banjo) boundaries.
Namespace: All types are defined in the display
namespace.
Filename: Each type is declared and defined in separate type-name.h
/ type-name.cc
files.
Documentation: Each type’s class-level documentation points to the related FIDL / banjo types. This library’s documentation does not duplicate the API contracts specified in the corresponding FIDL / banjo types.
One-to-many mapping: One type in this library may correspond to multiple FIDL or banjo types. The type’s documentation points to all related FIDL / banjo types.
Data structure naming: The library aims to reuse the FIDL vocabulary for type names and struct member names. FIDL names prevail in naming conflicts between FIDL and banjo. (The long-term conflict resolution is the removal of the banjo types.)
Conversion helpers: The library offers conversion helpers between library types and all related FIDL / banjo types. Conversion helpers that produce library types are named ToTypeName()
. Conversion helpers that produce FIDL / Banjo types are named ToFidlTypeName()
/ ToBanjoTypeName()
.
A type defined in api-types-cpp
may be an alias of the related FIDL C++ wire type. See AlphaMode
for an aliasing example.
The library defines its own types when the code generated by the FIDL C++ wire binding is not sufficiently ergonomic. Some examples of ergonomic gaps in the FIDL generated code:
FIDL uses unsigned numeric types for non-negative quantities. This library uses signed types for values that may be involved in arithmetic operations, so we can lean on UBSan for overflow detection. For a concrete example, compare display::Frame
with its associated fuchsia.hardware.display.types/Frame
FIDL type.
No comparison or arithmetics operators. As a minimum bar, this library overloads ==
and !=
for all the types it defines. This makes it easy to use the types in googletest assertions.
FIDL currently lacks newtype support for non-composite types (numeric and boolean), and the recommended workaround is struct wrappers. This library offers fbl::StrongInt
-based types for internal representation, together with conversion helpers for FIDL’s struct wrappers. This is especially useful for the Display stack, which makes extensive use of 64-bit integers as handles for various resources. For a concrete example, compare display::DisplayId
with the fuchsia.hardware.display.types/DisplayId
FIDL type.
Generated binding for FIDL types containing tables or unions require arena allocations.