Expand the macro syntax to support easy string usage and array auto-sizing.

Ref #3

Author: Cryptjar

examples/printer/mod.rs

@@ -7,14 +7,20 @@
 //! Quite useful for examples.
 //!
 
+// This a shared model, so there are function only used in specific cases
+#![allow(dead_code)]
 
 // Import the Arduino libraries, interestingly they don't cause problems perse
 // on other architectures. Through, we will not use there.
-use arduino_hal::port::mode::AnyInput;
-use arduino_hal::port::mode::Input;
-use arduino_hal::port::mode::Output;
-use arduino_hal::port::Pin;
-use arduino_hal::prelude::*;
+cfg_if::cfg_if! {
+	if #[cfg(target_arch = "avr")] {
+		use arduino_hal::port::mode::AnyInput;
+		use arduino_hal::port::mode::Input;
+		use arduino_hal::port::mode::Output;
+		use arduino_hal::port::Pin;
+		use arduino_hal::prelude::*;
+	}
+}
 
 
 #[cfg(target_arch = "avr")]

examples/uno-auto-sizing.rs

@@ -0,0 +1,115 @@
+//
+// This file provides a example on how to use auto-sizing statics on an
+// Arduino Uno.
+//
+
+
+// Define no_std only for AVR
+#![cfg_attr(target_arch = "avr", no_std)]
+#![cfg_attr(target_arch = "avr", no_main)]
+//
+// To unwrap the Option in const context
+#![feature(const_option)]
+//
+#![feature(extended_key_value_attributes)]
+
+
+use avr_progmem::progmem; // The macro
+#[cfg(target_arch = "avr")]
+use panic_halt as _; // halting panic implementation for AVR
+
+
+progmem! {
+	// Simple Auto-sizing
+	// This is equivalent to:
+	// `static progmem ARR: [u8; 3] = [1,2,3];`
+	// But you don't have to count the elements yourself, and you get an nice
+	// constant `ARR_LEN` to refer to the length of the array (e.g. to name the
+	// type).
+	static progmem<const ARR_LEN: usize> ARR: [u8; ARR_LEN] = [1,2,3];
+
+	// The size in the array type is automatically derived from the value.
+	// As note: don't confuse this with text, see `uno-string.rs` for those!
+	static progmem<const LONG_LEN: usize> LONG: [u8; LONG_LEN] =
+		*include_bytes!("./test_text.txt");
+}
+
+// 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() -> ! {
+	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("");
+
+	//
+	// Using auto-sized arrays
+	//
+
+	// We get the const to refer to the size of the array
+	ufmt::uwriteln!(&mut printer, "The array is {} bytes long\r", ARR_LEN).unwrap();
+	printer.println("");
+
+	// So we can easily name the type of the array, and load it as a whole:
+	let arr: [u8; ARR_LEN] = ARR.load();
+	ufmt::uwriteln!(&mut printer, "{:?}\r", arr).unwrap();
+	printer.println("");
+
+	// We can of course still use the array element accessors:
+	assert_eq!(2, ARR.load_at(1));
+
+	// Particularly useful is this auto-sizing with data from an external file.
+	ufmt::uwriteln!(&mut printer, "The long data is {} bytes long\r", LONG_LEN).unwrap();
+
+	// For longer data, it can easily become problematic to load it all at once,
+	// instead you can use a byte-by-byte iterator to get the only load them
+	// one at a time.
+	for b in LONG.iter() {
+		// assuming its all ASCII, so we actually print it,
+		// but if you happen to have text, better use strings
+		// see: `uno-string.rs`
+		printer.print(b as char);
+	}
+
+
+	// 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
+	}
+}

examples/uno-string.rs

@@ -12,33 +12,33 @@
 
 
 use avr_progmem::progmem; // The macro
-use avr_progmem::string::LoadedString; // Helper for storing strings
 #[cfg(target_arch = "avr")]
 use panic_halt as _; // halting panic implementation for AVR
 
 
