Lopdf Table

https://docs.rs/lopdf-table/0.5.0
Admin
Lopdf Table is a composable table drawing library for PDFs that provides an ergonomic API for...
Tokens:95,545
Snippets:866
Trust Score:9.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Create Tables for Font Metrics Comparison

Source: https://docs.rs/lopdf-table/0.5.0/src/lopdf_table/lib.rs.html

Initializes two tables with identical content, one with only regular font metrics and another with both regular and bold font metrics. This setup is used to compare layout calculations.

```rust
let bold_cell = Cell::new("WWWWWW").bold();

let table_regular_only = Table::new()
    .add_row(Row::new(vec![bold_cell.clone()]))
    .with_font_metrics(MockMetrics {
        char_width_pts: 2.0,
    });

let table_with_bold_metrics = Table::new()
    .add_row(Row::new(vec![bold_cell]))
    .with_font_metrics(MockMetrics {
        char_width_pts: 2.0,
    })
    .with_bold_font_metrics(MockMetrics {
        char_width_pts: 8.0,
    });
```

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

### Basic unwrap Usage

Source: https://docs.rs/lopdf-table/0.5.0/lopdf_table/error/type.Result.html

Demonstrates the basic usage of `unwrap` to get the value from an `Ok` variant. Panics if the `Result` is an `Err`.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.unwrap(), 2);
```

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

### Set up PDF Document Structure for Cell Hook Test

Source: https://docs.rs/lopdf-table/0.5.0/src/lopdf_table/lib.rs.html

Creates a minimal PDF document structure including Pages, a Page, and Resources with a Font. This setup is necessary to test the invocation of cell hooks within a valid PDF context.

```rust
let mut doc = Document::with_version("1.7");
let pages_id = doc.add_object(dictionary! {
    "Type" => "Pages",
    "Kids" => vec![],
    "Count" => 0,
});
let page_id = doc.add_object(dictionary! {
    "Type" => "Page",
    "Parent" => pages_id,
    "MediaBox" => vec![0.into(), 0.into(), 595.into(), 842.into()],
});
if let Ok(Object::Dictionary(pages)) = doc.get_object_mut(pages_id) {
    if let Ok(Object::Array(kids)) = pages.get_mut(b"Kids") {
        kids.push(page_id.into());
    }
    pages.set("Count", Object::Integer(1));
}
let font_id = doc.add_object(dictionary! {
    "Type" => "Font",
    "Subtype" => "Type1",
    "BaseFont" => "Helvetica",
});
let resources_id = doc.add_object(dictionary! {
    "Font" => dictionary! { "F1" => font_id },
});
if let Ok(Object::Dictionary(page)) = doc.get_object_mut(page_id) {
    page.set("Resources", resources_id);
}
let catalog_id = doc.add_object(dictionary! {
```

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

### Draw Paginated Table with Images

Source: https://docs.rs/lopdf-table/0.5.0/src/lopdf_table/lib.rs.html

Illustrates creating a table with custom pagination styles, including repeating headers and image cells. This example ensures tables spanning multiple pages render correctly, with images appearing on continuation pages.

```rust
const PAGE_HEIGHT: f32 = 842.0;
const TOP_MARGIN: f32 = 50.0;
const BOTTOM_MARGIN: f32 = 50.0;

let (mut doc, page_id) = make_test_doc();
let jpeg = tiny_jpeg_bytes();

let mut style = TableStyle::default();
style.page_height = Some(PAGE_HEIGHT);
style.top_margin = TOP_MARGIN;
style.bottom_margin = BOTTOM_MARGIN;
style.repeat_headers = true;

let mut table = Table::new()
    .with_style(style)
    .with_header_rows(1)
    .with_pixel_widths(vec![100.0, 200.0])
    .add_row(Row::new([
        Cell::new("Header").bold(),
        Cell::new("Photo").bold(),
    ]));

for _ in 0..30 {
    let img = CellImage::new(jpeg.clone()).unwrap().with_max_height(80.0);
    table = table.add_row(Row::new(vec![Cell::new("data"), Cell::from_image(img)]));
}

let result = doc
    .draw_table_with_pagination(page_id, table, (50.0, 500.0))
    .expect("paginated image table should succeed");

assert!(
    result.page_ids.len() >= 2,
    "expected at least 2 pages, got {}",
    result.page_ids.len()
);

// Verify continuation page has Do operator for images
let second_page_ops = page_content_operations(&doc, result.page_ids[1]);
let has_do = second_page_ops.iter().any(|op| op.operator == "Do");
assert!(
    has_do,
    "expected Do operator on continuation page for image rendering"
);
```

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

### Providing a Default Value with `unwrap_or`

Source: https://docs.rs/lopdf-table/0.5.0/lopdf_table/error/type.Result.html

Demonstrates how to get the `Ok` value or a default value if the `Result` is `Err`.

```APIDOC
## Providing a Default Value with `unwrap_or`

### Description
Returns the contained `Ok` value or a provided default. Arguments passed to `unwrap_or` are eagerly evaluated.

### Method Signature
`pub fn unwrap_or(self, default: T) -> T`

### Examples
```rust
let default = 2;
let x: Result<u32, &str> = Ok(9);
assert_eq!(x.unwrap_or(default), 9);

let x: Result<u32, &str> = Err("error");
assert_eq!(x.unwrap_or(default), default);
```
```

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

### Handling File Metadata with and_then

Source: https://docs.rs/lopdf-table/0.5.0/lopdf_table/error/type.Result.html

Shows how `and_then` can be used to chain fallible operations like getting file metadata and then its modification time. It handles potential errors during path access or metadata retrieval.

```rust
use std::{io::ErrorKind, path::Path};

// Note: on Windows "/" maps to "C:\\"
let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());
assert!(root_modified_time.is_ok());

let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());
assert!(should_fail.is_err());
assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);
```

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

### Draw Simple Paginated Table

Source: https://docs.rs/lopdf-table/0.5.0/src/lopdf_table/lib.rs.html

Draws a table that automatically paginates across multiple pages. This example focuses on the basic pagination logic without specific header styling.

```rust
        let mut doc = Document::with_version("1.7");
        let pages_id = doc.add_object(dictionary! {
            "Type" => "Pages",
            "Kids" => vec![],
            "Count" => 0,
        });
        let page_id = doc.add_object(dictionary! {
            "Type" => "Page",
            "Parent" => pages_id,
            "MediaBox" => vec![0.into(), 0.into(), 595.into(), PAGE_HEIGHT.into()],
        });
        if let Ok(Object::Dictionary(pages)) = doc.get_object_mut(pages_id) {
            if let Ok(Object::Array(kids)) = pages.get_mut(b"Kids") {
                kids.push(page_id.into());
            }
            pages.set("Count", Object::Integer(1));
        }
        let font_id = doc.add_object(dictionary! {
            "Type" => "Font",
            "Subtype" => "Type1",
            "BaseFont" => "Helvetica",
        });
        let resources_id = doc.add_object(dictionary! {
            "Font" => dictionary! { "F1" => font_id },
        });
        if let Ok(Object::Dictionary(page)) = doc.get_object_mut(page_id) {
            page.set("Resources", resources_id);
        }
        let catalog_id = doc.add_object(dictionary! {
            "Type" => "Catalog",
            "Pages" => pages_id,
        });
        doc.trailer.set("Root", catalog_id);

        let mut table = Table::new()
            .with_style(TableStyle {
                page_height: Some(PAGE_HEIGHT),
                top_margin: TOP_MARGIN,
                bottom_margin: BOTTOM_MARGIN,
                ..Default::default()
            })
            .with_pixel_widths(vec![300.0])
            .add_row(Row::new(vec![Cell::new("Header")]).with_height(30.0));

        for row in 0..120 {
            table = 
                table.add_row(Row::new(vec![Cell::new(format!("row-{row}"))]).with_height(30.0));
        }

        let result = doc
            .draw_table_with_pagination(page_id, table, (50.0, START_Y))
            .expect("paginated table draw should succeed");

        assert!(
            result.page_ids.len() >= 3,
            "expected at least 3 pages, got {}",
            result.page_ids.len()
        );

        let first_page_extents = 
            page_rect_extents(&doc, result.page_ids[0]).expect("first page should have rectangles");
        let second_page_extents = page_rect_extents(&doc, result.page_ids[1])
            .expect("second page should have rectangles");

        assert!(
            (first_page_extents.max_top - START_Y).abs() <= EPS,
            "expected first page max top ~{START_Y}, got {}",
            first_page_extents.max_top
        );
        assert!(
            (second_page_extents.max_top - (PAGE_HEIGHT - TOP_MARGIN)).abs() <= EPS,
            "expected second page max top ~{}, got {}",
            PAGE_HEIGHT - TOP_MARGIN,
            second_page_extents.max_top
        );
        assert!(
            second_page_extents.min_bottom >= BOTTOM_MARGIN - EPS,
            "expected second page min bottom >= {}, got {}",
            BOTTOM_MARGIN - EPS,
            second_page_extents.min_bottom
        );
    }

