Struct avr_progmem::string::PmString
source · #[non_exhaustive]pub struct PmString<const N: usize> { /* private fields */ }
Expand description
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§
source§impl<const N: usize> PmString<N>
impl<const N: usize> PmString<N>
sourcepub fn load(&self) -> LoadedString<N>
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.
sourcepub fn load_bytes(&self) -> [u8; N]
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()
).
sourcepub fn chars(&self) -> PmChars<'_, N> ⓘ
pub fn chars(&self) -> PmChars<'_, N> ⓘ
Lazily iterate over the char
s of the string.
This function is analog to ProgMem::iter
, except it performs UTF-8
parsing and returns the char
s of this string, thus it is more similar
to str::chars
.