Trait readable::str::HeadTail

pub trait HeadTail {
    // Required method
    fn as_str(&self) -> &str;

    // Provided methods
    fn head(&self, head: usize) -> Head<'_> { ... }
    fn head_dot(&self, head: usize) -> HeadDot<'_> { ... }
    fn tail(&self, tail: usize) -> Tail<'_> { ... }
    fn tail_dot(&self, tail: usize) -> TailDot<'_> { ... }
    fn head_tail(&self, head: usize, tail: usize) -> HeadTailStr<'_> { ... }
    fn head_tail_dot(&self, head: usize, tail: usize) -> HeadTailDot<'_> { ... }
}

Head/Tail characters of a str

This trait provides some functionality for cutting off a string either by the head, tail, or both, with optional ... after/before/in-between.

Anything that implements std::borrow::Borrow<str> can use this trait automatically.

Examples

use readable::HeadTail;

let string = "hello world";
assert_eq!(string.len(), 11);

assert_eq!(            string.head(5), "hello");
assert_eq!(        string.head_dot(5), "hello...");
assert_eq!(            string.tail(5), "world");
assert_eq!(        string.tail_dot(5), "...world");
assert_eq!(    string.head_tail(5, 5), "helloworld");
assert_eq!(string.head_tail_dot(5, 5), "hello...world");

The characters are split as UTF-8 characters, so strings like this will work:

use readable::HeadTail;

let emojis = "🦀🦀🦀🐸🐸🐸";
assert_eq!(emojis.len(), 24);

assert_eq!(            emojis.head(2), "🦀🦀");
assert_eq!(        emojis.head_dot(2), "🦀🦀...");
assert_eq!(            emojis.tail(2), "🐸🐸");
assert_eq!(        emojis.tail_dot(2), "...🐸🐸");
assert_eq!(    emojis.head_tail(2, 2), "🦀🦀🐸🐸");
assert_eq!(emojis.head_tail_dot(2, 2), "🦀🦀...🐸🐸");

Returned “HeadTail” Types

All types returned by this trait can compare with strings without any allocation, e.g:

let emojis = "🦀🦀🦀🐸🐸🐸";
// This comparison isn't allocating anything.
assert_eq!(emojis.head_tail_dot(2, 2), "🦀🦀...🐸🐸");

The head + tail types can selectively show each side:

use readable::str::{HeadTail, HeadTailStr};

let emojis: &str = "🦀🦀🦀🐸🐸🐸";
let headtail: HeadTailStr = emojis.head_tail(1, 1);
assert_eq!(headtail.head(), "🦀");
assert_eq!(headtail.tail(), "🐸");

And they all implement std::fmt::Display, so they can also use .to_string():

use readable::str::{
	// This is the main trait.
	HeadTail,
	// This is the returned struct
	// holding `str` references.
	HeadTailDot
};

let string: &str = "hello world";
let dot: HeadTailDot = string.head_tail_dot(2, 2);

// No allocation needed here.
assert_eq!(dot, "he...ld");

// Now it's an owned String.
let new: String = dot.to_string();
assert_eq!(new, "he...ld");

Required Methods

fn as_str(&self) -> &str

Turn self into a str.

If your type implements std::borrow::Borrow<str>, it will automatically implement HeadTail.

Provided Methods

fn head(&self, head: usize) -> Head<'_>

Return the first head UTF-8 characters of this str.

This will return the full str if head is longer than the actual inner str.

let string = "hello world";
assert_eq!(string.head(5), "hello");

fn head_dot(&self, head: usize) -> HeadDot<'_>

Same as HeadTail::head() but this will allocate a new String ending with ....

This will not allocate and will return the input without ... if head is longer than the actual inner str.

let string = "hello world";
assert_eq!(string.head_dot(5), "hello...");

// No dot appended.
let string = "hello world";
assert_eq!(string.head_dot(11), string);

fn tail(&self, tail: usize) -> Tail<'_>

Return the last tail UTF-8 characters of this str.

This will return the full str if tail is longer than the actual inner str.

let string = "hello world";
assert_eq!(string.tail(5), "world");

fn tail_dot(&self, tail: usize) -> TailDot<'_>

Same as HeadTail::tail() but this allocated a new String ending with ....

This will return the full string without ... if tail is longer than the actual inner str.

let string = "hello world";
assert_eq!(string.tail_dot(5), "...world");

// No dot appended.
let string = "hello world";
assert_eq!(string.tail_dot(11), string);

fn head_tail(&self, head: usize, tail: usize) -> HeadTailStr<'_>

Return the first head UTF-8 characters and last tail UTF-8 characters of this str.

let string = "hello world";
assert_eq!(string.head_tail(5, 5), "helloworld");

// No string allocated for this.
let string = "hello world";
assert_eq!(string.head_tail(6, 5), string);

// Non-ASCII characters.
let sixteen_chars = "🦀🦀🐸🐸";
let four_chars    = "ですけど";

assert_eq!(sixteen_chars.len(), 16);
assert_eq!(four_chars.len(),    12);

assert_eq!(sixteen_chars.head_tail(1, 1), "🦀🐸");
assert_eq!(four_chars.head_tail(1, 1),    "でど");

assert_eq!(sixteen_chars.head_tail(2, 2), sixteen_chars);
assert_eq!(four_chars.head_tail(2, 2),    four_chars);

fn head_tail_dot(&self, head: usize, tail: usize) -> HeadTailDot<'_>

Return the first head UTF-8 characters and last tail UTF-8 characters of this str separated with ....

let string = "hello world";
assert_eq!(string.head_tail_dot(5, 5), "hello...world");

// No dot appended.
let string = "hello world";
assert_eq!(string.head_tail_dot(6, 5), string);

// Non-ASCII characters.
let sixteen_chars = "🦀🦀🐸🐸";
let four_chars    = "ですけど";

assert_eq!(sixteen_chars.len(), 16);
assert_eq!(four_chars.len(),    12);

assert_eq!(sixteen_chars.head_tail_dot(1, 1), "🦀...🐸");
assert_eq!(four_chars.head_tail_dot(1, 1),    "で...ど");

assert_eq!(sixteen_chars.head_tail_dot(3, 3), sixteen_chars);
assert_eq!(four_chars.head_tail_dot(2, 2),    four_chars);

Implementors

impl<T: Borrow<str>> HeadTail for T