```

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

### Create and Draw a Simple Table

Source: https://docs.rs/lopdf-table/0.5.0/src/lopdf_table/lib.rs.html

Demonstrates creating a basic table with two rows and two columns, applying a border, and drawing it onto a PDF page.

```rust
let mut doc = Document::new();
let page_id = doc.add_page();

let table = Table::new()
    .add_row(Row::new(vec![Cell::new("A"), Cell::new("B")]))
    .add_row(Row::new(vec![Cell::new("C"), Cell::new("D")]))
    .with_border(1.0);

doc.draw_table(page_id, table, (50.0, 750.0))
    .expect("text-only table should still work");
```

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

### Getting References to Result Values

Source: https://docs.rs/lopdf-table/0.5.0/lopdf_table/error/type.Result.html

Use `as_ref()` to get a `Result<&T, &E>` from a `&Result<T, E>`, allowing you to inspect the values without consuming the original Result. `as_mut()` provides mutable references.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.as_ref(), Ok(&2));

let x: Result<u32, &str> = Err("Error");
assert_eq!(x.as_ref(), Err(&"Error"));
```

```rust
fn mutate(r: &mut Result<i32, i32>) {
    match r.as_mut() {
        Ok(v) => *v = 42,
        Err(e) => *e = 0,
    }
}

let mut x: Result<i32, i32> = Ok(2);
mutate(&mut x);
assert_eq!(x.unwrap(), 42);

let mut x: Result<i32, i32> = Err(13);
mutate(&mut x);
assert_eq!(x.unwrap_err(), 0);
```

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

### Get CellImage Pixel Height

Source: https://docs.rs/lopdf-table/0.5.0/src/lopdf_table/table.rs.html

Returns the intrinsic pixel height of the image.

```rust
    /// Intrinsic pixel height.
    pub fn height_px(&self) -> u32 {
        self.height_px
    }
```

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

### Table::new

Source: https://docs.rs/lopdf-table/0.5.0/src/lopdf_table/table.rs.html

Creates a new, empty table with default settings.

```APIDOC
## Table::new

### Description
Creates a new empty table with default styling and no rows.

### Method
Associated function (constructor)

### Returns
A new `Table` instance.

### Example
```rust
let table = Table::new();
```
```

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

### Get CellImage Pixel Width

Source: https://docs.rs/lopdf-table/0.5.0/src/lopdf_table/table.rs.html

Returns the intrinsic pixel width of the image.

