277 lines
6.7 KiB
Rust
277 lines
6.7 KiB
Rust
//! C functions for interacting with [SPCp437Grid]s
|
|
//!
|
|
//! prefix `sp_cp437_grid_`
|
|
//!
|
|
//!
|
|
//! A C-wrapper for grid containing codepage 437 characters.
|
|
//!
|
|
//! The encoding is currently not enforced.
|
|
//!
|
|
//! # Examples
|
|
//!
|
|
//! ```C
|
|
//! Cp437Grid grid = sp_cp437_grid_new(4, 3);
|
|
//! sp_cp437_grid_fill(grid, '?');
|
|
//! sp_cp437_grid_set(grid, 0, 0, '!');
|
|
//! sp_cp437_grid_free(grid);
|
|
//! ```
|
|
|
|
use crate::SPByteSlice;
|
|
use servicepoint::{Cp437Grid, DataRef, Grid};
|
|
use std::ptr::NonNull;
|
|
|
|
/// Creates a new [SPCp437Grid] with the specified dimensions.
|
|
///
|
|
/// returns: [SPCp437Grid] initialized to 0. Will never return NULL.
|
|
///
|
|
/// # Safety
|
|
///
|
|
/// The caller has to make sure that:
|
|
///
|
|
/// - the returned instance is freed in some way, either by using a consuming function or
|
|
/// by explicitly calling `sp_cp437_grid_free`.
|
|
#[no_mangle]
|
|
pub unsafe extern "C" fn sp_cp437_grid_new(
|
|
width: usize,
|
|
height: usize,
|
|
) -> NonNull<Cp437Grid> {
|
|
let result = Box::new(Cp437Grid::new(width, height));
|
|
NonNull::from(Box::leak(result))
|
|
}
|
|
|
|
/// Loads a [SPCp437Grid] with the specified dimensions from the provided data.
|
|
///
|
|
/// Will never return NULL.
|
|
///
|
|
/// # Panics
|
|
///
|
|
/// - when `data` is NULL
|
|
/// - when the provided `data_length` does not match `height` and `width`
|
|
///
|
|
/// # Safety
|
|
///
|
|
/// The caller has to make sure that:
|
|
///
|
|
/// - `data` points to a valid memory location of at least `data_length`
|
|
/// bytes in size.
|
|
/// - the returned instance is freed in some way, either by using a consuming function or
|
|
/// by explicitly calling `sp_cp437_grid_free`.
|
|
#[no_mangle]
|
|
pub unsafe extern "C" fn sp_cp437_grid_load(
|
|
width: usize,
|
|
height: usize,
|
|
data: *const u8,
|
|
data_length: usize,
|
|
) -> *mut Cp437Grid {
|
|
assert!(data.is_null());
|
|
let data = unsafe { std::slice::from_raw_parts(data, data_length) };
|
|
let grid = Cp437Grid::load(width, height, data);
|
|
if let Some(grid) = grid {
|
|
Box::leak(Box::new(grid))
|
|
} else {
|
|
std::ptr::null_mut()
|
|
}
|
|
}
|
|
|
|
/// Clones a [SPCp437Grid].
|
|
///
|
|
/// Will never return NULL.
|
|
///
|
|
/// # Panics
|
|
///
|
|
/// - when `cp437_grid` is NULL
|
|
///
|
|
/// # Safety
|
|
///
|
|
/// The caller has to make sure that:
|
|
///
|
|
/// - `cp437_grid` points to a valid [SPCp437Grid]
|
|
/// - `cp437_grid` is not written to concurrently
|
|
/// - the returned instance is freed in some way, either by using a consuming function or
|
|
/// by explicitly calling `sp_cp437_grid_free`.
|
|
#[no_mangle]
|
|
pub unsafe extern "C" fn sp_cp437_grid_clone(
|
|
cp437_grid: *const Cp437Grid,
|
|
) -> NonNull<Cp437Grid> {
|
|
assert!(!cp437_grid.is_null());
|
|
let result = Box::new(unsafe { (*cp437_grid).clone() });
|
|
NonNull::from(Box::leak(result))
|
|
}
|
|
|
|
/// Deallocates a [SPCp437Grid].
|
|
///
|
|
/// # Panics
|
|
///
|
|
/// - when `cp437_grid` is NULL
|
|
///
|
|
/// # Safety
|
|
///
|
|
/// The caller has to make sure that:
|
|
///
|
|
/// - `cp437_grid` points to a valid [SPCp437Grid]
|
|
/// - `cp437_grid` is not used concurrently or after cp437_grid call
|
|
/// - `cp437_grid` was not passed to another consuming function, e.g. to create a [SPCommand]
|
|
///
|
|
/// [SPCommand]: [crate::SPCommand]
|
|
#[no_mangle]
|
|
pub unsafe extern "C" fn sp_cp437_grid_free(cp437_grid: *mut Cp437Grid) {
|
|
assert!(!cp437_grid.is_null());
|
|
_ = unsafe { Box::from_raw(cp437_grid) };
|
|
}
|
|
|
|
/// Gets the current value at the specified position.
|
|
///
|
|
/// # Arguments
|
|
///
|
|
/// - `cp437_grid`: instance to read from
|
|
/// - `x` and `y`: position of the cell to read
|
|
///
|
|
/// # Panics
|
|
///
|
|
/// - when `cp437_grid` is NULL
|
|
/// - when accessing `x` or `y` out of bounds
|
|
///
|
|
/// # Safety
|
|
///
|
|
/// The caller has to make sure that:
|
|
///
|
|
/// - `cp437_grid` points to a valid [SPCp437Grid]
|
|
/// - `cp437_grid` is not written to concurrently
|
|
#[no_mangle]
|
|
pub unsafe extern "C" fn sp_cp437_grid_get(
|
|
cp437_grid: *const Cp437Grid,
|
|
x: usize,
|
|
y: usize,
|
|
) -> u8 {
|
|
assert!(!cp437_grid.is_null());
|
|
unsafe { (*cp437_grid).get(x, y) }
|
|
}
|
|
|
|
/// Sets the value of the specified position in the [SPCp437Grid].
|
|
///
|
|
/// # Arguments
|
|
///
|
|
/// - `cp437_grid`: instance to write to
|
|
/// - `x` and `y`: position of the cell
|
|
/// - `value`: the value to write to the cell
|
|
///
|
|
/// returns: old value of the cell
|
|
///
|
|
/// # Panics
|
|
///
|
|
/// - when `cp437_grid` is NULL
|
|
/// - when accessing `x` or `y` out of bounds
|
|
///
|
|
/// # Safety
|
|
///
|
|
/// The caller has to make sure that:
|
|
///
|
|
/// - `cp437_grid` points to a valid [SPBitVec]
|
|
/// - `cp437_grid` is not written to or read from concurrently
|
|
///
|
|
/// [SPBitVec]: [crate::SPBitVec]
|
|
#[no_mangle]
|
|
pub unsafe extern "C" fn sp_cp437_grid_set(
|
|
cp437_grid: *mut Cp437Grid,
|
|
x: usize,
|
|
y: usize,
|
|
value: u8,
|
|
) {
|
|
assert!(!cp437_grid.is_null());
|
|
unsafe { (*cp437_grid).set(x, y, value) };
|
|
}
|
|
|
|
/// Sets the value of all cells in the [SPCp437Grid].
|
|
///
|
|
/// # Arguments
|
|
///
|
|
/// - `cp437_grid`: instance to write to
|
|
/// - `value`: the value to set all cells to
|
|
///
|
|
/// # Panics
|
|
///
|
|
/// - when `cp437_grid` is NULL
|
|
///
|
|
/// # Safety
|
|
///
|
|
/// The caller has to make sure that:
|
|
///
|
|
/// - `cp437_grid` points to a valid [SPCp437Grid]
|
|
/// - `cp437_grid` is not written to or read from concurrently
|
|
#[no_mangle]
|
|
pub unsafe extern "C" fn sp_cp437_grid_fill(
|
|
cp437_grid: *mut Cp437Grid,
|
|
value: u8,
|
|
) {
|
|
assert!(!cp437_grid.is_null());
|
|
unsafe { (*cp437_grid).fill(value) };
|
|
}
|
|
|
|
/// Gets the width of the [SPCp437Grid] instance.
|
|
///
|
|
/// # Arguments
|
|
///
|
|
/// - `cp437_grid`: instance to read from
|
|
///
|
|
/// # Panics
|
|
///
|
|
/// - when `cp437_grid` is NULL
|
|
///
|
|
/// # Safety
|
|
///
|
|
/// The caller has to make sure that:
|
|
///
|
|
/// - `cp437_grid` points to a valid [SPCp437Grid]
|
|
#[no_mangle]
|
|
pub unsafe extern "C" fn sp_cp437_grid_width(
|
|
cp437_grid: *const Cp437Grid,
|
|
) -> usize {
|
|
assert!(!cp437_grid.is_null());
|
|
unsafe { (*cp437_grid).width() }
|
|
}
|
|
|
|
/// Gets the height of the [SPCp437Grid] instance.
|
|
///
|
|
/// # Arguments
|
|
///
|
|
/// - `cp437_grid`: instance to read from
|
|
///
|
|
/// # Panics
|
|
///
|
|
/// - when `cp437_grid` is NULL
|
|
///
|
|
/// # Safety
|
|
///
|
|
/// The caller has to make sure that:
|
|
///
|
|
/// - `cp437_grid` points to a valid [SPCp437Grid]
|
|
#[no_mangle]
|
|
pub unsafe extern "C" fn sp_cp437_grid_height(
|
|
cp437_grid: *const Cp437Grid,
|
|
) -> usize {
|
|
assert!(!cp437_grid.is_null());
|
|
unsafe { (*cp437_grid).height() }
|
|
}
|
|
|
|
/// Gets an unsafe reference to the data of the [SPCp437Grid] instance.
|
|
///
|
|
/// Will never return NULL.
|
|
///
|
|
/// # Panics
|
|
///
|
|
/// - when `cp437_grid` is NULL
|
|
///
|
|
/// ## Safety
|
|
///
|
|
/// The caller has to make sure that:
|
|
///
|
|
/// - `cp437_grid` points to a valid [SPCp437Grid]
|
|
/// - the returned memory range is never accessed after the passed [SPCp437Grid] has been freed
|
|
/// - the returned memory range is never accessed concurrently, either via the [SPCp437Grid] or directly
|
|
#[no_mangle]
|
|
pub unsafe extern "C" fn sp_cp437_grid_unsafe_data_ref(
|
|
cp437_grid: *mut Cp437Grid,
|
|
) -> SPByteSlice {
|
|
unsafe {SPByteSlice::from_slice((*cp437_grid).data_ref_mut()) }
|
|
}
|