html2text

https://docs.rs/html2text
Admin
html2text is a Rust crate that renders HTML into formatted text wrapped to a specified width,...
Tokens:68,599
Snippets:467
Trust Score:9.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### Run html2text example via CLI

Source: https://docs.rs/html2text

Uses the html2text example to convert HTML from stdin into plain text.

```bash
$ cargo run --example html2text < foo.html
[...]
```

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

### Run html2term example via CLI

Source: https://docs.rs/html2text

Uses the html2term example to view HTML in a terminal, utilizing the rich interface from_read_rich. This example requires an HTML file as a parameter to allow reading keys from stdin.

```bash
$ cargo run --example html2term foo.html
[...]
```

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

### Handle fragment start

Source: https://docs.rs/html2text/latest/src/html2text/lib.rs.html

Records the start of a fragment and unwinds the pushed style.

```rust
FragStart(fragname) => {
    renderer.record_frag_start(&fragname);
    pushed_style.unwind(renderer);
    Finished(None)
}
```

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

### Record fragment start

Source: https://docs.rs/html2text/latest/src/html2text/render/text_renderer.rs.html

Records the start of a fragment by adding a FragmentStart element to the current wrapping context. Uses get_wrapping_or_insert to obtain the wrapping element.

```rust
fn record_frag_start(&mut self, fragname: &str) {
    use self::TaggedLineElement::FragmentStart;

    get_wrapping_or_insert::<D>(
        &mut self.wrapping,
        &self.options,
        self.width,
        &self.ann_stack,
    )
    .add_element(FragmentStart(fragname.to_string()));
}
```

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

### Start and end link rendering

Source: https://docs.rs/html2text/latest/src/html2text/render/text_renderer.rs.html

Handles link start and end by delegating decoration to the decorator and managing the annotation stack. The start method pushes the annotation and adds the start text; the end method adds the end text and pops the annotation.

```rust
fn start_link(&mut self, target: &str) -> Result<()> {
    let (s, annotation) = self.decorator.decorate_link_start(target);
    self.ann_stack.push(annotation);
    self.add_inline_text(&s)
}
```

```rust
fn end_link(&mut self) -> Result<()> {
    let s = self.decorator.decorate_link_end();
    self.add_inline_text(&s)?;
    self.ann_stack.pop();
    Ok(())
}
```

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

### Example: Rc::clone_from_ref

Source: https://docs.rs/html2text/latest/html2text/type.Handle.html

Example for the nightly-only `clone_from_ref` method on `Rc<T>`, which constructs a new `Rc<T>` with a clone of the given value.

```rust
#![feature(clone_from_ref)]
use std::rc::Rc;

let hello: Rc<str> = Rc::clone_from_ref("hello");
```

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

### Example: Rc::try_clone_from_ref

Source: https://docs.rs/html2text/latest/html2text/type.Handle.html

Example for the nightly-only `try_clone_from_ref` method on `Rc<T>`, which constructs a new `Rc<T>` with a clone of the value, returning an error if allocation fails.

```rust
#![feature(clone_from_ref)]
#![feature(allocator_api)]
use std::rc::Rc;

let hello: Rc<str> = Rc::try_clone_from_ref("hello")?;
```

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

### Rc::new_uninit example

Source: https://docs.rs/html2text/latest/html2text/type.Handle.html

Demonstrates `Rc::new_uninit` with deferred initialization: create an uninitialized `Rc`, write a value via `get_mut`, then safely assume initialization. The example asserts the final value equals 5.

```rust
use std::rc::Rc;

let mut five = Rc::<u32>::new_uninit();

// Deferred initialization:
Rc::get_mut(&mut five).unwrap().write(5);

let five = unsafe { five.assume_init() };

assert_eq!(*five, 5)
```

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

### Start and end strong rendering

Source: https://docs.rs/html2text/latest/src/html2text/render/text_renderer.rs.html

Handles strong (bold) start and end by delegating decoration to the decorator and managing the annotation stack. The start method pushes the annotation and adds the start text; the end method adds the end text and pops the annotation.

```rust
fn start_strong(&mut self) -> Result<()> {
    let (s, annotation) = self.decorator.decorate_strong_start();
    self.ann_stack.push(annotation);
    self.add_inline_text(&s)
}
```