```rust
    /// Intrinsic pixel width.
    pub fn width_px(&self) -> u32 {
        self.width_px
    }
```

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

### Create ImageOverlay Instance

Source: https://docs.rs/lopdf-table/0.5.0/src/lopdf_table/table.rs.html

Constructs a new `ImageOverlay` with default values. Provide the text to be displayed.

```rust
impl ImageOverlay {
    /// Create a new overlay with the given text and sensible defaults.
    pub fn new(text: impl Into<String>) -> Self {
        Self {
            text: text.into(),
            font_size: 8.0,
            bar_height: 16.0,
            padding: 4.0,
        }
    }
}
```

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

### unwrap_err Usage

Source: https://docs.rs/lopdf-table/0.5.0/lopdf_table/error/type.Result.html

Shows `unwrap_err` to get the `Err` value. It panics if the `Result` is `Ok`.

```rust
let x: Result<u32, &str> = Ok(2);
x.unwrap_err(); // panics with `2`
```

```rust
let x: Result<u32, &str> = Err("emergency failure");
assert_eq!(x.unwrap_err(), "emergency failure");
```

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

### Table::column_count()

Source: https://docs.rs/lopdf-table/0.5.0/lopdf_table/table/struct.Table.html

Gets the number of columns in the table, based on the first row and accounting for colspan.

```APIDOC
## `column_count()`

### Description

Get the number of columns (based on the first row, accounting for colspan).

### Method

`table.column_count()`

### Returns

The number of columns as a `usize`.
```

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

### Create and Draw a Table on a PDF Page

Source: https://docs.rs/lopdf-table/0.5.0/src/lopdf_table/lib.rs.html

Demonstrates creating a simple table with two rows and two columns, applying a border, and drawing it onto a specified page in a PDF document. Asserts that font metrics are initially not set and the drawing operation is successful.

```rust
let table = Table::new()
            .add_row(Row::new(vec![Cell::new("A"), Cell::new("B")]))
            .add_row(Row::new(vec![Cell::new("C"), Cell::new("D")]))
            .with_border(1.0);

        assert!(table.font_metrics.is_none());
        let result = doc.draw_table(page_id, table, (50.0, 750.0));
        assert!(result.is_ok());
```

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

### Create a new empty table

Source: https://docs.rs/lopdf-table/0.5.0/lopdf_table/table/struct.Table.html

Initializes a new, empty Table instance.

```rust
pub fn new() -> Self
```

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

### ImageOverlay::new Constructor

Source: https://docs.rs/lopdf-table/0.5.0/lopdf_table/table/struct.ImageOverlay.html

Creates a new ImageOverlay instance with the provided text and default values for other fields.

```APIDOC
## impl ImageOverlay

### pub fn new(text: impl Into<String>) -> Self

Create a new overlay with the given text and sensible defaults.
```

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

### Pointable Dereference

Source: https://docs.rs/lopdf-table/0.5.0/lopdf_table/font/struct.TtfFontMetrics.html

Dereferences the given pointer to get an immutable reference. This is an unsafe method from the `Pointable` trait.

```rust
unsafe fn deref<'a>(ptr: usize) -> &'a T
```

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

### CloneToUninit (Nightly Experimental)

Source: https://docs.rs/lopdf-table/0.5.0/lopdf_table/layout/struct.TableLayout.html

An experimental nightly-only API for performing copy-assignment from self to an uninitialized memory location.

```rust
unsafe fn clone_to_uninit(&self, dest: *mut u8)
```

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

### Pointable Dereference Mutably

Source: https://docs.rs/lopdf-table/0.5.0/lopdf_table/font/struct.TtfFontMetrics.html

Dereferences the given pointer to get a mutable reference. This is an unsafe method from the `Pointable` trait.

```rust
unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T
```

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

### Get the number of columns

Source: https://docs.rs/lopdf-table/0.5.0/lopdf_table/table/struct.Table.html

Calculates and returns the total number of columns in the table, considering colspan values in the first row.

```rust
pub fn column_count(&self) -> usize
```

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

### Begin Text Object

Source: https://docs.rs/lopdf-table/0.5.0/src/lopdf_table/drawing.rs.html

Initiates a text object using the 'BT' operator. All subsequent text-related operators will be within this object until 'ET' is encountered.

```rust
    operations.push(Operation::new("BT", vec![]));
```

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

### into_ok

Source: https://docs.rs/lopdf-table/0.5.0/lopdf_table/error/type.Result.html

Returns the contained Ok value, but never panics. This is a nightly-only experimental API.

```APIDOC
## into_ok

### Description
Returns the contained `Ok` value, but never panics. This is a nightly-only experimental API.

### Method
`into_ok()`

### Parameters
None

### Response
- `T`: The contained `Ok` value.

### Notes
Unlike `unwrap`, this method is known to never panic on the result types it is implemented for. Therefore, it can be used instead of `unwrap` as a maintainability safeguard that will fail to compile if the error type of the `Result` is later changed to an error that can actually occur.

### Examples
```rust
fn only_good_news() -> Result<String, !> {
    Ok("this is fine".into())
}

let s: String = only_good_news().into_ok();
println!("{s}");
```
```

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

### Get Intrinsic Image Height

Source: https://docs.rs/lopdf-table/0.5.0/lopdf_table/table/struct.CellImage.html

Retrieves the intrinsic pixel height of the image. This value represents the original height of the image before any scaling or fitting.

```rust
pub fn height_px(&self) -> u32
```

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

### Get Intrinsic Image Width

Source: https://docs.rs/lopdf-table/0.5.0/lopdf_table/table/struct.CellImage.html

Retrieves the intrinsic pixel width of the image. This value represents the original width of the image before any scaling or fitting.

```rust
pub fn width_px(&self) -> u32
```

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

### Cell Creation Methods

