# [−] [src] Struct heapless::String

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

A fixed capacity `String`

## Implementations

### `impl<N> String<N> where
N: ArrayLength<u8>,` [src]

#### `pub fn new() -> Self` [src]

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>` [src]

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 `String`s, 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>` [src]

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>` [src]

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` [src]

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` [src]

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>` [src]

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 `String`s 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<(), ()>` [src]

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` [src]

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<(), ()>` [src]

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)` [src]

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>` [src]

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)` [src]

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>,` [src]

#### `fn as_ref(&self) -> &[u8]` [src]

Performs the conversion.

### `impl<N> AsRef<str> for String<N> where
N: ArrayLength<u8>,` [src]

#### `fn as_ref(&self) -> &str` [src]

Performs the conversion.

### `impl<N> Clone for String<N> where
N: ArrayLength<u8>,` [src]

#### `fn clone(&self) -> Self` [src]

Returns a copy of the value. Read more

#### `pub fn clone_from(&mut self, source: &Self)`1.0.0 [src]

Performs copy-assignment from `source`. Read more

### `impl<N> Debug for String<N> where
N: ArrayLength<u8>,` [src]

#### `fn fmt(&self, f: &mut Formatter<'_>) -> Result` [src]

Formats the value using the given formatter. Read more

### `impl<N> Default for String<N> where
N: ArrayLength<u8>,` [src]

#### `fn default() -> Self` [src]

Returns the "default value" for a type. Read more

### `impl<N> Deref for String<N> where
N: ArrayLength<u8>,` [src]

#### `type Target = str`

The resulting type after dereferencing.

#### `fn deref(&self) -> &str` [src]

Dereferences the value.

### `impl<N> DerefMut for String<N> where
N: ArrayLength<u8>,` [src]

#### `fn deref_mut(&mut self) -> &mut str` [src]

Mutably dereferences the value.

### `impl<N> Display for String<N> where
N: ArrayLength<u8>,` [src]

#### `fn fmt(&self, f: &mut Formatter<'_>) -> Result` [src]

Formats the value using the given formatter. Read more

### `impl<N> Eq for String<N> where
N: ArrayLength<u8>,` [src]

### `impl<'a, N> From<&'a str> for String<N> where
N: ArrayLength<u8>,` [src]

#### `fn from(s: &'a str) -> Self` [src]

Performs the conversion.

### `impl<N> From<i16> for String<N> where
N: ArrayLength<u8> + IsGreaterOrEqual<U6, Output = True>,` [src]

#### `fn from(s: i16) -> Self` [src]

Performs the conversion.

### `impl<N> From<i32> for String<N> where
N: ArrayLength<u8> + IsGreaterOrEqual<U11, Output = True>,` [src]

#### `fn from(s: i32) -> Self` [src]

Performs the conversion.

### `impl<N> From<i64> for String<N> where
N: ArrayLength<u8> + IsGreaterOrEqual<U20, Output = True>,` [src]

#### `fn from(s: i64) -> Self` [src]

Performs the conversion.

### `impl<N> From<i8> for String<N> where
N: ArrayLength<u8> + IsGreaterOrEqual<U4, Output = True>,` [src]

#### `fn from(s: i8) -> Self` [src]

Performs the conversion.

### `impl<N> From<u16> for String<N> where
N: ArrayLength<u8> + IsGreaterOrEqual<U5, Output = True>,` [src]

#### `fn from(s: u16) -> Self` [src]

Performs the conversion.

### `impl<N> From<u32> for String<N> where
N: ArrayLength<u8> + IsGreaterOrEqual<U10, Output = True>,` [src]

#### `fn from(s: u32) -> Self` [src]

Performs the conversion.

### `impl<N> From<u64> for String<N> where
N: ArrayLength<u8> + IsGreaterOrEqual<U20, Output = True>,` [src]

#### `fn from(s: u64) -> Self` [src]

Performs the conversion.

### `impl<N> From<u8> for String<N> where
N: ArrayLength<u8> + IsGreaterOrEqual<U3, Output = True>,` [src]

#### `fn from(s: u8) -> Self` [src]

Performs the conversion.

### `impl<N> FromStr for String<N> where
N: ArrayLength<u8>,` [src]

#### `type Err = ()`

The associated error which can be returned from parsing.

#### `fn from_str(s: &str) -> Result<Self, Self::Err>` [src]

Parses a string `s` to return a value of this type. Read more

### `impl<N> Hash for String<N> where
N: ArrayLength<u8>,` [src]

#### `fn hash<H: Hasher>(&self, hasher: &mut H)` [src]

Feeds this value into the given `Hasher`. Read more

#### `pub fn hash_slice<H>(data: &[Self], state: &mut H) where
H: Hasher,` 1.3.0 [src]

Feeds a slice of this type into the given `Hasher`. Read more

### `impl<N> Hash for String<N> where
N: ArrayLength<u8>,` [src]

#### `fn hash<H: Hasher>(&self, hasher: &mut H)` [src]

Feeds this value into the given `Hasher`.

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

Feeds a slice of this type into the given `Hasher`.

### `impl<'a, 'b, N> PartialEq<&'a str> for String<N> where
N: ArrayLength<u8>,` [src]

#### `fn eq(&self, other: &&'a str) -> bool` [src]

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

#### `fn ne(&self, other: &&'a str) -> bool` [src]

This method tests for `!=`.

### `impl<'a, 'b, N> PartialEq<String<N>> for str where
N: ArrayLength<u8>,` [src]

#### `fn eq(&self, other: &String<N>) -> bool` [src]

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

#### `fn ne(&self, other: &String<N>) -> bool` [src]

This method tests for `!=`.

### `impl<'a, 'b, N> PartialEq<String<N>> for &'a str where
N: ArrayLength<u8>,` [src]

#### `fn eq(&self, other: &String<N>) -> bool` [src]

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

#### `fn ne(&self, other: &String<N>) -> bool` [src]

This method tests for `!=`.

### `impl<N1, N2> PartialEq<String<N2>> for String<N1> where
N1: ArrayLength<u8>,
N2: ArrayLength<u8>,` [src]

#### `fn eq(&self, rhs: &String<N2>) -> bool` [src]

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

#### `fn ne(&self, rhs: &String<N2>) -> bool` [src]

This method tests for `!=`.

### `impl<'a, 'b, N> PartialEq<str> for String<N> where
N: ArrayLength<u8>,` [src]

#### `fn eq(&self, other: &str) -> bool` [src]

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

#### `fn ne(&self, other: &str) -> bool` [src]

This method tests for `!=`.

### `impl<N> Write for String<N> where
N: ArrayLength<u8>,` [src]

#### `fn write_str(&mut self, s: &str) -> Result<(), Error>` [src]

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

#### `fn write_char(&mut self, c: char) -> Result<(), Error>` [src]

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

#### `pub fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>`1.0.0 [src]

Glue for usage of the `write!` macro with implementors of this trait. Read more

## Auto Trait Implementations

### `impl<N> Send for String<N>` [src]

### `impl<N> Sync for String<N>` [src]

### `impl<N> Unpin for String<N> where
<N as ArrayLength<u8>>::ArrayType: Unpin,` [src]

## Blanket Implementations

### `impl<T> Any for T where
T: 'static + ?Sized,` [src]

#### `pub fn type_id(&self) -> TypeId` [src]

Gets the `TypeId` of `self`. Read more

### `impl<T> Borrow<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow(&self) -> &T` [src]

Immutably borrows from an owned value. Read more

### `impl<T> BorrowMut<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow_mut(&mut self) -> &mut T` [src]

Mutably borrows from an owned value. Read more

### `impl<T> From<T> for T` [src]

#### `pub fn from(t: T) -> T` [src]

Performs the conversion.

### `impl<T, U> Into<U> for T where
U: From<T>,` [src]

#### `pub fn into(self) -> U` [src]

Performs the conversion.

### `impl<T> Same<T> for T` [src]

#### `type Output = T`

Should always be `Self`

### `impl<T, U> TryFrom<U> for T where
U: Into<T>,` [src]

#### `type Error = Infallible`

The type returned in the event of a conversion error.

#### `pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>` [src]

Performs the conversion.

### `impl<T, U> TryInto<U> for T where
U: TryFrom<T>,` [src]

#### `type Error = <U as TryFrom<T>>::Error`

The type returned in the event of a conversion error.

#### `pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>` [src]

Performs the conversion.