```rust
fn end_strong(&mut self) -> Result<()> {
    let s = self.decorator.decorate_strong_end();
    self.add_inline_text(&s)?;
    self.ann_stack.pop();
    Ok(())
}
```

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

### Rc::try_new_uninit example

Source: https://docs.rs/html2text/latest/html2text/type.Handle.html

Uses the nightly-only `allocator_api` feature to call `Rc::try_new_uninit`, which returns a `Result` and errors if allocation fails. The example defers initialization, writes 5, then assumes initialization and asserts the value.

```rust
#![feature(allocator_api)]

use std::rc::Rc;

let mut five = Rc::<u32>::try_new_uninit()?;

// Deferred initialization:
Rc::get_mut(&mut five).unwrap().write(5);

let five = unsafe { five.assume_init() };

assert_eq!(*five, 5);
```

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

### Rc::into_raw_with_allocator example

Source: https://docs.rs/html2text/latest/html2text/type.Handle.html

Requires the nightly-only `allocator_api` feature. Consumes an `Rc` and returns the raw pointer and allocator, then reconstructs the `Rc` with `Rc::from_raw_in` to avoid a memory leak. The example creates an `Rc` with the `System` allocator and verifies the value after round-tripping.

```rust
#![feature(allocator_api)]
use std::rc::Rc;
use std::alloc::System;

let x = Rc::new_in("hello".to_owned(), System);
let (ptr, alloc) = Rc::into_raw_with_allocator(x);
assert_eq!(unsafe { &*ptr }, "hello");
let x = unsafe { Rc::from_raw_in(ptr, alloc) };
assert_eq!(&*x, "hello");
```

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

### Start and end emphasis rendering

Source: https://docs.rs/html2text/latest/src/html2text/render/text_renderer.rs.html

Handles emphasis start and end by delegating decoration to the decorator and managing the annotation stack. The start method pushes the annotation and adds the start text; the end method adds the end text and pops the annotation.

```rust
fn start_emphasis(&mut self) -> Result<()> {
    let (s, annotation) = self.decorator.decorate_em_start();
    self.ann_stack.push(annotation);
    self.add_inline_text(&s)
}
```

```rust
fn end_emphasis(&mut self) -> Result<()> {
    let s = self.decorator.decorate_em_end();
    self.add_inline_text(&s)?;
    self.ann_stack.pop();
    Ok(())
}
```

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

### Rc::le example

Source: https://docs.rs/html2text/latest/html2text/type.Handle.html

Performs less-than-or-equal comparison between two Rc values by calling <= on their inner values. The example asserts that an Rc of 5 is less than or equal to an Rc of 5.

```rust
use std::rc::Rc;

let five = Rc::new(5);

assert!(five <= Rc::new(5));
```

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

### Start and end inline code rendering

Source: https://docs.rs/html2text/latest/src/html2text/render/text_renderer.rs.html

Handles inline code start and end by delegating decoration to the decorator and managing the annotation stack. The start method pushes the annotation and adds the start text; the end method adds the end text and pops the annotation.

```rust
fn start_code(&mut self) -> Result<()> {
    let (s, annotation) = self.decorator.decorate_code_start();
    self.ann_stack.push(annotation);
    self.add_inline_text(&s)?;
    Ok(())
}
```

```rust
fn end_code(&mut self) -> Result<()> {
    let s = self.decorator.decorate_code_end();
    self.add_inline_text(&s)?;
    self.ann_stack.pop();
    Ok(())
}
```

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

### Rc::cmp example

Source: https://docs.rs/html2text/latest/html2text/type.Handle.html

Compares two Rc values by calling cmp on their inner values. The example creates an Rc of 5 and asserts that comparing it to an Rc of 6 yields Ordering::Less.

```rust
use std::rc::Rc;
use std::cmp::Ordering;

let five = Rc::new(5);

assert_eq!(Ordering::Less, five.cmp(&Rc::new(6)));
```

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

### Rc::downgrade example

Source: https://docs.rs/html2text/latest/html2text/type.Handle.html

Creates a `Weak` pointer to an `Rc` allocation using `Rc::downgrade`. The example creates an `Rc<i32>` and then downgrades it to a weak reference.

```rust
use std::rc::Rc;

let five = Rc::new(5);

let weak_five = Rc::downgrade(&five);
```

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

### Rc::new_zeroed example

Source: https://docs.rs/html2text/latest/html2text/type.Handle.html