Source: https://docs.rs/lopdf-table/0.5.0/lopdf_table/table/struct.Cell.html

Provides methods for creating new Cell instances with various initial configurations.

```APIDOC
### impl Cell

#### `new<S: Into<String>>(content: S) -> Self`

Create a new cell with text content.

#### `empty() -> Self`

Create an empty cell.

#### `from_image(image: CellImage) -> Self`

Create a cell containing a single image (with empty text).

#### `from_images(images: Vec<CellImage>) -> Self`

Create a cell containing multiple images rendered side-by-side (with empty text).
```

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

### Unchecked Unwrapping of `Err` Value

Source: https://docs.rs/lopdf-table/0.5.0/lopdf_table/error/type.Result.html

Provides an unsafe method to get the `Err` value without checking if it's an `Ok`, which can lead to undefined behavior.

```APIDOC
## Unchecked Unwrapping of `Err` Value

### Description
Returns the contained `Err` value, consuming the `self` value, without checking that the value is not an `Ok`. Calling this method on an `Ok` is undefined behavior.

### Method Signature
`pub unsafe fn unwrap_err_unchecked(self) -> E`

### Safety
Calling this method on an `Ok` is _undefined behavior_.

### Examples
```rust
let x: Result<u32, &str> = Ok(2);
unsafe { x.unwrap_err_unchecked() }; // Undefined behavior!
```

```rust
let x: Result<u32, &str> = Err("emergency failure");
assert_eq!(unsafe { x.unwrap_err_unchecked() }, "emergency failure");
```
```

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

### Configure Paginated Table with Repeated Headers

Source: https://docs.rs/lopdf-table/0.5.0/src/lopdf_table/lib.rs.html

Sets up a PDF document and a table with specific styling for pagination, including page height, margins, and enabling repeated headers on subsequent pages.

```rust
const PAGE_HEIGHT: f32 = 842.0;
        const TOP_MARGIN: f32 = 50.0;
        const BOTTOM_MARGIN: f32 = 50.0;
        const START_Y: f32 = 500.0;
        const EPS: f32 = 0.01;

        let mut doc = Document::with_version("1.7");
        let pages_id = doc.add_object(dictionary! {
            "Type" => "Pages",
            "Kids" => vec![],
            "Count" => 0,
        });
        let page_id = doc.add_object(dictionary! {
            "Type" => "Page",
            "Parent" => pages_id,
            "MediaBox" => vec![0.into(), 0.into(), 595.into(), PAGE_HEIGHT.into()],
        });
        if let Ok(Object::Dictionary(pages)) = doc.get_object_mut(pages_id) {
            if let Ok(Object::Array(kids)) = pages.get_mut(b"Kids") {
                kids.push(page_id.into());
            }
            pages.set("Count", Object::Integer(1));
        }
        let font_id = doc.add_object(dictionary! {
            "Type" => "Font",
            "Subtype" => "Type1",
            "BaseFont" => "Helvetica",
        });
        let resources_id = doc.add_object(dictionary! {
            "Font" => dictionary! { "F1" => font_id },
        });
        if let Ok(Object::Dictionary(page)) = doc.get_object_mut(page_id) {
            page.set("Resources", resources_id);
        }
        let catalog_id = doc.add_object(dictionary! {
            "Type" => "Catalog",
            "Pages" => pages_id,
        });
        doc.trailer.set("Root", catalog_id);

        let mut style = TableStyle::default();
        style.page_height = Some(PAGE_HEIGHT);
        style.top_margin = TOP_MARGIN;
        style.bottom_margin = BOTTOM_MARGIN;
        style.repeat_headers = true;

        let mut table = Table::new()
            .with_style(style)
            .with_header_rows(1)
            .with_pixel_widths(vec![300.0])
```

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

### Unchecked Unwrapping of `Ok` Value

Source: https://docs.rs/lopdf-table/0.5.0/lopdf_table/error/type.Result.html

Provides an unsafe method to get the `Ok` value without checking if it's an `Err`, which can lead to undefined behavior.

```APIDOC
## Unchecked Unwrapping of `Ok` Value

### Description
Returns the contained `Ok` value, consuming the `self` value, without checking that the value is not an `Err`. Calling this method on an `Err` is undefined behavior.

### Method Signature
`pub unsafe fn unwrap_unchecked(self) -> T`

### Safety
Calling this method on an `Err` is _undefined behavior_.

### Examples
```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(unsafe { x.unwrap_unchecked() }, 2);
```

```rust
let x: Result<u32, &str> = Err("emergency failure");
unsafe { x.unwrap_unchecked() }; // Undefined behavior!
```
```

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

### Get Text Width

Source: https://docs.rs/lopdf-table/0.5.0/lopdf_table/font/struct.TtfFontMetrics.html

Calculates the total width of a string in points at a given font size. This method is part of the FontMetrics trait implementation for TtfFontMetrics.

```rust
fn text_width(&self, text: &str, font_size: f32) -> f32
```

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

### TryInto Implementation

Source: https://docs.rs/lopdf-table/0.5.0/lopdf_table/style/struct.CellStyle.html

Methods for attempting conversions into other types.

```APIDOC
## impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

### try_into

Performs the conversion.
```

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

### Get Character Width

Source: https://docs.rs/lopdf-table/0.5.0/lopdf_table/font/struct.TtfFontMetrics.html

Calculates the width of a single character in points at a given font size. This method is part of the FontMetrics trait implementation for TtfFontMetrics.

```rust
fn char_width(&self, ch: char, font_size: f32) -> f32
```

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

### Test Basic Table Creation

Source: https://docs.rs/lopdf-table/0.5.0/src/lopdf_table/lib.rs.html

Tests the basic creation of a table with headers and data rows using the `Table::new()` constructor and `add_row` method. Asserts the number of rows and cells.

