Struct avr_progmem::string::PmString

#[non_exhaustive]
pub struct PmString<const N: usize> { /* private fields */ }

A byte string in progmem

Not to be confused with a LoadedString. A LoadedString is a simple wrapper around a byte array ([u8;N]) that derefs to str, and should be used in RAM. A PmString on the other hand, is a wrapper around a byte array in progmem aka around a ProgMem<[u8;N]>, and thus must always be progmem. Similar to ProgMem, PmString offers a load method to load its entire content into RAM. The loaded content will be a LoadedString, hence the name.

Besides loading the entire string at once into RAM, PmString also offers a lazy chars iterator method, that will load just one char at a time. This allows chars to be used on very large strings that do not fit into the RAM as whole.

Safety

This type is a wrapper around ProgMem, thus it any value of this type must be placed in program memory. See the ProgMem safety section for more details.

Additionally to the ProgMem contract, the byte array wrapped by this struct must be valid UTF-8.

Example

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 string 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)

Implementations

impl<const N: usize> PmString<N>

pub const unsafe fn new(pm: ProgMem<[u8; N]>) -> Self

Creates a new byte array from the given string

You are encouraged to use the progmem macro instead.

Safety

This function is only sound to call, if the value is stored in a static that is for instance attributed with #[link_section = ".progmem.data"].

The give byte array must contain valid UTF-8.

pub fn load(&self) -> LoadedString<N>

Loads the entire string into RAM

Panics

This method panics, if the size of the value (i.e. N) is beyond 255 bytes. However, this is currently just a implementation limitation, which may be lifted in the future.

If you have a very large string, consider using the lazy chars iterator that accesses the string by one char at a time and thus does not have such a limitation.

pub fn load_bytes(&self) -> [u8; N]

Loads the entire string as byte array into RAM

Panics

This method panics, if the size of the value (i.e. [u8; N]) is beyond 255 bytes. However, this is currently just a implementation limitation, which may be lifted in the future.

If you have a very large string, consider using the lazy chars iterator or the respective byte iterator (via as_bytes().iter()).

pub fn as_bytes(&self) -> &ProgMem<[u8; N]>

Returns the underlying progmem byte array.

pub fn chars(&self) -> PmChars<'_, N>

Lazily iterate over the chars of the string.

This function is analog to ProgMem::iter, except it performs UTF-8 parsing and returns the chars of this string, thus it is more similar to str::chars.

Trait Implementations

impl<const N: usize> Display for PmString<N>

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<const N: usize> uDisplay for PmString<N>

Available on crate feature ufmt only.

fn fmt<W: ?Sized>(&self, fmt: &mut Formatter<'_, W>) -> Result<(), W::Error> where
    W: uWrite, 

Formats the value using the given formatter