Struct heapless::String

pub struct String<N>(_)
 where
    N: ArrayLength<u8>;

A fixed capacity String

Implementations

impl<N> String<N> where
    N: ArrayLength<u8>, 

pub fn new() -> Self

Constructs a new, empty String with a fixed capacity of N

Examples

Basic usage:

use heapless::String;
use heapless::consts::*;

// allocate the string on the stack
let mut s: String<U4> = String::new();

// allocate the string in a static variable
static mut S: String<U4> = String(heapless::i::String::new());

pub fn from_utf8(vec: Vec<u8, N>) -> Result<String<N>, Utf8Error>

Converts a vector of bytes into a String.

A string slice (&str) is made of bytes (u8), and a vector of bytes (Vec<u8>) is made of bytes, so this function converts between the two. Not all byte slices are valid Strings, however: String requires that it is valid UTF-8. from_utf8() checks to ensure that the bytes are valid UTF-8, and then does the conversion.

See std::String for further information.

Examples

Basic usage:

use heapless::{String, Vec};
use heapless::consts::*;

let mut v: Vec<u8, U8> = Vec::new();
v.push('a' as u8).unwrap();
v.push('b' as u8).unwrap();

let s = String::from_utf8(v).unwrap();
assert!(s.len() == 2);

Incorrect bytes:

use heapless::{String, Vec};
use heapless::consts::*;

// some invalid bytes, in a vector

let mut v: Vec<u8, U8> = Vec::new();
v.push(0).unwrap();
v.push(159).unwrap();
v.push(146).unwrap();
v.push(150).unwrap();
assert!(String::from_utf8(v).is_err());

pub unsafe fn from_utf8_unchecked(vec: Vec<u8, N>) -> String<N>

Converts a vector of bytes to a String without checking that the string contains valid UTF-8.

See the safe version, from_utf8, for more details.

pub fn into_bytes(self) -> Vec<u8, N>

Converts a String into a byte vector.

This consumes the String, so we do not need to copy its contents.

Examples

Basic usage:

use heapless::String;
use heapless::consts::*;

let s: String<U4> = String::from("ab");
let b = s.into_bytes();
assert!(b.len() == 2);

assert_eq!(&['a' as u8, 'b' as u8], &b[..]);

pub fn as_str(&self) -> &str

Extracts a string slice containing the entire string.

Examples

Basic usage:

use heapless::String;
use heapless::consts::*;

let mut s: String<U4> = String::from("ab");
assert!(s.as_str() == "ab");

let _s = s.as_str();
// s.push('c'); // <- cannot borrow `s` as mutable because it is also borrowed as immutable

pub fn as_mut_str(&mut self) -> &mut str

Converts a String into a mutable string slice.

Examples

Basic usage:

use heapless::String;
use heapless::consts::*;

let mut s: String<U4> = String::from("ab");
let s = s.as_mut_str();
s.make_ascii_uppercase();

pub unsafe fn as_mut_vec(&mut self) -> &mut Vec<u8, N>

Returns a mutable reference to the contents of this String.

Safety

This function is unsafe because it does not check that the bytes passed to it are valid UTF-8. If this constraint is violated, it may cause memory unsafety issues with future users of the String, as the rest of the library assumes that Strings are valid UTF-8.

Examples

Basic usage:

let mut s = String::from("hello");

unsafe {
    let vec = s.as_mut_vec();
    assert_eq!(&[104, 101, 108, 108, 111][..], &vec[..]);

    vec.reverse();
}
assert_eq!(s, "olleh");

pub fn push_str(&mut self, string: &str) -> Result<(), ()>

Appends a given string slice onto the end of this String.

Examples

Basic usage:

use heapless::String;
use heapless::consts::*;

let mut s: String<U8> = String::from("foo");

assert!(s.push_str("bar").is_ok());

assert_eq!("foobar", s);

assert!(s.push_str("tender").is_err());

pub fn capacity(&self) -> usize

Returns the maximum number of elements the String can hold

Examples

Basic usage:

use heapless::String;
use heapless::consts::*;

let mut s: String<U4> = String::new();
assert!(s.capacity() == 4);

pub fn push(&mut self, c: char) -> Result<(), ()>

Appends the given char to the end of this String.

Examples

Basic usage:

use heapless::String;
use heapless::consts::*;

let mut s: String<U8> = String::from("abc");

s.push('1').unwrap();
s.push('2').unwrap();
s.push('3').unwrap();

assert!("abc123" == s.as_str());

assert_eq!("abc123", s);

pub fn truncate(&mut self, new_len: usize)

Shortens this String to the specified length.

If new_len is greater than the string’s current length, this has no effect.

Note that this method has no effect on the allocated capacity of the string

Panics

Panics if new_len does not lie on a char boundary.

Examples

Basic usage:

use heapless::String;
use heapless::consts::*;

let mut s: String<U8> = String::from("hello");

s.truncate(2);

assert_eq!("he", s);

pub fn pop(&mut self) -> Option<char>

Removes the last character from the string buffer and returns it.

Returns None if this String is empty.

Examples

Basic usage:

use heapless::String;
use heapless::consts::*;

let mut s: String<U8> = String::from("foo");