```rust
#[test]
    fn test_basic_table_creation() {
        let table = Table::new()
            .add_row(Row::new(vec![Cell::new("Header 1"), Cell::new("Header 2")]))
            .add_row(Row::new(vec![Cell::new("Data 1"), Cell::new("Data 2")]));

        assert_eq!(table.rows.len(), 2);
        assert_eq!(table.rows[0].cells.len(), 2);
    }
```

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

### Termination Implementation for Result

Source: https://docs.rs/lopdf-table/0.5.0/lopdf_table/error/type.Result.html

Provides a way to report the Result as an exit code. The `report` method is called to get the status code representation returned to the operating system.

```rust
fn report(self) -> ExitCode
```

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

### VZip Implementation

Source: https://docs.rs/lopdf-table/0.5.0/lopdf_table/style/struct.CellStyle.html

Method for zipping lanes.

```APIDOC
## impl<V, T> VZip<V> for T
where V: MultiLane<T>,

### vzip


```

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

### Wrap Objects as Artifact

Source: https://docs.rs/lopdf-table/0.5.0/src/lopdf_table/drawing.rs.html

Wraps a vector of PDF objects with BDC and EMC operators to mark them as artifacts. This is typically used for non-content elements like annotations or layout guides.

```rust
fn wrap_objects_as_artifact(mut objects: Vec<Object>) -> Vec<Object> {
    if objects.is_empty() {
        return objects;
    }

    let mut wrapped = Vec::with_capacity(objects.len() + 4);
    wrapped.push(Object::Name(b"BDC".to_vec()));
    wrapped.push(Object::Name(b"Artifact".to_vec()));
    wrapped.push(Object::Dictionary(dictionary! {
        "Type" => Object::Name(b"Layout".to_vec()),
    }));
    wrapped.append(&mut objects);
    wrapped.push(Object::Name(b"EMC".to_vec()));
    wrapped
}

```

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

### Table::new()

Source: https://docs.rs/lopdf-table/0.5.0/lopdf_table/table/struct.Table.html

Creates a new, empty table instance.

```APIDOC
## `new()`

### Description

Create a new empty table.

### Method

`Table::new()`

### Returns

A new `Table` instance.
```

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

### TryFrom Implementation

Source: https://docs.rs/lopdf-table/0.5.0/lopdf_table/style/struct.CellStyle.html

Methods for attempting conversions between types.

```APIDOC
## impl<T, U> TryFrom<U> for T
where U: Into<T>,

### try_from

Performs the conversion.
```

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

### Move Text Position

Source: https://docs.rs/lopdf-table/0.5.0/src/lopdf_table/drawing.rs.html

Moves the text cursor to a new position using the 'Td' operator. This is used for positioning subsequent lines of text relative to the previous line or the start.

```rust
            operations.push(Operation::new("Td", vec![dx.into(), dy.into()]));
```

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

### into_ok Usage (Nightly)

Source: https://docs.rs/lopdf-table/0.5.0/lopdf_table/error/type.Result.html

Illustrates `into_ok`, an experimental nightly feature that returns the `Ok` value without panicking. It's a compile-time safeguard against `Result` types that might later become fallible.

```rust
fn only_good_news() -> Result<String, !> {
    Ok("this is fine".into())
}

let s: String = only_good_news().into_ok();
println!("{s}");
```

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

### Draw a vertical line in PDF

Source: https://docs.rs/lopdf-table/0.5.0/src/lopdf_table/drawing_utils.rs.html

Generates PDF content stream operations to draw a vertical line. Uses 'm' to move to the start point and 'l' to draw to the end point, followed by 'S' to stroke.

```rust
pub fn draw_vertical_line(x: f32, start_y: f32, end_y: f32) -> Vec<Object> {
    vec![
        Object::Name(b"m".to_vec()),
        x.into(),
        start_y.into(),
        Object::Name(b"l".to_vec()),
        x.into(),
        end_y.into(),
        Object::Name(b"S".to_vec()),
    ]
}
```

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

### Create Test Document

Source: https://docs.rs/lopdf-table/0.5.0/src/lopdf_table/lib.rs.html

Generates a basic PDF document structure with a single page, a font resource, and a catalog. Useful for testing table drawing operations.

```rust
fn make_test_doc() -> (Document, ObjectId) {
        let mut doc = Document::with_version("1.7");
        let pages_id = doc.add_object(dictionary! {
            "Type" => "Pages",
            "Kids" => vec![],
            "Count" => 0,
        });
        let page_id = doc.add_object(dictionary! {
            "Type" => "Page",
            "Parent" => pages_id,
            "MediaBox" => vec![0.into(), 0.into(), 595.into(), 842.into()],
        });
        if let Ok(Object::Dictionary(pages)) = doc.get_object_mut(pages_id) {
            if let Ok(Object::Array(kids)) = pages.get_mut(b"Kids") {
                kids.push(page_id.into());
            }
            pages.set("Count", Object::Integer(1));
        }
        let font_id = doc.add_object(dictionary! {
            "Type" => "Font",
            "Subtype" => "Type1",
            "BaseFont" => "Helvetica",
        });
        let resources_id = doc.add_object(dictionary! {
            "Font" => dictionary! { "F1" => font_id },
        });
        if let Ok(Object::Dictionary(page)) = doc.get_object_mut(page_id) {
            page.set("Resources", resources_id);
        }
        let catalog_id = doc.add_object(dictionary! {
            "Type" => "Catalog",
            "Pages" => pages_id,
        });
        doc.trailer.set("Root", catalog_id);
        (doc, page_id)
    }
```

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

### Draw a horizontal line in PDF

Source: https://docs.rs/lopdf-table/0.5.0/src/lopdf_table/drawing_utils.rs.html

