diff --git a/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h b/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h index 453c6b1..2f9cab7 100644 --- a/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h +++ b/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h @@ -107,7 +107,7 @@ typedef struct SPBrightnessGrid SPBrightnessGrid; * * This struct and associated functions implement the UDP protocol for the display. * - * To send a `SPCommand`, use a `SPConnection`. + * To send a [SPCommand], use a [SPConnection]. * * # Examples * @@ -197,13 +197,19 @@ extern "C" { #endif // __cplusplus /** - * Clones a `SPBitVec`. + * Clones a [SPBitVec]. + * + * returns: new [SPBitVec] instance. Will never return NULL. + * + * # Panics + * + * - when `bit_vec` is NULL * * # Safety * * The caller has to make sure that: * - * - `bit_vec` points to a valid `SPBitVec` + * - `bit_vec` points to a valid [SPBitVec] * - `bit_vec` is not written to concurrently * - the returned instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_bit_vec_free`. @@ -211,37 +217,45 @@ extern "C" { struct SPBitVec *sp_bit_vec_clone(const struct SPBitVec *bit_vec); /** - * Sets the value of all bits in the `SPBitVec`. + * Sets the value of all bits in the [SPBitVec]. * * # Arguments * * - `bit_vec`: instance to write to * - `value`: the value to set all bits to * + * # Panics + * + * - when `bit_vec` is NULL + * * # Safety * * The caller has to make sure that: * - * - `bit_vec` points to a valid `SPBitVec` + * - `bit_vec` points to a valid [SPBitVec] * - `bit_vec` is not written to or read from concurrently */ void sp_bit_vec_fill(struct SPBitVec *bit_vec, bool value); /** - * Deallocates a `SPBitVec`. + * Deallocates a [SPBitVec]. + * + * # Panics + * + * - when `but_vec` is NULL * * # Safety * * The caller has to make sure that: * - * - `bit_vec` points to a valid `SPBitVec` + * - `bit_vec` points to a valid [SPBitVec] * - `bit_vec` is not used concurrently or after this call - * - `bit_vec` was not passed to another consuming function, e.g. to create a `SPCommand` + * - `bit_vec` was not passed to another consuming function, e.g. to create a [SPCommand] */ void sp_bit_vec_free(struct SPBitVec *bit_vec); /** - * Gets the value of a bit from the `SPBitVec`. + * Gets the value of a bit from the [SPBitVec]. * * # Arguments * @@ -252,13 +266,14 @@ void sp_bit_vec_free(struct SPBitVec *bit_vec); * * # Panics * - * When accessing `index` out of bounds. + * - when `bit_vec` is NULL + * - when accessing `index` out of bounds * * # Safety * * The caller has to make sure that: * - * - `bit_vec` points to a valid `SPBitVec` + * - `bit_vec` points to a valid [SPBitVec] * - `bit_vec` is not written to concurrently */ bool sp_bit_vec_get(const struct SPBitVec *bit_vec, size_t index); @@ -270,31 +285,45 @@ bool sp_bit_vec_get(const struct SPBitVec *bit_vec, size_t index); * * - `bit_vec`: instance to write to * + * # Panics + * + * - when `bit_vec` is NULL + * * # Safety * * The caller has to make sure that: * - * - `bit_vec` points to a valid `SPBitVec` + * - `bit_vec` points to a valid [SPBitVec] */ bool sp_bit_vec_is_empty(const struct SPBitVec *bit_vec); /** - * Gets the length of the `SPBitVec` in bits. + * Gets the length of the [SPBitVec] in bits. * * # Arguments * * - `bit_vec`: instance to write to * + * # Panics + * + * - when `bit_vec` is NULL + * * # Safety * * The caller has to make sure that: * - * - `bit_vec` points to a valid `SPBitVec` + * - `bit_vec` points to a valid [SPBitVec] */ size_t sp_bit_vec_len(const struct SPBitVec *bit_vec); /** - * Interpret the data as a series of bits and load then into a new `SPBitVec` instance. + * Interpret the data as a series of bits and load then into a new [SPBitVec] instance. + * + * returns: [SPBitVec] instance containing data. Will never return NULL. + * + * # Panics + * + * - when `data` is NULL * * # Safety * @@ -309,17 +338,17 @@ struct SPBitVec *sp_bit_vec_load(const uint8_t *data, size_t data_length); /** - * Creates a new `SPBitVec` instance. + * Creates a new [SPBitVec] instance. * * # Arguments * * - `size`: size in bits. * - * returns: `SPBitVec` with all bits set to false. Will never return NULL. + * returns: [SPBitVec] with all bits set to false. Will never return NULL. * * # Panics * - * When `size` is not divisible by 8. + * - when `size` is not divisible by 8. * * # Safety * @@ -331,7 +360,7 @@ struct SPBitVec *sp_bit_vec_load(const uint8_t *data, struct SPBitVec *sp_bit_vec_new(size_t size); /** - * Sets the value of a bit in the `SPBitVec`. + * Sets the value of a bit in the [SPBitVec]. * * # Arguments * @@ -339,50 +368,59 @@ struct SPBitVec *sp_bit_vec_new(size_t size); * - `index`: the bit index to edit * - `value`: the value to set the bit to * - * returns: old value of the bit - * * # Panics * - * When accessing `index` out of bounds. + * - when `bit_vec` is NULL + * - when accessing `index` out of bounds * * # Safety * * The caller has to make sure that: * - * - `bit_vec` points to a valid `SPBitVec` + * - `bit_vec` points to a valid [SPBitVec] * - `bit_vec` is not written to or read from concurrently */ void sp_bit_vec_set(struct SPBitVec *bit_vec, size_t index, bool value); /** - * Gets an unsafe reference to the data of the `SPBitVec` instance. + * Gets an unsafe reference to the data of the [SPBitVec] instance. * * # Arguments * * - `bit_vec`: instance to write to * + * # Panics + * + * - when `bit_vec` is NULL + * * ## Safety * * The caller has to make sure that: * - * - `bit_vec` points to a valid `SPBitVec` - * - the returned memory range is never accessed after the passed `SPBitVec` has been freed - * - the returned memory range is never accessed concurrently, either via the `SPBitVec` or directly + * - `bit_vec` points to a valid [SPBitVec] + * - the returned memory range is never accessed after the passed [SPBitVec] has been freed + * - the returned memory range is never accessed concurrently, either via the [SPBitVec] or directly */ struct SPByteSlice sp_bit_vec_unsafe_data_ref(struct SPBitVec *bit_vec); /** - * Clones a `SPBrightnessGrid`. + * Clones a [SPBrightnessGrid]. * * # Arguments * * - `brightness_grid`: instance to read from * + * returns: new [SPBrightnessGrid] instance. Will never return NULL. + * + * # Panics + * + * - when `brightness_grid` is NULL + * * # Safety * * The caller has to make sure that: * - * - `brightness_grid` points to a valid `SPBrightnessGrid` + * - `brightness_grid` points to a valid [SPBrightnessGrid] * - `brightness_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_brightness_grid_free`. @@ -390,7 +428,7 @@ struct SPByteSlice sp_bit_vec_unsafe_data_ref(struct SPBitVec *bit_vec); struct SPBrightnessGrid *sp_brightness_grid_clone(const struct SPBrightnessGrid *brightness_grid); /** - * Sets the value of all cells in the `SPBrightnessGrid`. + * Sets the value of all cells in the [SPBrightnessGrid]. * * # Arguments * @@ -399,32 +437,37 @@ struct SPBrightnessGrid *sp_brightness_grid_clone(const struct SPBrightnessGrid * * # Panics * + * - when `brightness_grid` is NULL * - When providing an invalid brightness value * * # Safety * * The caller has to make sure that: * - * - `brightness_grid` points to a valid `SPBrightnessGrid` + * - `brightness_grid` points to a valid [SPBrightnessGrid] * - `brightness_grid` is not written to or read from concurrently */ void sp_brightness_grid_fill(struct SPBrightnessGrid *brightness_grid, uint8_t value); /** - * Deallocates a `SPBrightnessGrid`. + * Deallocates a [SPBrightnessGrid]. * * # Arguments * * - `brightness_grid`: instance to read from * + * # Panics + * + * - when `brightness_grid` is NULL + * * # Safety * * The caller has to make sure that: * - * - `brightness_grid` points to a valid `SPBrightnessGrid` + * - `brightness_grid` points to a valid [SPBrightnessGrid] * - `brightness_grid` is not used concurrently or after this call - * - `brightness_grid` was not passed to another consuming function, e.g. to create a `SPCommand` + * - `brightness_grid` was not passed to another consuming function, e.g. to create a [SPCommand] */ void sp_brightness_grid_free(struct SPBrightnessGrid *brightness_grid); @@ -436,15 +479,18 @@ void sp_brightness_grid_free(struct SPBrightnessGrid *brightness_grid); * - `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. + * - when `brightness_grid` is NULL + * - When accessing `x` or `y` out of bounds. * * # Safety * * The caller has to make sure that: * - * - `brightness_grid` points to a valid `SPBrightnessGrid` + * - `brightness_grid` points to a valid [SPBrightnessGrid] * - `brightness_grid` is not written to concurrently */ uint8_t sp_brightness_grid_get(const struct SPBrightnessGrid *brightness_grid, @@ -452,26 +498,35 @@ uint8_t sp_brightness_grid_get(const struct SPBrightnessGrid *brightness_grid, size_t y); /** - * Gets the height of the `SPBrightnessGrid` instance. + * Gets the height of the [SPBrightnessGrid] instance. * * # Arguments * * - `brightness_grid`: instance to read from * + * returns: height + * + * # Panics + * + * - when `brightness_grid` is NULL + * * # Safety * * The caller has to make sure that: * - * - `brightness_grid` points to a valid `SPBrightnessGrid` + * - `brightness_grid` points to a valid [SPBrightnessGrid] */ size_t sp_brightness_grid_height(const struct SPBrightnessGrid *brightness_grid); /** - * Loads a `SPBrightnessGrid` with the specified dimensions from the provided data. + * Loads a [SPBrightnessGrid] with the specified dimensions from the provided data. + * + * returns: new [SPBrightnessGrid] instance. Will never return NULL. * * # Panics * - * When the provided `data_length` is not sufficient for the `height` and `width` + * - when `data` is NULL + * - when the provided `data_length` does not match `height` and `width` * * # Safety * @@ -488,9 +543,9 @@ struct SPBrightnessGrid *sp_brightness_grid_load(size_t width, size_t data_length); /** - * Creates a new `SPBrightnessGrid` with the specified dimensions. + * Creates a new [SPBrightnessGrid] with the specified dimensions. * - * returns: `SPBrightnessGrid` initialized to 0. Will never return NULL. + * returns: [SPBrightnessGrid] initialized to 0. Will never return NULL. * * # Safety * @@ -503,7 +558,7 @@ struct SPBrightnessGrid *sp_brightness_grid_new(size_t width, size_t height); /** - * Sets the value of the specified position in the `SPBrightnessGrid`. + * Sets the value of the specified position in the [SPBrightnessGrid]. * * # Arguments * @@ -515,6 +570,7 @@ struct SPBrightnessGrid *sp_brightness_grid_new(size_t width, * * # Panics * + * - when `brightness_grid` is NULL * - When accessing `x` or `y` out of bounds. * - When providing an invalid brightness value * @@ -522,7 +578,7 @@ struct SPBrightnessGrid *sp_brightness_grid_new(size_t width, * * The caller has to make sure that: * - * - `brightness_grid` points to a valid `SPBitVec` + * - `brightness_grid` points to a valid [SPBitVec] * - `brightness_grid` is not written to or read from concurrently */ void sp_brightness_grid_set(struct SPBrightnessGrid *brightness_grid, @@ -531,34 +587,46 @@ void sp_brightness_grid_set(struct SPBrightnessGrid *brightness_grid, uint8_t value); /** - * Gets an unsafe reference to the data of the `SPBrightnessGrid` instance. + * Gets an unsafe reference to the data of the [SPBrightnessGrid] instance. * * # Arguments * * - `brightness_grid`: instance to read from * - * ## Safety + * returns: slice of bytes underlying the `brightness_grid`. * - * The caller has to make sure that: + * # Panics * - * - `brightness_grid` points to a valid `SPBrightnessGrid` - * - the returned memory range is never accessed after the passed `SPBrightnessGrid` has been freed - * - the returned memory range is never accessed concurrently, either via the `SPBrightnessGrid` or directly - */ -struct SPByteSlice sp_brightness_grid_unsafe_data_ref(struct SPBrightnessGrid *brightness_grid); - -/** - * Gets the width of the `SPBrightnessGrid` instance. - * - * # Arguments - * - * - `brightness_grid`: instance to read from + * - when `brightness_grid` is NULL * * # Safety * * The caller has to make sure that: * - * - `brightness_grid` points to a valid `SPBrightnessGrid` + * - `brightness_grid` points to a valid [SPBrightnessGrid] + * - the returned memory range is never accessed after the passed [SPBrightnessGrid] has been freed + * - the returned memory range is never accessed concurrently, either via the [SPBrightnessGrid] or directly + */ +struct SPByteSlice sp_brightness_grid_unsafe_data_ref(struct SPBrightnessGrid *brightness_grid); + +/** + * Gets the width of the [SPBrightnessGrid] instance. + * + * # Arguments + * + * - `brightness_grid`: instance to read from + * + * returns: width + * + * # Panics + * + * - when `brightness_grid` is NULL + * + * # Safety + * + * The caller has to make sure that: + * + * - `brightness_grid` points to a valid [SPBrightnessGrid] */ size_t sp_brightness_grid_width(const struct SPBrightnessGrid *brightness_grid); @@ -568,20 +636,25 @@ size_t sp_brightness_grid_width(const struct SPBrightnessGrid *brightness_grid); * The screen will continuously overwrite more pixel data without regarding the offset, meaning * once the starting row is full, overwriting will continue on column 0. * - * The contained `SPBitVec` is always uncompressed. + * The contained [SPBitVec] is always uncompressed. * - * The passed `SPBitVec` gets consumed. + * The passed [SPBitVec] gets consumed. * - * Returns: a new `Command::BitmapLinear` instance. Will never return NULL. + * Returns: a new [Command::BitmapLinear] instance. Will never return NULL. + * + * # Panics + * + * - when `bit_vec` is null + * - when `compression_code` is not a valid value * * # Safety * * The caller has to make sure that: * - * - `bit_vec` points to a valid instance of `SPBitVec` + * - `bit_vec` points to a valid instance of [SPBitVec] * - `bit_vec` is not used concurrently or after this call * - `compression` matches one of the allowed enum values - * - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + * - the returned [SPCommand] instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_free`. */ struct SPCommand *sp_command_bitmap_linear(size_t offset, @@ -594,20 +667,25 @@ struct SPCommand *sp_command_bitmap_linear(size_t offset, * The screen will continuously overwrite more pixel data without regarding the offset, meaning * once the starting row is full, overwriting will continue on column 0. * - * The contained `SPBitVec` is always uncompressed. + * The contained [SPBitVec] is always uncompressed. * - * The passed `SPBitVec` gets consumed. + * The passed [SPBitVec] gets consumed. * - * Returns: a new `Command::BitmapLinearAnd` instance. Will never return NULL. + * Returns: a new [Command::BitmapLinearAnd] instance. Will never return NULL. + * + * # Panics + * + * - when `bit_vec` is null + * - when `compression_code` is not a valid value * * # Safety * * The caller has to make sure that: * - * - `bit_vec` points to a valid instance of `SPBitVec` + * - `bit_vec` points to a valid instance of [SPBitVec] * - `bit_vec` is not used concurrently or after this call * - `compression` matches one of the allowed enum values - * - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + * - the returned [SPCommand] instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_free`. */ struct SPCommand *sp_command_bitmap_linear_and(size_t offset, @@ -620,20 +698,25 @@ struct SPCommand *sp_command_bitmap_linear_and(size_t offset, * The screen will continuously overwrite more pixel data without regarding the offset, meaning * once the starting row is full, overwriting will continue on column 0. * - * The contained `SPBitVec` is always uncompressed. + * The contained [SPBitVec] is always uncompressed. * - * The passed `SPBitVec` gets consumed. + * The passed [SPBitVec] gets consumed. * - * Returns: a new `Command::BitmapLinearOr` instance. Will never return NULL. + * Returns: a new [Command::BitmapLinearOr] instance. Will never return NULL. + * + * # Panics + * + * - when `bit_vec` is null + * - when `compression_code` is not a valid value * * # Safety * * The caller has to make sure that: * - * - `bit_vec` points to a valid instance of `SPBitVec` + * - `bit_vec` points to a valid instance of [SPBitVec] * - `bit_vec` is not used concurrently or after this call * - `compression` matches one of the allowed enum values - * - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + * - the returned [SPCommand] instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_free`. */ struct SPCommand *sp_command_bitmap_linear_or(size_t offset, @@ -643,18 +726,23 @@ struct SPCommand *sp_command_bitmap_linear_or(size_t offset, /** * Sets a window of pixels to the specified values. * - * The passed `SPPixelGrid` gets consumed. + * The passed [SPPixelGrid] gets consumed. * - * Returns: a new `Command::BitmapLinearWin` instance. Will never return NULL. + * Returns: a new [Command::BitmapLinearWin] instance. Will never return NULL. + * + * # Panics + * + * - when `pixel_grid` is null + * - when `compression_code` is not a valid value * * # Safety * * The caller has to make sure that: * - * - `pixel_grid` points to a valid instance of `SPPixelGrid` + * - `pixel_grid` points to a valid instance of [SPPixelGrid] * - `pixel_grid` is not used concurrently or after this call * - `compression` matches one of the allowed enum values - * - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + * - the returned [SPCommand] instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_free`. */ struct SPCommand *sp_command_bitmap_linear_win(size_t x, @@ -668,20 +756,25 @@ struct SPCommand *sp_command_bitmap_linear_win(size_t x, * The screen will continuously overwrite more pixel data without regarding the offset, meaning * once the starting row is full, overwriting will continue on column 0. * - * The contained `SPBitVec` is always uncompressed. + * The contained [SPBitVec] is always uncompressed. * - * The passed `SPBitVec` gets consumed. + * The passed [SPBitVec] gets consumed. * - * Returns: a new `Command::BitmapLinearXor` instance. Will never return NULL. + * Returns: a new [Command::BitmapLinearXor] instance. Will never return NULL. + * + * # Panics + * + * - when `bit_vec` is null + * - when `compression_code` is not a valid value * * # Safety * * The caller has to make sure that: * - * - `bit_vec` points to a valid instance of `SPBitVec` + * - `bit_vec` points to a valid instance of [SPBitVec] * - `bit_vec` is not used concurrently or after this call * - `compression` matches one of the allowed enum values - * - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + * - the returned [SPCommand] instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_free`. */ struct SPCommand *sp_command_bitmap_linear_xor(size_t offset, @@ -691,7 +784,7 @@ struct SPCommand *sp_command_bitmap_linear_xor(size_t offset, /** * Set the brightness of all tiles to the same value. * - * Returns: a new `Command::Brightness` instance. Will never return NULL. + * Returns: a new [Command::Brightness] instance. Will never return NULL. * * # Panics * @@ -701,7 +794,7 @@ struct SPCommand *sp_command_bitmap_linear_xor(size_t offset, * * The caller has to make sure that: * - * - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + * - the returned [SPCommand] instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_free`. */ struct SPCommand *sp_command_brightness(uint8_t brightness); @@ -709,17 +802,21 @@ struct SPCommand *sp_command_brightness(uint8_t brightness); /** * Set the brightness of individual tiles in a rectangular area of the display. * - * The passed `SPBrightnessGrid` gets consumed. + * The passed [SPBrightnessGrid] gets consumed. * - * Returns: a new `Command::CharBrightness` instance. Will never return NULL. + * Returns: a new [Command::CharBrightness] instance. Will never return NULL. + * + * # Panics + * + * - when `grid` is NULL * * # Safety * * The caller has to make sure that: * - * - `grid` points to a valid instance of `SPBrightnessGrid` + * - `grid` points to a valid instance of [SPBrightnessGrid] * - `grid` is not used concurrently or after this call - * - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + * - the returned [SPCommand] instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_free`. */ struct SPCommand *sp_command_char_brightness(size_t x, @@ -731,7 +828,7 @@ struct SPCommand *sp_command_char_brightness(size_t x, * * Does not affect brightness. * - * Returns: a new `Command::Clear` instance. Will never return NULL. + * Returns: a new [Command::Clear] instance. Will never return NULL. * * # Examples * @@ -743,21 +840,27 @@ struct SPCommand *sp_command_char_brightness(size_t x, * * The caller has to make sure that: * - * - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + * - the returned [SPCommand] instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_free`. */ struct SPCommand *sp_command_clear(void); /** - * Clones a `SPCommand` instance. + * Clones a [SPCommand] instance. + * + * returns: new [SPCommand] instance. Will never return NULL. + * + * # Panics + * + * - when `command` is NULL * * # Safety * * The caller has to make sure that: * - * - `command` points to a valid instance of `SPCommand` + * - `command` points to a valid instance of [SPCommand] * - `command` is not written to concurrently - * - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + * - the returned [SPCommand] instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_free`. */ struct SPCommand *sp_command_clone(const struct SPCommand *command); @@ -765,22 +868,21 @@ struct SPCommand *sp_command_clone(const struct SPCommand *command); /** * Show text on the screen. * - *
- * The library does not currently convert between UTF-8 and CP-437. - * Because Rust expects UTF-8 strings, it might be necessary to only send ASCII for now. - *
+ * The passed [SPCp437Grid] gets consumed. * - * The passed `SPCp437Grid` gets consumed./// + * Returns: a new [Command::Cp437Data] instance. Will never return NULL. * - * Returns: a new `Command::Cp437Data` instance. Will never return NULL. + * # Panics + * + * - when `grid` is null * * # Safety * * The caller has to make sure that: * - * - `grid` points to a valid instance of `SPCp437Grid` + * - `grid` points to a valid instance of [SPCp437Grid] * - `grid` is not used concurrently or after this call - * - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + * - the returned [SPCommand] instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_free`. */ struct SPCommand *sp_command_cp437_data(size_t x, @@ -796,13 +898,13 @@ struct SPCommand *sp_command_cp437_data(size_t x, * * The caller has to make sure that: * - * - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + * - the returned [SPCommand] instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_free`. */ struct SPCommand *sp_command_fade_out(void); /** - * Deallocates a `SPCommand`. + * Deallocates a [SPCommand]. * * # Examples * @@ -811,13 +913,17 @@ struct SPCommand *sp_command_fade_out(void); * sp_command_free(c); * ``` * + * # Panics + * + * - when `command` is NULL + * * # Safety * * The caller has to make sure that: * - * - `command` points to a valid `SPCommand` + * - `command` points to a valid [SPCommand] * - `command` is not used concurrently or after this call - * - `command` was not passed to another consuming function, e.g. to create a `SPPacket` + * - `command` was not passed to another consuming function, e.g. to create a [SPPacket] */ void sp_command_free(struct SPCommand *command); @@ -826,56 +932,64 @@ void sp_command_free(struct SPCommand *command); * * Please do not send this in your normal program flow. * - * Returns: a new `Command::HardReset` instance. Will never return NULL. + * Returns: a new [Command::HardReset] instance. Will never return NULL. * * # Safety * * The caller has to make sure that: * - * - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + * - the returned [SPCommand] instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_free`. */ struct SPCommand *sp_command_hard_reset(void); /** - * Tries to turn a `SPPacket` into a `SPCommand`. + * Tries to turn a [SPPacket] into a [SPCommand]. * * The packet is deallocated in the process. * - * Returns: pointer to new `SPCommand` instance or NULL + * Returns: pointer to new [SPCommand] instance or NULL if parsing failed. + * + * # Panics + * + * - when `packet` is NULL * * # Safety * * The caller has to make sure that: * - * - `SPPacket` points to a valid instance of `SPPacket` - * - `SPPacket` is not used concurrently or after this call + * - [SPPacket] points to a valid instance of [SPPacket] + * - [SPPacket] is not used concurrently or after this call * - the result is checked for NULL - * - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + * - the returned [SPCommand] instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_free`. */ struct SPCommand *sp_command_try_from_packet(struct SPPacket *packet); /** - * Closes and deallocates a `SPConnection`. + * Closes and deallocates a [SPConnection]. + * + * # Panics + * + * - when `connection` is NULL * * # Safety * * The caller has to make sure that: * - * - `connection` points to a valid `SPConnection` + * - `connection` points to a valid [SPConnection] * - `connection` is not used concurrently or after this call */ void sp_connection_free(struct SPConnection *connection); /** - * Creates a new instance of `SPConnection`. + * Creates a new instance of [SPConnection]. * * returns: NULL if connection fails, or connected instance * * # Panics * - * Bad string encoding + * - when `host` is null or an invalid host * * # Safety * @@ -887,51 +1001,65 @@ void sp_connection_free(struct SPConnection *connection); struct SPConnection *sp_connection_open(const char *host); /** - * Sends a `SPCommand` to the display using the `SPConnection`. + * Sends a [SPCommand] to the display using the [SPConnection]. * * The passed `command` gets consumed. * * returns: true in case of success * + * # Panics + * + * - when `connection` is NULL + * - when `command` is NULL + * * # Safety * * The caller has to make sure that: * - * - `connection` points to a valid instance of `SPConnection` - * - `command` points to a valid instance of `SPPacket` + * - `connection` points to a valid instance of [SPConnection] + * - `command` points to a valid instance of [SPPacket] * - `command` is not used concurrently or after this call */ bool sp_connection_send_command(const struct SPConnection *connection, struct SPCommand *command); /** - * Sends a `SPPacket` to the display using the `SPConnection`. + * Sends a [SPPacket] to the display using the [SPConnection]. * * The passed `packet` gets consumed. * * returns: true in case of success * + * # Panics + * + * - when `connection` is NULL + * - when `packet` is NULL + * * # Safety * * The caller has to make sure that: * - * - `connection` points to a valid instance of `SPConnection` - * - `packet` points to a valid instance of `SPPacket` + * - `connection` points to a valid instance of [SPConnection] + * - `packet` points to a valid instance of [SPPacket] * - `packet` is not used concurrently or after this call */ bool sp_connection_send_packet(const struct SPConnection *connection, struct SPPacket *packet); /** - * Clones a `SPCp437Grid`. + * 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` 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`. @@ -939,32 +1067,40 @@ bool sp_connection_send_packet(const struct SPConnection *connection, struct SPCp437Grid *sp_cp437_grid_clone(const struct SPCp437Grid *cp437_grid); /** - * Sets the value of all cells in the `SPCp437Grid`. + * 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` points to a valid [SPCp437Grid] * - `cp437_grid` is not written to or read from concurrently */ void sp_cp437_grid_fill(struct SPCp437Grid *cp437_grid, uint8_t value); /** - * Deallocates a `SPCp437Grid`. + * 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` 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` + * - `cp437_grid` was not passed to another consuming function, e.g. to create a [SPCommand] */ void sp_cp437_grid_free(struct SPCp437Grid *cp437_grid); @@ -978,13 +1114,14 @@ void sp_cp437_grid_free(struct SPCp437Grid *cp437_grid); * * # Panics * - * When accessing `x` or `y` out of bounds. + * - 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` points to a valid [SPCp437Grid] * - `cp437_grid` is not written to concurrently */ uint8_t sp_cp437_grid_get(const struct SPCp437Grid *cp437_grid, @@ -992,28 +1129,33 @@ uint8_t sp_cp437_grid_get(const struct SPCp437Grid *cp437_grid, size_t y); /** - * Gets the height of the `SPCp437Grid` instance. + * 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` + * - `cp437_grid` points to a valid [SPCp437Grid] */ size_t sp_cp437_grid_height(const struct SPCp437Grid *cp437_grid); /** - * Loads a `SPCp437Grid` with the specified dimensions from the provided data. + * Loads a [SPCp437Grid] with the specified dimensions from the provided data. * * Will never return NULL. * * # Panics * - * When the provided `data_length` is not sufficient for the `height` and `width` + * - when `data` is NULL + * - when the provided `data_length` does not match `height` and `width` * * # Safety * @@ -1030,9 +1172,9 @@ struct SPCp437Grid *sp_cp437_grid_load(size_t width, size_t data_length); /** - * Creates a new `SPCp437Grid` with the specified dimensions. + * Creates a new [SPCp437Grid] with the specified dimensions. * - * returns: `SPCp437Grid` initialized to 0. + * returns: [SPCp437Grid] initialized to 0. Will never return NULL. * * # Safety * @@ -1045,7 +1187,7 @@ struct SPCp437Grid *sp_cp437_grid_new(size_t width, size_t height); /** - * Sets the value of the specified position in the `SPCp437Grid`. + * Sets the value of the specified position in the [SPCp437Grid]. * * # Arguments * @@ -1057,13 +1199,14 @@ struct SPCp437Grid *sp_cp437_grid_new(size_t width, * * # Panics * - * When accessing `x` or `y` out of bounds. + * - 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` points to a valid [SPBitVec] * - `cp437_grid` is not written to or read from concurrently */ void sp_cp437_grid_set(struct SPCp437Grid *cp437_grid, @@ -1072,45 +1215,57 @@ void sp_cp437_grid_set(struct SPCp437Grid *cp437_grid, uint8_t value); /** - * Gets an unsafe reference to the data of the `SPCp437Grid` instance. + * 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 + * - `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 */ struct SPByteSlice sp_cp437_grid_unsafe_data_ref(struct SPCp437Grid *cp437_grid); /** - * Gets the width of the `SPCp437Grid` instance. + * 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` + * - `cp437_grid` points to a valid [SPCp437Grid] */ size_t sp_cp437_grid_width(const struct SPCp437Grid *cp437_grid); /** - * Clones a `SPPacket`. + * Clones a [SPPacket]. * * Will never return NULL. * + * # Panics + * + * - when `packet` is NULL + * * # Safety * * The caller has to make sure that: * - * - `packet` points to a valid `SPPacket` + * - `packet` points to a valid [SPPacket] * - `packet` is not written to concurrently * - the returned instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_packet_free`. @@ -1118,61 +1273,77 @@ size_t sp_cp437_grid_width(const struct SPCp437Grid *cp437_grid); struct SPPacket *sp_packet_clone(const struct SPPacket *packet); /** - * Deallocates a `SPPacket`. + * Deallocates a [SPPacket]. + * + * # Panics + * + * - when `sp_packet_free` is NULL * * # Safety * * The caller has to make sure that: * - * - `packet` points to a valid `SPPacket` + * - `packet` points to a valid [SPPacket] * - `packet` is not used concurrently or after this call */ void sp_packet_free(struct SPPacket *packet); /** - * Turns a `SPCommand` into a `SPPacket`. - * The `SPCommand` gets consumed. + * Turns a [SPCommand] into a [SPPacket]. + * The [SPCommand] gets consumed. * * Will never return NULL. * + * # Panics + * + * - when `command` is NULL + * * # Safety * * The caller has to make sure that: * - * - `SPCommand` points to a valid instance of `SPCommand` - * - `SPCommand` is not used concurrently or after this call - * - the returned `SPPacket` instance is freed in some way, either by using a consuming function or + * - [SPCommand] points to a valid instance of [SPCommand] + * - [SPCommand] is not used concurrently or after this call + * - the returned [SPPacket] instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_packet_free`. */ struct SPPacket *sp_packet_from_command(struct SPCommand *command); /** - * Tries to load a `SPPacket` from the passed array with the specified length. + * Tries to load a [SPPacket] from the passed array with the specified length. * * returns: NULL in case of an error, pointer to the allocated packet otherwise * + * # Panics + * + * - when `data` is NULL + * * # Safety * * The caller has to make sure that: * * - `data` points to a valid memory region of at least `length` bytes * - `data` is not written to concurrently - * - the returned `SPPacket` instance is freed in some way, either by using a consuming function or + * - the returned [SPPacket] instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_packet_free`. */ struct SPPacket *sp_packet_try_load(const uint8_t *data, size_t length); /** - * Clones a `SPPixelGrid`. + * Clones a [SPPixelGrid]. * * Will never return NULL. * + * # Panics + * + * - when `pixel_grid` is NULL + * * # Safety * * The caller has to make sure that: * - * - `pixel_grid` points to a valid `SPPixelGrid` + * - `pixel_grid` points to a valid [SPPixelGrid] * - `pixel_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_pixel_grid_free`. @@ -1180,37 +1351,45 @@ struct SPPacket *sp_packet_try_load(const uint8_t *data, struct SPPixelGrid *sp_pixel_grid_clone(const struct SPPixelGrid *pixel_grid); /** - * Sets the state of all pixels in the `SPPixelGrid`. + * Sets the state of all pixels in the [SPPixelGrid]. * * # Arguments * * - `pixel_grid`: instance to write to * - `value`: the value to set all pixels to * + * # Panics + * + * - when `pixel_grid` is NULL + * * # Safety * * The caller has to make sure that: * - * - `pixel_grid` points to a valid `SPPixelGrid` + * - `pixel_grid` points to a valid [SPPixelGrid] * - `pixel_grid` is not written to or read from concurrently */ void sp_pixel_grid_fill(struct SPPixelGrid *pixel_grid, bool value); /** - * Deallocates a `SPPixelGrid`. + * Deallocates a [SPPixelGrid]. + * + * # Panics + * + * - when `pixel_grid` is NULL * * # Safety * * The caller has to make sure that: * - * - `pixel_grid` points to a valid `SPPixelGrid` + * - `pixel_grid` points to a valid [SPPixelGrid] * - `pixel_grid` is not used concurrently or after pixel_grid call - * - `pixel_grid` was not passed to another consuming function, e.g. to create a `SPCommand` + * - `pixel_grid` was not passed to another consuming function, e.g. to create a [SPCommand] */ void sp_pixel_grid_free(struct SPPixelGrid *pixel_grid); /** - * Gets the current value at the specified position in the `SPPixelGrid`. + * Gets the current value at the specified position in the [SPPixelGrid]. * * # Arguments * @@ -1219,13 +1398,14 @@ void sp_pixel_grid_free(struct SPPixelGrid *pixel_grid); * * # Panics * - * When accessing `x` or `y` out of bounds. + * - when `pixel_grid` is NULL + * - when accessing `x` or `y` out of bounds * * # Safety * * The caller has to make sure that: * - * - `pixel_grid` points to a valid `SPPixelGrid` + * - `pixel_grid` points to a valid [SPPixelGrid] * - `pixel_grid` is not written to concurrently */ bool sp_pixel_grid_get(const struct SPPixelGrid *pixel_grid, @@ -1233,32 +1413,37 @@ bool sp_pixel_grid_get(const struct SPPixelGrid *pixel_grid, size_t y); /** - * Gets the height in pixels of the `SPPixelGrid` instance. + * Gets the height in pixels of the [SPPixelGrid] instance. * * # Arguments * * - `pixel_grid`: instance to read from * + * # Panics + * + * - when `pixel_grid` is NULL + * * # Safety * * The caller has to make sure that: * - * - `pixel_grid` points to a valid `SPPixelGrid` + * - `pixel_grid` points to a valid [SPPixelGrid] */ size_t sp_pixel_grid_height(const struct SPPixelGrid *pixel_grid); /** - * Loads a `SPPixelGrid` with the specified dimensions from the provided data. + * Loads a [SPPixelGrid] with the specified dimensions from the provided data. * * # Arguments * * - `width`: size in pixels in x-direction * - `height`: size in pixels in y-direction * - * returns: `SPPixelGrid` that contains a copy of the provided data. Will never return NULL. + * returns: [SPPixelGrid] that contains a copy of the provided data. Will never return NULL. * * # Panics * + * - when `data` is NULL * - when the dimensions and data size do not match exactly. * - when the width is not dividable by 8 * @@ -1276,14 +1461,14 @@ struct SPPixelGrid *sp_pixel_grid_load(size_t width, size_t data_length); /** - * Creates a new `SPPixelGrid` with the specified dimensions. + * Creates a new [SPPixelGrid] with the specified dimensions. * * # Arguments * * - `width`: size in pixels in x-direction * - `height`: size in pixels in y-direction * - * returns: `SPPixelGrid` initialized to all pixels off. Will never return NULL. + * returns: [SPPixelGrid] initialized to all pixels off. Will never return NULL. * * # Panics * @@ -1300,7 +1485,7 @@ struct SPPixelGrid *sp_pixel_grid_new(size_t width, size_t height); /** - * Sets the value of the specified position in the `SPPixelGrid`. + * Sets the value of the specified position in the [SPPixelGrid]. * * # Arguments * @@ -1312,13 +1497,14 @@ struct SPPixelGrid *sp_pixel_grid_new(size_t width, * * # Panics * - * When accessing `x` or `y` out of bounds. + * - when `pixel_grid` is NULL + * - when accessing `x` or `y` out of bounds * * # Safety * * The caller has to make sure that: * - * - `pixel_grid` points to a valid `SPPixelGrid` + * - `pixel_grid` points to a valid [SPPixelGrid] * - `pixel_grid` is not written to or read from concurrently */ void sp_pixel_grid_set(struct SPPixelGrid *pixel_grid, @@ -1327,30 +1513,38 @@ void sp_pixel_grid_set(struct SPPixelGrid *pixel_grid, bool value); /** - * Gets an unsafe reference to the data of the `SPPixelGrid` instance. + * Gets an unsafe reference to the data of the [SPPixelGrid] instance. * - * ## Safety + * # Panics * - * The caller has to make sure that: - * - * - `pixel_grid` points to a valid `SPPixelGrid` - * - the returned memory range is never accessed after the passed `SPPixelGrid` has been freed - * - the returned memory range is never accessed concurrently, either via the `SPPixelGrid` or directly - */ -struct SPByteSlice sp_pixel_grid_unsafe_data_ref(struct SPPixelGrid *pixel_grid); - -/** - * Gets the width in pixels of the `SPPixelGrid` instance. - * - * # Arguments - * - * - `pixel_grid`: instance to read from + * - when `pixel_grid` is NULL * * # Safety * * The caller has to make sure that: * - * - `pixel_grid` points to a valid `SPPixelGrid` + * - `pixel_grid` points to a valid [SPPixelGrid] + * - the returned memory range is never accessed after the passed [SPPixelGrid] has been freed + * - the returned memory range is never accessed concurrently, either via the [SPPixelGrid] or directly + */ +struct SPByteSlice sp_pixel_grid_unsafe_data_ref(struct SPPixelGrid *pixel_grid); + +/** + * Gets the width in pixels of the [SPPixelGrid] instance. + * + * # Arguments + * + * - `pixel_grid`: instance to read from + * + * # Panics + * + * - when `pixel_grid` is NULL + * + * # Safety + * + * The caller has to make sure that: + * + * - `pixel_grid` points to a valid [SPPixelGrid] */ size_t sp_pixel_grid_width(const struct SPPixelGrid *pixel_grid); diff --git a/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs b/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs index d23b2b9..42a5977 100644 --- a/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs +++ b/crates/servicepoint_binding_cs/ServicePoint/BindGen/ServicePoint.g.cs @@ -20,17 +20,17 @@ namespace ServicePoint.BindGen /// - /// Creates a new `SPBitVec` instance. + /// Creates a new [SPBitVec] instance. /// /// # Arguments /// /// - `size`: size in bits. /// - /// returns: `SPBitVec` with all bits set to false. Will never return NULL. + /// returns: [SPBitVec] with all bits set to false. Will never return NULL. /// /// # Panics /// - /// When `size` is not divisible by 8. + /// - when `size` is not divisible by 8. /// /// # Safety /// @@ -43,7 +43,13 @@ namespace ServicePoint.BindGen public static extern BitVec* sp_bit_vec_new(nuint size); /// - /// Interpret the data as a series of bits and load then into a new `SPBitVec` instance. + /// Interpret the data as a series of bits and load then into a new [SPBitVec] instance. + /// + /// returns: [SPBitVec] instance containing data. Will never return NULL. + /// + /// # Panics + /// + /// - when `data` is NULL /// /// # Safety /// @@ -58,13 +64,19 @@ namespace ServicePoint.BindGen public static extern BitVec* sp_bit_vec_load(byte* data, nuint data_length); /// - /// Clones a `SPBitVec`. + /// Clones a [SPBitVec]. + /// + /// returns: new [SPBitVec] instance. Will never return NULL. + /// + /// # Panics + /// + /// - when `bit_vec` is NULL /// /// # Safety /// /// The caller has to make sure that: /// - /// - `bit_vec` points to a valid `SPBitVec` + /// - `bit_vec` points to a valid [SPBitVec] /// - `bit_vec` is not written to concurrently /// - the returned instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_bit_vec_free`. @@ -73,21 +85,25 @@ namespace ServicePoint.BindGen public static extern BitVec* sp_bit_vec_clone(BitVec* bit_vec); /// - /// Deallocates a `SPBitVec`. + /// Deallocates a [SPBitVec]. + /// + /// # Panics + /// + /// - when `but_vec` is NULL /// /// # Safety /// /// The caller has to make sure that: /// - /// - `bit_vec` points to a valid `SPBitVec` + /// - `bit_vec` points to a valid [SPBitVec] /// - `bit_vec` is not used concurrently or after this call - /// - `bit_vec` was not passed to another consuming function, e.g. to create a `SPCommand` + /// - `bit_vec` was not passed to another consuming function, e.g. to create a [SPCommand] /// [DllImport(__DllName, EntryPoint = "sp_bit_vec_free", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_bit_vec_free(BitVec* bit_vec); /// - /// Gets the value of a bit from the `SPBitVec`. + /// Gets the value of a bit from the [SPBitVec]. /// /// # Arguments /// @@ -98,13 +114,14 @@ namespace ServicePoint.BindGen /// /// # Panics /// - /// When accessing `index` out of bounds. + /// - when `bit_vec` is NULL + /// - when accessing `index` out of bounds /// /// # Safety /// /// The caller has to make sure that: /// - /// - `bit_vec` points to a valid `SPBitVec` + /// - `bit_vec` points to a valid [SPBitVec] /// - `bit_vec` is not written to concurrently /// [DllImport(__DllName, EntryPoint = "sp_bit_vec_get", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] @@ -112,7 +129,7 @@ namespace ServicePoint.BindGen public static extern bool sp_bit_vec_get(BitVec* bit_vec, nuint index); /// - /// Sets the value of a bit in the `SPBitVec`. + /// Sets the value of a bit in the [SPBitVec]. /// /// # Arguments /// @@ -120,52 +137,59 @@ namespace ServicePoint.BindGen /// - `index`: the bit index to edit /// - `value`: the value to set the bit to /// - /// returns: old value of the bit - /// /// # Panics /// - /// When accessing `index` out of bounds. + /// - when `bit_vec` is NULL + /// - when accessing `index` out of bounds /// /// # Safety /// /// The caller has to make sure that: /// - /// - `bit_vec` points to a valid `SPBitVec` + /// - `bit_vec` points to a valid [SPBitVec] /// - `bit_vec` is not written to or read from concurrently /// [DllImport(__DllName, EntryPoint = "sp_bit_vec_set", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_bit_vec_set(BitVec* bit_vec, nuint index, [MarshalAs(UnmanagedType.U1)] bool value); /// - /// Sets the value of all bits in the `SPBitVec`. + /// Sets the value of all bits in the [SPBitVec]. /// /// # Arguments /// /// - `bit_vec`: instance to write to /// - `value`: the value to set all bits to /// + /// # Panics + /// + /// - when `bit_vec` is NULL + /// /// # Safety /// /// The caller has to make sure that: /// - /// - `bit_vec` points to a valid `SPBitVec` + /// - `bit_vec` points to a valid [SPBitVec] /// - `bit_vec` is not written to or read from concurrently /// [DllImport(__DllName, EntryPoint = "sp_bit_vec_fill", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_bit_vec_fill(BitVec* bit_vec, [MarshalAs(UnmanagedType.U1)] bool value); /// - /// Gets the length of the `SPBitVec` in bits. + /// Gets the length of the [SPBitVec] in bits. /// /// # Arguments /// /// - `bit_vec`: instance to write to /// + /// # Panics + /// + /// - when `bit_vec` is NULL + /// /// # Safety /// /// The caller has to make sure that: /// - /// - `bit_vec` points to a valid `SPBitVec` + /// - `bit_vec` points to a valid [SPBitVec] /// [DllImport(__DllName, EntryPoint = "sp_bit_vec_len", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern nuint sp_bit_vec_len(BitVec* bit_vec); @@ -177,38 +201,46 @@ namespace ServicePoint.BindGen /// /// - `bit_vec`: instance to write to /// + /// # Panics + /// + /// - when `bit_vec` is NULL + /// /// # Safety /// /// The caller has to make sure that: /// - /// - `bit_vec` points to a valid `SPBitVec` + /// - `bit_vec` points to a valid [SPBitVec] /// [DllImport(__DllName, EntryPoint = "sp_bit_vec_is_empty", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] [return: MarshalAs(UnmanagedType.U1)] public static extern bool sp_bit_vec_is_empty(BitVec* bit_vec); /// - /// Gets an unsafe reference to the data of the `SPBitVec` instance. + /// Gets an unsafe reference to the data of the [SPBitVec] instance. /// /// # Arguments /// /// - `bit_vec`: instance to write to /// + /// # Panics + /// + /// - when `bit_vec` is NULL + /// /// ## Safety /// /// The caller has to make sure that: /// - /// - `bit_vec` points to a valid `SPBitVec` - /// - the returned memory range is never accessed after the passed `SPBitVec` has been freed - /// - the returned memory range is never accessed concurrently, either via the `SPBitVec` or directly + /// - `bit_vec` points to a valid [SPBitVec] + /// - the returned memory range is never accessed after the passed [SPBitVec] has been freed + /// - the returned memory range is never accessed concurrently, either via the [SPBitVec] or directly /// [DllImport(__DllName, EntryPoint = "sp_bit_vec_unsafe_data_ref", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern ByteSlice sp_bit_vec_unsafe_data_ref(BitVec* bit_vec); /// - /// Creates a new `SPBrightnessGrid` with the specified dimensions. + /// Creates a new [SPBrightnessGrid] with the specified dimensions. /// - /// returns: `SPBrightnessGrid` initialized to 0. Will never return NULL. + /// returns: [SPBrightnessGrid] initialized to 0. Will never return NULL. /// /// # Safety /// @@ -221,11 +253,14 @@ namespace ServicePoint.BindGen public static extern BrightnessGrid* sp_brightness_grid_new(nuint width, nuint height); /// - /// Loads a `SPBrightnessGrid` with the specified dimensions from the provided data. + /// Loads a [SPBrightnessGrid] with the specified dimensions from the provided data. + /// + /// returns: new [SPBrightnessGrid] instance. Will never return NULL. /// /// # Panics /// - /// When the provided `data_length` is not sufficient for the `height` and `width` + /// - when `data` is NULL + /// - when the provided `data_length` does not match `height` and `width` /// /// # Safety /// @@ -240,17 +275,23 @@ namespace ServicePoint.BindGen public static extern BrightnessGrid* sp_brightness_grid_load(nuint width, nuint height, byte* data, nuint data_length); /// - /// Clones a `SPBrightnessGrid`. + /// Clones a [SPBrightnessGrid]. /// /// # Arguments /// /// - `brightness_grid`: instance to read from /// + /// returns: new [SPBrightnessGrid] instance. Will never return NULL. + /// + /// # Panics + /// + /// - when `brightness_grid` is NULL + /// /// # Safety /// /// The caller has to make sure that: /// - /// - `brightness_grid` points to a valid `SPBrightnessGrid` + /// - `brightness_grid` points to a valid [SPBrightnessGrid] /// - `brightness_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_brightness_grid_free`. @@ -259,19 +300,23 @@ namespace ServicePoint.BindGen public static extern BrightnessGrid* sp_brightness_grid_clone(BrightnessGrid* brightness_grid); /// - /// Deallocates a `SPBrightnessGrid`. + /// Deallocates a [SPBrightnessGrid]. /// /// # Arguments /// /// - `brightness_grid`: instance to read from /// + /// # Panics + /// + /// - when `brightness_grid` is NULL + /// /// # Safety /// /// The caller has to make sure that: /// - /// - `brightness_grid` points to a valid `SPBrightnessGrid` + /// - `brightness_grid` points to a valid [SPBrightnessGrid] /// - `brightness_grid` is not used concurrently or after this call - /// - `brightness_grid` was not passed to another consuming function, e.g. to create a `SPCommand` + /// - `brightness_grid` was not passed to another consuming function, e.g. to create a [SPCommand] /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_free", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_brightness_grid_free(BrightnessGrid* brightness_grid); @@ -284,22 +329,25 @@ namespace ServicePoint.BindGen /// - `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. + /// - when `brightness_grid` is NULL + /// - When accessing `x` or `y` out of bounds. /// /// # Safety /// /// The caller has to make sure that: /// - /// - `brightness_grid` points to a valid `SPBrightnessGrid` + /// - `brightness_grid` points to a valid [SPBrightnessGrid] /// - `brightness_grid` is not written to concurrently /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_get", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern byte sp_brightness_grid_get(BrightnessGrid* brightness_grid, nuint x, nuint y); /// - /// Sets the value of the specified position in the `SPBrightnessGrid`. + /// Sets the value of the specified position in the [SPBrightnessGrid]. /// /// # Arguments /// @@ -311,6 +359,7 @@ namespace ServicePoint.BindGen /// /// # Panics /// + /// - when `brightness_grid` is NULL /// - When accessing `x` or `y` out of bounds. /// - When providing an invalid brightness value /// @@ -318,14 +367,14 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - `brightness_grid` points to a valid `SPBitVec` + /// - `brightness_grid` points to a valid [SPBitVec] /// - `brightness_grid` is not written to or read from concurrently /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_set", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_brightness_grid_set(BrightnessGrid* brightness_grid, nuint x, nuint y, byte value); /// - /// Sets the value of all cells in the `SPBrightnessGrid`. + /// Sets the value of all cells in the [SPBrightnessGrid]. /// /// # Arguments /// @@ -334,98 +383,127 @@ namespace ServicePoint.BindGen /// /// # Panics /// + /// - when `brightness_grid` is NULL /// - When providing an invalid brightness value /// /// # Safety /// /// The caller has to make sure that: /// - /// - `brightness_grid` points to a valid `SPBrightnessGrid` + /// - `brightness_grid` points to a valid [SPBrightnessGrid] /// - `brightness_grid` is not written to or read from concurrently /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_fill", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_brightness_grid_fill(BrightnessGrid* brightness_grid, byte value); /// - /// Gets the width of the `SPBrightnessGrid` instance. + /// Gets the width of the [SPBrightnessGrid] instance. /// /// # Arguments /// /// - `brightness_grid`: instance to read from /// + /// returns: width + /// + /// # Panics + /// + /// - when `brightness_grid` is NULL + /// /// # Safety /// /// The caller has to make sure that: /// - /// - `brightness_grid` points to a valid `SPBrightnessGrid` + /// - `brightness_grid` points to a valid [SPBrightnessGrid] /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_width", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern nuint sp_brightness_grid_width(BrightnessGrid* brightness_grid); /// - /// Gets the height of the `SPBrightnessGrid` instance. + /// Gets the height of the [SPBrightnessGrid] instance. /// /// # Arguments /// /// - `brightness_grid`: instance to read from /// + /// returns: height + /// + /// # Panics + /// + /// - when `brightness_grid` is NULL + /// /// # Safety /// /// The caller has to make sure that: /// - /// - `brightness_grid` points to a valid `SPBrightnessGrid` + /// - `brightness_grid` points to a valid [SPBrightnessGrid] /// [DllImport(__DllName, EntryPoint = "sp_brightness_grid_height", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern nuint sp_brightness_grid_height(BrightnessGrid* brightness_grid); /// - /// Gets an unsafe reference to the data of the `SPBrightnessGrid` instance. + /// Gets an unsafe reference to the data of the [SPBrightnessGrid] instance. /// /// # Arguments /// /// - `brightness_grid`: instance to read from /// - /// ## Safety + /// returns: slice of bytes underlying the `brightness_grid`. /// - /// The caller has to make sure that: + /// # Panics /// - /// - `brightness_grid` points to a valid `SPBrightnessGrid` - /// - the returned memory range is never accessed after the passed `SPBrightnessGrid` has been freed - /// - the returned memory range is never accessed concurrently, either via the `SPBrightnessGrid` or directly - /// - [DllImport(__DllName, EntryPoint = "sp_brightness_grid_unsafe_data_ref", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] - public static extern ByteSlice sp_brightness_grid_unsafe_data_ref(BrightnessGrid* brightness_grid); - - /// - /// Tries to turn a `SPPacket` into a `SPCommand`. - /// - /// The packet is deallocated in the process. - /// - /// Returns: pointer to new `SPCommand` instance or NULL + /// - when `brightness_grid` is NULL /// /// # Safety /// /// The caller has to make sure that: /// - /// - `SPPacket` points to a valid instance of `SPPacket` - /// - `SPPacket` is not used concurrently or after this call + /// - `brightness_grid` points to a valid [SPBrightnessGrid] + /// - the returned memory range is never accessed after the passed [SPBrightnessGrid] has been freed + /// - the returned memory range is never accessed concurrently, either via the [SPBrightnessGrid] or directly + /// + [DllImport(__DllName, EntryPoint = "sp_brightness_grid_unsafe_data_ref", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] + public static extern ByteSlice sp_brightness_grid_unsafe_data_ref(BrightnessGrid* brightness_grid); + + /// + /// Tries to turn a [SPPacket] into a [SPCommand]. + /// + /// The packet is deallocated in the process. + /// + /// Returns: pointer to new [SPCommand] instance or NULL if parsing failed. + /// + /// # Panics + /// + /// - when `packet` is NULL + /// + /// # Safety + /// + /// The caller has to make sure that: + /// + /// - [SPPacket] points to a valid instance of [SPPacket] + /// - [SPPacket] is not used concurrently or after this call /// - the result is checked for NULL - /// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + /// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_command_free`. /// [DllImport(__DllName, EntryPoint = "sp_command_try_from_packet", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern Command* sp_command_try_from_packet(Packet* packet); /// - /// Clones a `SPCommand` instance. + /// Clones a [SPCommand] instance. + /// + /// returns: new [SPCommand] instance. Will never return NULL. + /// + /// # Panics + /// + /// - when `command` is NULL /// /// # Safety /// /// The caller has to make sure that: /// - /// - `command` points to a valid instance of `SPCommand` + /// - `command` points to a valid instance of [SPCommand] /// - `command` is not written to concurrently - /// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + /// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_command_free`. /// [DllImport(__DllName, EntryPoint = "sp_command_clone", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] @@ -436,7 +514,7 @@ namespace ServicePoint.BindGen /// /// Does not affect brightness. /// - /// Returns: a new `Command::Clear` instance. Will never return NULL. + /// Returns: a new [Command::Clear] instance. Will never return NULL. /// /// # Examples /// @@ -448,7 +526,7 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + /// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_command_free`. /// [DllImport(__DllName, EntryPoint = "sp_command_clear", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] @@ -459,13 +537,13 @@ namespace ServicePoint.BindGen /// /// Please do not send this in your normal program flow. /// - /// Returns: a new `Command::HardReset` instance. Will never return NULL. + /// Returns: a new [Command::HardReset] instance. Will never return NULL. /// /// # Safety /// /// The caller has to make sure that: /// - /// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + /// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_command_free`. /// [DllImport(__DllName, EntryPoint = "sp_command_hard_reset", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] @@ -480,7 +558,7 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + /// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_command_free`. /// [DllImport(__DllName, EntryPoint = "sp_command_fade_out", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] @@ -489,7 +567,7 @@ namespace ServicePoint.BindGen /// /// Set the brightness of all tiles to the same value. /// - /// Returns: a new `Command::Brightness` instance. Will never return NULL. + /// Returns: a new [Command::Brightness] instance. Will never return NULL. /// /// # Panics /// @@ -499,7 +577,7 @@ namespace ServicePoint.BindGen /// /// The caller has to make sure that: /// - /// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + /// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_command_free`. /// [DllImport(__DllName, EntryPoint = "sp_command_brightness", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] @@ -508,17 +586,21 @@ namespace ServicePoint.BindGen /// /// Set the brightness of individual tiles in a rectangular area of the display. /// - /// The passed `SPBrightnessGrid` gets consumed. + /// The passed [SPBrightnessGrid] gets consumed. /// - /// Returns: a new `Command::CharBrightness` instance. Will never return NULL. + /// Returns: a new [Command::CharBrightness] instance. Will never return NULL. + /// + /// # Panics + /// + /// - when `grid` is NULL /// /// # Safety /// /// The caller has to make sure that: /// - /// - `grid` points to a valid instance of `SPBrightnessGrid` + /// - `grid` points to a valid instance of [SPBrightnessGrid] /// - `grid` is not used concurrently or after this call - /// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + /// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_command_free`. /// [DllImport(__DllName, EntryPoint = "sp_command_char_brightness", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] @@ -530,20 +612,25 @@ namespace ServicePoint.BindGen /// The screen will continuously overwrite more pixel data without regarding the offset, meaning /// once the starting row is full, overwriting will continue on column 0. /// - /// The contained `SPBitVec` is always uncompressed. + /// The contained [SPBitVec] is always uncompressed. /// - /// The passed `SPBitVec` gets consumed. + /// The passed [SPBitVec] gets consumed. /// - /// Returns: a new `Command::BitmapLinear` instance. Will never return NULL. + /// Returns: a new [Command::BitmapLinear] instance. Will never return NULL. + /// + /// # Panics + /// + /// - when `bit_vec` is null + /// - when `compression_code` is not a valid value /// /// # Safety /// /// The caller has to make sure that: /// - /// - `bit_vec` points to a valid instance of `SPBitVec` + /// - `bit_vec` points to a valid instance of [SPBitVec] /// - `bit_vec` is not used concurrently or after this call /// - `compression` matches one of the allowed enum values - /// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + /// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_command_free`. /// [DllImport(__DllName, EntryPoint = "sp_command_bitmap_linear", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] @@ -555,20 +642,25 @@ namespace ServicePoint.BindGen /// The screen will continuously overwrite more pixel data without regarding the offset, meaning /// once the starting row is full, overwriting will continue on column 0. /// - /// The contained `SPBitVec` is always uncompressed. + /// The contained [SPBitVec] is always uncompressed. /// - /// The passed `SPBitVec` gets consumed. + /// The passed [SPBitVec] gets consumed. /// - /// Returns: a new `Command::BitmapLinearAnd` instance. Will never return NULL. + /// Returns: a new [Command::BitmapLinearAnd] instance. Will never return NULL. + /// + /// # Panics + /// + /// - when `bit_vec` is null + /// - when `compression_code` is not a valid value /// /// # Safety /// /// The caller has to make sure that: /// - /// - `bit_vec` points to a valid instance of `SPBitVec` + /// - `bit_vec` points to a valid instance of [SPBitVec] /// - `bit_vec` is not used concurrently or after this call /// - `compression` matches one of the allowed enum values - /// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + /// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_command_free`. /// [DllImport(__DllName, EntryPoint = "sp_command_bitmap_linear_and", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] @@ -580,20 +672,25 @@ namespace ServicePoint.BindGen /// The screen will continuously overwrite more pixel data without regarding the offset, meaning /// once the starting row is full, overwriting will continue on column 0. /// - /// The contained `SPBitVec` is always uncompressed. + /// The contained [SPBitVec] is always uncompressed. /// - /// The passed `SPBitVec` gets consumed. + /// The passed [SPBitVec] gets consumed. /// - /// Returns: a new `Command::BitmapLinearOr` instance. Will never return NULL. + /// Returns: a new [Command::BitmapLinearOr] instance. Will never return NULL. + /// + /// # Panics + /// + /// - when `bit_vec` is null + /// - when `compression_code` is not a valid value /// /// # Safety /// /// The caller has to make sure that: /// - /// - `bit_vec` points to a valid instance of `SPBitVec` + /// - `bit_vec` points to a valid instance of [SPBitVec] /// - `bit_vec` is not used concurrently or after this call /// - `compression` matches one of the allowed enum values - /// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + /// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_command_free`. /// [DllImport(__DllName, EntryPoint = "sp_command_bitmap_linear_or", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] @@ -605,20 +702,25 @@ namespace ServicePoint.BindGen /// The screen will continuously overwrite more pixel data without regarding the offset, meaning /// once the starting row is full, overwriting will continue on column 0. /// - /// The contained `SPBitVec` is always uncompressed. + /// The contained [SPBitVec] is always uncompressed. /// - /// The passed `SPBitVec` gets consumed. + /// The passed [SPBitVec] gets consumed. /// - /// Returns: a new `Command::BitmapLinearXor` instance. Will never return NULL. + /// Returns: a new [Command::BitmapLinearXor] instance. Will never return NULL. + /// + /// # Panics + /// + /// - when `bit_vec` is null + /// - when `compression_code` is not a valid value /// /// # Safety /// /// The caller has to make sure that: /// - /// - `bit_vec` points to a valid instance of `SPBitVec` + /// - `bit_vec` points to a valid instance of [SPBitVec] /// - `bit_vec` is not used concurrently or after this call /// - `compression` matches one of the allowed enum values - /// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + /// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_command_free`. /// [DllImport(__DllName, EntryPoint = "sp_command_bitmap_linear_xor", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] @@ -627,22 +729,21 @@ namespace ServicePoint.BindGen /// /// Show text on the screen. /// - /// <div class="warning"> - /// The library does not currently convert between UTF-8 and CP-437. - /// Because Rust expects UTF-8 strings, it might be necessary to only send ASCII for now. - /// </div> + /// The passed [SPCp437Grid] gets consumed. /// - /// The passed `SPCp437Grid` gets consumed./// + /// Returns: a new [Command::Cp437Data] instance. Will never return NULL. /// - /// Returns: a new `Command::Cp437Data` instance. Will never return NULL. + /// # Panics + /// + /// - when `grid` is null /// /// # Safety /// /// The caller has to make sure that: /// - /// - `grid` points to a valid instance of `SPCp437Grid` + /// - `grid` points to a valid instance of [SPCp437Grid] /// - `grid` is not used concurrently or after this call - /// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + /// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_command_free`. /// [DllImport(__DllName, EntryPoint = "sp_command_cp437_data", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] @@ -651,25 +752,30 @@ namespace ServicePoint.BindGen /// /// Sets a window of pixels to the specified values. /// - /// The passed `SPPixelGrid` gets consumed. + /// The passed [SPPixelGrid] gets consumed. /// - /// Returns: a new `Command::BitmapLinearWin` instance. Will never return NULL. + /// Returns: a new [Command::BitmapLinearWin] instance. Will never return NULL. + /// + /// # Panics + /// + /// - when `pixel_grid` is null + /// - when `compression_code` is not a valid value /// /// # Safety /// /// The caller has to make sure that: /// - /// - `pixel_grid` points to a valid instance of `SPPixelGrid` + /// - `pixel_grid` points to a valid instance of [SPPixelGrid] /// - `pixel_grid` is not used concurrently or after this call /// - `compression` matches one of the allowed enum values - /// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or + /// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_command_free`. /// [DllImport(__DllName, EntryPoint = "sp_command_bitmap_linear_win", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern Command* sp_command_bitmap_linear_win(nuint x, nuint y, PixelGrid* pixel_grid, CompressionCode compression_code); /// - /// Deallocates a `SPCommand`. + /// Deallocates a [SPCommand]. /// /// # Examples /// @@ -678,25 +784,29 @@ namespace ServicePoint.BindGen /// sp_command_free(c); /// ``` /// + /// # Panics + /// + /// - when `command` is NULL + /// /// # Safety /// /// The caller has to make sure that: /// - /// - `command` points to a valid `SPCommand` + /// - `command` points to a valid [SPCommand] /// - `command` is not used concurrently or after this call - /// - `command` was not passed to another consuming function, e.g. to create a `SPPacket` + /// - `command` was not passed to another consuming function, e.g. to create a [SPPacket] /// [DllImport(__DllName, EntryPoint = "sp_command_free", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_command_free(Command* command); /// - /// Creates a new instance of `SPConnection`. + /// Creates a new instance of [SPConnection]. /// /// returns: NULL if connection fails, or connected instance /// /// # Panics /// - /// Bad string encoding + /// - when `host` is null or an invalid host /// /// # Safety /// @@ -709,18 +819,23 @@ namespace ServicePoint.BindGen public static extern Connection* sp_connection_open(byte* host); /// - /// Sends a `SPPacket` to the display using the `SPConnection`. + /// Sends a [SPPacket] to the display using the [SPConnection]. /// /// The passed `packet` gets consumed. /// /// returns: true in case of success /// + /// # Panics + /// + /// - when `connection` is NULL + /// - when `packet` is NULL + /// /// # Safety /// /// The caller has to make sure that: /// - /// - `connection` points to a valid instance of `SPConnection` - /// - `packet` points to a valid instance of `SPPacket` + /// - `connection` points to a valid instance of [SPConnection] + /// - `packet` points to a valid instance of [SPPacket] /// - `packet` is not used concurrently or after this call /// [DllImport(__DllName, EntryPoint = "sp_connection_send_packet", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] @@ -728,18 +843,23 @@ namespace ServicePoint.BindGen public static extern bool sp_connection_send_packet(Connection* connection, Packet* packet); /// - /// Sends a `SPCommand` to the display using the `SPConnection`. + /// Sends a [SPCommand] to the display using the [SPConnection]. /// /// The passed `command` gets consumed. /// /// returns: true in case of success /// + /// # Panics + /// + /// - when `connection` is NULL + /// - when `command` is NULL + /// /// # Safety /// /// The caller has to make sure that: /// - /// - `connection` points to a valid instance of `SPConnection` - /// - `command` points to a valid instance of `SPPacket` + /// - `connection` points to a valid instance of [SPConnection] + /// - `command` points to a valid instance of [SPPacket] /// - `command` is not used concurrently or after this call /// [DllImport(__DllName, EntryPoint = "sp_connection_send_command", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] @@ -747,22 +867,26 @@ namespace ServicePoint.BindGen public static extern bool sp_connection_send_command(Connection* connection, Command* command); /// - /// Closes and deallocates a `SPConnection`. + /// Closes and deallocates a [SPConnection]. + /// + /// # Panics + /// + /// - when `connection` is NULL /// /// # Safety /// /// The caller has to make sure that: /// - /// - `connection` points to a valid `SPConnection` + /// - `connection` points to a valid [SPConnection] /// - `connection` is not used concurrently or after this call /// [DllImport(__DllName, EntryPoint = "sp_connection_free", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_connection_free(Connection* connection); /// - /// Creates a new `SPCp437Grid` with the specified dimensions. + /// Creates a new [SPCp437Grid] with the specified dimensions. /// - /// returns: `SPCp437Grid` initialized to 0. + /// returns: [SPCp437Grid] initialized to 0. Will never return NULL. /// /// # Safety /// @@ -775,13 +899,14 @@ namespace ServicePoint.BindGen public static extern Cp437Grid* sp_cp437_grid_new(nuint width, nuint height); /// - /// Loads a `SPCp437Grid` with the specified dimensions from the provided data. + /// Loads a [SPCp437Grid] with the specified dimensions from the provided data. /// /// Will never return NULL. /// /// # Panics /// - /// When the provided `data_length` is not sufficient for the `height` and `width` + /// - when `data` is NULL + /// - when the provided `data_length` does not match `height` and `width` /// /// # Safety /// @@ -796,15 +921,19 @@ namespace ServicePoint.BindGen public static extern Cp437Grid* sp_cp437_grid_load(nuint width, nuint height, byte* data, nuint data_length); /// - /// Clones a `SPCp437Grid`. + /// 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` 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`. @@ -813,15 +942,19 @@ namespace ServicePoint.BindGen public static extern Cp437Grid* sp_cp437_grid_clone(Cp437Grid* cp437_grid); /// - /// Deallocates a `SPCp437Grid`. + /// 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` 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` + /// - `cp437_grid` was not passed to another consuming function, e.g. to create a [SPCommand] /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_free", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_cp437_grid_free(Cp437Grid* cp437_grid); @@ -836,20 +969,21 @@ namespace ServicePoint.BindGen /// /// # Panics /// - /// When accessing `x` or `y` out of bounds. + /// - 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` points to a valid [SPCp437Grid] /// - `cp437_grid` is not written to concurrently /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_get", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern byte sp_cp437_grid_get(Cp437Grid* cp437_grid, nuint x, nuint y); /// - /// Sets the value of the specified position in the `SPCp437Grid`. + /// Sets the value of the specified position in the [SPCp437Grid]. /// /// # Arguments /// @@ -861,129 +995,158 @@ namespace ServicePoint.BindGen /// /// # Panics /// - /// When accessing `x` or `y` out of bounds. + /// - 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` points to a valid [SPBitVec] /// - `cp437_grid` is not written to or read from concurrently /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_set", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_cp437_grid_set(Cp437Grid* cp437_grid, nuint x, nuint y, byte value); /// - /// Sets the value of all cells in the `SPCp437Grid`. + /// 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` points to a valid [SPCp437Grid] /// - `cp437_grid` is not written to or read from concurrently /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_fill", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_cp437_grid_fill(Cp437Grid* cp437_grid, byte value); /// - /// Gets the width of the `SPCp437Grid` instance. + /// 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` + /// - `cp437_grid` points to a valid [SPCp437Grid] /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_width", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern nuint sp_cp437_grid_width(Cp437Grid* cp437_grid); /// - /// Gets the height of the `SPCp437Grid` instance. + /// 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` + /// - `cp437_grid` points to a valid [SPCp437Grid] /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_height", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern nuint sp_cp437_grid_height(Cp437Grid* cp437_grid); /// - /// Gets an unsafe reference to the data of the `SPCp437Grid` instance. + /// 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 + /// - `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 /// [DllImport(__DllName, EntryPoint = "sp_cp437_grid_unsafe_data_ref", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern ByteSlice sp_cp437_grid_unsafe_data_ref(Cp437Grid* cp437_grid); /// - /// Turns a `SPCommand` into a `SPPacket`. - /// The `SPCommand` gets consumed. + /// Turns a [SPCommand] into a [SPPacket]. + /// The [SPCommand] gets consumed. /// /// Will never return NULL. /// + /// # Panics + /// + /// - when `command` is NULL + /// /// # Safety /// /// The caller has to make sure that: /// - /// - `SPCommand` points to a valid instance of `SPCommand` - /// - `SPCommand` is not used concurrently or after this call - /// - the returned `SPPacket` instance is freed in some way, either by using a consuming function or + /// - [SPCommand] points to a valid instance of [SPCommand] + /// - [SPCommand] is not used concurrently or after this call + /// - the returned [SPPacket] instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_packet_free`. /// [DllImport(__DllName, EntryPoint = "sp_packet_from_command", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern Packet* sp_packet_from_command(Command* command); /// - /// Tries to load a `SPPacket` from the passed array with the specified length. + /// Tries to load a [SPPacket] from the passed array with the specified length. /// /// returns: NULL in case of an error, pointer to the allocated packet otherwise /// + /// # Panics + /// + /// - when `data` is NULL + /// /// # Safety /// /// The caller has to make sure that: /// /// - `data` points to a valid memory region of at least `length` bytes /// - `data` is not written to concurrently - /// - the returned `SPPacket` instance is freed in some way, either by using a consuming function or + /// - the returned [SPPacket] instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_packet_free`. /// [DllImport(__DllName, EntryPoint = "sp_packet_try_load", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern Packet* sp_packet_try_load(byte* data, nuint length); /// - /// Clones a `SPPacket`. + /// Clones a [SPPacket]. /// /// Will never return NULL. /// + /// # Panics + /// + /// - when `packet` is NULL + /// /// # Safety /// /// The caller has to make sure that: /// - /// - `packet` points to a valid `SPPacket` + /// - `packet` points to a valid [SPPacket] /// - `packet` is not written to concurrently /// - the returned instance is freed in some way, either by using a consuming function or /// by explicitly calling `sp_packet_free`. @@ -992,27 +1155,31 @@ namespace ServicePoint.BindGen public static extern Packet* sp_packet_clone(Packet* packet); /// - /// Deallocates a `SPPacket`. + /// Deallocates a [SPPacket]. + /// + /// # Panics + /// + /// - when `sp_packet_free` is NULL /// /// # Safety /// /// The caller has to make sure that: /// - /// - `packet` points to a valid `SPPacket` + /// - `packet` points to a valid [SPPacket] /// - `packet` is not used concurrently or after this call /// [DllImport(__DllName, EntryPoint = "sp_packet_free", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_packet_free(Packet* packet); /// - /// Creates a new `SPPixelGrid` with the specified dimensions. + /// Creates a new [SPPixelGrid] with the specified dimensions. /// /// # Arguments /// /// - `width`: size in pixels in x-direction /// - `height`: size in pixels in y-direction /// - /// returns: `SPPixelGrid` initialized to all pixels off. Will never return NULL. + /// returns: [SPPixelGrid] initialized to all pixels off. Will never return NULL. /// /// # Panics /// @@ -1029,17 +1196,18 @@ namespace ServicePoint.BindGen public static extern PixelGrid* sp_pixel_grid_new(nuint width, nuint height); /// - /// Loads a `SPPixelGrid` with the specified dimensions from the provided data. + /// Loads a [SPPixelGrid] with the specified dimensions from the provided data. /// /// # Arguments /// /// - `width`: size in pixels in x-direction /// - `height`: size in pixels in y-direction /// - /// returns: `SPPixelGrid` that contains a copy of the provided data. Will never return NULL. + /// returns: [SPPixelGrid] that contains a copy of the provided data. Will never return NULL. /// /// # Panics /// + /// - when `data` is NULL /// - when the dimensions and data size do not match exactly. /// - when the width is not dividable by 8 /// @@ -1055,15 +1223,19 @@ namespace ServicePoint.BindGen public static extern PixelGrid* sp_pixel_grid_load(nuint width, nuint height, byte* data, nuint data_length); /// - /// Clones a `SPPixelGrid`. + /// Clones a [SPPixelGrid]. /// /// Will never return NULL. /// + /// # Panics + /// + /// - when `pixel_grid` is NULL + /// /// # Safety /// /// The caller has to make sure that: /// - /// - `pixel_grid` points to a valid `SPPixelGrid` + /// - `pixel_grid` points to a valid [SPPixelGrid] /// - `pixel_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_pixel_grid_free`. @@ -1072,21 +1244,25 @@ namespace ServicePoint.BindGen public static extern PixelGrid* sp_pixel_grid_clone(PixelGrid* pixel_grid); /// - /// Deallocates a `SPPixelGrid`. + /// Deallocates a [SPPixelGrid]. + /// + /// # Panics + /// + /// - when `pixel_grid` is NULL /// /// # Safety /// /// The caller has to make sure that: /// - /// - `pixel_grid` points to a valid `SPPixelGrid` + /// - `pixel_grid` points to a valid [SPPixelGrid] /// - `pixel_grid` is not used concurrently or after pixel_grid call - /// - `pixel_grid` was not passed to another consuming function, e.g. to create a `SPCommand` + /// - `pixel_grid` was not passed to another consuming function, e.g. to create a [SPCommand] /// [DllImport(__DllName, EntryPoint = "sp_pixel_grid_free", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_pixel_grid_free(PixelGrid* pixel_grid); /// - /// Gets the current value at the specified position in the `SPPixelGrid`. + /// Gets the current value at the specified position in the [SPPixelGrid]. /// /// # Arguments /// @@ -1095,13 +1271,14 @@ namespace ServicePoint.BindGen /// /// # Panics /// - /// When accessing `x` or `y` out of bounds. + /// - when `pixel_grid` is NULL + /// - when accessing `x` or `y` out of bounds /// /// # Safety /// /// The caller has to make sure that: /// - /// - `pixel_grid` points to a valid `SPPixelGrid` + /// - `pixel_grid` points to a valid [SPPixelGrid] /// - `pixel_grid` is not written to concurrently /// [DllImport(__DllName, EntryPoint = "sp_pixel_grid_get", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] @@ -1109,7 +1286,7 @@ namespace ServicePoint.BindGen public static extern bool sp_pixel_grid_get(PixelGrid* pixel_grid, nuint x, nuint y); /// - /// Sets the value of the specified position in the `SPPixelGrid`. + /// Sets the value of the specified position in the [SPPixelGrid]. /// /// # Arguments /// @@ -1121,78 +1298,95 @@ namespace ServicePoint.BindGen /// /// # Panics /// - /// When accessing `x` or `y` out of bounds. + /// - when `pixel_grid` is NULL + /// - when accessing `x` or `y` out of bounds /// /// # Safety /// /// The caller has to make sure that: /// - /// - `pixel_grid` points to a valid `SPPixelGrid` + /// - `pixel_grid` points to a valid [SPPixelGrid] /// - `pixel_grid` is not written to or read from concurrently /// [DllImport(__DllName, EntryPoint = "sp_pixel_grid_set", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_pixel_grid_set(PixelGrid* pixel_grid, nuint x, nuint y, [MarshalAs(UnmanagedType.U1)] bool value); /// - /// Sets the state of all pixels in the `SPPixelGrid`. + /// Sets the state of all pixels in the [SPPixelGrid]. /// /// # Arguments /// /// - `pixel_grid`: instance to write to /// - `value`: the value to set all pixels to /// + /// # Panics + /// + /// - when `pixel_grid` is NULL + /// /// # Safety /// /// The caller has to make sure that: /// - /// - `pixel_grid` points to a valid `SPPixelGrid` + /// - `pixel_grid` points to a valid [SPPixelGrid] /// - `pixel_grid` is not written to or read from concurrently /// [DllImport(__DllName, EntryPoint = "sp_pixel_grid_fill", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern void sp_pixel_grid_fill(PixelGrid* pixel_grid, [MarshalAs(UnmanagedType.U1)] bool value); /// - /// Gets the width in pixels of the `SPPixelGrid` instance. + /// Gets the width in pixels of the [SPPixelGrid] instance. /// /// # Arguments /// /// - `pixel_grid`: instance to read from /// + /// # Panics + /// + /// - when `pixel_grid` is NULL + /// /// # Safety /// /// The caller has to make sure that: /// - /// - `pixel_grid` points to a valid `SPPixelGrid` + /// - `pixel_grid` points to a valid [SPPixelGrid] /// [DllImport(__DllName, EntryPoint = "sp_pixel_grid_width", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern nuint sp_pixel_grid_width(PixelGrid* pixel_grid); /// - /// Gets the height in pixels of the `SPPixelGrid` instance. + /// Gets the height in pixels of the [SPPixelGrid] instance. /// /// # Arguments /// /// - `pixel_grid`: instance to read from /// + /// # Panics + /// + /// - when `pixel_grid` is NULL + /// /// # Safety /// /// The caller has to make sure that: /// - /// - `pixel_grid` points to a valid `SPPixelGrid` + /// - `pixel_grid` points to a valid [SPPixelGrid] /// [DllImport(__DllName, EntryPoint = "sp_pixel_grid_height", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern nuint sp_pixel_grid_height(PixelGrid* pixel_grid); /// - /// Gets an unsafe reference to the data of the `SPPixelGrid` instance. + /// Gets an unsafe reference to the data of the [SPPixelGrid] instance. /// - /// ## Safety + /// # Panics + /// + /// - when `pixel_grid` is NULL + /// + /// # Safety /// /// The caller has to make sure that: /// - /// - `pixel_grid` points to a valid `SPPixelGrid` - /// - the returned memory range is never accessed after the passed `SPPixelGrid` has been freed - /// - the returned memory range is never accessed concurrently, either via the `SPPixelGrid` or directly + /// - `pixel_grid` points to a valid [SPPixelGrid] + /// - the returned memory range is never accessed after the passed [SPPixelGrid] has been freed + /// - the returned memory range is never accessed concurrently, either via the [SPPixelGrid] or directly /// [DllImport(__DllName, EntryPoint = "sp_pixel_grid_unsafe_data_ref", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)] public static extern ByteSlice sp_pixel_grid_unsafe_data_ref(PixelGrid* pixel_grid);