assert_eq!(s.pop(), Some('o'));
assert_eq!(s.pop(), Some('o'));
assert_eq!(s.pop(), Some('f'));

assert_eq!(s.pop(), None);

pub fn clear(&mut self)

Truncates this String, removing all contents.

While this means the String will have a length of zero, it does not touch its capacity.

Examples

Basic usage:

use heapless::String;
use heapless::consts::*;

let mut s: String<U8> = String::from("foo");

s.clear();

assert!(s.is_empty());
assert_eq!(0, s.len());
assert_eq!(8, s.capacity());

Trait Implementations

impl<N> AsRef<[u8]> for String<N> where
    N: ArrayLength<u8>, 

fn as_ref(&self) -> &[u8]

Performs the conversion.

impl<N> AsRef<str> for String<N> where
    N: ArrayLength<u8>, 

fn as_ref(&self) -> &str

Performs the conversion.

impl<N> Clone for String<N> where
    N: ArrayLength<u8>, 

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<N> Debug for String<N> where
    N: ArrayLength<u8>, 

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

Formats the value using the given formatter.

impl<N> Default for String<N> where
    N: ArrayLength<u8>, 

fn default() -> Self

Returns the “default value” for a type.

impl<N> Deref for String<N> where
    N: ArrayLength<u8>, 

type Target = str

The resulting type after dereferencing.

fn deref(&self) -> &str

Dereferences the value.

impl<N> DerefMut for String<N> where
    N: ArrayLength<u8>, 

fn deref_mut(&mut self) -> &mut str

Mutably dereferences the value.

impl<N> Display for String<N> where
    N: ArrayLength<u8>, 

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

Formats the value using the given formatter.

impl<'a, N> From<&'a str> for String<N> where
    N: ArrayLength<u8>, 

fn from(s: &'a str) -> Self

Performs the conversion.

impl<N> From<i16> for String<N> where
    N: ArrayLength<u8> + IsGreaterOrEqual<U6, Output = True>, 

fn from(s: i16) -> Self

Performs the conversion.

impl<N> From<i32> for String<N> where
    N: ArrayLength<u8> + IsGreaterOrEqual<U11, Output = True>, 

fn from(s: i32) -> Self

Performs the conversion.

impl<N> From<i64> for String<N> where
    N: ArrayLength<u8> + IsGreaterOrEqual<U20, Output = True>, 

fn from(s: i64) -> Self

Performs the conversion.

impl<N> From<i8> for String<N> where
    N: ArrayLength<u8> + IsGreaterOrEqual<U4, Output = True>, 

fn from(s: i8) -> Self

Performs the conversion.

impl<N> From<u16> for String<N> where
    N: ArrayLength<u8> + IsGreaterOrEqual<U5, Output = True>, 

fn from(s: u16) -> Self

Performs the conversion.

impl<N> From<u32> for String<N> where
    N: ArrayLength<u8> + IsGreaterOrEqual<U10, Output = True>, 

fn from(s: u32) -> Self

Performs the conversion.

impl<N> From<u64> for String<N> where
    N: ArrayLength<u8> + IsGreaterOrEqual<U20, Output = True>, 

fn from(s: u64) -> Self

Performs the conversion.

impl<N> From<u8> for String<N> where
    N: ArrayLength<u8> + IsGreaterOrEqual<U3, Output = True>, 

fn from(s: u8) -> Self

Performs the conversion.

impl<N> FromStr for String<N> where
    N: ArrayLength<u8>, 

type Err = ()

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl<N> Hash for String<N> where
    N: ArrayLength<u8>, 

fn hash<H: Hasher>(&self, hasher: &mut H)

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given [Hasher].

impl<N> Hash for String<N> where
    N: ArrayLength<u8>, 

fn hash<H: Hasher>(&self, hasher: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl<'a, 'b, N> PartialEq<&'a str> for String<N> where
    N: ArrayLength<u8>, 

fn eq(&self, other: &&'a str) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &&'a str) -> bool

This method tests for !=.

impl<'a, 'b, N> PartialEq<String<N>> for str where
    N: ArrayLength<u8>, 

fn eq(&self, other: &String<N>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &String<N>) -> bool

This method tests for !=.

impl<'a, 'b, N> PartialEq<String<N>> for &'a str where
    N: ArrayLength<u8>, 

fn eq(&self, other: &String<N>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &String<N>) -> bool

This method tests for !=.

impl<N1, N2> PartialEq<String<N2>> for String<N1> where
    N1: ArrayLength<u8>,
    N2: ArrayLength<u8>, 

fn eq(&self, rhs: &String<N2>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, rhs: &String<N2>) -> bool

This method tests for !=.

impl<'a, 'b, N> PartialEq<str> for String<N> where
    N: ArrayLength<u8>, 

fn eq(&self, other: &str) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &str) -> bool

This method tests for !=.

impl<N> Write for String<N> where
    N: ArrayLength<u8>, 

fn write_str(&mut self, s: &str) -> Result<(), Error>

Writes a string slice into this writer, returning whether the write succeeded.

fn write_char(&mut self, c: char) -> Result<(), Error>

Writes a char into this writer, returning whether the write succeeded.

fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>

Glue for usage of the [write!] macro with implementors of this trait.

impl<N> Eq for String<N> where
    N: ArrayLength<u8>,