From dea176d0d92c0d49645a8f39e9ee28700ce1bc78 Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Sun, 12 Jan 2025 02:36:43 +0100 Subject: [PATCH] fix warnings, minor docs changes --- crates/servicepoint/src/bitmap.rs | 2 -- crates/servicepoint/src/bitvec.rs | 1 + crates/servicepoint/src/byte_grid.rs | 2 +- crates/servicepoint/src/char_grid.rs | 20 +++++++++++++--- crates/servicepoint/src/command.rs | 2 +- crates/servicepoint/src/lib.rs | 2 +- crates/servicepoint/src/value_grid.rs | 23 +++++++++++-------- .../src/brightness_grid.rs | 4 ++-- 8 files changed, 37 insertions(+), 19 deletions(-) diff --git a/crates/servicepoint/src/bitmap.rs b/crates/servicepoint/src/bitmap.rs index 76170b3..85983e5 100644 --- a/crates/servicepoint/src/bitmap.rs +++ b/crates/servicepoint/src/bitmap.rs @@ -1,5 +1,3 @@ -//! Implementation of [Bitmap] - use crate::data_ref::DataRef; use crate::BitVec; use crate::*; diff --git a/crates/servicepoint/src/bitvec.rs b/crates/servicepoint/src/bitvec.rs index 7006105..d512cf6 100644 --- a/crates/servicepoint/src/bitvec.rs +++ b/crates/servicepoint/src/bitvec.rs @@ -1,3 +1,4 @@ pub use bitvec::prelude::*; + /// An alias for the specific type of [bitvec::prelude::BitVec] used. pub type BitVec = bitvec::prelude::BitVec; diff --git a/crates/servicepoint/src/byte_grid.rs b/crates/servicepoint/src/byte_grid.rs index 6ebf882..b9a077a 100644 --- a/crates/servicepoint/src/byte_grid.rs +++ b/crates/servicepoint/src/byte_grid.rs @@ -1,2 +1,2 @@ -/// A simple grid of bytes - see [primitive_grid::PrimitiveGrid]. +/// A 2d grid of bytes - see [crate::ValueGrid]. pub type ByteGrid = crate::value_grid::ValueGrid; diff --git a/crates/servicepoint/src/char_grid.rs b/crates/servicepoint/src/char_grid.rs index 7d55cf3..717e70b 100644 --- a/crates/servicepoint/src/char_grid.rs +++ b/crates/servicepoint/src/char_grid.rs @@ -1,8 +1,22 @@ -use crate::value_grid::{SetValueSeriesError, TryLoadPrimitiveGridError, ValueGrid}; -use crate::Grid; +use crate::{Grid, SetValueSeriesError, TryLoadValueGridError, ValueGrid}; use std::string::FromUtf8Error; /// A grid containing UTF-8 characters. +/// +/// To send a CharGrid to the display, use [crate::Command::Utf8Data]. +/// +/// Also see [crate::ValueGrid] for the non-specialized operations and examples. +/// +/// # Examples +/// +/// ```rust +/// # use servicepoint::{CharGrid, Command, Connection, Origin}; +/// let grid = CharGrid::from("You can\nload multiline\nstrings directly"); +/// assert_eq!(grid.get_row_str(1), Some("load multiline\0\0".to_string())); +/// +/// # let connection = Connection::Fake; +/// let command = Command::Utf8Data(Origin::ZERO, grid); +/// ``` pub type CharGrid = ValueGrid; impl CharGrid { @@ -64,7 +78,7 @@ pub enum LoadUtf8Error { #[error(transparent)] FromUtf8Error(#[from] FromUtf8Error), #[error(transparent)] - TryLoadError(#[from] TryLoadPrimitiveGridError), + TryLoadError(#[from] TryLoadValueGridError), } impl From<&str> for CharGrid { diff --git a/crates/servicepoint/src/command.rs b/crates/servicepoint/src/command.rs index 0807c80..92ea8a9 100644 --- a/crates/servicepoint/src/command.rs +++ b/crates/servicepoint/src/command.rs @@ -522,7 +522,7 @@ impl Command { String::from_utf8(payload.clone())?.chars().collect(); Ok(Command::Utf8Data( Origin::new(*a as usize, *b as usize), - CharGrid::load(*c as usize, *d as usize, &*payload), + CharGrid::load(*c as usize, *d as usize, &payload), )) } } diff --git a/crates/servicepoint/src/lib.rs b/crates/servicepoint/src/lib.rs index 8cb04d2..74899ad 100644 --- a/crates/servicepoint/src/lib.rs +++ b/crates/servicepoint/src/lib.rs @@ -51,7 +51,7 @@ pub use crate::grid::Grid; pub use crate::origin::{Origin, Pixels, Tiles}; pub use crate::packet::{Header, Packet, Payload}; pub use crate::value_grid::{ - IterGridRows, SetValueSeriesError, TryLoadPrimitiveGridError, Value, ValueGrid, + IterGridRows, SetValueSeriesError, TryLoadValueGridError, Value, ValueGrid, }; mod bitmap; diff --git a/crates/servicepoint/src/value_grid.rs b/crates/servicepoint/src/value_grid.rs index b01067f..e6c92e8 100644 --- a/crates/servicepoint/src/value_grid.rs +++ b/crates/servicepoint/src/value_grid.rs @@ -1,5 +1,3 @@ -//! This module contains the implementation of the [ValueGrid]. - use std::fmt::Debug; use std::slice::{Iter, IterMut}; @@ -9,7 +7,12 @@ use crate::*; pub trait Value: Sized + Default + Copy + Clone + Debug {} impl Value for T {} -/// A 2D grid of bytes +/// A 2D grid of values. +/// +/// The memory layout is the one the display expects in [Command]s. +/// +/// This structure can be used with any type that implements the [Value] trait. +/// You can also use the concrete type aliases provided in this crate, e.g. [CharGrid] and [ByteGrid]. #[derive(Debug, Clone, PartialEq)] pub struct ValueGrid { width: usize, @@ -78,14 +81,14 @@ impl ValueGrid { /// Loads a [ValueGrid] with the specified dimensions from the provided data. /// - /// returns: [ValueGrid] that contains a copy of the provided data or [TryLoadPrimitiveGridError]. + /// returns: [ValueGrid] that contains a copy of the provided data or [TryLoadValueGridError]. pub fn try_load( width: usize, height: usize, data: Vec, - ) -> Result { + ) -> Result { if width * height != data.len() { - return Err(TryLoadPrimitiveGridError::InvalidDimensions); + return Err(TryLoadValueGridError::InvalidDimensions); } Ok(Self { @@ -159,7 +162,7 @@ impl ValueGrid { } } - /// Convert between PrimitiveGrid types. + /// Convert between ValueGrid types. /// /// See also [Iterator::map]. /// @@ -273,14 +276,16 @@ impl ValueGrid { } } +/// Errors that can occur when loading a grid #[derive(Debug, thiserror::Error)] -pub enum TryLoadPrimitiveGridError { +pub enum TryLoadValueGridError { #[error("The provided dimensions do not match with the data size")] + /// The provided dimensions do not match with the data size InvalidDimensions, } impl Grid for ValueGrid { - /// Sets the value of the cell at the specified position in the `PrimitiveGrid. + /// Sets the value of the cell at the specified position in the `ValueGrid. /// /// # Arguments /// diff --git a/crates/servicepoint_binding_c/src/brightness_grid.rs b/crates/servicepoint_binding_c/src/brightness_grid.rs index 93880a1..83af008 100644 --- a/crates/servicepoint_binding_c/src/brightness_grid.rs +++ b/crates/servicepoint_binding_c/src/brightness_grid.rs @@ -8,9 +8,9 @@ use std::convert::Into; use std::intrinsics::transmute; use std::ptr::NonNull; -/// see [Brightness::MIN] +/// see [servicepoint::Brightness::MIN] pub const SP_BRIGHTNESS_MIN: u8 = 0; -/// see [Brightness::MAX] +/// see [servicepoint::Brightness::MAX] pub const SP_BRIGHTNESS_MAX: u8 = 11; /// Count of possible brightness values pub const SP_BRIGHTNESS_LEVELS: u8 = 12;