Trait StringTransform

Source

pub trait StringTransform<'a> {
    type Iter: Iterator<Item = char>;

    // Required method
    fn transform_chars(&self, chars: Chars<'a>) -> Self::Iter;

    // Provided methods
    fn will_modify(&self, val: &str) -> bool { ... }
    fn transform<'b, T: Into<Cow<'b, str>>>(&self, s: T) -> Cow<'b, str> { ... }
}

Expand description

A factory trait for in-place string transformations.

This trait allows character-iterator adaptors to modify strings in-place. It is implemented by adaptor factories with a single required method, transform_chars, for constructing the adaptors. In return, this trait provides a method, transform, which can apply the transformation to both owned strings and string slices, without allocating when possible.

The in-place operation works by treating the underlying string as a circular buffer. The transform reads characters from the front of the buffer and writes characters to the back of the buffer. Once the transform returns None, the unread characters are deleted and the circular buffer is cast back into a string. Note that the transformation cannot always be applied in place; if the transform ever returns more bytes than it has read, an allocation is required to grow the buffer.

This trait supports copy-on-write optimizations. Implementors can override the StringTransform::will_modify method to short-circuit the transform.

See SimpleTransform for a variant of this trait that is implemented directly by iterator adaptors.

The lifetime 'a refers to the lifetime of the transform method.

Required Associated Types§

Source

type Iter: Iterator<Item = char>

The type after applying this transform to a Chars iterator.

Required Methods§

Source

fn transform_chars(&self, chars: Chars<'a>) -> Self::Iter

Transform the characters of a string.

Provided Methods§

Source

fn will_modify(&self, val: &str) -> bool

A hint to short-circuit string transformations.

If true, the string might be modified by the transform. If false, the string will definitely not be modified by the transform.

Implementors may override this function to facilitate copy-on-write optimizations. The default implementation always returns true, which disables copy-on-write.

Source