### Encode UTF-8 bytes into HTML entities

Source: https://context7.com/fefit/htmlentity/llms.txt

Demonstrates how to use the `encode` function to convert UTF-8 byte slices into HTML entities. It shows examples of using `EncodeType::NamedOrHex` and `CharacterSet::HtmlAndNonASCII`, and how to consume the `EncodedData` result as a String, bytes, or characters.

```APIDOC
## encode — Encode UTF-8 bytes into HTML entities

Encodes characters in a UTF-8 byte slice into HTML entities according to a chosen `EncodeType` (format) and `CharacterSet` (which characters to encode). Returns `EncodedData<'_>`, which can be converted to a `String`, `Vec<u8>`, or `Vec<char>` via the `ICodedDataTrait` methods.

```rust
use htmlentity::entity::{encode, EncodeType, CharacterSet, ICodedDataTrait};
use htmlentity::types::AnyhowResult;

fn main() -> AnyhowResult<()> {
    let html = "<div class='htmlentity'>Hello!世界!</div>";

    // Named encoding for HTML special characters and non-ASCII characters.
    // Non-ASCII chars without named entities fall back to hex.
    let encoded = encode(
        html.as_bytes(),
        &EncodeType::NamedOrHex,
        &CharacterSet::HtmlAndNonASCII,
    );

    let result = encoded.to_string()?;
    // "&lt;div class='htmlentity'&gt;Hello!&#x4e16;&#x754c;!&lt;/div&gt;"
    println!("{}", result);

    // Consume as raw bytes
    let bytes = encoded.to_bytes();
    assert_eq!(bytes, result.as_bytes());

    // Consume as Vec<char>
    let chars = encoded.to_chars()?;
    assert_eq!(chars.iter().collect::<String>(), result);

    // Iterate byte-by-byte; second tuple element is Some((entity_idx, byte_within_entity))
    // when the byte is part of an encoded entity, None otherwise
    for (byte, entity_pos) in encoded.into_iter() {
        let _ = (byte, entity_pos);
    }
    Ok(())
}
```
```

--------------------------------

### Decode HTML entities in UTF-8 bytes

Source: https://context7.com/fefit/htmlentity/llms.txt

Explains how to use the `decode` function to parse HTML entities from UTF-8 byte slices. It covers handling errors for invalid entities and consuming the `DecodedData` result as a String, bytes, or characters, with an example of encoding and then decoding.

```APIDOC
## decode — Decode HTML entities in UTF-8 bytes

Parses HTML entities in a UTF-8 byte slice and returns `DecodedData<'_>`. Invalid or unrecognised entities are recorded in an error list rather than causing a panic. The result supports the same `to_string()` / `to_bytes()` / `to_chars()` conversions.

