mod ffi

module ffi

Functions

unsafe extern C fn con_frame_iterator_next(iterator: *mut CConFrameIterator) -> *mut RKRConFrame

Reads the next frame from the iterator, returning an opaque handle. The caller OWNS the returned handle and must free it with free_rkr_frame.

unsafe extern C fn create_writer_from_path_c(filename_c: *const c_char) -> *mut RKRConFrameWriter

Creates a new frame writer for the specified file. The caller OWNS the returned pointer and MUST call free_rkr_writer.

unsafe extern C fn create_writer_from_path_with_precision_c(filename_c: *const c_char, precision: u8) -> *mut RKRConFrameWriter

Creates a new frame writer with custom floating-point precision. The caller OWNS the returned pointer and MUST call free_rkr_writer.

unsafe extern C fn free_c_frame(frame: *mut CFrame)

Frees the memory of a CFrame struct, including its internal atoms array.

unsafe extern C fn free_con_frame_iterator(iterator: *mut CConFrameIterator)

Frees the memory for a CConFrameIterator.

unsafe extern C fn free_rkr_frame(frame_handle: *mut RKRConFrame)

Frees the memory for an opaque RKRConFrame handle.

unsafe extern C fn free_rkr_frame_array(frames: *mut *mut RKRConFrame, num_frames: usize)

Frees an array of frame handles returned by rkr_read_all_frames. Each frame is freed individually, then the array itself.

unsafe extern C fn free_rkr_frame_builder(builder_handle: *mut RKRConFrameBuilder)

Frees a frame builder without building.

unsafe extern C fn free_rkr_writer(writer_handle: *mut RKRConFrameWriter)

Frees the memory for an RKRConFrameWriter, closing the associated file.

unsafe extern C fn read_con_file_iterator(filename_c: *const c_char) -> *mut CConFrameIterator

Creates a new iterator for a .con file. The caller OWNS the returned pointer and MUST call free_con_frame_iterator. Returns NULL if there are no more frames or on error.

unsafe extern C fn rkr_frame_add_atom(builder_handle: *mut RKRConFrameBuilder, symbol: *const c_char, x: f64, y: f64, z: f64, is_fixed: bool, atom_id: u64, mass: f64) -> i32

Adds an atom (without velocity) to the frame builder. Returns 0 on success, -1 on error.

unsafe extern C fn rkr_frame_add_atom_with_velocity(builder_handle: *mut RKRConFrameBuilder, symbol: *const c_char, x: f64, y: f64, z: f64, is_fixed: bool, atom_id: u64, mass: f64, vx: f64, vy: f64, vz: f64) -> i32

Adds an atom with velocity data to the frame builder. Returns 0 on success, -1 on error.

unsafe extern C fn rkr_frame_builder_build(builder_handle: *mut RKRConFrameBuilder) -> *mut RKRConFrame

Consumes the builder and returns a finalized RKRConFrame handle. The builder handle is invalidated after this call. The caller OWNS the returned frame and MUST call free_rkr_frame. Returns NULL on error.

unsafe extern C fn rkr_frame_get_header_line(frame_handle: *const RKRConFrame, is_prebox: bool, line_index: usize, buffer: *mut c_char, buffer_len: usize) -> i32

Copies a header string line into a user-provided buffer. This is a C style helper… where the user explicitly sets the buffer. Returns the number of bytes written (excluding null terminator), or -1 on error.

unsafe extern C fn rkr_frame_get_header_line_cpp(frame_handle: *const RKRConFrame, is_prebox: bool, line_index: usize) -> *mut c_char

Gets a header string line as a newly allocated, null-terminated C string.

The caller OWNS the returned pointer and MUST call rkr_free_string on it to prevent a memory leak. Returns NULL on error or if the index is invalid.

unsafe extern C fn rkr_frame_new(cell: *const f64, angles: *const f64, prebox0: *const c_char, prebox1: *const c_char, postbox0: *const c_char, postbox1: *const c_char) -> *mut RKRConFrameBuilder

Creates a new frame builder with the given cell dimensions, angles, and header lines. The caller OWNS the returned pointer and MUST call free_rkr_frame_builder or rkr_frame_builder_build. Returns NULL on error.

unsafe extern C fn rkr_frame_to_c_frame(frame_handle: *const RKRConFrame) -> *mut CFrame

Extracts the core atomic data into a transparent CFrame struct. The caller OWNS the returned pointer and MUST call free_c_frame on it.

unsafe extern C fn rkr_free_string(s: *mut c_char)

Frees a C string that was allocated by Rust (e.g., from rkr_frame_get_header_line).

unsafe extern C fn rkr_read_all_frames(filename_c: *const c_char, num_frames: *mut usize) -> *mut *mut RKRConFrame

Reads all frames from a .con file using mmap. Returns an array of frame handles and sets num_frames to the count. The caller OWNS both the array and each frame handle. Free frames with free_rkr_frame and the array with free_rkr_frame_array. Returns NULL on error.

unsafe extern C fn rkr_read_first_frame(filename_c: *const c_char) -> *mut RKRConFrame

Reads the first frame from a .con file. Uses read_to_string for small files (< 64 KiB) and mmap for larger ones. Stops after the first frame rather than parsing the entire file. The caller OWNS the returned handle and MUST call free_rkr_frame. Returns NULL on error.

unsafe extern C fn rkr_writer_extend(writer_handle: *mut RKRConFrameWriter, frame_handles: *const *const RKRConFrame, num_frames: usize) -> i32

Writes multiple frames from an array of handles to the file managed by the writer.

Structs and Unions

struct CAtom

atomic_number: u64

x: f64

y: f64

z: f64

atom_id: u64

mass: f64

is_fixed: bool

vx: f64

vy: f64

vz: f64

has_velocity: bool

struct CConFrameIterator

struct CFrame

A transparent, “lossy” C-struct containing only the core atomic data. This can be extracted from an RKRConFrame handle for direct data access. The caller is responsible for freeing the atoms array using free_c_frame.

atoms: *mut CAtom

num_atoms: usize

cell: [f64; 3]

angles: [f64; 3]

has_velocities: bool

struct RKRConFrame

An opaque handle to a full, lossless Rust ConFrame object. The C/C++ side needs to treat this as a void pointer

struct RKRConFrameBuilder

An opaque handle to a Rust ConFrameBuilder object.

struct RKRConFrameWriter

An opaque handle to a Rust ConFrameWriter object. The C/C++ side needs to treat this as a void pointer