readcon-core 0.13.1

language = "C"

############## Options for Wrapping the Contents of the Header #################

header = """
/*
 * readcon-core C API.
 *
 * Memory ownership
 *   - Opaque handles (RKRConFrame, RKRConFrameWriter, RKRConFrameBuilder,
 *     CConFrameIterator) are caller-owned. Free each with its dedicated
 *     destructor: free_rkr_frame, free_rkr_frame_writer,
 *     free_rkr_frame_builder, free_con_frame_iterator.
 *   - rkr_read_all_frames returns a heap-allocated array of RKRConFrame*
 *     handles together with the frame count via the *num_frames out-param.
 *     The array's capacity equals the count (shrunk to fit). Free with
 *     free_rkr_frame_array(frames, *num_frames). Each individual frame is
 *     released by free_rkr_frame_array; do NOT also call free_rkr_frame.
 *   - char* values returned by rkr_frame_metadata_json,
 *     rkr_frame_potential_type, and rkr_frame_get_header_line_cpp are heap
 *     allocated; free them with rkr_free_string. rkr_free_string is safe
 *     to call with NULL (no-op).
 *   - const char* returned by rkr_library_version is process-static; do
 *     NOT free it.
 *   - rkr_frame_to_c_frame returns a CFrame whose `atoms` array is owned
 *     by the caller; release with free_c_frame.
 *
 * Sentinel values for absent metadata
 *   - Floating-point getters (rkr_frame_energy, rkr_frame_time,
 *     rkr_frame_timestep, etc.) return NaN when the metadata key is
 *     absent. Test with isnan() from <math.h>.
 *   - Unsigned-integer getters (rkr_frame_frame_index, rkr_frame_neb_bead,
 *     rkr_frame_neb_band) return UINT64_MAX when absent.
 *   - String getters return NULL when absent.
 *
 * Thread safety
 *   - Opaque handles are NOT Sync. Do not share a single
 *     RKRConFrame/RKRConFrameWriter/RKRConFrameBuilder across threads
 *     without external synchronization. Distinct handles are independent.
 *   - rkr_read_all_frames internally uses sequential parsing; the
 *     `parallel` Cargo feature is exposed only through the Rust API and
 *     is not surfaced via this C header.
 */

/* Forward-declare the DLPack-managed tensor type for the tier-3
 * builder export FFI. Consumers that want to dereference fields
 * (data, shape, strides, dtype, deleter) must include
 * <dlpack/dlpack.h> (or equivalent) themselves; the readcon-core C
 * ABI only passes the pointer through. */
struct DLManagedTensorVersioned;
typedef struct DLManagedTensorVersioned RKRDLManagedTensorVersioned;
"""
include_guard = "READCON_H"
include_version = true
pragma_once = true
autogen_warning = "/* Warning, this file is autogenerated by cbindgen. Don't modify this manually. */"
namespace = "readcon"
no_includes = false
cpp_compat = true

############################ Code Style Options ################################

line_length = 80
tab_width = 4
braces = "SameLine"
documentation = true
documentation_style = "Doxy"
documentation_length = "full"
line_endings = "LF"

[defines]
# The zstd-compressed writer FFI (`create_writer_zstd_c`,
# `create_writer_zstd_with_precision_c`) is gated behind the `zstd`
# Cargo feature. cbindgen always emits the declarations but wraps them
# in `#if defined(READCON_CORE_HAS_ZSTD)`, so consumers that link a
# build with the feature enabled define that macro to reach the
# symbols; builds without the feature omit the symbols and the guard
# keeps the declarations out of reach.
"feature = zstd" = "READCON_CORE_HAS_ZSTD"
# Chemfiles selection symbols are always declared (stubbed in Rust when the
# `chemfiles` feature is off) so C++ wrappers compile without -DREADCON_CORE_HAS_CHEMFILES.

[export]
# `FxHashMap` (rustc-hash) is re-exported by the Rust API for
# `ConFrame::build_atom_id_index`. C/C++ consumers reach the index
# through `rkr_frame_atom_index_by_id` instead; the hash map type
# never crosses the FFI boundary, so cbindgen does not need to
# generate a mangling for it.
exclude = ["FxHashMap"]