Trait ansi_str::AnsiStr

pub trait AnsiStr {
    // Required methods
    fn ansi_get<I>(&self, i: I) -> Option<Cow<'_, str>>
       where I: RangeBounds<usize>;
    fn ansi_cut<I>(&self, i: I) -> Cow<'_, str>
       where I: RangeBounds<usize>;
    fn ansi_is_char_boundary(&self, index: usize) -> bool;
    fn ansi_find(&self, pat: &str) -> Option<usize>;
    fn ansi_strip_prefix(&self, prefix: &str) -> Option<Cow<'_, str>>;
    fn ansi_strip_suffix(&self, pat: &str) -> Option<Cow<'_, str>>;
    fn ansi_split<'a>(&'a self, pat: &'a str) -> AnsiSplit<'a> ;
    fn ansi_split_at(&self, mid: usize) -> (Cow<'_, str>, Cow<'_, str>);
    fn ansi_starts_with(&self, pat: &str) -> bool;
    fn ansi_ends_with(&self, pat: &str) -> bool;
    fn ansi_trim(&self) -> Cow<'_, str>;
    fn ansi_strip(&self) -> Cow<'_, str>;
    fn ansi_has_any(&self) -> bool;
}

AnsiStr represents a list of functions to work with colored strings defined as ANSI control sequences.

Required Methods

fn ansi_get<I>(&self, i: I) -> Option<Cow<'_, str>>where I: RangeBounds<usize>,

Returns a substring of a string.

It preserves accurate style of a substring.

Range is defined in terms of bytes of the string not containing ANSI control sequences (If the string is stripped).

This is the non-panicking alternative to [Self::ansi_cut]. Returns None whenever equivalent indexing operation would panic.

Exceeding the boundaries of the string results in the same result if the upper boundary to be equal to the string length.

If the text doesn’t contains any ansi sequences the function must return result if [str::get] was called.

Examples

Basic usage:

use owo_colors::*;
use ansi_str::AnsiStr;

let v = "🗻 on the 🌏".red().to_string();

assert_eq!(Some("🗻 on".red().to_string().into()), v.ansi_get(0..7));

// indices not on UTF-8 sequence boundaries
assert!(v.ansi_get(1..).is_none());
assert!(v.ansi_get(..13).is_none());

// going over boundries doesn't panic
assert!(v.ansi_get(..std::usize::MAX).is_some());
assert!(v.ansi_get(std::usize::MAX..).is_some());

Text doesn’t contain ansi sequences

use ansi_str::AnsiStr;

let v = "🗻 on the 🌏";

assert_eq!(Some("on the 🌏".into()), v.ansi_get(5..));

fn ansi_cut<I>(&self, i: I) -> Cow<'_, str>where I: RangeBounds<usize>,

Cut makes a sub string, keeping the colors in the substring.

The ANSI escape sequences are ignored when calculating the positions within the string.

Range is defined in terms of bytes of the string not containing ANSI control sequences (If the string is stripped).

Exceeding an upper bound does not panic.

Panics

Panics if a start or end indexes are not on a UTF-8 code point boundary.

Examples

Basic usage:

use owo_colors::*;
use ansi_str::AnsiStr;

let v = "🗻 on the 🌏".red().on_black().to_string();
assert_eq!("🗻", v.ansi_cut(0..4).ansi_strip());
assert_eq!("🗻 on", v.ansi_cut(..7).ansi_strip());
assert_eq!("the 🌏", v.ansi_cut(8..).ansi_strip());

Panics when index is not a valud UTF-8 char

use owo_colors::*;
use ansi_str::AnsiStr;

let v = "🗻 on the 🌏".yellow().to_string();
v.ansi_cut(1..);

fn ansi_is_char_boundary(&self, index: usize) -> bool

Checks that index-th byte is the first byte in a UTF-8 code point sequence or the end of the string.

The index is determined in a string if it would be stripped.

Examples

Basic usage:

use owo_colors::*;
use ansi_str::AnsiStr;

let s = "Löwe 老虎 Léopard".blue().to_string();

assert!(s.ansi_is_char_boundary(0));
// start of `老`
assert!(s.ansi_is_char_boundary(6));
assert!(s.ansi_is_char_boundary(s.ansi_strip().len()));