Generates PDF content stream operations to draw a horizontal line. Uses 'm' to move to the start point and 'l' to draw to the end point, followed by 'S' to stroke.

```rust
pub fn draw_horizontal_line(start_x: f32, end_x: f32, y: f32) -> Vec<Object> {
    vec![
        Object::Name(b"m".to_vec()),
        start_x.into(),
        y.into(),
        Object::Name(b"l".to_vec()),
        end_x.into(),
        y.into(),
        Object::Name(b"S".to_vec()),
    ]
}
```

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

### Draw Table with Basic Hook

Source: https://docs.rs/lopdf-table/0.5.0/src/lopdf_table/lib.rs.html

Demonstrates drawing a table with a simple hook to count begin and end calls. Ensure the `Hook` struct is defined and implemented correctly.

```rust
let mut hook = Hook {
            begin_calls: 0,
            end_calls: 0,
        };
        doc.draw_table_with_hook(page_id, table, (50.0, 750.0), Some(&mut hook))
            .expect("table draw with hook should succeed");

        assert_eq!(hook.begin_calls, 4);
        assert_eq!(hook.end_calls, 4);
```

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

### VZip Implementation

Source: https://docs.rs/lopdf-table/0.5.0/lopdf_table/table/struct.Cell.html

Provides functionality for zipping with a multi-lane lane.

```APIDOC
## impl<V, T> VZip<V> for T
where V: MultiLane<T>,

### fn vzip(self) -> V
```

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

### TryFrom Implementation

Source: https://docs.rs/lopdf-table/0.5.0/lopdf_table/table/struct.Cell.html

Enables attempting to convert one type into another, returning a Result.

```APIDOC
## impl<T, U> TryFrom<U> for T
where U: Into<T>,

### type Error = Infallible
The type returned in the event of a conversion error.

### fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
Performs the conversion. Read more
```

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

### Get Font Metrics for Cell in Rust

Source: https://docs.rs/lopdf-table/0.5.0/src/lopdf_table/drawing.rs.html

Retrieves the appropriate font metrics for a cell, prioritizing bold font metrics if the cell text is bold. Falls back to default font metrics if bold metrics are unavailable.

```rust
fn metrics_for_cell<'a>(
    table: &'a Table,
    cell: &crate::table::Cell,
) -> Option<&'a dyn crate::font::FontMetrics> {
    if cell_is_bold(cell) {
        table
            .bold_font_metrics
            .as_ref()
            .map(|m| m.as_ref())
            .or(table.font_metrics.as_ref().map(|m| m.as_ref()))
    } else {
        table.font_metrics.as_ref().map(|m| m.as_ref())
    }
}
```

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

### Register All Images and Ensure GState

Source: https://docs.rs/lopdf-table/0.5.0/src/lopdf_table/drawing.rs.html

Pre-registers all unique images from a table into the document. It also creates an ExtGState for overlay transparency if any image has an overlay defined.

```rust
pub(crate) fn register_all_images(doc: &mut Document, table: &Table) -> ImageXObjects {
    let mut registry = ImageXObjects::new();
    let mut has_overlay = false;
    for row in &table.rows {
        for cell in &row.cells {
            for image in &cell.images {
                registry.register(doc, image);
                if image.overlay.is_some() {
                    has_overlay = true;
                }
            }
        }
    }
    if has_overlay {
        registry.ensure_gstate(doc);
    }
    registry
}

```

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

### Create a Table with Unicode Characters

Source: https://docs.rs/lopdf-table/0.5.0/src/lopdf_table/lib.rs.html

Illustrates creating a table containing Unicode characters in its cells. It asserts the number of rows and that the layout calculation for the table is successful, even without explicit font metrics.

```rust
let table = Table::new()
            .add_row(Row::new(vec![
                Cell::new("caf\u{00e9}"),
                Cell::new("\u{00fc}ber"),
            ]))
            .add_row(Row::new(vec![
                Cell::new("\u{4f60}\u{597d}"),
                Cell::new("\u{00a9} 2025"),
            ]));

        assert_eq!(table.rows.len(), 2);
        let layout = layout::calculate_layout(&table);
        assert!(layout.is_ok());
```

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

### Providing an Alternative `Ok` Value with `or`

Source: https://docs.rs/lopdf-table/0.5.0/lopdf_table/error/type.Result.html

Shows how to return a secondary `Result` if the initial `Result` is `Err`.

```APIDOC
## Providing an Alternative `Ok` Value with `or`

### Description
Returns `res` if the result is `Err`, otherwise returns the `Ok` value of `self`. Arguments passed to `or` are eagerly evaluated.

### Method Signature
`pub fn or<F>(self, res: Result<T, F>) -> Result<T, F>`

### Examples
```rust
let x: Result<u32, &str> = Ok(2);
let y: Result<u32, &str> = Err("late error");
assert_eq!(x.or(y), Ok(2));

let x: Result<u32, &str> = Err("early error");
let y: Result<u32, &str> = Ok(2);
assert_eq!(x.or(y), Ok(2));

let x: Result<u32, &str> = Err("not a 2");
let y: Result<u32, &str> = Err("late error");
assert_eq!(x.or(y), Err("late error"));

let x: Result<u32, &str> = Ok(2);
let y: Result<u32, &str> = Ok(100);
assert_eq!(x.or(y), Ok(2));
```
```

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

### Create New ImageOverlay

Source: https://docs.rs/lopdf-table/0.5.0/lopdf_table/table/struct.ImageOverlay.html

Constructs a new ImageOverlay with the provided text and default values for other fields.

```rust
pub fn new(text: impl Into<String>) -> Self>
```

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

### and Method Usage

Source: https://docs.rs/lopdf-table/0.5.0/lopdf_table/error/type.Result.html

Demonstrates the `and` method, which returns the second `Result` if the first is `Ok`, otherwise returns the first `Result`'s `Err`. Arguments are eagerly evaluated.

