Merge pull request #11 from Cryptjar/impl-unsized

Impl unsized

Author: Cryptjar

Cargo.toml

@@ -35,10 +35,17 @@ default = ["lpm-asm-loop", "ufmt"]
 lpm-asm-loop = []
 # Enables some tweak to ease debugging, should not be use in production
 dev = []
+# Enables unsize utilities, such as wrapper coercing.
+# However, this requires additional nightly Rust features, which might be unstable.
+unsize = []
 
 [dependencies]
 cfg-if = "1.0"
 
+[dependencies.derivative]
+version = "2.2.0"
+features = [ "use_core" ]
+
 [dependencies.ufmt]
 version = "0.1.0"
 optional = true

examples/uno-slices.rs

@@ -0,0 +1,167 @@
+//
+// This file provides a example on how to work with slice in progmem (sort of)
+// on an Arduino Uno.
+//
+
+
+// Define no_std only for AVR
+#![cfg_attr(target_arch = "avr", no_std)]
+#![cfg_attr(target_arch = "avr", no_main)]
+
+
+use avr_progmem::progmem; // The macro
+use avr_progmem::wrapper::ProgMem;
+use cfg_if::cfg_if;
+#[cfg(target_arch = "avr")]
+use panic_halt as _; // halting panic implementation for AVR
+
+// First, there are no slices in progmem. All data must be statically size,
+// such as an array:
+progmem! {
+	// Just one array of size 3
+	static progmem<const ARRAY_A_LEN: usize> ARRAY_A: [u8; ARRAY_A_LEN] = [1,2,3];
+
+	// Another array of size 5
+	static progmem<const ARRAY_B_LEN: usize> ARRAY_B: [u8; ARRAY_B_LEN] = [1,2,3,4,5];
+
+	// Yet another array
+	static progmem<const ARRAY_C_LEN: usize> ARRAY_C: [u8; ARRAY_C_LEN] = [42];
+}
+
+// Include a fancy printer supporting Arduino Uno's USB-Serial output as well
+// as stdout on non-AVR targets.
+mod printer;
+use printer::Printer;
+
+#[cfg_attr(target_arch = "avr", arduino_hal::entry)]
+fn main() -> ! {
+	// Setup the output
+	let mut printer = setup();
+
+	//
+	// Working with slices.
+	//
+	// So, we actually only have statically sized arrays in progmem. However,
+	// sometimes slices are nicer to work with, for instance if you want to put
+	// them into a list or something, e.g. to iterate over them.
+	//
+	// There are basically to way to accomplish this, first just load those
+	// arrays into RAM and coerce the standard Rust arrays into standard Rust
+	// slices as usual. The drawback is the potential high RAM usage.
+	//
+	// In order to have the benefits of slices while the data is still in
+	// progmem, we can also just coerce the ProgMems of arrays into ProgMems of
+	// slices:
+
+	// Once we have slice wrappers, we can store them together e.g. in a array
+	let list_of_slices: [ProgMem<[u8]>; 3] = {
+		cfg_if! {
+			if #[cfg(feature = "unsize")] {
+				// Option 1: just coerce them to a slice wrapper
+				// but this requires the crate feature "unsize"
+
+				[
+					ARRAY_A,
+					ARRAY_B,
+					ARRAY_C,
+				]
+			} else {
+				// Option 2: convert them explicitly via the "as_slice" method
+
+				[
+					ARRAY_A.as_slice(),
+					ARRAY_B.as_slice(),
+					ARRAY_C.as_slice(),
+				]
+			}
+		}
+	};
+
+	// And for instance iterate through that list.
+	for (i, slice) in list_of_slices.iter().enumerate() {
+		// Here `slice` is a `ProgMem<[u8]>`, which has (among others) a `len` and a
+		// `load_at` method.
+
+		ufmt::uwriteln!(
+			&mut printer,
+			"Element #{}, size: {}, first element: {}\r",
+			i,
+			slice.len(),
+			slice.load_at(0)
+		)
+		.unwrap();
+
+		// We can also use a progmem-iterator that gives a ProgMem wrapper for
+		// each element of that slice (without yet loading any of them).
+		for elem_wrapper in slice.wrapper_iter() {
+			// Fun fact, if that element happened to be another array, we would
+			// also iterate its elements without loading it yet.
+			// That allows to iterate multi-dimensional arrays and only ever
+			// loading a single element into RAM.
+
+			// Only load a single element at a time
+			let e = elem_wrapper.load();
+			ufmt::uwrite!(&mut printer, "{}, ", e).unwrap();
+		}
+		printer.println("");
+	}
+
+	// "end" the program
+	finish(printer)
+}
+
+//
+// Following are just some auxiliary functions to setup and finish up the Arduino
+//
+
+
+// Setup the serial UART as output at 9600 baud and print a "Hello from Arduino"
+fn setup() -> Printer {
+	let mut printer = {
+		#[cfg(target_arch = "avr")]
+		{
+			// Initialize the USB-Serial output on the Arduino Uno
+
+			let dp = arduino_hal::Peripherals::take().unwrap();
+			let pins = arduino_hal::pins!(dp);
+			let serial = arduino_hal::default_serial!(dp, pins, 9600);
+
+			Printer(serial)
+		}
+		#[cfg(not(target_arch = "avr"))]
+		{
+			// Just use stdout for non-AVR targets
+			Printer
+		}
+	};
+
+	// Print some introduction text
+	printer.println("Hello from Arduino!");
+	printer.println("");
+	printer.println("--------------------------");
+	printer.println("");
+
+	// return the printer
+	printer
+}
+
+// Print a "DONE" and exit (or go into an infinite loop).
+fn finish(mut printer: Printer) -> ! {
+	// Print some final lines
+	printer.println("");
+	printer.println("--------------------------");
+	printer.println("");
+	printer.println("DONE");
+
+	// It is very convenient to just exit on non-AVR platforms, otherwise users
+	// might get the impression that the program hangs, whereas it already
+	// succeeded.
+	#[cfg(not(target_arch = "avr"))]
+	std::process::exit(0);
+
+	// Otherwise, that is on AVR, just go into an infinite loop, because on AVR
+	// we just can't exit!
+	loop {
+		// Done, just do nothing
+	}
+}