Shows `Rc::new_zeroed` creating an `Rc` with zeroed memory, then using `assume_init` to obtain the value. The example asserts the value is 0.

```rust
use std::rc::Rc;

let zero = Rc::<u32>::new_zeroed();
let zero = unsafe { zero.assume_init() };

assert_eq!(*zero, 0)
```

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

### Rc::try_new_uninit_in example

Source: https://docs.rs/html2text/latest/html2text/type.Handle.html

Constructs an uninitialized Rc in the System allocator, then initializes it via unsafe deferred initialization. Requires the nightly allocator_api and get_mut_unchecked features.

```rust
#![feature(allocator_api)]
#![feature(get_mut_unchecked)]

use std::rc::Rc;
use std::alloc::System;

let mut five = Rc::<u32, _>::try_new_uninit_in(System)?;

let five = unsafe {
    // Deferred initialization:
    Rc::get_mut_unchecked(&mut five).as_mut_ptr().write(5);

    five.assume_init()
};

assert_eq!(*five, 5);
```

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

### Rc::try_new_zeroed_in example

Source: https://docs.rs/html2text/latest/html2text/type.Handle.html

Constructs a zeroed Rc in the System allocator and initializes it. Requires the nightly allocator_api feature.

```rust
#![feature(allocator_api)]

use std::rc::Rc;
use std::alloc::System;

let zero = Rc::<u32, _>::try_new_zeroed_in(System)?;
let zero = unsafe { zero.assume_init() };

assert_eq!(*zero, 0);
```

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

### Rc::clone_from_ref_in example

Source: https://docs.rs/html2text/latest/html2text/type.Handle.html

Requires the nightly-only `clone_from_ref` and `allocator_api` features. Constructs a new `Rc<T>` by cloning a value into the provided allocator. The example creates an `Rc<str, System>` from a string literal using the `System` allocator.

```rust
#![feature(clone_from_ref)]
#![feature(allocator_api)]
use std::rc::Rc;
use std::alloc::System;

let hello: Rc<str, System> = Rc::clone_from_ref_in("hello", System);
```

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

### Rc::lt example

Source: https://docs.rs/html2text/latest/html2text/type.Handle.html

Performs less-than comparison between two Rc values by calling < on their inner values. The example asserts that an Rc of 5 is less than an Rc of 6.

```rust
use std::rc::Rc;

let five = Rc::new(5);

assert!(five < Rc::new(6));
```

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

### Rc::from(Box<T>) example

Source: https://docs.rs/html2text/latest/html2text/type.Handle.html

Converts a Box into an Rc by moving the boxed value into a new reference-counted allocation. The example creates a Box<i32>, converts it with Rc::from, and asserts the inner value is 1.

```rust
let original: Box<i32> = Box::new(1);
let shared: Rc<i32> = Rc::from(original);
assert_eq!(1, *shared);
```

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

### Rc::try_new example

Source: https://docs.rs/html2text/latest/html2text/type.Handle.html

Uses the nightly-only `allocator_api` feature to call `Rc::try_new`, which returns a `Result` and errors if allocation fails. The example creates an `Rc` containing the value 5.

```rust
#![feature(allocator_api)]
use std::rc::Rc;

let five = Rc::try_new(5);
```

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

### Rc::map example

Source: https://docs.rs/html2text/latest/html2text/type.Handle.html

Uses the nightly-only `smart_pointer_try_map` feature to call `Rc::map`, which maps the value in an `Rc` and reuses the allocation if possible. The example maps 7 to 14 and asserts the result.

```rust
#![feature(smart_pointer_try_map)]

use std::rc::Rc;

let r = Rc::new(7);
let new = Rc::map(r, |i| i + 7);
assert_eq!(*new, 14);
```

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

### Rc::from(Cow<'_, B>) example

Source: https://docs.rs/html2text/latest/html2text/type.Handle.html

Creates an Rc from a Cow by copying its content. The example borrows a string literal as Cow::Borrowed, converts it to Rc<str>, and asserts the content is "eggplant".

```rust
let cow: Cow<'_, str> = Cow::Borrowed("eggplant");
let shared: Rc<str> = Rc::from(cow);
assert_eq!("eggplant", &shared[..]);
```

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

### Clone an Rc pointer

Source: https://docs.rs/html2text/latest/html2text/type.Handle.html

