Struct in_place_string_map::MapInPlace [−][src]
pub struct MapInPlace<'a> { /* fields omitted */ }
Expand description
A mutable reference to a str
that allows for in-place pushes and pops while maintaining
valid UTF-8 at all times.
Semantically, this creates 2 buffers, a “mapped” buffer, and an “unmapped” buffer.
The mapped buffer starts off empty, and the unmapped buffer starts off with the full contents
of the &mut str
given in MapInPlace::new
.
The mapped buffer can be pushed to, and this will append to the end of it. The unmapped buffer can be popped from, and this will pop from the start of it.
The size of the mapped buffer, plus the size of the unmapped buffer, can never be bigger than the original string size, and you will get errors when you go to push if this is the case.
However, it’s free to be smaller, in which case there will be some area in the middle with unspecified contents. It will still be valid UTF-8 though, to ensure safety.
Implementations
impl<'a> MapInPlace<'a>
[src]
impl<'a> MapInPlace<'a>
[src]pub fn new(s: &'a mut str) -> Self
[src]
pub fn new(s: &'a mut str) -> Self
[src]Creates a new MapInPlace
, used to do in-place string conversions without allocating a new
buffer.
let mut string = String::from("Hello, World!"); let mut map = in_place_string_map::MapInPlace::new(&mut string);
#[must_use]pub fn mapped(&self) -> &str
[src]
#[must_use]pub fn mapped(&self) -> &str
[src]Returns the mapped portion of the string.
let mut string = String::from("Hello, World!"); let mut map = in_place_string_map::MapInPlace::new(&mut string); assert_eq!(map.mapped(), ""); map.pop_chars(6); map.push_str("Yellow"); assert_eq!(map.mapped(), "Yellow");
#[must_use]pub fn into_mapped(self) -> &'a mut str
[src]
#[must_use]pub fn into_mapped(self) -> &'a mut str
[src]Consumes this MapInPlace
and returns the mapped slice of the original string with the
original lifetime.
This is useful for when you want the lifetime of the returned string to outlive the
instance of MapInPlace
.
fn push_yellow(s: &mut str) -> &mut str { let mut map = in_place_string_map::MapInPlace::new(s); map.pop_chars(6); map.push_str("Yellow"); map.into_mapped() } let mut string = String::from("Hello, World!"); let result = push_yellow(&mut string); assert_eq!(result, "Yellow");
You cannot simply use MapInPlace::mapped
because that will return a reference that
can’t outlive the original MapInPlace
fn push_yellow(s: &mut str) -> &str { let mut map = in_place_string_map::MapInPlace::new(s); map.pop_chars(6); map.push_str("Yellow"); // cannot return value referencing local variable `map` map.mapped() } let mut string = String::from("Hello, World!"); let result = push_yellow(&mut string); assert_eq!(result, "Yellow");
#[must_use]pub fn unmapped(&self) -> &str
[src]
#[must_use]pub fn unmapped(&self) -> &str
[src]Returns the not yet mapped portion of the string.
let mut string = String::from("Hello, World!"); let mut map = in_place_string_map::MapInPlace::new(&mut string); assert_eq!(map.unmapped(), "Hello, World!"); map.pop_chars(5); assert_eq!(map.unmapped(), ", World!");
#[must_use]pub fn into_unmapped(self) -> &'a mut str
[src]
#[must_use]pub fn into_unmapped(self) -> &'a mut str
[src]Consumes this MapInPlace
and returns the unmapped slice of the original string with the
original lifetime.
This is useful for when you want the lifetime of the returned string to outlive the
instance of MapInPlace
.
fn pop_five(s: &mut str) -> &mut str { let mut map = in_place_string_map::MapInPlace::new(s); map.pop_chars(5); map.into_unmapped() } let mut string = String::from("Hello, World!"); let result = pop_five(&mut string); assert_eq!(result, ", World!");
You cannot simply use MapInPlace::mapped
because that will return a reference that
can’t outlive the original MapInPlace
fn pop_five(s: &mut str) -> &str { let mut map = in_place_string_map::MapInPlace::new(s); map.pop_chars(5); // cannot return value referencing local variable `map` map.unmapped() } let mut string = String::from("Hello, World!"); let result = pop_five(&mut string); assert_eq!(result, ", World!");
pub fn push(&mut self, ch: char) -> Result<(), NoCapacityError>
[src]
pub fn push(&mut self, ch: char) -> Result<(), NoCapacityError>
[src]Pushes a character onto the end of the mapped portion.
let mut string = String::from("Hello!"); let mut map = in_place_string_map::MapInPlace::new(&mut string); map.pop_chars(6); assert_eq!(map.mapped(), ""); map.push('£').unwrap(); map.push('1').unwrap(); map.push('.').unwrap(); map.push('2').unwrap(); map.push('5').unwrap(); assert_eq!(map.mapped(), "£1.25"); map.push('5').unwrap_err(); assert_eq!(map.mapped(), "£1.25");
Errors
NoCapacityError
: If there is not enough room to fitch
being pushed.
pub fn push_str(&mut self, s: &str) -> Result<(), NoCapacityError>
[src]
pub fn push_str(&mut self, s: &str) -> Result<(), NoCapacityError>
[src]Pushes a string onto the end of the mapped portion. If the string is too long, an error is returned, and no changes will be made to the input.
let mut string = String::from("Hello!"); let mut map = in_place_string_map::MapInPlace::new(&mut string); map.pop_chars(6); assert_eq!(map.mapped(), ""); map.push_str("This string is *far* too long!").unwrap_err(); assert_eq!(map.mapped(), ""); map.push_str("Short").unwrap(); assert_eq!(map.mapped(), "Short"); map.push_str(".").unwrap(); assert_eq!(map.mapped(), "Short.");
Errors
NoCapacityError
: If there is not enough room to fits
being pushed.
pub fn pop(&mut self) -> Option<char>
[src]
pub fn pop(&mut self) -> Option<char>
[src]Pops a character from the start of the unmapped portion
Will return None
if there are no more characters left to pop.
let mut string = String::from("Hi!"); let mut map = in_place_string_map::MapInPlace::new(&mut string); assert_eq!(map.pop(), Some('H')); assert_eq!(map.unmapped(), "i!"); assert_eq!(map.pop(), Some('i')); assert_eq!(map.unmapped(), "!"); assert_eq!(map.pop(), Some('!')); assert_eq!(map.unmapped(), ""); assert_eq!(map.pop(), None); assert_eq!(map.unmapped(), "");
pub fn pop_chars(&mut self, n: usize) -> Option<&str>
[src]
pub fn pop_chars(&mut self, n: usize) -> Option<&str>
[src]Pops n
characters from the start of the unmapped portion.
Note how this pops in terms of characters, not bytes.
If n
is 0 then will always return None
If this fails because there are not enough characters then will return None
, and no
changes will have been made to self
.
let mut string = String::from("A £3.00 sandwich"); let mut map = in_place_string_map::MapInPlace::new(&mut string); assert_eq!(map.pop_chars(0), None); assert_eq!(map.pop_chars(2), Some("A ")); assert_eq!(map.pop_chars(5), Some("£3.00")); // Nothing is done if you try to pop too many characters assert_eq!(map.pop_chars(10), None); assert_eq!(map.pop_chars(9), Some(" sandwich"));