Trait ansi_str::AnsiStr

source · [−]
pub trait AnsiStr {

Show 13 methods    fn ansi_get<I>(&self, i: I) -> Option<String>
    where
        I: RangeBounds<usize>;
    fn ansi_cut<I>(&self, i: I) -> String
    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<String>;
    fn ansi_strip_suffix(&self, pat: &str) -> Option<String>;
    fn ansi_split<'a>(&'a self, pat: &'a str) -> AnsiSplit<'a>ⓘNotable traits for AnsiSplit<'a>impl<'a> Iterator for AnsiSplit<'a>    type Item = Cow<'a, str>;;
    fn ansi_split_at(&self, mid: usize) -> (String, String);
    fn ansi_starts_with(&self, pat: &str) -> bool;
    fn ansi_ends_with(&self, pat: &str) -> bool;
    fn ansi_trim(&self) -> String;
    fn ansi_strip(&self) -> String;
    fn ansi_has_any(&self) -> bool;

}
Expand description

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

Required Methods

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()), 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 🌏".to_owned()), v.ansi_get(5..));

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..);

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));

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));

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()));
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()));

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. Unlike trim_end_matches, this method removes the suffix exactly once.

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()));
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()));

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()]);

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.

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());

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"));

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"));

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());

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!");

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

Implementors