Shows how to clone an Rc pointer, increasing the strong reference count. The example creates an Rc<i32> and clones it, discarding the clone immediately.

```rust
use std::rc::Rc;

let five = Rc::new(5);

let _ = Rc::clone(&five);

```

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

### Rc::try_clone_from_ref_in example

Source: https://docs.rs/html2text/latest/html2text/type.Handle.html

Requires the nightly-only `clone_from_ref` and `allocator_api` features. Attempts to construct a new `Rc<T>` with a clone of the value in the provided allocator, returning `Result<Rc<T, A>, AllocError>` on allocation failure. The example uses the `?` operator to propagate the error.

```rust
#![feature(clone_from_ref)]
#![feature(allocator_api)]
use std::rc::Rc;
use std::alloc::System;

let hello: Rc<str, System> = Rc::try_clone_from_ref_in("hello", System)?;
```

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

### Using expanded_name with and without namespaces

Source: https://docs.rs/html2text/latest/html2text/macro.expanded_name.html

Examples demonstrating how to use the macro to create ExpandedName objects with no namespace and with the 'html' namespace.

```rust
use markup5ever::ExpandedName;

assert_eq!(
    expanded_name!("", "div"),
    ExpandedName {
        ns: &ns!(),
        local: &local_name!("div")
    }
);

assert_eq!(
    expanded_name!(html "div"),
    ExpandedName {
        ns: &ns!(html),
        local: &local_name!("div")
    }
);
```

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

### Render definition list (Dl)

Source: https://docs.rs/html2text/latest/src/html2text/lib.rs.html

Renders a definition list by starting a block and returning a pending children result that unwinds the pushed style when consumed.

```rust
Dl(items) => {
    renderer.start_block()?;

    TreeMapResult::PendingChildren {
        children: items,
        cons: Box::new(|renderer, _| {
            pushed_style.unwind(renderer);
            Ok(Some(None))
        }),
        prefn: None,
        postfn: None,
    }
}
```

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

### Rc::strong_count example

Source: https://docs.rs/html2text/latest/html2text/type.Handle.html

Gets the number of strong (`Rc`) pointers to an allocation using `Rc::strong_count`. The example clones the `Rc` and asserts the strong count is 2.

```rust
use std::rc::Rc;

let five = Rc::new(5);
let _also_five = Rc::clone(&five);

assert_eq!(2, Rc::strong_count(&five));
```

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

### Rc::weak_count example

Source: https://docs.rs/html2text/latest/html2text/type.Handle.html

Gets the number of `Weak` pointers to an `Rc` allocation using `Rc::weak_count`. The example creates one weak reference and asserts the count is 1.

```rust
use std::rc::Rc;

let five = Rc::new(5);
let _weak_five = Rc::downgrade(&five);

assert_eq!(1, Rc::weak_count(&five));
```

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

### Start and end strikeout rendering with Unicode filter

Source: https://docs.rs/html2text/latest/src/html2text/render/text_renderer.rs.html

Handles strikeout start and end. When use_unicode_strikeout is enabled, a text filter is pushed on start and popped on end; otherwise the filter is not used. The end method panics if called without a matching start.

```rust
fn start_strikeout(&mut self) -> Result<()> {
    let (s, annotation) = self.decorator.decorate_strikeout_start();
    self.ann_stack.push(annotation);
    self.add_inline_text(&s)?;
    if self.options.use_unicode_strikeout {
        self.text_filter_stack.push(filter_text_strikeout);
    }
    Ok(())
}
```

```rust
fn end_strikeout(&mut self) -> Result<()> {
    if self.options.use_unicode_strikeout {
        self.text_filter_stack
            .pop()
            .expect("end_strikeout() called without a corresponding start_strokeout()");
    }
    let s = self.decorator.decorate_strikeout_end();
    self.add_inline_text(&s)?;
    self.ann_stack.pop();
    Ok(())
}
```

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

### plain

Source: https://docs.rs/html2text/latest/html2text/config/index.html

Returns a Config initialized with a PlainDecorator for plain text output.

```APIDOC
## Function: plain

### Description
Returns a Config initialized with a `PlainDecorator`.

### Signature
`pub fn plain() -> Config`

### Returns
- **Config** - A configuration for plain text rendering.

### Example
```rust
let config = html2text::config::plain();
```
```

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

### Rc::new_uninit_in