```rust
use htmlentity::entity::{encode, decode, EncodeType, CharacterSet, ICodedDataTrait};
use htmlentity::types::AnyhowResult;

fn main() -> AnyhowResult<()> {
    let original = "<div class='header'></div>";

    // First encode, then decode back to the original
    let encoded_bytes = encode(
        original.as_bytes(),
        &EncodeType::Named,
        &CharacterSet::SpecialChars,
    ).to_bytes();
    // b"&lt;div class=&apos;header&apos;&gt;&lt;/div&gt;"

    let decoded = decode(&encoded_bytes);

    // Check for decode errors (e.g. malformed entities)
    assert!(decoded.is_ok(), "unexpected errors: {:?}", decoded.get_errors());
    assert_eq!(decoded.entity_count(), 6);

    assert_eq!(decoded.to_string()?,
 original);
    assert_eq!(decoded.to_bytes(), original.as_bytes());
    assert_eq!(decoded.to_chars()?,
 original.chars().collect::<Vec<char>>());

    // Iterate byte-by-byte over the decoded output
    for (idx, (byte, _)) in decoded.into_iter().enumerate() {
        assert_eq!(*byte, original.as_bytes()[idx]);
    }
    Ok(())
}
```
```

--------------------------------

### Encode and Decode HTML Entities in Rust

Source: https://github.com/fefit/htmlentity/blob/main/README.md

Demonstrates the core encoding and decoding functionalities of the htmlentity library. Shows how to encode a string into HTML entities using different formats and character sets, and then decode it back. Includes assertions to verify the correctness of the operations.

```rust
use htmlentity::entity::{ encode, decode, EncodeType, CharacterSet, ICodedDataTrait };
use htmlentity::types::{ AnyhowResult, Byte };
fn main() -> AnyhowResult<()> {
  let html = "<div name='htmlentity'>Hello!世界!</div>";
  let html_after_encoded = "&lt;div name='htmlentity'&gt;Hello!&#x4e16;&#x754c;!&lt;/div&gt;";
  // encode
  let encoded_data = encode(
    html.as_bytes(), 
    // encode format
    &EncodeType::NamedOrHex,
    // charcters need to be encoded 
    &CharacterSet::HtmlAndNonASCII
  );
  assert_eq!(encoded_data.to_bytes(), html_after_encoded.as_bytes());
  assert_eq!(encoded_data.to_string()?, String::from(html_after_encoded));
  let char_list = String::from(html_after_encoded).chars().collect::<Vec<char>>();
  assert_eq!(encoded_data.to_chars()?, char_list);
  // decode
  let bytes = encoded_data.into_iter().map(|(byte, _)| *byte).collect::<Vec<Byte>>();
  let decoded_data = decode(&bytes);
  assert_eq!(decoded_data.to_bytes(), html.as_bytes());
  assert_eq!(decoded_data.to_string()?, String::from(html));
  let char_list = String::from(html).chars().collect::<Vec<char>>();
  assert_eq!(decoded_data.to_chars()?, char_list);
  // shortcut usage
  assert_eq(
    encode(
      html.as_bytes(), 
      &EncodeType::NamedOrHex,
      &CharacterSet::HtmlAndNonASCII,
    ).to_string()?,
    String::from(html)
  );
  Ok(())
}
```

--------------------------------

### Encode with Different Character Sets

Source: https://context7.com/fefit/htmlentity/llms.txt

Demonstrates encoding text using various predefined character sets like Html, SpecialChars, NonASCII, HtmlAndNonASCII, SpecialCharsAndNonASCII, and All. Also shows direct membership checking with `contains`.

```Rust
use htmlentity::entity::{encode, CharacterSet, EncodeType, ICodedDataTrait};
use htmlentity::types::AnyhowResult;