src/lib.rs

@@ -5,6 +5,15 @@
 // As of now (mid 2022), inline assembly for AVR is still unstable.
 #![feature(asm_experimental_arch)]
 //
+// We to access the length of a slice pointer (for unsized `ProgMem`s)
+#![feature(slice_ptr_len)]
+//
+// Allow to implement `CoerceUnsized` on `ProgMem`
+#![cfg_attr(feature = "unsize", feature(coerce_unsized))]
+//
+// Needed for implementing `CoerceUnsized` on `ProgMem`
+#![cfg_attr(feature = "unsize", feature(unsize))]
+//
 // Allows to document required crate features on items
 #![cfg_attr(doc, feature(doc_auto_cfg))]
 //
@@ -95,7 +104,7 @@
 //! use core::ptr::addr_of;
 //!
 //! // This `static` must never be directly dereferenced/accessed!
-//! // So a `let data: u8 = P_BYTE;` is **undefined behavior**!!!
+//! // So a `let data: u8 = P_BYTE;` ⚠️ is **undefined behavior**!!!
 //! /// Static byte stored in progmem!
 //! #[link_section = ".progmem.data"]
 //! static P_BYTE: u8 = b'A';

src/string.rs

@@ -375,7 +375,16 @@ impl<const N: usize> ufmt::uDisplay for LoadedString<N> {
 /// assert_eq!("dai 大賢者 kenja", &*loaded)
 /// ```
 ///
-#[non_exhaustive] // SAFETY: this struct must not be publicly constructible
+//
+//
+// SAFETY: this struct must not be publicly constructible
+#[non_exhaustive]
+//
+// Its just a pointer type, thus copy, clone & debug are fine (none of them
+// will access the progmem, that's what `Display` is for).
+#[derive(Copy, Clone, Debug)]
+// Also impl `uDebug` if enabled.
+#[cfg_attr(feature = "ufmt", derive(ufmt::derive::uDebug))]
 pub struct PmString<const N: usize> {
 	/// The inner UTF-8 string as byte array in progmem.
 	///