Source: https://docs.rs/html2text/latest/html2text/type.Handle.html

Constructs a new Rc with uninitialized contents in the provided allocator. This is a nightly-only experimental API.

```APIDOC
## Rc::new_uninit_in

### Description
Constructs a new `Rc` with uninitialized contents in the provided allocator. This is a nightly-only experimental API.

### Method Signature
`pub fn new_uninit_in(alloc: A) -> Rc<MaybeUninit<T>, A>`

### Parameters
- `alloc` (`A`) - Required - The allocator to use.

### Return Value
- `Rc<MaybeUninit<T>, A>` - The newly constructed `Rc` with uninitialized contents.

### Examples
```rust
#![feature(get_mut_unchecked)]
#![feature(allocator_api)]

use std::rc::Rc;
use std::alloc::System;

let mut five = Rc::<u32, _>::new_uninit_in(System);

let five = unsafe {
    // Deferred initialization:
    Rc::get_mut_unchecked(&mut five).as_mut_ptr().write(5);

    five.assume_init()
};

assert_eq!(*five, 5)
```
```

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

### PlainDecorator::new

Source: https://docs.rs/html2text/latest/html2text/render/struct.PlainDecorator.html

Creates a new PlainDecorator instance.

```APIDOC
## PlainDecorator::new

### Description
Creates a new `PlainDecorator` instance.

### Method
`pub fn new() -> PlainDecorator`

### Parameters
None.

### Returns
- `PlainDecorator` - A new instance of the decorator.

```

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

### TextStyle constructor methods

Source: https://docs.rs/html2text/latest/src/html2text/lib.rs.html

Provides constructors for TextStyle: colours for both foreground and background, and foreground for only foreground colour.

```rust
#[cfg(feature = "css_ext")]
impl TextStyle {
    /// Create a TextStyle from foreground and background colours.
    pub fn colours(fg_colour: Colour, bg_colour: Colour) -> Self {
        TextStyle {
            fg_colour,
            bg_colour: Some(bg_colour),
        }
    }

    /// Create a TextStyle using only a foreground colour.
    pub fn foreground(fg_colour: Colour) -> Self {
        TextStyle {
            fg_colour,
            bg_colour: None,
        }
    }
}
```

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

### Rc::make_mut clone-on-write and Weak disassociation examples

Source: https://docs.rs/html2text/latest/html2text/type.Handle.html

Shows clone-on-write behavior of Rc::make_mut. The first example demonstrates that cloning is avoided when there is only one strong reference, and that cloning occurs when another strong reference exists. The second example shows that Weak pointers are disassociated when make_mut is called on a uniquely owned Rc.

```rust
use std::rc::Rc;

let mut data = Rc::new(5);

*Rc::make_mut(&mut data) += 1;         // Won't clone anything
let mut other_data = Rc::clone(&data); // Won't clone inner data
*Rc::make_mut(&mut data) += 1;         // Clones inner data
*Rc::make_mut(&mut data) += 1;         // Won't clone anything
*Rc::make_mut(&mut other_data) *= 2;   // Won't clone anything

// Now `data` and `other_data` point to different allocations.
assert_eq!(*data, 8);
assert_eq!(*other_data, 12);
```

```rust
use std::rc::Rc;

let mut data = Rc::new(75);
let weak = Rc::downgrade(&data);

assert!(75 == *data);
assert!(75 == *weak.upgrade().unwrap());

*Rc::make_mut(&mut data) += 1;

assert!(76 == *data);
assert!(weak.upgrade().is_none());
```

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

### Rc::gt example

Source: https://docs.rs/html2text/latest/html2text/type.Handle.html

Performs greater-than comparison between two Rc values by calling > on their inner values. The example asserts that an Rc of 5 is greater than an Rc of 4.

```rust
use std::rc::Rc;

let five = Rc::new(5);

assert!(five > Rc::new(4));
```

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

### fn decorate_superscript_start(&self) -> (String, Self::Annotation)

Source: https://docs.rs/html2text/latest/html2text/render/text_renderer/trait.TextDecorator.html

Returns an annotation and rendering prefix for superscript text.

```APIDOC
## fn decorate_superscript_start(&self) -> (String, Self::Annotation)

### Description
Returns an annotation and rendering prefix for superscript text.

### Method
decorate_superscript_start

### Signature
fn decorate_superscript_start(&self) -> (String, Self::Annotation)

### Parameters
None

### Return Value
(String, Self::Annotation) - A tuple containing the rendering prefix and an annotation.
```

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