```rust
let x: Result<u32, &str> = Ok(2);
let y: Result<&str, &str> = Err("late error");
assert_eq!(x.and(y), Err("late error"));
```

```rust
let x: Result<u32, &str> = Err("early error");
let y: Result<&str, &str> = Ok("foo");
assert_eq!(x.and(y), Err("early error"));
```

```rust
let x: Result<u32, &str> = Err("not a 2");
let y: Result<&str, &str> = Err("late error");
assert_eq!(x.and(y), Err("not a 2"));
```

```rust
let x: Result<u32, &str> = Ok(2);
let y: Result<&str, &str> = Ok("different result type");
assert_eq!(x.and(y), Ok("different result type"));
```

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

### ImageXObjects Registration and Management

Source: https://docs.rs/lopdf-table/0.5.0/src/lopdf_table/drawing.rs.html

Manages the registration of image XObjects within a PDF document for table drawing. It ensures images are added only once and returns a unique resource name for referencing. Also handles the creation and registration of an ExtGState for overlay transparency.

```rust
pub(crate) struct ImageXObjects {
    /// Maps Arc raw pointer → (resource_name, ObjectId)
    entries: HashMap<*const lopdf::Stream, (String, ObjectId)>,
    counter: usize,
    /// ExtGState ObjectId for overlay transparency (created on demand).
    gstate_id: Option<ObjectId>,
}

impl ImageXObjects {
    fn new() -> Self {
        Self {
            entries: HashMap::new(),
            counter: 0,
            gstate_id: None,
        }
    }

    /// Register an image in the document if not already registered.
    /// Returns the resource name to reference it with `Do`.
    fn register(&mut self, doc: &mut Document, image: &CellImage) -> String {
        let ptr = Arc::as_ptr(&image.xobject);
        if let Some((name, _)) = self.entries.get(&ptr) {
            return name.clone();
        }
        let name = format!("TblImg{}", self.counter);
        self.counter += 1;
        let obj_id = doc.add_object((*image.xobject).clone());
        self.entries.insert(ptr, (name.clone(), obj_id));
        name
    }

    /// Ensure an ExtGState for 50% opacity overlays exists in the document.
    fn ensure_gstate(&mut self, doc: &mut Document) {
        if self.gstate_id.is_some() {
            return;
        }
        let gs_dict = dictionary! {
            "Type" => "ExtGState",
            "ca" => Object::Real(0.5),
            "CA" => Object::Real(0.5),
        };
        self.gstate_id = Some(doc.add_object(gs_dict));
    }

    /// Register the ExtGState into a page's Resources/ExtGState dictionary.
    fn register_gstate_on_page(&self, doc: &mut Document, page_id: ObjectId) -> Result<()> {
        let gstate_obj_id = match self.gstate_id {
            Some(id) => id,
            None => return Ok(()),
        };

        // Get the Resources dictionary reference from the page
        let resources_ref = if let Ok(Object::Dictionary(page_dict)) = doc.get_object(page_id) {
            match page_dict.get(b"Resources") {
                Ok(Object::Reference(r)) => Some(*r),
                _ => None,
            }
        } else {
            None
        };

        let resources_id = match resources_ref {
            Some(id) => id,
            None => return Ok(()),
        };

        // Get or create ExtGState sub-dictionary on the Resources dictionary
        if let Ok(Object::Dictionary(res_dict)) = doc.get_object_mut(resources_id) {
            match res_dict.get_mut(b"ExtGState") {
                Ok(Object::Dictionary(gs_dict)) => {
                    gs_dict.set(OVERLAY_GSTATE_NAME, gstate_obj_id);
                }
                _ => {
                    let gs_sub = dictionary! {
                        OVERLAY_GSTATE_NAME => gstate_obj_id,
                    };
                    res_dict.set("ExtGState", gs_sub);
                }
            }
        }

        Ok(())
    }

    /// Register all image XObjects (and ExtGState if needed) into a page's Resources.
    pub(crate) fn register_on_page(&self, doc: &mut Document, page_id: ObjectId) -> Result<()> {
        for (_, (name, obj_id)) in &self.entries {
            doc.add_xobject(page_id, name.as_bytes().to_vec(), *obj_id)
                .map_err(|e| {
                    crate::error::TableError::DrawingError(format!(
                        "Failed to register image XObject: {e}"
                    ))
                })?;
        }
        self.register_gstate_on_page(doc, page_id)?;
        Ok(())
    }
}
```

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

### Create New Page for Table Continuation

Source: https://docs.rs/lopdf-table/0.5.0/src/lopdf_table/drawing.rs.html

Creates a new PDF page, inheriting properties like MediaBox and Resources from a source page. This is used to continue drawing a table that spans multiple pages. It ensures the new page is correctly linked to the document's Pages object and updates the page count.