// second byte of `ö`
assert!(!s.ansi_is_char_boundary(2));

// third byte of `老`
assert!(!s.ansi_is_char_boundary(8));

fn ansi_find(&self, pat: &str) -> Option<usize>

Returns the byte index of the first character of this string slice that matches the pattern, considering the ansi sequences.

Returns None if the pattern doesn’t match.

Examples

Basic usage:

use owo_colors::*;
use ansi_str::AnsiStr;

let s = "Löwe 老虎 Léopard Gepardi".red().on_black().to_string();

assert_eq!(s.ansi_find("L"), Some(0));
assert_eq!(s.ansi_find("é"), Some(14));
assert_eq!(s.ansi_find("pard"), Some(17));

fn ansi_strip_prefix(&self, prefix: &str) -> Option<Cow<'_, str>>

Returns a string with the prefix removed, considering the ansi sequences.

If the string starts with the pattern prefix, returns substring after the prefix, wrapped in Some.

If the string does not start with prefix, returns None.

Examples

Basic usage:

use owo_colors::*;
use ansi_str::AnsiStr;

assert_eq!(
    "foo:bar".red().to_string().ansi_strip_prefix("foo:"),
    Some("bar".red().to_string().into()),
);
assert_eq!(
    "foo:bar".red().to_string().ansi_strip_prefix("bar"),
    None,
);
assert_eq!(
    "foofoo".red().to_string().ansi_strip_prefix("foo"),
    Some("foo".red().to_string().into()),
);

fn ansi_strip_suffix(&self, pat: &str) -> Option<Cow<'_, str>>

Returns a string slice with the suffix removed, considering the ansi sequences.

If the string ends with the pattern suffix, returns the substring before the suffix, wrapped in Some.

If the string does not end with suffix, returns None.

Examples

Basic usage:

use owo_colors::*;
use ansi_str::AnsiStr;

assert_eq!("bar:foo".red().to_string().ansi_strip_suffix(":foo"), Some("bar".red().to_string().into()));
assert_eq!("bar:foo".red().to_string().ansi_strip_suffix("bar"), None);
assert_eq!("foofoo".red().to_string().ansi_strip_suffix("foo"), Some("foo".red().to_string().into()));

fn ansi_split<'a>(&'a self, pat: &'a str) -> AnsiSplit<'a>

An iterator over substrings of the string, separated by characters matched by a pattern. While keeping colors in substrings.

Examples

Basic usage:

use owo_colors::*;
use ansi_str::AnsiStr;

let text = "Mary had a little lamb".red().to_string();

let words: Vec<_> = text.ansi_split(" ").collect();

assert_eq!(
    words,
    [
        "Mary".red().to_string(),
        "had".red().to_string(),
        "a".red().to_string(),
        "little".red().to_string(),
        "lamb".red().to_string(),
    ]
);

let v: Vec<_> = "".ansi_split("X").collect();
assert_eq!(v, [""]);

let text = "lionXXtigerXleopard".red().to_string();
let v: Vec<_> = text.ansi_split("X").collect();
assert_eq!(v, ["lion".red().to_string(), "".to_string(), "tiger".red().to_string(), "leopard".red().to_string()]);

let text = "lion::tiger::leopard".red().to_string();
let v: Vec<_> = text.ansi_split("::").collect();
assert_eq!(v, ["lion".red().to_string(), "tiger".red().to_string(), "leopard".red().to_string()]);

fn ansi_split_at(&self, mid: usize) -> (Cow<'_, str>, Cow<'_, str>)

Divide one string into two at an index. While considering colors.

The argument, mid, should be a byte offset from the start of the string. It must also be on the boundary of a UTF-8 code point.

The two strings returned go from the start of the string to mid, and from mid to the end of the string.

Panics

It might panic in case mid is not on the boundry of a UTF-8 code point.

Examples

Basic usage:

use owo_colors::*;
use ansi_str::AnsiStr;

let s = "Per Martin-Löf".red().on_black().to_string();

let (first, last) = s.ansi_split_at(3);

assert_eq!("Per", first.ansi_strip());
assert_eq!(" Martin-Löf", last.ansi_strip());

Panic

use ansi_str::AnsiStr;
use owo_colors::*;