fn main() -> AnyhowResult<()> {
    let input = "<div class='x'>&nbsp;"世界"</div>";

    // Html: encodes '<', '>', '&' only
    println!("{}", encode(input.as_bytes(), &EncodeType::Named, &CharacterSet::Html).to_string()?);
    // → &lt;div class='x'&gt;&amp;nbsp;"世界"&lt;/div&gt;

    // SpecialChars: encodes '<', '>', '&', '\'', '"'
    println!("{}", encode(input.as_bytes(), &EncodeType::Named, &CharacterSet::SpecialChars).to_string()?);
    // → &lt;div class=&apos;x&apos;&gt;&amp;nbsp;&quot;世界&quot;&lt;/div&gt;

    // NonASCII: encodes code points > 0xff
    println!("{}", encode(input.as_bytes(), &EncodeType::NamedOrHex, &CharacterSet::NonASCII).to_string()?);

    // HtmlAndNonASCII: combines Html + NonASCII
    println!("{}", encode(input.as_bytes(), &EncodeType::NamedOrHex, &CharacterSet::HtmlAndNonASCII).to_string()?);

    // SpecialCharsAndNonASCII: combines SpecialChars + NonASCII
    println!("{}", encode(input.as_bytes(), &EncodeType::NamedOrHex, &CharacterSet::SpecialCharsAndNonASCII).to_string()?);

    // All: encodes every character
    println!("{}", encode(input.as_bytes(), &EncodeType::NamedOrHex, &CharacterSet::All).to_string()?);

    // Check membership directly
    assert!(CharacterSet::Html.contains(&'<'));
    assert!(!CharacterSet::Html.contains(&'\'''));
    assert!(CharacterSet::SpecialChars.contains(&'\'''));
    Ok(())
}
```

--------------------------------

### Decode HTML Entities and Handle Errors

Source: https://context7.com/fefit/htmlentity/llms.txt

Shows how to decode HTML entities and inspect the result. It covers checking for success, counting entities, retrieving errors, and converting the result to a string or owned bytes.

```Rust
use htmlentity::entity::{decode, ICodedDataTrait};
use htmlentity::types::AnyhowResult;
use std::borrow::Cow;

fn main() -> AnyhowResult<()> {
    // Valid input
    let mut data = decode(b"&lt;div&gt;&amp;");
    assert!(data.is_ok());
    assert_eq!(data.entity_count(), 3);
    assert_eq!(data.to_string()?, "<div>&");

    // Input with an invalid entity — decode continues, errors are recorded
    let data = decode(b"&#q123;");
    assert!(!data.is_ok());
    assert_eq!(data.get_errors().len(), 1);
    assert_eq!(data.entity_count(), 0);

    // `bytes()` returns Cow::Borrowed when no entities were resolved
    assert_eq!(data.bytes(), Cow::Borrowed(b"&#q123;".as_ref()));

    // Materialise everything into an owned Vec<u8>
    let mut data = decode(b"&lt;b&gt;");
    data.to_owned(); // flattens entities into inner_bytes
    let owned: Vec<u8> = data.into_bytes();
    assert_eq!(owned, b"<b>");
    Ok(())
}
```

--------------------------------

### Encode and Access Encoded Data

Source: https://context7.com/fefit/htmlentity/llms.txt

Illustrates encoding HTML content and accessing the encoded result. It covers entity counting, byte-level access, borrowing as `Cow`, and flattening entities into owned bytes.

```Rust
use htmlentity::entity::{encode, EncodeType, CharacterSet, ICodedDataTrait};
use htmlentity::types::AnyhowResult;
use std::borrow::Cow;

fn main() -> AnyhowResult<()> {
    let html = "<b>hi</b>";
    let mut encoded = encode(html.as_bytes(), &EncodeType::Named, &CharacterSet::Html);

    assert_eq!(encoded.entity_count(), 4); // <, >, <, >
    assert_eq!(encoded.bytes_len(), "&lt;b&gt;hi&lt;/b&gt;".len());

    // Random access to individual bytes in the encoded output
    let expected = b"&lt;b&gt;hi&lt;/b&gt;";
    for i in 0..encoded.bytes_len() {
        assert_eq!(encoded.byte(i), Some(&expected[i]));
    }

    // Borrow as Cow — Cow::Borrowed when no entities; Cow::Owned when entities present
    let cow = encoded.bytes();
    assert!(matches!(cow, Cow::Owned(_)));

    // Flatten entities into owned bytes
    encoded.to_owned();
    assert_eq!(encoded.entity_count(), 0);
    assert_eq!(encoded.into_bytes(), expected.to_vec());
    Ok(())
}
```

--------------------------------

### Streaming encode/decode directly into a buffer

Source: https://context7.com/fefit/htmlentity/llms.txt

Introduces the `encode_to` and `decode_to` functions, which are streaming variants for encoding and decoding HTML entities directly into a caller-supplied buffer. This is useful for avoiding intermediate allocations when building larger data payloads.

```APIDOC
## encode_to / decode_to — Encode/decode directly into a buffer

Streaming variants that write output directly into a caller-supplied `Vec<u8>`, avoiding an intermediate allocation. Useful when building up larger payloads.

```rust
use htmlentity::entity::{encode_to, decode_to, EncodeType, CharacterSet};
use htmlentity::types::ByteList;

fn main() {
    let html = "<div class='header'></div>";
    let mut encoded_buf: ByteList = Vec::new();

    encode_to(
        html.as_bytes(),
        &EncodeType::Named,
        &CharacterSet::SpecialChars,
        &mut encoded_buf,
    );
    assert_eq!(encoded_buf, b"&lt;div class=&apos;header&apos;&gt;&lt;/div&gt;");

    let mut decoded_buf: ByteList = Vec::new();
    decode_to(&encoded_buf, &mut decoded_buf);
    assert_eq!(decoded_buf, html.as_bytes());
}
```
```

--------------------------------

### `Entity::decode` / `Entity::decode_chars`

Source: https://context7.com/fefit/htmlentity/llms.txt

These methods decode a single raw HTML entity, accepting its inner content (between `&` and `;`). They support named, hexadecimal, and decimal entity formats and return a `AnyhowResult<char>`. `decode_chars` operates on a character slice.

```APIDOC
## `Entity::decode` / `Entity::decode_chars` — Decode a single raw entity

Decodes a single HTML entity given its inner bytes/chars (i.e., the content between `&` and `;`). All three formats — named, hexadecimal, and decimal — are supported. Returns `AnyhowResult<char>`.

```rust
use htmlentity::entity::Entity;
use htmlentity::types::AnyhowResult;

fn main() -> AnyhowResult<()> {
    // Named entity bytes (without '&' and ';')
    assert_eq!(Entity::decode(b"lt")?,   '<');
    assert_eq!(Entity::decode(b"amp")?,  '&');
    assert_eq!(Entity::decode(b"nbsp")?, '\u{a0}');

    // Hexadecimal numeric reference
    assert_eq!(Entity::decode(b"#x3c")?,   '<');
    assert_eq!(Entity::decode(b"#x4e16")?, '世');

    // Decimal numeric reference
    assert_eq!(Entity::decode(b"#60")?,   '<');
    assert_eq!(Entity::decode(b"#8594")?, '→');

    // Character-slice variant
    assert_eq!(Entity::decode_chars(&['l', 't'])?, '<');

    // Errors on unknown named entity
    assert!(Entity::decode(b"unknown_entity").is_err());
    // Errors on empty input
    assert!(Entity::decode(b"").is_err());
    Ok(())
}
```
```

--------------------------------

### `decode_chars` / `decode_chars_to`

Source: https://context7.com/fefit/htmlentity/llms.txt

These functions decode HTML entities within a slice of characters. `decode_chars` returns a `Cow<'_, [char]>`, which is borrowed if no entities are found and owned otherwise. `decode_chars_to` writes the decoded characters into a provided `Vec<char>` buffer.

```APIDOC
## `decode_chars` / `decode_chars_to` — Decode HTML entities in a `&[char]` slice

Character-slice variants of `decode`. `decode_chars` returns `Cow<'_, [char]>` (borrowed when no entities are found); `decode_chars_to` writes into an existing `Vec<char>` buffer.

```rust
use htmlentity::entity::{decode_chars, decode_chars_to};
use std::borrow::Cow;

fn main() {
    let input: Vec<char> = "a&lt;b".chars().collect();

    // Returns Cow::Borrowed when nothing changes, Cow::Owned otherwise
    let result = decode_chars(&input);
    assert_eq!(result.iter().collect::<String>(), "a<b");

    // All three entity formats are supported
    let hex: Vec<char>     = "a&#x3c;b".chars().collect();
    let decimal: Vec<char> = "a&#60;b".chars().collect();
    let expected = Cow::from(vec!['a', '<', 'b']);
    assert_eq!(decode_chars(&hex),     expected);
    assert_eq!(decode_chars(&decimal), expected);

    // Write into an existing buffer
    let mut buf: Vec<char> = Vec::new();
    decode_chars_to(&"a&lt;b".chars().collect::<Vec<char>>(), &mut buf);
    assert_eq!(buf, vec!['a', '<', 'b']);
}
```
```

--------------------------------

### Custom-Filter Encode Directly into a Buffer

Source: https://context7.com/fefit/htmlentity/llms.txt

Utilize `encode_with_to` for a zero-allocation output strategy when encoding with a custom filter. This function writes directly into a provided buffer.

```Rust
use htmlentity::entity::{encode_with_to, CharacterSet, EncodeType, ICodedDataTrait};
use htmlentity::types::ByteList;
use htmlentity::types::AnyhowResult;

fn main() -> AnyhowResult<()> {
    let html = "<div class='header'></div>";
    let charset = CharacterSet::SpecialChars;
    let mut data: ByteList = vec![];

    encode_with_to(
        html.as_bytes(),
        &EncodeType::Named,
        |ch, encode_type| charset.filter(ch, encode_type),
        &mut data,
    );

    assert_eq!(data, b"&lt;div class=&apos;header&apos;&gt;&lt;/div&gt;");
    Ok(())
}
```

--------------------------------

### `encode_with_to` — Custom-filter encode directly into a buffer

Source: https://context7.com/fefit/htmlentity/llms.txt

Encodes a byte slice into a provided buffer using a custom filter, similar to `encode_with`, but optimized for zero-allocation output.

```APIDOC
## `encode_with_to` — Custom-filter encode directly into a buffer

Combines the flexibility of `encode_with` with the zero-allocation output strategy of `encode_to`.

### Request Example
```rust
use htmlentity::entity::{encode_with_to, CharacterSet, EncodeType, ICodedDataTrait};
use htmlentity::types::ByteList;
use htmlentity::types::AnyhowResult;

fn main() -> AnyhowResult<()> {
    let html = "<div class='header'></div>";
    let charset = CharacterSet::SpecialChars;
    let mut data: ByteList = vec![];

    encode_with_to(
        html.as_bytes(),
        &EncodeType::Named,
        |ch, encode_type| charset.filter(ch, encode_type),
        &mut data,
    );

    assert_eq!(data, b"&lt;div class=&apos;header&apos;&gt;&lt;/div&gt;");
    Ok(())
}
```
```

--------------------------------

### Encode/Decode Directly Into a Buffer

Source: https://context7.com/fefit/htmlentity/llms.txt

Streaming variants for encoding and decoding that write output directly into a caller-supplied Vec<u8>, avoiding intermediate allocations. Useful for building larger payloads.

```rust
use htmlentity::entity::{encode_to, decode_to, EncodeType, CharacterSet};
use htmlentity::types::ByteList;

fn main() {
    let html = "<div class='header'></div>";
    let mut encoded_buf: ByteList = Vec::new();

    encode_to(
        html.as_bytes(),
        &EncodeType::Named,
        &CharacterSet::SpecialChars,
        &mut encoded_buf,
    );
    assert_eq!(encoded_buf, b"&lt;div class=&apos;header&apos;&gt;&lt;/div&gt;");

    let mut decoded_buf: ByteList = Vec::new();
    decode_to(&encoded_buf, &mut decoded_buf);
    assert_eq!(decoded_buf, html.as_bytes());
}
```

--------------------------------

### `encode_with` — Encode with a custom per-character filter

Source: https://context7.com/fefit/htmlentity/llms.txt

Encodes a byte slice using a provided closure for per-character control over encoding. The closure can selectively encode characters and override entity formats.

```APIDOC
## `encode_with` — Encode with a custom per-character filter

Accepts a closure `|ch: &char, encode_type: &EncodeType| -> EncodeFilterReturnData` for complete per-character control. The closure returns `(should_encode: bool, override_entity: Option<(EntityType, Cow<[u8]>)>)`, allowing selective encoding and format overrides on a per-character basis.

### Request Example
```rust
use htmlentity::entity::{encode_with, encode_char, CharacterSet, EncodeType, EntityType, ICodedDataTrait};
use htmlentity::types::AnyhowResult;
use std::borrow::Cow;

fn main() -> AnyhowResult<()> {
    let html = "<div class='header'></div>";
    let charset = CharacterSet::SpecialChars;

    // Encode everything in SpecialChars, but force single quotes to decimal encoding
    let encoded = encode_with(html.as_bytes(), &EncodeType::NamedOrDecimal, |ch, encode_type| {
        if *ch == '\'' {
            // Override: always use decimal entity &#39; for single quotes
            return (true, Some((EntityType::Decimal, Cow::Owned(b"39".to_vec()))));
        }
        charset.filter(ch, encode_type)
    });

    assert_eq!(
        encoded.to_string()?,
        "&lt;div class=&#39;header&#39;&gt;&lt;/div&gt;"
    );

    // Exclude a specific character from encoding entirely
    let encoded2 = encode_with(html.as_bytes(), &EncodeType::Named, |ch, _| {
        if *ch == '<' {
            return (false, None); // do NOT encode '<'
        }
        charset.filter(ch, &EncodeType::Named)
    });
    // '<' is left as-is; '>', '&', '\'' are encoded
    println!("{}", encoded2.to_string()?);
    Ok(())
}
```
```

--------------------------------

### Decode HTML Entities in Character Slices

Source: https://context7.com/fefit/htmlentity/llms.txt

Use `decode_chars` for a borrowed or owned result, or `decode_chars_to` to write into an existing buffer. Supports named, hexadecimal, and decimal entity formats.

```rust
use htmlentity::entity::{decode_chars, decode_chars_to};
use std::borrow::Cow;

fn main() {
    let input: Vec<char> = "a&lt;b".chars().collect();

    // Returns Cow::Borrowed when nothing changes, Cow::Owned otherwise
    let result = decode_chars(&input);
    assert_eq!(result.iter().collect::<String>(), "a<b");

    // All three entity formats are supported
    let hex: Vec<char>     = "a&#x3c;b".chars().collect();
    let decimal: Vec<char> = "a&#60;b".chars().collect();
    let expected = Cow::from(vec!['a', '<', 'b']);
    assert_eq!(decode_chars(&hex),     expected);
    assert_eq!(decode_chars(&decimal), expected);

    // Write into an existing buffer
    let mut buf: Vec<char> = Vec::new();
    decode_chars_to(&"a&lt;b".chars().collect::<Vec<char>>(), &mut buf);
    assert_eq!(buf, vec!['a', '<', 'b']);
}
```

--------------------------------

### Decode HTML Entities in UTF-8 Bytes

Source: https://context7.com/fefit/htmlentity/llms.txt

Parses HTML entities in a UTF-8 byte slice, returning DecodedData. Invalid entities are recorded as errors. The result supports String, bytes, and Vec<char> conversions.

```rust
use htmlentity::entity::{encode, decode, EncodeType, CharacterSet, ICodedDataTrait};
use htmlentity::types::AnyhowResult;

fn main() -> AnyhowResult<()> {
    let original = "<div class='header'></div>";

    // First encode, then decode back to the original
    let encoded_bytes = encode(
        original.as_bytes(),
        &EncodeType::Named,
        &CharacterSet::SpecialChars,
    ).to_bytes();
    // b"&lt;div class=&apos;header&apos;&gt;&lt;/div&gt;"

    let decoded = decode(&encoded_bytes);

    // Check for decode errors (e.g. malformed entities)
    assert!(decoded.is_ok(), "unexpected errors: {:?}", decoded.get_errors());
    assert_eq!(decoded.entity_count(), 6);

    assert_eq!(decoded.to_string()?,
 original);
    assert_eq!(decoded.to_bytes(), original.as_bytes());
    assert_eq!(decoded.to_chars()?,
 original.chars().collect::<Vec<char>>());

    // Iterate byte-by-byte over the decoded output
    for (idx, (byte, _)) in decoded.into_iter().enumerate() {
        assert_eq!(*byte, original.as_bytes()[idx]);
    }
    Ok(())
}
```

--------------------------------

### Encode with Custom Per-Character Filter

Source: https://context7.com/fefit/htmlentity/llms.txt

Use `encode_with` for complete per-character control over HTML entity encoding. It accepts a closure that can selectively encode characters or override the entity format.

```Rust
use htmlentity::entity::{encode_with, encode_char, CharacterSet, EncodeType, EntityType, ICodedDataTrait};
use htmlentity::types::AnyhowResult;
use std::borrow::Cow;

fn main() -> AnyhowResult<()> {
    let html = "<div class='header'></div>";
    let charset = CharacterSet::SpecialChars;

    // Encode everything in SpecialChars, but force single quotes to decimal encoding
    let encoded = encode_with(html.as_bytes(), &EncodeType::NamedOrDecimal, |ch, encode_type| {
        if *ch == '\'' {
            // Override: always use decimal entity &#39; for single quotes
            return (true, Some((EntityType::Decimal, Cow::Owned(b"39".to_vec()))));
        }
        charset.filter(ch, encode_type)
    });

    assert_eq!(
        encoded.to_string()?,
        "&lt;div class=&#39;header&#39;&gt;&lt;/div&gt;"
    );

    // Exclude a specific character from encoding entirely
    let encoded2 = encode_with(html.as_bytes(), &EncodeType::Named, |ch, _| {
        if *ch == '<' {
            return (false, None); // do NOT encode '<'
        }
        charset.filter(ch, &EncodeType::Named)
    });
    // '<' is left as-is; '>', '&', '\'' are encoded
    println!("{}", encoded2.to_string()?);
    Ok(())
}
```

--------------------------------

### Decode Single Raw HTML Entity

Source: https://context7.com/fefit/htmlentity/llms.txt

Use `Entity::decode` for byte slices or `Entity::decode_chars` for character slices to decode a single entity. Supports named, hexadecimal, and decimal formats. Returns an error for unknown or empty entities.

```rust
use htmlentity::entity::Entity;
use htmlentity::types::AnyhowResult;

fn main() -> AnyhowResult<()> {
    // Named entity bytes (without '&' and ';')
    assert_eq!(Entity::decode(b"lt")?,   '<');
    assert_eq!(Entity::decode(b"amp")?,  '&');
    assert_eq!(Entity::decode(b"nbsp")?, '\u{a0}');

    // Hexadecimal numeric reference
    assert_eq!(Entity::decode(b"#x3c")?,   '<');
    assert_eq!(Entity::decode(b"#x4e16")?, '世');

    // Decimal numeric reference
    assert_eq!(Entity::decode(b"#60")?,   '<');
    assert_eq!(Entity::decode(b"#8594")?, '→');

    // Character-slice variant
    assert_eq!(Entity::decode_chars(&['l', 't'])?, '<');

    // Errors on unknown named entity
    assert!(Entity::decode(b"unknown_entity").is_err());
    // Errors on empty input
    assert!(Entity::decode(b"").is_err());
    Ok(())
}
```

--------------------------------

### Encode UTF-8 Bytes to HTML Entities

Source: https://context7.com/fefit/htmlentity/llms.txt

Encodes characters in a UTF-8 byte slice into HTML entities using specified encoding type and character set. The result can be consumed as a String, bytes, or Vec<char>.

```rust
use htmlentity::entity::{encode, EncodeType, CharacterSet, ICodedDataTrait};
use htmlentity::types::AnyhowResult;

fn main() -> AnyhowResult<()> {
    let html = "<div class='htmlentity'>Hello!世界!</div>";

    // Named encoding for HTML special characters and non-ASCII characters.
    // Non-ASCII chars without named entities fall back to hex.
    let encoded = encode(
        html.as_bytes(),
        &EncodeType::NamedOrHex,
        &CharacterSet::HtmlAndNonASCII,
    );

    let result = encoded.to_string()?;
    // "&lt;div class='htmlentity'&gt;Hello!&#x4e16;&#x754c;!&lt;/div&gt;"
    println!("{}", result);

    // Consume as raw bytes
    let bytes = encoded.to_bytes();
    assert_eq!(bytes, result.as_bytes());

    // Consume as Vec<char>
    let chars = encoded.to_chars()?;
    assert_eq!(chars.iter().collect::<String>(), result);

    // Iterate byte-by-byte; second tuple element is Some((entity_idx, byte_within_entity))
    // when the byte is part of an encoded entity, None otherwise
    for (byte, entity_pos) in encoded.into_iter() {
        let _ = (byte, entity_pos);
    }
    Ok(())
}
```

--------------------------------

### Control HTML Entity Encoding Format

Source: https://context7.com/fefit/htmlentity/llms.txt

The `EncodeType` enum dictates the output format for HTML entity encoding. Options include `Named`, `Hex`, `Decimal`, `NamedOrHex`, and `NamedOrDecimal`, allowing fallback to numeric formats when named entities are unavailable.

```rust
use htmlentity::entity::{encode, EncodeType, CharacterSet, ICodedDataTrait};
use htmlentity::types::AnyhowResult;

fn main() -> AnyhowResult<()> {
    let input = "<©>".as_bytes(); // © = U+00A9, has named entity &copy;

    // Named only — uses &lt; / &copy; / &gt;
    println!("{}", encode(input, &EncodeType::Named,          &CharacterSet::All).to_string()?);

    // Hex only — uses &#x3c; / &#xa9; / &#x3e;
    println!("{}", encode(input, &EncodeType::Hex,            &CharacterSet::All).to_string()?);

    // Decimal only — uses &#60; / &#169; / &#62;
    println!("{}", encode(input, &EncodeType::Decimal,        &CharacterSet::All).to_string()?);

    // Named, fallback to hex — uses &lt; / &copy; / &gt;
    println!("{}", encode(input, &EncodeType::NamedOrHex,     &CharacterSet::All).to_string()?);

    // Named, fallback to decimal
    println!("{}", encode(input, &EncodeType::NamedOrDecimal, &CharacterSet::All).to_string()?);

    Ok(())
}
```

--------------------------------

### `encode_char` — Encode a single character into a `CharEntity`

Source: https://context7.com/fefit/htmlentity/llms.txt

Encodes a single character into a `CharEntity` struct based on the specified `EncodeType`. Handles named, decimal, and hexadecimal entities, with fallbacks.

```APIDOC
## `encode_char` — Encode a single character into a `CharEntity`

Encodes a single `char` into a `CharEntity` struct for a given `EncodeType`. Returns `None` if the character has no named entity and the format is `Named` (without a numeric fallback). `CharEntity` can be rendered to a `String` via its `to_string()` method.

### Request Example
```rust
use htmlentity::entity::{encode_char, EncodeType};

fn main() {
    // Named entity
    let entity = encode_char(&'<', &EncodeType::Named).unwrap();
    assert_eq!(entity.to_string(), "&lt;");

    // Decimal entity
    let entity = encode_char(&'<', &EncodeType::Decimal).unwrap();
    assert_eq!(entity.to_string(), "&#60;");

    // Hexadecimal entity
    let entity = encode_char(&'<', &EncodeType::Hex).unwrap();
    assert_eq!(entity.to_string(), "&#x3c;");

    // A character with no named entity — Named returns None
    let entity = encode_char(&'世', &EncodeType::Named);
    assert!(entity.is_none());

    // But NamedOrHex falls back to hex
    let entity = encode_char(&'世', &EncodeType::NamedOrHex).unwrap();
    assert_eq!(entity.to_string(), "&#x4e16;");
}
```
```

--------------------------------

### Encode Character Slice with Custom Filter

Source: https://context7.com/fefit/htmlentity/llms.txt

Employ `encode_chars_with` to encode a slice of characters (`&[char]`) using a custom filter closure. The closure determines whether to encode a character and which `EncodeType` to use.

```Rust
use htmlentity::entity::{encode_chars_with, CharacterSet, EncodeType};

fn main() {
    let chars: Vec<char> = "<div class='header'></div>".chars().collect();
    let charset = CharacterSet::HtmlAndNonASCII;

    let result = encode_chars_with(&chars, |ch| {
        // Encode HTML special chars plus single quotes
        if charset.contains(ch) || *ch == '\'' {
            return Some(&EncodeType::Named);
        }
        None
    });

    assert_eq!(
        result.iter().collect::<String>(),
        "&lt;div class=&apos;header&apos;&gt;&lt;/div&gt;"
    );
}
```

--------------------------------

### `encode_chars_with` — Encode a `&[char]` slice with a custom filter

Source: https://context7.com/fefit/htmlentity/llms.txt

Encodes a slice of characters (`&[char]`) using a custom filter closure. The closure determines whether to encode a character and which `EncodeType` to use, returning a `Cow<'_, [char]>`.

```APIDOC
## `encode_chars_with` — Encode a `&[char]` slice with a custom filter

Operates on a `Vec<char>` / `&[char]` rather than bytes. The filter closure returns `Option<&EncodeType>`: `Some(encode_type)` to encode the character, `None` to leave it unchanged. Returns `Cow<'_, [char]>` — borrowed if nothing was encoded, owned otherwise.

### Request Example
```rust
use htmlentity::entity::{encode_chars_with, CharacterSet, EncodeType};

fn main() {
    let chars: Vec<char> = "<div class='header'></div>".chars().collect();
    let charset = CharacterSet::HtmlAndNonASCII;

    let result = encode_chars_with(&chars, |ch| {
        // Encode HTML special chars plus single quotes
        if charset.contains(ch) || *ch == '\'' {
            return Some(&EncodeType::Named);
        }
        None
    });

    assert_eq!(
        result.iter().collect::<String>(),
        "&lt;div class=&apos;header&apos;&gt;&lt;/div&gt;"
    );
}
```
```

--------------------------------

### `EncodeType` enum and `encode` function

Source: https://context7.com/fefit/htmlentity/llms.txt

The `EncodeType` enum controls the output format for HTML entity encoding. The `encode` function uses this enum to determine whether to use named entities, hexadecimal, decimal, or a combination thereof, falling back when necessary. It supports different character sets.

```APIDOC
## `EncodeType` — Encoding format enum

Controls the output format of HTML entity encoding. Five variants are available; the `NamedOrHex` and `NamedOrDecimal` variants try named encoding first and fall back to a numeric form when no named entity exists for a character.

```rust
use htmlentity::entity::{encode, EncodeType, CharacterSet, ICodedDataTrait};
use htmlentity::types::AnyhowResult;

fn main() -> AnyhowResult<()> {
    let input = "<©>".as_bytes(); // © = U+00A9, has named entity &copy;

    // Named only — uses &lt; / &copy; / &gt;
    println!("{}", encode(input, &EncodeType::Named,          &CharacterSet::All).to_string()?);

    // Hex only — uses &#x3c; / &#xa9; / &#x3e;
    println!("{}", encode(input, &EncodeType::Hex,            &CharacterSet::All).to_string()?);

    // Decimal only — uses &#60; / &#169; / &#62;
    println!("{}", encode(input, &EncodeType::Decimal,        &CharacterSet::All).to_string()?);

    // Named, fallback to hex — uses &lt; / &copy; / &gt;
    println!("{}", encode(input, &EncodeType::NamedOrHex,     &CharacterSet::All).to_string()?);

    // Named, fallback to decimal
    println!("{}", encode(input, &EncodeType::NamedOrDecimal, &CharacterSet::All).to_string()?);

    Ok(())
}
```
```

--------------------------------

### Encode Single Character to CharEntity

Source: https://context7.com/fefit/htmlentity/llms.txt

Use `encode_char` to encode a single character into a `CharEntity` for a specific `EncodeType`. Returns `None` if the character has no named entity and the format is `Named`.

```Rust
use htmlentity::entity::{encode_char, EncodeType};

fn main() {
    // Named entity
    let entity = encode_char(&'<', &EncodeType::Named).unwrap();
    assert_eq!(entity.to_string(), "&lt;");

    // Decimal entity
    let entity = encode_char(&'<', &EncodeType::Decimal).unwrap();
    assert_eq!(entity.to_string(), "&#60;");

    // Hexadecimal entity
    let entity = encode_char(&'<', &EncodeType::Hex).unwrap();
    assert_eq!(entity.to_string(), "&#x3c;");

    // A character with no named entity — Named returns None
    let entity = encode_char(&'世', &EncodeType::Named);
    assert!(entity.is_none());

    // But NamedOrHex falls back to hex
    let entity = encode_char(&'世', &EncodeType::NamedOrHex).unwrap();
    assert_eq!(entity.to_string(), "&#x4e16;");
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.