```rust
/// Create a new page with the same configuration as the source page
fn create_new_page(doc: &mut Document, source_page_id: ObjectId) -> Result<ObjectId> {
    debug!("Creating new page for table continuation");

    // Get the parent Pages object from the source page
    let pages_id = if let Ok(Object::Dictionary(page_dict)) = doc.get_object(source_page_id) {
        if let Ok(Object::Reference(pages_ref)) = page_dict.get(b"Parent") {
            *pages_ref
        } else {
            return Err(crate::error::TableError::DrawingError(
                "Could not find parent Pages object".to_string(),
            ));
        }
    } else {
        return Err(crate::error::TableError::DrawingError(
            "Invalid page object".to_string(),
        ));
    };

    // Get MediaBox and Resources from source page
    let (media_box, resources_id) = 
        if let Ok(Object::Dictionary(page_dict)) = doc.get_object(source_page_id) {
            let media_box = page_dict.get(b"MediaBox").ok().cloned();
            let resources = page_dict.get(b"Resources").ok().cloned();
            (media_box, resources)
        } else {
            (None, None)
        };

    // Create new page dictionary
    let mut new_page_dict = dictionary! {
        "Type" => "Page",
        "Parent" => pages_id,
    };

    if let Some(media_box) = media_box {
        new_page_dict.set("MediaBox", media_box);
    } else {
        // Default to A4
        new_page_dict.set(
            "MediaBox",
            vec![0.into(), 0.into(), A4_WIDTH.into(), A4_HEIGHT.into()],
        );
    }

    if let Some(resources) = resources_id {
        new_page_dict.set("Resources", resources);
    }

    let new_page_id = doc.add_object(new_page_dict);

    // Add page to Pages kids array
    if let Ok(Object::Dictionary(pages_dict)) = doc.get_object_mut(pages_id) {
        if let Ok(Object::Array(kids)) = pages_dict.get_mut(b"Kids") {
            kids.push(new_page_id.into());
        }

        // Update page count
        if let Ok(Object::Integer(count)) = pages_dict.get(b"Count") {
            pages_dict.set("Count", Object::Integer(count + 1));
        }
    }

    trace!("Created new page {:?}", new_page_id);
    Ok(new_page_id)
}
```

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

### Test Backward Compatibility (No Font Metrics)

Source: https://docs.rs/lopdf-table/0.5.0/src/lopdf_table/lib.rs.html

Ensures that tables can be created and processed even when font metrics are not explicitly provided, maintaining backward compatibility with older PDF versions.

```rust
#[test]
    fn test_backward_compat_no_metrics() {
        // Tables without font_metrics should still work identically
        let mut doc = Document::with_version("1.5");
        let pages_id = doc.add_object(dictionary! {
            "Type" => "Pages",
            "Kids" => vec![],
            "Count" => 0,
        });
        let page_id = doc.add_object(dictionary! {
            "Type" => "Page",
            "Parent" => pages_id,

```

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

### Table::with_column_widths() Method

Source: https://docs.rs/lopdf-table/0.5.0/src/lopdf_table/table.rs.html

Sets the column width specifications for the table and returns the modified Table instance.

```rust
pub fn with_column_widths(mut self, widths: Vec<ColumnWidth>) -> Self {
    self.column_widths = Some(widths);
    self
}
```

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

### Calculate Layouts and Assert Bold Metrics Impact

Source: https://docs.rs/lopdf-table/0.5.0/src/lopdf_table/lib.rs.html

Calculates the layout for tables with and without bold font metrics, then asserts that the layout using bold metrics results in a greater total width. This confirms that bold metrics are correctly applied.

```rust
let regular_layout = layout::calculate_layout(&table_regular_only)
    .expect("layout should succeed with regular metrics only");
let bold_layout = layout::calculate_layout(&table_with_bold_metrics)
    .expect("layout should succeed with bold metrics");

assert!(
    bold_layout.total_width > regular_layout.total_width,
    "expected bold metrics to increase width: regular={} bold={}",
    regular_layout.total_width,
    bold_layout.total_width
);
```

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

### Test Cell Builder Methods

Source: https://docs.rs/lopdf-table/0.5.0/src/lopdf_table/table.rs.html

Demonstrates chaining multiple cell builder methods like bold, italic, with_font_size, and with_colspan. Asserts the final state of the cell's content, colspan, and style properties.

```rust
#[test]
    fn test_cell_builder() {
        let cell = Cell::new("Test")
            .bold()
            .italic()
            .with_font_size(14.0)
            .with_colspan(2);

        assert_eq!(cell.content, "Test");
        assert_eq!(cell.colspan, 2);
        let style = cell.style.unwrap();
        assert!(style.bold);
        assert!(style.italic);
        assert_eq!(style.font_size, Some(14.0));
    }
```

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

### Test Bold Font Metrics Builder

Source: https://docs.rs/lopdf-table/0.5.0/src/lopdf_table/table.rs.html

Tests the integration of custom font metrics, specifically for bold text, by providing a `DummyMetrics` implementation. Asserts that the `bold_font_metrics` field is set.

```rust
#[test]
    fn test_with_bold_font_metrics_builder() {
        struct DummyMetrics;

        impl crate::font::FontMetrics for DummyMetrics {
            fn char_width(&self, _ch: char, _font_size: f32) -> f32 {
                5.0
            }

            fn text_width(&self, text: &str, _font_size: f32) -> f32 {
                text.chars().count() as f32 * 5.0
            }

            fn encode_text(&self, text: &str) -> Vec<u8> {
                vec![0; text.chars().count() * 2]
            }
        }

        let table = Table::new().with_bold_font_metrics(DummyMetrics);
        assert!(table.bold_font_metrics.is_some());
    }
```

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

### From Implementation

Source: https://docs.rs/lopdf-table/0.5.0/lopdf_table/layout/struct.TableLayout.html

A generic implementation that returns the argument unchanged, useful for identity conversions.

```rust
fn from(t: T) -> T
```

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

### Generate Tiny PNG Bytes

Source: https://docs.rs/lopdf-table/0.5.0/src/lopdf_table/lib.rs.html

Creates a minimal 4x3 PNG image as a byte vector for testing purposes. Requires the 'image' crate.

```rust
fn tiny_png_bytes() -> Vec<u8> {
        use image::{ImageBuffer, Rgb};
        let img: ImageBuffer<Rgb<u8>, Vec<u8>> = 
            ImageBuffer::from_fn(4, 3, |_, _| Rgb([0, 128, 255]));
        let mut buf = std::io::Cursor::new(Vec::new());
        img.write_to(&mut buf, image::ImageFormat::Png)
            .expect("PNG encoding should succeed");
        buf.into_inner()
    }
```
Tokens:
Raw