+//
+// Defining strings as statics in progmem
+//
+
 progmem! {
-	/// The static data to be stored in program code section
-	/// Notice the usage of `LoadedString`, to store a string as `[u8;N]`,
-	/// because you can't store a `str` and storing a `&str` wouldn't have
-	/// much of an effect.
-	static progmem SOME_TEXT: LoadedString<191> = LoadedString::new("
-A long test string literal, that is stored in progmem instead of DRAM.
-However, to use it, it needs to be temporarily load into DRAM,
-so an individual `LoadedString` shouldn't be too long.
-	").unwrap();
-
-	/// More data to be stored in program code section
-	static progmem MORE_TEXT: LoadedString<102> = LoadedString::new("
-However, you easily store your strings individual, limiting the amount of
-temporary DRAM necessary.
-	").unwrap();
-
-	/// Unicode works of course as expected
-	///
-	static progmem UNICODE_TEXT: LoadedString<137> = LoadedString::new(
-		"dai 大賢者 kenja, Völlerei lässt grüßen, le garçon de théâtre, Ελληνική Δημοκρατία, Слава Україні"
-	).unwrap();
+	/// A static string to be stored in program code section.
+	/// Notice the usage of special `string` modifier, that accepts a `&str`
+	/// as value and will wrap it in a `PmString` instead of a
+	/// standard `ProgMem`.
+	static progmem string SOME_TEXT = concat!(
+		"A long test string literal, that is stored in progmem instead of RAM. ",
+		"If used via `load`, it is load as `LoadedString` entirely into RAM, ",
+		"so for those use-case an individual string shouldn't be too long."
+	);
+
+	/// You can also load a file as string via the std `include_str` macro.
+	/// And because this is stored in progmem, it can be big,
+	/// e.g. this one is over 2 KiB is size.
+	static progmem string MUCH_LONGER_TEXT = include_str!("./test_text.txt");
+
+	/// Of course, Unicode works as expected.
+	static progmem string UNICODE_TEXT =
+		"dai 大賢者 kenja, Völlerei lässt grüßen, le garçon de théâtre, Ελληνική Δημοκρατία, Слава Україні";
 }
 
 // Include a fancy printer supporting Arduino Uno's USB-Serial output as well
@@ -72,41 +72,62 @@ fn main() -> ! {
 	printer.println("--------------------------");
 	printer.println("");
 
-	// Scope to limit the lifetime of `text_buffer`
+
+	//
+	// Using string from progmem
+	//
+
+	// Option 1)
+	// We can load the entire string at once and use references to the resulting
+	// `LoadedString` everywhere where a `&str` is expected.
+	// However, the string must of limited in size to not exceed RAM.
 	{
-		// The temporary DRAM buffer for the string
+		// Scope to limit the lifetime of `text_buffer`, since it is big.
+
+		// The temporary DRAM buffer for the string of type `LoadedString`
 		let text_buffer = SOME_TEXT.load();
-		let text: &str = &text_buffer; // Just derefs to `str`
-		printer.println(text);
+		// Just derefs to `str`
+		let _text: &str = &text_buffer;
+		// This function only accepts `&str`, deref makes this possible:
+		printer.println(&text_buffer);
 	}
 
-	// Or just using temporaries
-	printer.println(&MORE_TEXT.load());
-	printer.println(&UNICODE_TEXT.load());
 
-	// Even more convenient: use a one-off in-place progmem static via `progmem_str`
-	printer.println(avr_progmem::progmem_str!("Just a lone literal progmem str"));
+	// Option 2)
+	// We can use the `char`-iterator to access the text iteratively,
+	// this has the advantage of limiting the stack usage.
+	for c in MUCH_LONGER_TEXT.chars() {
+		// Here, `c` is just a `char`
+		let _c: char = c;
+		printer.print(c);
+	}
+	printer.println("");
+
+
+	// Option 3)
+	// We directly use the Display/uDisplay impl, which uses the char-iterator.
+	#[cfg(feature = "ufmt")] // this however requires the `ufmt` a crate feature
+	ufmt::uwriteln!(&mut printer, "{}\r", UNICODE_TEXT).unwrap();
+
+
+	// Option 4)
+	// We can use a in-place immediate string, similar to the popular C macro:
 	use avr_progmem::progmem_str as F;
-	printer.println(F!("And another one"));
+	ufmt::uwriteln!(&mut printer, "{}\r", F!("Some immediate string")).unwrap();
+
 
-	// Using the ufmt impl
-	#[cfg(feature = "ufmt")]
-	ufmt::uwriteln!(&mut printer, "{}\r", UNICODE_TEXT.load()).unwrap();
 
 	// 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.
+	// It is convenient to just exit on non-AVR platforms.
 	#[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!
+	// Otherwise, that is on AVR, just go into an infinite loop.
 	loop {
 		// Done, just do nothing
 	}

src/raw.rs

@@ -271,6 +271,9 @@ unsafe fn read_asm_loop_raw<T>(p_addr: *const T, out: *mut T, len: u8) {
 			// We just use normal data or text segment, and thus that it is
 			// actually save to just access the data.
 
+			// Ignore the unused vars:
+			let _ = size_bytes;
+
 			// Now, just copy the bytes from p_addr to out
 			// It is save by the way, because we require the user to give use
 			// pointer valid for exactly that case.

src/string.rs

@@ -26,7 +26,27 @@
 //! converting a normal string literal into a [`PmString`]:
 //!
 //! ```rust
-//! // TODO: code
+//! #![feature(const_option)]
+//!
+//! # use std::iter::FromIterator;
+//! use avr_progmem::progmem;
+//!
+//! progmem! {
+//!     // A simple Unicode string in progmem, internally stored as fix-sized
+//!     // byte array.
+//!     static progmem string TEXT = "Hello 大賢者";
+//! }
+//!
+//! // You can load it all at once (like a `ProgMem`)
+//! let buffer = TEXT.load();
+//! // and use that as `&str`
+//! assert_eq!("Hello 大賢者", &*buffer);
+//!
+//! // Or you load it one char at a time (limits RAM usage) via the
+//! // chars-iterator
+//! let chars_iter = TEXT.chars(); // impl Iterator<Item=char>
+//! let exp = ['H', 'e', 'l', 'l', 'o', ' ', '大', '賢', '者'];
+//! assert_eq!(&exp, &*Vec::from_iter(chars_iter));
 //! ```
 //!
 
@@ -64,20 +84,21 @@ pub struct InvalidLengthError;
 /// #![feature(const_option)]
 ///
 /// use avr_progmem::progmem;
+/// use avr_progmem::string::PmString;
 /// use avr_progmem::string::LoadedString;
 ///
 /// progmem! {
 ///     // Stores a string as a byte array, i.e. `[u8;19]`, but makes it usable
 ///     // as `&str` (via `Deref`)
-///     static progmem TEXT: LoadedString<19> = LoadedString::new(
-///         "dai 大賢者 kenja"
-///     ).unwrap();
+///     static progmem string TEXT = "dai 大賢者 kenja";
 /// }
 ///
-/// // usage:
-/// let text_buffer = TEXT.load(); // The temporary DRAM buffer for `TEXT`
-/// let text: &str = &text_buffer; // Just derefs to `str`
-/// assert_eq!(text, "dai 大賢者 kenja")
+/// // The static has type `PmString`
+/// let text: &PmString<19> = &TEXT;
+/// // The loaded RAM string has type `LoadedString`
+/// let loaded: LoadedString<19> = text.load();
+/// // Which derefs to `&str`
+/// assert_eq!("dai 大賢者 kenja", &*loaded)
 /// ```
 ///
 /// # Safety
@@ -434,37 +455,40 @@ impl<'a, const N: usize> Iterator for PmChars<'a, N> {
 /// This is a short-cut macro to create an ad-hoc static storing the given
 /// string literal as by [`LoadedString`] and load it here from progmem into a
 /// temporary and return it as `&str`.
+/// This is similar to the `F` macro available in Arduino.
+///
+/// Similar to the C marco, this will load the full string into RAM at once
+/// and thus the string should be of limited size, to not exceed the space
+/// available in RAM.
 ///
 /// This macro allows to conveniently put literal string into progmem exactly,
 /// where they are used. However, since they are directly loaded into a
 /// temporary you don't get a `&'static str` back, and must use the `&str`
 /// immediately (i.e. pass it as a function parameter).
 /// You can't even store the returned `&str` in a local `let` assignment.
 ///
+///
 /// # Example
 ///
 /// ```rust
 /// #![feature(const_option)]
 ///
-/// use avr_progmem::progmem_str as S;
+/// use avr_progmem::progmem_str as F;
 ///
 /// fn print(s: &str) {
 ///     // -- snip --
 ///     # assert_eq!(s, "dai 大賢者 kenja")
 /// }
 ///
-/// // Put the literal as byte array into progmem and load it here as `&str`
-/// print(S!("dai 大賢者 kenja"));
+/// // Put the literal `str` into progmem and load it here as `&str`
+/// print(F!("dai 大賢者 kenja"));
 /// ```
+///
 #[macro_export]
 macro_rules! progmem_str {
 	($text:literal) => {{
-		const TEXT_LEN: usize = <str>::as_bytes($text).len();
 		$crate::progmem! {
-			// TODO: use PmString
-			static progmem TEXT: $crate::string::LoadedString<TEXT_LEN> = $crate::string::LoadedString::new(
-				$text
-			).unwrap();
+			static progmem string TEXT = $text;
 		}
 		&*TEXT.load()
 	}};