expose CharGrid to C API

crates/servicepoint/src/bit_vec.rs

@@ -0,0 +1,10 @@
+/// A byte-packed vector of booleans.
+///
+/// The implementation is provided by [bitvec].
+/// This is an alias for the specific type of [bitvec::BitVec] used in this crate.
+pub type BitVec = bitvec::BitVec<u8, bitvec::Msb0>;
+
+pub mod bitvec {
+    //! Re-export of the used library [mod@bitvec].
+    pub use bitvec::prelude::*;
+}

crates/servicepoint/src/bitmap.rs

@@ -5,7 +5,18 @@ use ::bitvec::order::Msb0;
 use ::bitvec::prelude::BitSlice;
 use ::bitvec::slice::IterMut;
 
-/// A grid of pixels stored in packed bytes.
+/// A fixed-size 2D grid of booleans.
+///
+/// The values are stored in packed bytes (8 values per byte) in the same order as used by the display for storing pixels.
+/// This means that no conversion is necessary for sending the data to the display.
+///
+/// # Examples
+///
+/// ```rust
+/// use servicepoint::Bitmap;
+/// let mut bitmap = Bitmap::new(4, 2);
+///
+/// ```
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Bitmap {
     width: usize,
@@ -27,7 +38,11 @@ impl Bitmap {
     ///
     /// - when the width is not dividable by 8
     pub fn new(width: usize, height: usize) -> Self {
-        assert_eq!(width % 8, 0);
+        assert_eq!(
+            width % 8,
+            0,
+            "width must be a multiple of 8, but is {width}"
+        );
         Self {
             width,
             height,
@@ -182,6 +197,26 @@ impl From<Bitmap> for BitVec {
     }
 }
 
+impl From<&ValueGrid<bool>> for Bitmap {
+    fn from(value: &ValueGrid<bool>) -> Self {
+        let mut result = Self::new(value.width(), value.height());
+        for (mut to, from) in result.iter_mut().zip(value.iter()) {
+            *to = *from;
+        }
+        result
+    }
+}
+
+impl From<&Bitmap> for ValueGrid<bool> {
+    fn from(value: &Bitmap) -> Self {
+        let mut result = Self::new(value.width(), value.height());
+        for (to, from) in result.iter_mut().zip(value.iter()) {
+            *to = *from;
+        }
+        result
+    }
+}
+
 pub struct IterRows<'t> {
     bitmap: &'t Bitmap,
     row: usize,
@@ -204,7 +239,7 @@ impl<'t> Iterator for IterRows<'t> {
 
 #[cfg(test)]
 mod tests {
-    use crate::{BitVec, Bitmap, DataRef, Grid};
+    use crate::{BitVec, Bitmap, DataRef, Grid, ValueGrid};
 
     #[test]
     fn fill() {
@@ -304,4 +339,16 @@ mod tests {
         let bitvec: BitVec = grid.into();
         assert_eq!(bitvec.as_raw_slice(), [0x80, 0x00]);
     }
+
+    #[test]
+    fn from_bool_grid() {
+        let original = ValueGrid::load(
+            8,
+            1,
+            &[true, false, true, false, true, false, true, false],
+        );
+        let converted = Bitmap::from(&original);
+        let reconverted = ValueGrid::from(&converted);
+        assert_eq!(original, reconverted);
+    }
 }

crates/servicepoint/src/bitvec.rs

@@ -1,4 +0,0 @@
-pub use bitvec::prelude::*;
-
-/// An alias for the specific type of [bitvec::prelude::BitVec] used.
-pub type BitVec = bitvec::prelude::BitVec<u8, Msb0>;

crates/servicepoint/src/byte_grid.rs

@@ -1,2 +1,4 @@
-/// A 2d grid of bytes - see [crate::ValueGrid].
-pub type ByteGrid = crate::value_grid::ValueGrid<u8>;
+use crate::ValueGrid;
+
+/// A 2d grid of bytes - see [ValueGrid].
+pub type ByteGrid = ValueGrid<u8>;

crates/servicepoint/src/lib.rs

@@ -2,14 +2,17 @@
 //!
 //! Your starting point is a [Connection] to the display.
 //! With a connection, you can send [Command]s.
-//! When received, the display will update the state of the pixels.
+//! When received, the display will update the state of its pixels.
 //!
 //! # Examples
 //!
-//! ```rust
-//! use servicepoint::{Command, CompressionCode, Grid, Bitmap};
+//! ### Clear display
 //!
-//! let connection = servicepoint::Connection::open("127.0.0.1:2342")
+//! ```rust
+//! use servicepoint::{Connection, Command};
+//!
+//! // establish a connection
+//! let connection = Connection::open("127.0.0.1:2342")
 //!     .expect("connection failed");
 //!
 //!  // turn off all pixels on display
@@ -17,6 +20,8 @@
 //!     .expect("send failed");
 //! ```
 //!
+//! ### Set all pixels to on
+//!
 //! ```rust
 //! # use servicepoint::{Command, CompressionCode, Grid, Bitmap};
 //! # let connection = servicepoint::Connection::open("127.0.0.1:2342").expect("connection failed");
@@ -34,9 +39,24 @@
 //!  // send command to display
 //!  connection.send(command).expect("send failed");
 //! ```
+//!
+//! ### Send text
+//!
+//! ```rust
+//! # use servicepoint::{Command, CompressionCode, Grid, Bitmap, CharGrid};
+//! # let connection = servicepoint::Connection::open("127.0.0.1:2342").expect("connection failed");
+//! // create a text grid
+//! let mut grid = CharGrid::from("Hello\nCCCB?");
+//! // modify the grid
+//! grid.set(grid.width() - 1, 1, '!');
+//! // create the command to send the data
+//! let command = Command::Utf8Data(servicepoint::Origin::ZERO, grid);
+//! // send command to display
+//! connection.send(command).expect("send failed");
+//! ```
 
+pub use crate::bit_vec::{bitvec, BitVec};
 pub use crate::bitmap::Bitmap;
-pub use crate::bitvec::BitVec;
 pub use crate::brightness::Brightness;
 pub use crate::brightness_grid::BrightnessGrid;
 pub use crate::byte_grid::ByteGrid;
@@ -55,8 +75,8 @@ pub use crate::value_grid::{
     IterGridRows, SetValueSeriesError, TryLoadValueGridError, Value, ValueGrid,
 };
 
+mod bit_vec;
 mod bitmap;
-mod bitvec;
 mod brightness;
 mod brightness_grid;
 mod byte_grid;