let s = "Per Martin-Löf".red().on_black().to_string();

s.ansi_split_at(13);

fn ansi_starts_with(&self, pat: &str) -> bool

Returns true if the given pattern matches a prefix of this string slice. Ignoring the ansi sequences.

Returns false if it does not.

Examples

Basic usage:

use owo_colors::*;
use ansi_str::AnsiStr;

let bananas = "bananas".red().on_black().to_string();

assert!(bananas.ansi_starts_with("bana"));
assert!(!bananas.ansi_starts_with("nana"));

fn ansi_ends_with(&self, pat: &str) -> bool

Returns true if the given pattern matches a suffix of this string slice. Ignoring the ansi sequences.

Returns false if it does not.

Examples

Basic usage:

use owo_colors::*;
use ansi_str::AnsiStr;

let bananas = "bananas".red().on_black().to_string();

assert!(bananas.ansi_ends_with("anas"));
assert!(!bananas.ansi_ends_with("nana"));

fn ansi_trim(&self) -> Cow<'_, str>

Returns a string slice with leading and trailing whitespace removed. Ignoring the ansi sequences.

Examples

Basic usage:

use owo_colors::*;
use ansi_str::AnsiStr;

let s = " Hello\tworld\t".red().to_string();

assert_eq!("Hello\tworld".red().to_string(), s.ansi_trim());

fn ansi_strip(&self) -> Cow<'_, str>

Returns a string with all ANSI sequences removed.

Examples

Basic usage:

use owo_colors::*;
use ansi_str::AnsiStr;

let hello = "Hello World!".red().on_black().to_string();

assert_eq!(hello.ansi_strip(), "Hello World!");

fn ansi_has_any(&self) -> bool

Returns true if a string contains any ansi sequences.

Returns false if it does not.

Examples

Basic usage:

use owo_colors::*;
use ansi_str::AnsiStr;

assert!(!"Hi".ansi_has_any());
assert!("Hi".red().to_string().ansi_has_any());

Implementations on Foreign Types

impl AnsiStr for str

fn ansi_get<I>(&self, i: I) -> Option<Cow<'_, str>>where I: RangeBounds<usize>,

fn ansi_cut<I>(&self, i: I) -> Cow<'_, str>where I: RangeBounds<usize>,

fn ansi_is_char_boundary(&self, index: usize) -> bool

fn ansi_find(&self, pat: &str) -> Option<usize>

fn ansi_strip_prefix(&self, prefix: &str) -> Option<Cow<'_, str>>

fn ansi_strip_suffix(&self, suffix: &str) -> Option<Cow<'_, str>>

fn ansi_split_at(&self, mid: usize) -> (Cow<'_, str>, Cow<'_, str>)

fn ansi_starts_with(&self, pat: &str) -> bool

fn ansi_ends_with(&self, pat: &str) -> bool

fn ansi_trim(&self) -> Cow<'_, str>

fn ansi_strip(&self) -> Cow<'_, str>

fn ansi_has_any(&self) -> bool

fn ansi_split<'a>(&'a self, pat: &'a str) -> AnsiSplit<'a>

impl AnsiStr for String

fn ansi_get<I>(&self, i: I) -> Option<Cow<'_, str>>where I: RangeBounds<usize>,

fn ansi_cut<I>(&self, i: I) -> Cow<'_, str>where I: RangeBounds<usize>,

fn ansi_is_char_boundary(&self, index: usize) -> bool

fn ansi_find(&self, pat: &str) -> Option<usize>

fn ansi_strip_prefix(&self, prefix: &str) -> Option<Cow<'_, str>>

fn ansi_strip_suffix(&self, suffix: &str) -> Option<Cow<'_, str>>

fn ansi_split_at(&self, mid: usize) -> (Cow<'_, str>, Cow<'_, str>)

fn ansi_starts_with(&self, pat: &str) -> bool

fn ansi_ends_with(&self, pat: &str) -> bool

fn ansi_trim(&self) -> Cow<'_, str>

fn ansi_strip(&self) -> Cow<'_, str>

fn ansi_has_any(&self) -> bool

fn ansi_split<'a>(&'a self, pat: &'a str) -> AnsiSplit<'a>

Implementors