diff --git a/include/servicepoint.h b/include/servicepoint.h index 4caa011..6d3b891 100644 --- a/include/servicepoint.h +++ b/include/servicepoint.h @@ -645,14 +645,24 @@ void init_env_logger(void); struct Bitmap */*notnull*/ sp_bitmap_clone(struct Bitmap */*notnull*/ instance); /** + * Calls [`servicepoint::Bitmap::data_ref_mut`]. + * + * Gets an unsafe reference to the data of the [Bitmap] instance. + * + * The returned memory is valid for the lifetime of the bitmap. + */ +struct ByteSlice sp_bitmap_data_ref_mut(struct Bitmap */*notnull*/ instance); + +/** + * Calls [`servicepoint::Bitmap::fill`]. + * * Sets the state of all pixels in the [Bitmap]. * * # Arguments * - * - `bitmap`: instance to write to * - `value`: the value to set all pixels to */ -void sp_bitmap_fill(struct Bitmap */*notnull*/ bitmap, bool value); +void sp_bitmap_fill(struct Bitmap */*notnull*/ instance, bool value); /** *Deallocates a [Bitmap] instance. @@ -669,30 +679,29 @@ void sp_bitmap_free(struct Bitmap */*notnull*/ instance); struct Bitmap *sp_bitmap_from_bitvec(size_t width, BitVec */*notnull*/ bitvec); /** - * Gets the current value at the specified position in the [Bitmap]. + * Calls [`servicepoint::Bitmap::get`]. + * + * Gets the current value at the specified position. * * # Arguments * - * - `bitmap`: instance to read from * - `x` and `y`: position of the cell to read * * # Panics * * - when accessing `x` or `y` out of bounds */ -bool sp_bitmap_get(struct Bitmap */*notnull*/ bitmap, size_t x, size_t y); +bool sp_bitmap_get(struct Bitmap */*notnull*/ instance, size_t x, size_t y); /** - * Gets the height in pixels of the [Bitmap] instance. + * Calls [`servicepoint::Bitmap::height`]. * - * # Arguments - * - * - `bitmap`: instance to read from + * Gets the height in pixels. */ -size_t sp_bitmap_height(struct Bitmap */*notnull*/ bitmap); +size_t sp_bitmap_height(struct Bitmap */*notnull*/ instance); /** - * Consumes the Bitmap and returns the contained BitVec + * Consumes the Bitmap and returns the contained BitVec. */ BitVec */*notnull*/ sp_bitmap_into_bitvec(struct Bitmap */*notnull*/ bitmap); @@ -757,11 +766,12 @@ struct Bitmap *sp_bitmap_new(size_t width, size_t height); struct Bitmap */*notnull*/ sp_bitmap_new_max_sized(void); /** - * Sets the value of the specified position in the [Bitmap]. + * Calls [`servicepoint::Bitmap::set`]. + * + * Sets the value of the specified position. * * # Arguments * - * - `bitmap`: instance to write to * - `x` and `y`: position of the cell * - `value`: the value to write to the cell * @@ -769,36 +779,26 @@ struct Bitmap */*notnull*/ sp_bitmap_new_max_sized(void); * * - when accessing `x` or `y` out of bounds */ -void sp_bitmap_set(struct Bitmap */*notnull*/ bitmap, +void sp_bitmap_set(struct Bitmap */*notnull*/ instance, size_t x, size_t y, bool value); /** - * Gets an unsafe reference to the data of the [Bitmap] instance. + * Calls [`servicepoint::Bitmap::width`]. * - * The returned memory is valid for the lifetime of the bitmap. + * Gets the width in pixels. */ -struct ByteSlice sp_bitmap_unsafe_data_ref(struct Bitmap */*notnull*/ bitmap); +size_t sp_bitmap_width(struct Bitmap */*notnull*/ instance); /** - * Gets the width in pixels of the [Bitmap] instance. + * Calls [`servicepoint::DisplayBitVec::as_raw_mut_slice`]. * - * # Arguments + * Gets an unsafe reference to the data of the [DisplayBitVec] instance. * - * - `bitmap`: instance to read from - * - * # Panics - * - * - when `bitmap` is NULL - * - * # Safety - * - * The caller has to make sure that: - * - * - `bitmap` points to a valid [Bitmap] + * The returned memory is valid for the lifetime of the bitvec. */ -size_t sp_bitmap_width(struct Bitmap */*notnull*/ bitmap); +struct ByteSlice sp_bitvec_as_raw_mut_slice(BitVec */*notnull*/ instance); /** *Clones a [DisplayBitVec] instance. @@ -806,14 +806,15 @@ size_t sp_bitmap_width(struct Bitmap */*notnull*/ bitmap); BitVec */*notnull*/ sp_bitvec_clone(BitVec */*notnull*/ instance); /** - * Sets the value of all bits in the [DisplayBitVec]. + * Calls [`servicepoint::DisplayBitVec::fill`]. + * + * Sets the value of all bits. * * # Arguments * - * - `bit_vec`: instance to write to * - `value`: the value to set all bits to */ -void sp_bitvec_fill(BitVec */*notnull*/ bit_vec, bool value); +void sp_bitvec_fill(BitVec */*notnull*/ instance, bool value); /** *Deallocates a [DisplayBitVec] instance. @@ -821,7 +822,9 @@ void sp_bitvec_fill(BitVec */*notnull*/ bit_vec, bool value); void sp_bitvec_free(BitVec */*notnull*/ instance); /** - * Gets the value of a bit from the [DisplayBitVec]. + * Calls [`servicepoint::DisplayBitVec::get`]. + * + * Gets the value of a bit. * * # Arguments * @@ -834,7 +837,7 @@ void sp_bitvec_free(BitVec */*notnull*/ instance); * * - when accessing `index` out of bounds */ -bool sp_bitvec_get(BitVec */*notnull*/ bit_vec, size_t index); +bool sp_bitvec_get(BitVec */*notnull*/ instance, size_t index); /** * Creates a [BitVecCommand] and immediately turns that into a [Packet]. @@ -849,22 +852,18 @@ struct Packet *sp_bitvec_into_packet(BitVec */*notnull*/ bitvec, CompressionCode compression); /** + * Calls [`servicepoint::DisplayBitVec::is_empty`]. + * * Returns true if length is 0. - * - * # Arguments - * - * - `bit_vec`: instance to write to */ -bool sp_bitvec_is_empty(BitVec */*notnull*/ bit_vec); +bool sp_bitvec_is_empty(BitVec */*notnull*/ instance); /** - * Gets the length of the [DisplayBitVec] in bits. + * Calls [`servicepoint::DisplayBitVec::len`]. * - * # Arguments - * - * - `bit_vec`: instance to write to + * Gets the length in bits. */ -size_t sp_bitvec_len(BitVec */*notnull*/ bit_vec); +size_t sp_bitvec_len(BitVec */*notnull*/ instance); /** * Interpret the data as a series of bits and load then into a new [DisplayBitVec] instance. @@ -889,11 +888,12 @@ BitVec */*notnull*/ sp_bitvec_load(struct ByteSlice data); BitVec */*notnull*/ sp_bitvec_new(size_t size); /** - * Sets the value of a bit in the [DisplayBitVec]. + * Calls [`servicepoint::DisplayBitVec::set`]. + * + * Sets the value of a bit. * * # Arguments * - * - `bit_vec`: instance to write to * - `index`: the bit index to edit * - `value`: the value to set the bit to * @@ -901,18 +901,7 @@ BitVec */*notnull*/ sp_bitvec_new(size_t size); * * - when accessing `index` out of bounds */ -void sp_bitvec_set(BitVec */*notnull*/ bit_vec, size_t index, bool value); - -/** - * Gets an unsafe reference to the data of the [DisplayBitVec] instance. - * - * The returned memory is valid for the lifetime of the bitvec. - * - * # Arguments - * - * - `bit_vec`: instance to write to - */ -struct ByteSlice sp_bitvec_unsafe_data_ref(BitVec */*notnull*/ bit_vec); +void sp_bitvec_set(BitVec */*notnull*/ instance, size_t index, bool value); /** *Clones a [BrightnessGrid] instance. @@ -920,14 +909,24 @@ struct ByteSlice sp_bitvec_unsafe_data_ref(BitVec */*notnull*/ bit_vec); BrightnessGrid */*notnull*/ sp_brightness_grid_clone(BrightnessGrid */*notnull*/ instance); /** - * Sets the value of all cells in the [BrightnessGrid]. + * Calls [`servicepoint::BrightnessGrid::data_ref_mut`]. + * + * Gets an unsafe reference to the data of the instance. + * + * The returned memory is valid for the lifetime of the grid. + */ +struct ByteSlice sp_brightness_grid_data_ref_mut(BrightnessGrid */*notnull*/ instance); + +/** + * Calls [`servicepoint::BrightnessGrid::fill`]. + * + * Sets the value of all cells. * * # Arguments * - * - `brightness_grid`: instance to write to * - `value`: the value to set all cells to */ -void sp_brightness_grid_fill(BrightnessGrid */*notnull*/ brightness_grid, +void sp_brightness_grid_fill(BrightnessGrid */*notnull*/ instance, Brightness value); /** @@ -936,11 +935,12 @@ void sp_brightness_grid_fill(BrightnessGrid */*notnull*/ brightness_grid, void sp_brightness_grid_free(BrightnessGrid */*notnull*/ instance); /** + * Calls [`servicepoint::BrightnessGrid::get`]. + * * Gets the current value at the specified position. * * # Arguments * - * - `brightness_grid`: instance to read from * - `x` and `y`: position of the cell to read * * returns: value at position @@ -948,20 +948,16 @@ void sp_brightness_grid_free(BrightnessGrid */*notnull*/ instance); * # Panics * - When accessing `x` or `y` out of bounds. */ -Brightness sp_brightness_grid_get(BrightnessGrid */*notnull*/ brightness_grid, +Brightness sp_brightness_grid_get(BrightnessGrid */*notnull*/ instance, size_t x, size_t y); /** - * Gets the height of the [BrightnessGrid] instance. + * Calls [`servicepoint::BrightnessGrid::height`]. * - * # Arguments - * - * - `brightness_grid`: instance to read from - * - * returns: height + * Gets the height of the grid. */ -size_t sp_brightness_grid_height(BrightnessGrid */*notnull*/ brightness_grid); +size_t sp_brightness_grid_height(BrightnessGrid */*notnull*/ instance); /** * Creates a [BrightnessGridCommand] and immediately turns that into a [Packet]. @@ -1007,11 +1003,12 @@ BrightnessGrid *sp_brightness_grid_load(size_t width, BrightnessGrid */*notnull*/ sp_brightness_grid_new(size_t width, size_t height); /** - * Sets the value of the specified position in the [BrightnessGrid]. + * Calls [`servicepoint::BrightnessGrid::set`]. + * + * Sets the value of the specified position. * * # Arguments * - * - `brightness_grid`: instance to write to * - `x` and `y`: position of the cell * - `value`: the value to write to the cell * @@ -1021,34 +1018,17 @@ BrightnessGrid */*notnull*/ sp_brightness_grid_new(size_t width, size_t height); * * - When accessing `x` or `y` out of bounds. */ -void sp_brightness_grid_set(BrightnessGrid */*notnull*/ brightness_grid, +void sp_brightness_grid_set(BrightnessGrid */*notnull*/ instance, size_t x, size_t y, Brightness value); /** - * Gets an unsafe reference to the data of the [BrightnessGrid] instance. + * Calls [`servicepoint::BrightnessGrid::width`]. * - * The returned memory is valid for the lifetime of the brightness grid. - * - * # Arguments - * - * - `brightness_grid`: instance to read from - * - * returns: slice of bytes underlying the `brightness_grid`. + * Gets the width of the grid. */ -struct ByteSlice sp_brightness_grid_unsafe_data_ref(BrightnessGrid */*notnull*/ brightness_grid); - -/** - * Gets the width of the [BrightnessGrid] instance. - * - * # Arguments - * - * - `brightness_grid`: instance to read from - * - * returns: width - */ -size_t sp_brightness_grid_width(BrightnessGrid */*notnull*/ brightness_grid); +size_t sp_brightness_grid_width(BrightnessGrid */*notnull*/ instance); /** *Clones a [CharGrid] instance. @@ -1056,14 +1036,16 @@ size_t sp_brightness_grid_width(BrightnessGrid */*notnull*/ brightness_grid); CharGrid */*notnull*/ sp_char_grid_clone(CharGrid */*notnull*/ instance); /** - * Sets the value of all cells in the [CharGrid]. + * Calls [`servicepoint::CharGrid::fill`]. + * + * Sets the value of all cells in the grid. * * # Arguments * - * - `char_grid`: instance to write to * - `value`: the value to set all cells to + * - when providing values that cannot be converted to Rust's `char`. */ -void sp_char_grid_fill(CharGrid */*notnull*/ char_grid, uint32_t value); +void sp_char_grid_fill(CharGrid */*notnull*/ instance, uint32_t value); /** *Deallocates a [CharGrid] instance. @@ -1071,27 +1053,26 @@ void sp_char_grid_fill(CharGrid */*notnull*/ char_grid, uint32_t value); void sp_char_grid_free(CharGrid */*notnull*/ instance); /** + * Calls [`servicepoint::CharGrid::get`]. + * * Returns the current value at the specified position. * * # Arguments * - * - `char_grid`: instance to read from * - `x` and `y`: position of the cell to read * * # Panics * * - when accessing `x` or `y` out of bounds */ -uint32_t sp_char_grid_get(CharGrid */*notnull*/ char_grid, size_t x, size_t y); +uint32_t sp_char_grid_get(CharGrid */*notnull*/ instance, size_t x, size_t y); /** - * Gets the height of the [CharGrid] instance. + * Calls [`servicepoint::CharGrid::height`]. * - * # Arguments - * - * - `char_grid`: instance to read from + * Gets the height of the grid. */ -size_t sp_char_grid_height(CharGrid */*notnull*/ char_grid); +size_t sp_char_grid_height(CharGrid */*notnull*/ instance); /** * Creates a [CharGridCommand] and immediately turns that into a [Packet]. @@ -1128,11 +1109,12 @@ CharGrid *sp_char_grid_load(size_t width, size_t height, struct ByteSlice data); CharGrid */*notnull*/ sp_char_grid_new(size_t width, size_t height); /** - * Sets the value of the specified position in the [CharGrid]. + * Calls [`servicepoint::CharGrid::set`]. + * + * Sets the value of the specified position in the grid. * * # Arguments * - * - `char_grid`: instance to write to * - `x` and `y`: position of the cell * - `value`: the value to write to the cell * @@ -1141,20 +1123,19 @@ CharGrid */*notnull*/ sp_char_grid_new(size_t width, size_t height); * # Panics * * - when accessing `x` or `y` out of bounds + * - when providing values that cannot be converted to Rust's `char`. */ -void sp_char_grid_set(CharGrid */*notnull*/ char_grid, +void sp_char_grid_set(CharGrid */*notnull*/ instance, size_t x, size_t y, uint32_t value); /** - * Gets the width of the [CharGrid] instance. + * Calls [`servicepoint::CharGrid::width`]. * - * # Arguments - * - * - `char_grid`: instance to read from + * Gets the width of the grid. */ -size_t sp_char_grid_width(CharGrid */*notnull*/ char_grid); +size_t sp_char_grid_width(CharGrid */*notnull*/ instance); /** *Clones a [BitmapCommand] instance. @@ -1608,49 +1589,50 @@ void sp_cmd_hard_reset_free(struct HardResetCommand */*notnull*/ instance); struct HardResetCommand */*notnull*/ sp_cmd_hard_reset_new(void); /** - *Clones a [Cp437Grid] instance. + * Calls [`servicepoint::Cp437Grid::data_ref_mut`]. + * + * Gets an unsafe reference to the data of the grid. + * + * The returned memory is valid for the lifetime of the instance. */ -Cp437Grid */*notnull*/ sp_cp437_grid_clone(Cp437Grid */*notnull*/ instance); +struct ByteSlice sp_cp437_data_ref_mut(Cp437Grid */*notnull*/ instance); /** - * Sets the value of all cells in the [Cp437Grid]. + * Calls [`servicepoint::Cp437Grid::fill`]. + * + * Sets the value of all cells in the grid. * * # Arguments * * - `cp437_grid`: instance to write to * - `value`: the value to set all cells to */ -void sp_cp437_grid_fill(Cp437Grid */*notnull*/ cp437_grid, uint8_t value); - -/** - *Deallocates a [Cp437Grid] instance. - */ -void sp_cp437_grid_free(Cp437Grid */*notnull*/ instance); +void sp_cp437_fill(Cp437Grid */*notnull*/ instance, uint8_t value); /** + * Calls [`servicepoint::Cp437Grid::get`]. + * * 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 accessing `x` or `y` out of bounds */ -uint8_t sp_cp437_grid_get(Cp437Grid */*notnull*/ cp437_grid, - size_t x, - size_t y); +uint8_t sp_cp437_get(Cp437Grid */*notnull*/ instance, size_t x, size_t y); /** - * Gets the height of the [Cp437Grid] instance. - * - * # Arguments - * - * - `cp437_grid`: instance to read from + *Clones a [Cp437Grid] instance. */ -size_t sp_cp437_grid_height(Cp437Grid */*notnull*/ cp437_grid); +Cp437Grid */*notnull*/ sp_cp437_grid_clone(Cp437Grid */*notnull*/ instance); + +/** + *Deallocates a [Cp437Grid] instance. + */ +void sp_cp437_grid_free(Cp437Grid */*notnull*/ instance); /** * Creates a [Cp437GridCommand] and immediately turns that into a [Packet]. @@ -1678,11 +1660,19 @@ Cp437Grid *sp_cp437_grid_load(size_t width, Cp437Grid */*notnull*/ sp_cp437_grid_new(size_t width, size_t height); /** - * Sets the value of the specified position in the [Cp437Grid]. + * Calls [`servicepoint::Cp437Grid::height`]. + * + * Gets the height of the grid. + */ +size_t sp_cp437_height(Cp437Grid */*notnull*/ instance); + +/** + * Calls [`servicepoint::Cp437Grid::set`]. + * + * Sets the value at the specified position. * * # Arguments * - * - `cp437_grid`: instance to write to * - `x` and `y`: position of the cell * - `value`: the value to write to the cell * @@ -1692,26 +1682,17 @@ Cp437Grid */*notnull*/ sp_cp437_grid_new(size_t width, size_t height); * * - when accessing `x` or `y` out of bounds */ -void sp_cp437_grid_set(Cp437Grid */*notnull*/ cp437_grid, - size_t x, - size_t y, - uint8_t value); +void sp_cp437_set(Cp437Grid */*notnull*/ instance, + size_t x, + size_t y, + uint8_t value); /** - * Gets an unsafe reference to the data of the [Cp437Grid] instance. + * Calls [`servicepoint::Cp437Grid::width`]. * - * The returned memory is valid for the lifetime of the grid. + * Gets the width of the grid. */ -struct ByteSlice sp_cp437_grid_unsafe_data_ref(Cp437Grid */*notnull*/ cp437_grid); - -/** - * Gets the width of the [Cp437Grid] instance. - * - * # Arguments - * - * - `cp437_grid`: instance to read from - */ -size_t sp_cp437_grid_width(Cp437Grid */*notnull*/ cp437_grid); +size_t sp_cp437_width(Cp437Grid */*notnull*/ instance); /** *Clones a [Packet] instance. diff --git a/src/containers/bitmap.rs b/src/containers/bitmap.rs index 63cac85..ae97597 100644 --- a/src/containers/bitmap.rs +++ b/src/containers/bitmap.rs @@ -1,6 +1,6 @@ use crate::{ containers::ByteSlice, - macros::{wrap_clone, wrap_free}, + macros::{wrap_clone, wrap_free, wrap_method}, mem::{heap_move_nonnull, heap_move_ok, heap_move_some, heap_remove}, }; use servicepoint::{ @@ -83,98 +83,67 @@ pub unsafe extern "C" fn sp_bitmap_from_bitvec( wrap_clone!(Bitmap, sp_bitmap); wrap_free!(Bitmap, sp_bitmap); -/// Gets the current value at the specified position in the [Bitmap]. -/// -/// # Arguments -/// -/// - `bitmap`: instance to read from -/// - `x` and `y`: position of the cell to read -/// -/// # Panics -/// -/// - when accessing `x` or `y` out of bounds -#[no_mangle] -pub unsafe extern "C" fn sp_bitmap_get( - bitmap: NonNull, - x: usize, - y: usize, -) -> bool { - unsafe { bitmap.as_ref().get(x, y) } -} +wrap_method!( + sp_bitmap :: Bitmap; + /// Gets the current value at the specified position. + /// + /// # Arguments + /// + /// - `x` and `y`: position of the cell to read + /// + /// # Panics + /// + /// - when accessing `x` or `y` out of bounds + ref fn get(x: usize, y: usize) -> bool; +); -/// Sets the value of the specified position in the [Bitmap]. -/// -/// # Arguments -/// -/// - `bitmap`: instance to write to -/// - `x` and `y`: position of the cell -/// - `value`: the value to write to the cell -/// -/// # Panics -/// -/// - when accessing `x` or `y` out of bounds -#[no_mangle] -pub unsafe extern "C" fn sp_bitmap_set( - bitmap: NonNull, - x: usize, - y: usize, - value: bool, -) { - unsafe { (*bitmap.as_ptr()).set(x, y, value) }; -} +wrap_method!( + sp_bitmap :: Bitmap; + /// Sets the value of the specified position. + /// + /// # Arguments + /// + /// - `x` and `y`: position of the cell + /// - `value`: the value to write to the cell + /// + /// # Panics + /// + /// - when accessing `x` or `y` out of bounds + mut fn set(x: usize, y: usize, value: bool); +); -/// Sets the state of all pixels in the [Bitmap]. -/// -/// # Arguments -/// -/// - `bitmap`: instance to write to -/// - `value`: the value to set all pixels to -#[no_mangle] -pub unsafe extern "C" fn sp_bitmap_fill(bitmap: NonNull, value: bool) { - unsafe { (*bitmap.as_ptr()).fill(value) }; -} +wrap_method!( + sp_bitmap :: Bitmap; + /// Sets the state of all pixels in the [Bitmap]. + /// + /// # Arguments + /// + /// - `value`: the value to set all pixels to + mut fn fill(value: bool); +); -/// Gets the width in pixels of the [Bitmap] instance. -/// -/// # Arguments -/// -/// - `bitmap`: instance to read from -/// -/// # Panics -/// -/// - when `bitmap` is NULL -/// -/// # Safety -/// -/// The caller has to make sure that: -/// -/// - `bitmap` points to a valid [Bitmap] -#[no_mangle] -pub unsafe extern "C" fn sp_bitmap_width(bitmap: NonNull) -> usize { - unsafe { bitmap.as_ref().width() } -} +wrap_method!( + sp_bitmap :: Bitmap; + /// Gets the width in pixels. + ref fn width() -> usize; +); -/// Gets the height in pixels of the [Bitmap] instance. -/// -/// # Arguments -/// -/// - `bitmap`: instance to read from -#[no_mangle] -pub unsafe extern "C" fn sp_bitmap_height(bitmap: NonNull) -> usize { - unsafe { bitmap.as_ref().height() } -} +wrap_method!( + sp_bitmap :: Bitmap; + /// Gets the height in pixels. + ref fn height() -> usize; +); -/// Gets an unsafe reference to the data of the [Bitmap] instance. -/// -/// The returned memory is valid for the lifetime of the bitmap. -#[no_mangle] -pub unsafe extern "C" fn sp_bitmap_unsafe_data_ref( - mut bitmap: NonNull, -) -> ByteSlice { - unsafe { ByteSlice::from_slice(bitmap.as_mut().data_ref_mut()) } -} +wrap_method!( + sp_bitmap :: Bitmap; + /// Gets an unsafe reference to the data of the [Bitmap] instance. + /// + /// The returned memory is valid for the lifetime of the bitmap. + mut fn data_ref_mut() -> ByteSlice; + |slice| unsafe { ByteSlice::from_slice(slice) }; +); -/// Consumes the Bitmap and returns the contained BitVec +/// Consumes the Bitmap and returns the contained BitVec. #[no_mangle] pub unsafe extern "C" fn sp_bitmap_into_bitvec( bitmap: NonNull, diff --git a/src/containers/bitvec.rs b/src/containers/bitvec.rs index 5f2d7b0..ea0ca4b 100644 --- a/src/containers/bitvec.rs +++ b/src/containers/bitvec.rs @@ -1,6 +1,6 @@ use crate::{ containers::ByteSlice, - macros::{wrap_clone, wrap_free}, + macros::{wrap_clone, wrap_free, wrap_method}, mem::{heap_move_nonnull, heap_move_ok, heap_remove}, }; use servicepoint::{ @@ -38,97 +38,69 @@ pub unsafe extern "C" fn sp_bitvec_load( wrap_clone!(DisplayBitVec, sp_bitvec); wrap_free!(DisplayBitVec, sp_bitvec); -/// Gets the value of a bit from the [DisplayBitVec]. -/// -/// # Arguments -/// -/// - `bit_vec`: instance to read from -/// - `index`: the bit index to read -/// -/// returns: value of the bit -/// -/// # Panics -/// -/// - when accessing `index` out of bounds -#[no_mangle] -pub unsafe extern "C" fn sp_bitvec_get( - bit_vec: NonNull, - index: usize, -) -> bool { - unsafe { *bit_vec.as_ref().get(index).unwrap() } -} +wrap_method!( + sp_bitvec :: DisplayBitVec; + /// Gets the value of a bit. + /// + /// # Arguments + /// + /// - `bit_vec`: instance to read from + /// - `index`: the bit index to read + /// + /// returns: value of the bit + /// + /// # Panics + /// + /// - when accessing `index` out of bounds + ref fn get(index: usize) -> bool; + |result| result.map(|x| *x).unwrap_or(false); +); -/// Sets the value of a bit in the [DisplayBitVec]. -/// -/// # Arguments -/// -/// - `bit_vec`: instance to write to -/// - `index`: the bit index to edit -/// - `value`: the value to set the bit to -/// -/// # Panics -/// -/// - when accessing `index` out of bounds -#[no_mangle] -pub unsafe extern "C" fn sp_bitvec_set( - bit_vec: NonNull, - index: usize, - value: bool, -) { - unsafe { (*bit_vec.as_ptr()).set(index, value) } -} +wrap_method!( + sp_bitvec :: DisplayBitVec; + /// Sets the value of a bit. + /// + /// # Arguments + /// + /// - `index`: the bit index to edit + /// - `value`: the value to set the bit to + /// + /// # Panics + /// + /// - when accessing `index` out of bounds + mut fn set(index: usize, value: bool); +); -/// Sets the value of all bits in the [DisplayBitVec]. -/// -/// # Arguments -/// -/// - `bit_vec`: instance to write to -/// - `value`: the value to set all bits to -#[no_mangle] -pub unsafe extern "C" fn sp_bitvec_fill( - bit_vec: NonNull, - value: bool, -) { - unsafe { (*bit_vec.as_ptr()).fill(value) } -} +wrap_method!( + sp_bitvec :: DisplayBitVec; + /// Sets the value of all bits. + /// + /// # Arguments + /// + /// - `value`: the value to set all bits to + mut fn fill(value: bool); +); -/// Gets the length of the [DisplayBitVec] in bits. -/// -/// # Arguments -/// -/// - `bit_vec`: instance to write to -#[no_mangle] -pub unsafe extern "C" fn sp_bitvec_len( - bit_vec: NonNull, -) -> usize { - unsafe { bit_vec.as_ref().len() } -} +wrap_method!( + sp_bitvec :: DisplayBitVec; + /// Gets the length in bits. + ref fn len() -> usize; +); -/// Returns true if length is 0. -/// -/// # Arguments -/// -/// - `bit_vec`: instance to write to -#[no_mangle] -pub unsafe extern "C" fn sp_bitvec_is_empty( - bit_vec: NonNull, -) -> bool { - unsafe { bit_vec.as_ref().is_empty() } -} +wrap_method!( + sp_bitvec :: DisplayBitVec; + /// Returns true if length is 0. + ref fn is_empty() -> bool; +); -/// Gets an unsafe reference to the data of the [DisplayBitVec] instance. -/// -/// The returned memory is valid for the lifetime of the bitvec. -/// -/// # Arguments -/// -/// - `bit_vec`: instance to write to -#[no_mangle] -pub unsafe extern "C" fn sp_bitvec_unsafe_data_ref( - bit_vec: NonNull, -) -> ByteSlice { - unsafe { ByteSlice::from_slice((*bit_vec.as_ptr()).as_raw_mut_slice()) } -} +wrap_method!( + sp_bitvec :: DisplayBitVec; + /// Gets an unsafe reference to the data of the [DisplayBitVec] instance. + /// + /// The returned memory is valid for the lifetime of the bitvec. + mut fn as_raw_mut_slice() -> ByteSlice; + |slice| unsafe { ByteSlice::from_slice(slice) }; +); /// Creates a [BitVecCommand] and immediately turns that into a [Packet]. /// diff --git a/src/containers/brightness_grid.rs b/src/containers/brightness_grid.rs index 21c3636..a1a5e4e 100644 --- a/src/containers/brightness_grid.rs +++ b/src/containers/brightness_grid.rs @@ -1,6 +1,6 @@ use crate::{ containers::ByteSlice, - macros::{wrap_clone, wrap_free}, + macros::{wrap_clone, wrap_free, wrap_method}, mem::{heap_move_nonnull, heap_move_ok, heap_move_some, heap_remove}, }; use servicepoint::{ @@ -55,112 +55,73 @@ pub unsafe extern "C" fn sp_brightness_grid_load( wrap_clone!(BrightnessGrid, sp_brightness_grid); wrap_free!(BrightnessGrid, sp_brightness_grid); -/// Gets the current value at the specified position. -/// -/// # Arguments -/// -/// - `brightness_grid`: instance to read from -/// - `x` and `y`: position of the cell to read -/// -/// returns: value at position -/// -/// # Panics -/// - When accessing `x` or `y` out of bounds. -#[no_mangle] -pub unsafe extern "C" fn sp_brightness_grid_get( - brightness_grid: NonNull, - x: usize, - y: usize, -) -> Brightness { - unsafe { brightness_grid.as_ref().get(x, y) } -} +wrap_method!( + sp_brightness_grid :: BrightnessGrid; + /// Gets the current value at the specified position. + /// + /// # Arguments + /// + /// - `x` and `y`: position of the cell to read + /// + /// returns: value at position + /// + /// # Panics + /// - When accessing `x` or `y` out of bounds. + ref fn get(x: usize, y: usize) -> Brightness; +); -/// Sets the value of the specified position in the [BrightnessGrid]. -/// -/// # Arguments -/// -/// - `brightness_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 accessing `x` or `y` out of bounds. -#[no_mangle] -pub unsafe extern "C" fn sp_brightness_grid_set( - brightness_grid: NonNull, - x: usize, - y: usize, - value: Brightness, -) { - unsafe { (*brightness_grid.as_ptr()).set(x, y, value) }; -} +wrap_method!( + sp_brightness_grid :: BrightnessGrid; + /// Sets the value of the specified position. + /// + /// # Arguments + /// + /// - `x` and `y`: position of the cell + /// - `value`: the value to write to the cell + /// + /// returns: old value of the cell + /// + /// # Panics + /// + /// - When accessing `x` or `y` out of bounds. + mut fn set(x: usize, y: usize, value: Brightness); +); -/// Sets the value of all cells in the [BrightnessGrid]. -/// -/// # Arguments -/// -/// - `brightness_grid`: instance to write to -/// - `value`: the value to set all cells to -#[no_mangle] -pub unsafe extern "C" fn sp_brightness_grid_fill( - brightness_grid: NonNull, - value: Brightness, -) { - unsafe { (*brightness_grid.as_ptr()).fill(value) }; -} +wrap_method!( + sp_brightness_grid :: BrightnessGrid; + /// Sets the value of all cells. + /// + /// # Arguments + /// + /// - `value`: the value to set all cells to + mut fn fill(value: Brightness); +); -/// Gets the width of the [BrightnessGrid] instance. -/// -/// # Arguments -/// -/// - `brightness_grid`: instance to read from -/// -/// returns: width -#[no_mangle] -pub unsafe extern "C" fn sp_brightness_grid_width( - brightness_grid: NonNull, -) -> usize { - unsafe { brightness_grid.as_ref().width() } -} +wrap_method!( + sp_brightness_grid :: BrightnessGrid; + /// Gets the width of the grid. + ref fn width() -> usize; +); -/// Gets the height of the [BrightnessGrid] instance. -/// -/// # Arguments -/// -/// - `brightness_grid`: instance to read from -/// -/// returns: height -#[no_mangle] -pub unsafe extern "C" fn sp_brightness_grid_height( - brightness_grid: NonNull, -) -> usize { - unsafe { brightness_grid.as_ref().height() } -} +wrap_method!( + sp_brightness_grid :: BrightnessGrid; + /// Gets the height of the grid. + ref fn height() -> usize; +); -/// Gets an unsafe reference to the data of the [BrightnessGrid] instance. -/// -/// The returned memory is valid for the lifetime of the brightness grid. -/// -/// # Arguments -/// -/// - `brightness_grid`: instance to read from -/// -/// returns: slice of bytes underlying the `brightness_grid`. -#[no_mangle] -pub unsafe extern "C" fn sp_brightness_grid_unsafe_data_ref( - brightness_grid: NonNull, -) -> ByteSlice { - //noinspection RsAssertEqual - const _: () = assert!(size_of::() == 1); +wrap_method!( + sp_brightness_grid :: BrightnessGrid; + /// Gets an unsafe reference to the data of the instance. + /// + /// The returned memory is valid for the lifetime of the grid. + mut fn data_ref_mut() -> ByteSlice; + |br_slice| unsafe { + //noinspection RsAssertEqual + const _: () = assert!(size_of::() == 1); - let data = unsafe { (*brightness_grid.as_ptr()).data_ref_mut() }; - unsafe { - ByteSlice::from_slice(transmute::<&mut [Brightness], &mut [u8]>(data)) - } -} + ByteSlice::from_slice(transmute::<&mut [Brightness], &mut [u8]>(br_slice)) + }; +); /// Creates a [BrightnessGridCommand] and immediately turns that into a [Packet]. /// diff --git a/src/containers/char_grid.rs b/src/containers/char_grid.rs index 5c788f4..bc421b5 100644 --- a/src/containers/char_grid.rs +++ b/src/containers/char_grid.rs @@ -1,6 +1,6 @@ use crate::{ containers::ByteSlice, - macros::{wrap_clone, wrap_free}, + macros::{wrap_clone, wrap_free, wrap_method}, mem::{heap_move_nonnull, heap_move_ok, heap_remove}, }; use servicepoint::{CharGrid, CharGridCommand, Grid, Origin, Packet}; @@ -42,85 +42,63 @@ pub unsafe extern "C" fn sp_char_grid_load( wrap_clone!(CharGrid, sp_char_grid); wrap_free!(CharGrid, sp_char_grid); -/// Returns the current value at the specified position. -/// -/// # Arguments -/// -/// - `char_grid`: instance to read from -/// - `x` and `y`: position of the cell to read -/// -/// # Panics -/// -/// - when accessing `x` or `y` out of bounds -#[no_mangle] -pub unsafe extern "C" fn sp_char_grid_get( - char_grid: NonNull, - x: usize, - y: usize, -) -> u32 { - unsafe { char_grid.as_ref().get(x, y) as u32 } -} +wrap_method!( + sp_char_grid :: CharGrid; + /// Returns the current value at the specified position. + /// + /// # Arguments + /// + /// - `x` and `y`: position of the cell to read + /// + /// # Panics + /// + /// - when accessing `x` or `y` out of bounds + ref fn get(x: usize, y: usize) -> u32; + | char | char as u32 +); -/// Sets the value of the specified position in the [CharGrid]. -/// -/// # Arguments -/// -/// - `char_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 accessing `x` or `y` out of bounds -#[no_mangle] -pub unsafe extern "C" fn sp_char_grid_set( - char_grid: NonNull, - x: usize, - y: usize, - value: u32, -) { - unsafe { (*char_grid.as_ptr()).set(x, y, char::from_u32(value).unwrap()) }; -} +wrap_method!( + sp_char_grid :: CharGrid; + /// Sets the value of the specified position in the grid. + /// + /// # Arguments + /// + /// - `x` and `y`: position of the cell + /// - `value`: the value to write to the cell + /// + /// returns: old value of the cell + /// + /// # Panics + /// + /// - when accessing `x` or `y` out of bounds + /// - when providing values that cannot be converted to Rust's `char`. + mut fn set(x: usize, y: usize, value: u32); + let value = char::from_u32(value).unwrap(); +); -/// Sets the value of all cells in the [CharGrid]. -/// -/// # Arguments -/// -/// - `char_grid`: instance to write to -/// - `value`: the value to set all cells to -#[no_mangle] -pub unsafe extern "C" fn sp_char_grid_fill( - char_grid: NonNull, - value: u32, -) { - unsafe { (*char_grid.as_ptr()).fill(char::from_u32(value).unwrap()) }; -} +wrap_method!( + sp_char_grid :: CharGrid; + /// Sets the value of all cells in the grid. + /// + /// # Arguments + /// + /// - `value`: the value to set all cells to + /// - when providing values that cannot be converted to Rust's `char`. + mut fn fill(value: u32); + let value = char::from_u32(value).unwrap(); +); -/// Gets the width of the [CharGrid] instance. -/// -/// # Arguments -/// -/// - `char_grid`: instance to read from -#[no_mangle] -pub unsafe extern "C" fn sp_char_grid_width( - char_grid: NonNull, -) -> usize { - unsafe { char_grid.as_ref().width() } -} +wrap_method!( + sp_char_grid :: CharGrid; + /// Gets the width of the grid. + ref fn width() -> usize; +); -/// Gets the height of the [CharGrid] instance. -/// -/// # Arguments -/// -/// - `char_grid`: instance to read from -#[no_mangle] -pub unsafe extern "C" fn sp_char_grid_height( - char_grid: NonNull, -) -> usize { - unsafe { char_grid.as_ref().height() } -} +wrap_method!( + sp_char_grid :: CharGrid; + /// Gets the height of the grid. + ref fn height() -> usize; +); /// Creates a [CharGridCommand] and immediately turns that into a [Packet]. /// diff --git a/src/containers/cp437_grid.rs b/src/containers/cp437_grid.rs index bd58981..88fb2b0 100644 --- a/src/containers/cp437_grid.rs +++ b/src/containers/cp437_grid.rs @@ -1,6 +1,6 @@ use crate::{ containers::ByteSlice, - macros::{wrap_clone, wrap_free}, + macros::{wrap_clone, wrap_free, wrap_method}, mem::{heap_move_nonnull, heap_move_ok, heap_move_some, heap_remove}, }; use servicepoint::{ @@ -33,95 +33,68 @@ pub unsafe extern "C" fn sp_cp437_grid_load( wrap_clone!(Cp437Grid, sp_cp437_grid); wrap_free!(Cp437Grid, sp_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 accessing `x` or `y` out of bounds -#[no_mangle] -pub unsafe extern "C" fn sp_cp437_grid_get( - cp437_grid: NonNull, - x: usize, - y: usize, -) -> u8 { - unsafe { cp437_grid.as_ref().get(x, y) } -} +wrap_method!( + sp_cp437 :: Cp437Grid; + /// Gets the current value at the specified position. + /// + /// # Arguments + /// + /// - `x` and `y`: position of the cell to read + /// + /// # Panics + /// + /// - when accessing `x` or `y` out of bounds + ref fn get(x: usize, y: usize) -> u8; +); -/// Sets the value of the specified position in the [Cp437Grid]. -/// -/// # 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 accessing `x` or `y` out of bounds -#[no_mangle] -pub unsafe extern "C" fn sp_cp437_grid_set( - cp437_grid: NonNull, - x: usize, - y: usize, - value: u8, -) { - unsafe { (*cp437_grid.as_ptr()).set(x, y, value) }; -} +wrap_method!( + sp_cp437 :: Cp437Grid; + /// Sets the value at the specified position. + /// + /// # Arguments + /// + /// - `x` and `y`: position of the cell + /// - `value`: the value to write to the cell + /// + /// returns: old value of the cell + /// + /// # Panics + /// + /// - when accessing `x` or `y` out of bounds + mut fn set(x: usize, y: usize, value: u8); +); -/// Sets the value of all cells in the [Cp437Grid]. -/// -/// # Arguments -/// -/// - `cp437_grid`: instance to write to -/// - `value`: the value to set all cells to -#[no_mangle] -pub unsafe extern "C" fn sp_cp437_grid_fill( - cp437_grid: NonNull, - value: u8, -) { - unsafe { (*cp437_grid.as_ptr()).fill(value) }; -} +wrap_method!( + sp_cp437 :: Cp437Grid; + /// Sets the value of all cells in the grid. + /// + /// # Arguments + /// + /// - `cp437_grid`: instance to write to + /// - `value`: the value to set all cells to + mut fn fill(value: u8); +); -/// Gets the width of the [Cp437Grid] instance. -/// -/// # Arguments -/// -/// - `cp437_grid`: instance to read from -#[no_mangle] -pub unsafe extern "C" fn sp_cp437_grid_width( - cp437_grid: NonNull, -) -> usize { - unsafe { cp437_grid.as_ref().width() } -} +wrap_method!( + sp_cp437 :: Cp437Grid; + /// Gets the width of the grid. + ref fn width() -> usize; +); -/// Gets the height of the [Cp437Grid] instance. -/// -/// # Arguments -/// -/// - `cp437_grid`: instance to read from -#[no_mangle] -pub unsafe extern "C" fn sp_cp437_grid_height( - cp437_grid: NonNull, -) -> usize { - unsafe { cp437_grid.as_ref().height() } -} +wrap_method!( + sp_cp437 :: Cp437Grid; + /// Gets the height of the grid. + ref fn height() -> usize; +); -/// Gets an unsafe reference to the data of the [Cp437Grid] instance. -/// -/// 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, -) -> ByteSlice { - unsafe { ByteSlice::from_slice((*cp437_grid.as_ptr()).data_ref_mut()) } -} +wrap_method!( + sp_cp437 :: Cp437Grid; + /// Gets an unsafe reference to the data of the grid. + /// + /// The returned memory is valid for the lifetime of the instance. + mut fn data_ref_mut() -> ByteSlice; + | slice | unsafe { ByteSlice::from_slice(slice) }; +); /// Creates a [Cp437GridCommand] and immediately turns that into a [Packet]. /// diff --git a/src/macros.rs b/src/macros.rs index 80e19ef..c91248e 100644 --- a/src/macros.rs +++ b/src/macros.rs @@ -1,25 +1,77 @@ macro_rules! wrap_free { - ($typ:ident, $prefix:ident) => { + ($typ:ty, $prefix:ident) => { paste::paste! { #[doc = concat!("Deallocates a [", stringify!($typ), "] instance.")] #[no_mangle] pub unsafe extern "C" fn [<$prefix _free>](instance: NonNull<$typ>) { - unsafe { crate::mem::heap_drop(instance) } + unsafe { $crate::mem::heap_drop(instance) } } } }; } macro_rules! wrap_clone { - ($typ:ident, $prefix:ident) => { + ($typ:ty, $prefix:ident) => { paste::paste! { #[doc = concat!("Clones a [", stringify!($typ), "] instance.")] #[no_mangle] pub unsafe extern "C" fn [<$prefix _clone>](instance: NonNull<$typ>) -> NonNull<$typ> { - unsafe { crate::mem::heap_clone(instance) } + unsafe { $crate::mem::heap_clone(instance) } } } }; } -pub(crate) use {wrap_clone, wrap_free}; +macro_rules! nonnull_as_ref { + ($ident:ident) => { + $ident.as_ref() + }; +} + +macro_rules! nonnull_as_mut { + ($ident:ident) => { + &mut *$ident.as_ptr() + }; +} + +// meta required on purpose, because otherwise the added documentation would suppress warnings +macro_rules! wrap_method { + ( + $prefix:ident :: $object_type:ty; + $(#[$meta:meta])+ + $ref_or_mut:ident fn $function:ident($($param_name:ident: $param_type:ty),*) + $(-> $return_type:ty$(; |$it:ident | $return_expr:expr)?)? + $(; let $param_let_name:ident = $param_let_expr:expr)* + $(;)? + ) => { + paste::paste! { + #[doc = concat!(" Calls [`servicepoint::", stringify!($object_type), + "::", stringify!($function), "`].")] + #[doc = ""] + $(#[$meta])* + #[no_mangle] + pub unsafe extern "C" fn [<$prefix _ $function>]( + instance: NonNull<$object_type>, + $($param_name: $param_type),* + ) $(-> $return_type)? { + let instance = unsafe {$crate::macros:: [< nonnull_as_ $ref_or_mut >] !(instance)}; + $(let $param_let_name = $param_let_expr;)* + #[allow( + unused_variables, + reason = "This variable may not be used depending on macro variables" )] + let result = instance.$function($($param_name),*); + $( + $( + let $it = result; + let result = $return_expr; + )? + return result; + )? + } + } + }; +} + +pub(crate) use { + nonnull_as_mut, nonnull_as_ref, wrap_clone, wrap_free, wrap_method, +};