### Rc::ge example

Source: https://docs.rs/html2text/latest/html2text/type.Handle.html

Performs greater-than-or-equal comparison between two Rc values by calling >= on their inner values. The example asserts that an Rc of 5 is greater than or equal to an Rc of 5.

```rust
use std::rc::Rc;

let five = Rc::new(5);

assert!(five >= Rc::new(5));
```

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

### fn decorate_superscript_start(&self) -> (String, Self::Annotation)

Source: https://docs.rs/html2text/latest/html2text/render/trait.TextDecorator.html

Returns an annotation and rendering prefix for superscript text.

```APIDOC
## fn decorate_superscript_start(&self) -> (String, Self::Annotation)

### Description
Returns an annotation and rendering prefix for superscript text.

### Method
decorate_superscript_start

### Returns
- **(String, Self::Annotation)** - A tuple containing the rendering prefix and an annotation.
```

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

### Config::render_to_string

Source: https://docs.rs/html2text/latest/html2text/config/struct.Config.html

Renders an existing RenderTree into a string. This is used to produce the final text output.

```APIDOC
## render_to_string

### Description
Render an existing RenderTree into a string.

### Method
render_to_string

### Signature
pub fn render_to_string(&self, render_tree: RenderTree, width: usize) -> Result<String, Error>

### Parameters
- **render_tree** (RenderTree) - Required - The render tree to render.
- **width** (usize) - Required - The width to wrap text to.

### Returns
- **Result<String, Error>** - The rendered string or an error.
```

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

### rich

Source: https://docs.rs/html2text/latest/html2text/config/index.html

Returns a Config initialized with a RichDecorator for rich text output.

```APIDOC
## Function: rich

### Description
Returns a Config initialized with a `RichDecorator`.

### Signature
`pub fn rich() -> Config`

### Returns
- **Config** - A configuration for rich text rendering.

### Example
```rust
let config = html2text::config::rich();
```
```

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

### Rc::ne example

Source: https://docs.rs/html2text/latest/html2text/type.Handle.html

Checks inequality between two Rc values. Two Rc's are not equal if their inner values are not equal. The example asserts that an Rc of 5 is not equal to an Rc of 6.

```rust
use std::rc::Rc;

let five = Rc::new(5);

assert!(five != Rc::new(6));
```

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

### with_decorator

Source: https://docs.rs/html2text/latest/html2text/config/index.html

Returns a Config initialized with a custom decorator.

```APIDOC
## Function: with_decorator

### Description
Returns a Config initialized with a custom decorator.

### Signature
`pub fn with_decorator(decorator: D) -> Config`

### Parameters
- **decorator** (D) - Required - The custom decorator to use.

### Returns
- **Config** - A configuration using the provided decorator.

### Example
```rust
let config = html2text::config::with_decorator(my_decorator);
```
```

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

### Rc::from(T) generic conversion example

Source: https://docs.rs/html2text/latest/html2text/type.Handle.html

Converts a generic type T into an Rc<T> by allocating on the heap and moving the value from the stack. The example converts an integer and compares it to an Rc created with Rc::new.

```rust
let x = 5;
let rc = Rc::new(5);

assert_eq!(Rc::from(x), rc);
```

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

### fn push_bgcolour(&mut self, _: Colour) -> Option<Self::Annotation>

Source: https://docs.rs/html2text/latest/html2text/render/text_renderer/trait.TextDecorator.html

Returns an annotation corresponding to adding a background colour, or none.

```APIDOC
## fn push_bgcolour(&mut self, _: Colour) -> Option<Self::Annotation>

### Description
Returns an annotation corresponding to adding a background colour, or none.

### Method
push_bgcolour

### Signature
fn push_bgcolour(&mut self, _: Colour) -> Option<Self::Annotation>

### Parameters
- `_` (Colour) - The background colour to push.

### Return Value
Option<Self::Annotation> - An annotation corresponding to the background colour, or none.
```

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

### Rc::partial_cmp example

Source: https://docs.rs/html2text/latest/html2text/type.Handle.html

Performs partial comparison between two Rc values by calling partial_cmp on their inner values. The example asserts that comparing an Rc of 5 to an Rc of 6 yields Some(Ordering::Less).

