move generic safety information into README
This commit is contained in:
Vinzenz Schroeter
parent
e0d82b2b87
commit
fc80e1b83f
11 changed files with 202 additions and 1944 deletions
|
|
@ -1,35 +1,10 @@
|
|||
//! C functions for interacting with [Cp437Grid]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 crate::ByteSlice;
|
||||
use servicepoint::{Cp437Grid, DataRef, Grid};
|
||||
use std::ptr::NonNull;
|
||||
|
||||
/// Creates a new [Cp437Grid] with the specified dimensions.
|
||||
///
|
||||
/// returns: [Cp437Grid] 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`.
|
||||
/// returns: [Cp437Grid] initialized to 0.
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn sp_cp437_grid_new(
|
||||
width: usize,
|
||||
|
|
@ -40,27 +15,11 @@ pub unsafe extern "C" fn sp_cp437_grid_new(
|
|||
}
|
||||
|
||||
/// Loads a [Cp437Grid] 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: SPByteSlice,
|
||||
data: ByteSlice,
|
||||
) -> *mut Cp437Grid {
|
||||
let data = unsafe { data.as_slice() };
|
||||
let grid = Cp437Grid::load(width, height, data);
|
||||
|
|
@ -72,21 +31,6 @@ pub unsafe extern "C" fn sp_cp437_grid_load(
|
|||
}
|
||||
|
||||
/// Clones a [Cp437Grid].
|
||||
///
|
||||
/// Will never return NULL.
|
||||
///
|
||||
/// # Panics
|
||||
///
|
||||
/// - when `cp437_grid` is NULL
|
||||
///
|
||||
/// # Safety
|
||||
///
|
||||
/// The caller has to make sure that:
|
||||
///
|
||||
/// - `cp437_grid` points to a valid [Cp437Grid]
|
||||
/// - `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: NonNull<Cp437Grid>,
|
||||
|
|
@ -96,20 +40,6 @@ pub unsafe extern "C" fn sp_cp437_grid_clone(
|
|||
}
|
||||
|
||||
/// Deallocates a [Cp437Grid].
|
||||
///
|
||||
/// # Panics
|
||||
///
|
||||
/// - when `cp437_grid` is NULL
|
||||
///
|
||||
/// # Safety
|
||||
///
|
||||
/// The caller has to make sure that:
|
||||
///
|
||||
/// - `cp437_grid` points to a valid [Cp437Grid]
|
||||
/// - `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 [TypedCommand]
|
||||
///
|
||||
/// [TypedCommand]: [crate::TypedCommand]
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn sp_cp437_grid_free(cp437_grid: NonNull<Cp437Grid>) {
|
||||
_ = unsafe { Box::from_raw(cp437_grid.as_ptr()) };
|
||||
|
|
@ -124,15 +54,7 @@ pub unsafe extern "C" fn sp_cp437_grid_free(cp437_grid: NonNull<Cp437Grid>) {
|
|||
///
|
||||
/// # 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 [Cp437Grid]
|
||||
/// - `cp437_grid` is not written to concurrently
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn sp_cp437_grid_get(
|
||||
cp437_grid: NonNull<Cp437Grid>,
|
||||
|
|
@ -154,17 +76,7 @@ pub unsafe extern "C" fn sp_cp437_grid_get(
|
|||
///
|
||||
/// # 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: NonNull<Cp437Grid>,
|
||||
|
|
@ -181,17 +93,6 @@ pub unsafe extern "C" fn sp_cp437_grid_set(
|
|||
///
|
||||
/// - `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 [Cp437Grid]
|
||||
/// - `cp437_grid` is not written to or read from concurrently
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn sp_cp437_grid_fill(
|
||||
cp437_grid: NonNull<Cp437Grid>,
|
||||
|
|
@ -205,16 +106,6 @@ pub unsafe extern "C" fn sp_cp437_grid_fill(
|
|||
/// # 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 [Cp437Grid]
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn sp_cp437_grid_width(
|
||||
cp437_grid: NonNull<Cp437Grid>,
|
||||
|
|
@ -227,16 +118,6 @@ pub unsafe extern "C" fn sp_cp437_grid_width(
|
|||
/// # 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 [Cp437Grid]
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn sp_cp437_grid_height(
|
||||
cp437_grid: NonNull<Cp437Grid>,
|
||||
|
|
@ -246,22 +127,10 @@ pub unsafe extern "C" fn sp_cp437_grid_height(
|
|||
|
||||
/// Gets an unsafe reference to the data of the [Cp437Grid] 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 [Cp437Grid]
|
||||
/// - the returned memory range is never accessed after the passed [Cp437Grid] has been freed
|
||||
/// - the returned memory range is never accessed concurrently, either via the [Cp437Grid] or directly
|
||||
/// The returned memory is valid for the lifetime of the grid.
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn sp_cp437_grid_unsafe_data_ref(
|
||||
cp437_grid: NonNull<Cp437Grid>,
|
||||
) -> SPByteSlice {
|
||||
unsafe { SPByteSlice::from_slice((*cp437_grid.as_ptr()).data_ref_mut()) }
|
||||
) -> ByteSlice {
|
||||
unsafe { ByteSlice::from_slice((*cp437_grid.as_ptr()).data_ref_mut()) }
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in a new issue