# ansi-replace

ANSI-aware string replacement that matches visible text while preserving escape sequences.

## Overview

`ansi-replace` provides utilities for performing find-and-replace operations on strings that contain ANSI escape sequences (e.g., terminal colors and styles). Replacements are matched against the visible text only, while preserving all embedded ANSI sequences in their original positions.

## Usage

Add the dependency to your `Cargo.toml`:

```toml
[dependencies]
ansi-replace = "0.1"
```

To disable regex support, opt out of default features:

```toml
[dependencies]
ansi-replace = { version = "0.1", default-features = false }
```

### Example

```rust
use ansi_replace::AnsiExt;

let colored = "\x1b[31mhello world\x1b[0m";
let result = colored.ansi_replace("hello", "goodbye");
assert_eq!(result, "\x1b[31mgoodbye world\x1b[0m");
```

### Replacer functions

You can use a closure to dynamically produce replacement text:

```rust
use ansi_replace::AnsiExt;
use ansi_replace::replacer::Writable;
use std::ops::Range;
use std::fmt::Write;

let colored = "\x1b[31mhello world\x1b[0m";
let result = colored.ansi_replace("hello", |matched: &str, _range: Range<usize>, dst: &mut Writable| {
    write!(dst, "{}", matched.to_uppercase())
});
assert_eq!(result, "\x1b[31mHELLO world\x1b[0m");
```

### Limited replacements

Use `ansi_replacen` to limit the number of replacements:

```rust
use ansi_replace::AnsiExt;

let text = "\x1b[32mfoo foo foo\x1b[0m";
let result = text.ansi_replacen("foo", "bar", 2);
assert_eq!(result, "\x1b[32mbar bar foo\x1b[0m");
```

## Features

| Feature | Default | Description |
|---------|---------|-------------|
| `regex` | yes | Enables using `&regex::Regex` as a search pattern |

## Minimum Supported Rust Version

The MSRV is **1.80**.

## License

Licensed under either of

- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)

at your option.