```rust
use std::rc::Rc;
use std::cmp::Ordering;

let five = Rc::new(5);

assert_eq!(Some(Ordering::Less), five.partial_cmp(&Rc::new(6)));
```

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

### fn push_bgcolour(&mut self, _: Colour) -> Option<Self::Annotation>

Source: https://docs.rs/html2text/latest/html2text/render/trait.TextDecorator.html

Returns an annotation corresponding to adding background colour, or none.

```APIDOC
## fn push_bgcolour(&mut self, _: Colour) -> Option<Self::Annotation>

### Description
Returns an annotation corresponding to adding background colour, or none.

### Method
push_bgcolour

### Parameters
- **colour** (Colour) - Required - The background colour to push.

### Returns
- **Option<Self::Annotation>** - An annotation corresponding to adding background colour, or none.
```

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

### Rc::into_inner example

Source: https://docs.rs/html2text/latest/html2text/type.Handle.html

Shows that into_inner returns Some when there is exactly one strong reference, and None when there are multiple strong references. The example uses Rc::new and Rc::clone to create the two cases.

```rust
use std::rc::Rc;

let x = Rc::new(3);
assert_eq!(Rc::into_inner(x), Some(3));

let x = Rc::new(4);
let y = Rc::clone(&x);

assert_eq!(Rc::into_inner(y), None);
assert_eq!(Rc::into_inner(x), Some(4));
```

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

### RichDecorator::new

Source: https://docs.rs/html2text/latest/html2text/render/struct.RichDecorator.html

Creates a new RichDecorator with default settings. This is the primary constructor for generating rich text output.

```APIDOC
## RichDecorator::new

### Description
Creates a new `RichDecorator` with default settings. Use this to start generating rich text.

### Method

`pub fn new()`

### Returns

- **RichDecorator** - A new instance of `RichDecorator`.

### Example

```rust
let decorator = RichDecorator::new();
```

```

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

### Convert HTML to plain text with from_read

Source: https://docs.rs/html2text

Demonstrates the basic usage of the from_read function to convert an HTML byte slice into a formatted string with a specified width.

```rust
let html = b"
       <ul>
         <li>Item one</li>
         <li>Item two</li>
         <li>Item three</li>
       </ul>";
assert_eq!(from_read(&html[..], 20).unwrap(),
           "
* Item one
* Item two
* Item three
");
```

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

### Config::render_to_lines

Source: https://docs.rs/html2text/latest/html2text/config/struct.Config.html

Renders an existing RenderTree into lines with annotations. Returns text wrapped to the specified width.

```APIDOC
## render_to_lines

### Description
Take an existing RenderTree, and returns text wrapped to `width` columns. The text is returned as a `Vec<TaggedLine<_>>`; the annotations are vectors of the provided text decorator’s `Annotation`. The “outer” annotation comes first in the `Vec`.

### Method
render_to_lines

### Signature
pub fn render_to_lines(&self, render_tree: RenderTree, width: usize) -> Result<Vec<TaggedLine<Vec<D::Annotation>>>, Error>

### Parameters
- **render_tree** (RenderTree) - Required - The render tree to render.
- **width** (usize) - Required - The width to wrap text to.

### Returns
- **Result<Vec<TaggedLine<Vec<D::Annotation>>>, Error>** - The rendered lines with annotations or an error.
```

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

### Rc::try_unwrap example

Source: https://docs.rs/html2text/latest/html2text/type.Handle.html

Shows that try_unwrap returns Ok when there is exactly one strong reference, and Err with the same Rc when there are multiple strong references. The example uses Rc::new and Rc::clone to create the two cases.

```rust
use std::rc::Rc;

let x = Rc::new(3);
assert_eq!(Rc::try_unwrap(x), Ok(3));

let x = Rc::new(4);
let _y = Rc::clone(&x);
assert_eq!(*Rc::try_unwrap(x).unwrap_err(), 4);
```

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

### Config::do_decorate

Source: https://docs.rs/html2text/latest/html2text/config/struct.Config.html

Configures the Config to decorate _etc. similarly to markdown.

```APIDOC
## do_decorate

### Description
Decorate _etc. similarly to markdown_

### Method
do_decorate

### Signature
pub fn do_decorate(self) -> Self


### Returns
- **Self** - The updated Config.
```
Tokens:
Raw