Pngmeta

https://docs.rs/pngmeta/latest/
Admin
Pngmeta is a Rust project that provides functionality for reading and writing text chunks in PNG...
Tokens:9,237
Snippets:84
Trust Score:9.1
Update:4 months ago
Show doc for...
Tokens:
Raw
### Find IEND Chunk Position

Source: https://docs.rs/pngmeta/latest/src/pngmeta/write.rs.html

Locates the starting byte offset of the IEND chunk within PNG data. Skips the PNG signature and iterates through chunks to find 'IEND'.

```rust
fn find_iend_position(data: &[u8]) -> io::Result<usize> {
    // Skip PNG signature
    let mut pos = 8;

    while pos + 8 <= data.len() {
        let length = u32::from_be_bytes([data[pos], data[pos + 1], data[pos + 2], data[pos + 3]]);
        let chunk_type = &data[pos + 4..pos + 8];

        if chunk_type == b"IEND" {
            return Ok(pos);
        }

        // length(4) + type(4) + data(length) + crc(4)
        let chunk_total = 4 + 4 + length as usize + 4;
        pos = pos
            .checked_add(chunk_total)
            .ok_or_else(|| io::Error::new(io::ErrorKind::InvalidData, "chunk size overflow"))?;
    }

    Err(io::Error::new(
        io::ErrorKind::InvalidData,
        "IEND chunk not found",
    ))
}
```

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

### Write Multiple Text Chunks Sequentially

Source: https://docs.rs/pngmeta/latest/src/pngmeta/write.rs.html

Demonstrates writing two text chunks ('alpha' and 'beta') to a PNG file and then verifying their content and count.

```Rust
    #[test]
    fn write_multiple_chunks_sequentially() {
        let path = write_test_png("pngmeta_write_multi.png", &[]);
        write_text_chunk(&path, "alpha", "a").unwrap();
        write_text_chunk(&path, "beta", "b").unwrap();

        let chunks = read_text_chunks(&path).unwrap();
        assert_eq!(chunks.len(), 2);
        assert_eq!(chunks["alpha"], "a");
        assert_eq!(chunks["beta"], "b");
        std::fs::remove_file(&path).ok();
    }
```

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

### pngmeta Library Overview

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

This snippet provides a high-level overview of the pngmeta library, including its purpose, core functionalities, and re-exported modules. It also defines the PNG file signature constant.

```rust
1//! pngmeta: Read and write PNG tEXt metadata chunks.
2//!
3//! Low-level library for PNG tEXt chunk I/O without image decoding.
4//! Operates directly on the binary PNG structure using only std.
5
6mod read;
7mod write;
8
9#[cfg(any(test, feature = "test-util"))]
10pub mod test_util;
11
12pub use read::{contains_in_text_chunks, read_text_chunks, scan_text_chunks};
13pub use write::write_text_chunk;
14
15/// PNG file signature (8 bytes).
16const PNG_SIGNATURE: [u8; 8] = [137, 80, 78, 71, 13, 10, 26, 10];

```

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

### Verify Sorted Text Chunk Keys

Source: https://docs.rs/pngmeta/latest/src/pngmeta/read.rs.html

Reads text chunks from a PNG file and verifies that the keys are returned in sorted order.

```rust
    #[test]
    fn keys_are_sorted() {
        let path = write_test_png(
            "pngmeta_test_sorted.png",
            &[("zebra", "z"), ("alpha", "a"), ("middle", "m")],
        );
        let chunks = read_text_chunks(&path).unwrap();
        let keys: Vec<&String> = chunks.keys().collect();
        assert_eq!(keys, vec!["alpha", "middle", "zebra"]);
        std::fs::remove_file(&path).ok();
    }
```

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

### Test: Write to Empty PNG

Source: https://docs.rs/pngmeta/latest/src/pngmeta/write.rs.html

Tests writing a tEXt chunk to a newly created, empty PNG file. Verifies that the chunk is correctly added and readable.

```rust
#[test]
fn write_to_empty_png() {
    let path = write_test_png("pngmeta_write_empty.png", &[]);
    write_text_chunk(&path, "vdsl", r#"{"seed":42}"#).unwrap();

    let chunks = read_text_chunks(&path).unwrap();
    assert_eq!(chunks.len(), 1);
    assert_eq!(chunks["vdsl"], r#"{"seed":42}"#);
    std::fs::remove_file(&path).ok();
}
```

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

### Read All tEXt Chunks into a Map

Source: https://docs.rs/pngmeta/latest/src/pngmeta/read.rs.html

Extracts all tEXt chunks from a PNG file and returns them as a sorted BTreeMap of keyword-to-text string pairs. Non-tEXt chunks are skipped efficiently.

```rust
pub fn read_text_chunks(path: &Path) -> io::Result<BTreeMap<String, String>> {
    let file = File::open(path)?;
    let mut reader = BufReader::new(file);

    let mut sig = [0u8; 8];
    reader.read_exact(&mut sig)?;
    if sig != PNG_SIGNATURE {
        return Err(io::Error::new(io::ErrorKind::InvalidData, "not a PNG file"));
    }

    let mut chunks = BTreeMap::new();
    let mut header = [0u8; 8];

    while reader.read_exact(&mut header).is_ok() {
        let length = u32::from_be_bytes([header[0], header[1], header[2], header[3]]);

        if &header[4..8] == b"tEXt" {
            let mut data = vec![0u8; length as usize];
            reader.read_exact(&mut data)?;
            reader.seek(SeekFrom::Current(4))?; // skip CRC

            if let Some(null_pos) = data.iter().position(|&b| b == 0) {
                let keyword = String::from_utf8_lossy(&data[..null_pos]).into_owned();
                let text = String::from_utf8_lossy(&data[null_pos + 1..]).into_owned();
                chunks.insert(keyword, text);
            }
        } else if &header[4..8] == b"IEND" {
            break;
        } else {
            reader.seek(SeekFrom::Current(i64::from(length) + 4))?;
        }
    }

    Ok(chunks)
}
```

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

### Check for Byte Pattern in tEXt Chunks

Source: https://docs.rs/pngmeta/latest/src/pngmeta/read.rs.html

Searches for a specific byte pattern (needle) within the raw data of all tEXt chunks in a PNG file. Uses SIMD-accelerated search for efficiency and exits on the first match.

```rust
pub fn contains_in_text_chunks(path: &Path, needle: &[u8]) -> io::Result<bool> {
    let finder = memmem::Finder::new(needle);
    scan_text_chunks(path, |data| finder.find(data).is_some())
}
```

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

### Build tEXt Chunk Bytes

Source: https://docs.rs/pngmeta/latest/src/pngmeta/write.rs.html

Constructs a complete tEXt chunk including length, type, data, and CRC-32. The data is formed by concatenating the keyword, a null byte, and the text.

```rust
fn build_text_chunk(keyword: &str, text: &str) -> Vec<u8> {
    let mut chunk_data = Vec::with_capacity(keyword.len() + 1 + text.len());
    chunk_data.extend_from_slice(keyword.as_bytes());
    chunk_data.push(0); // null separator
    chunk_data.extend_from_slice(text.as_bytes());

    let length = chunk_data.len() as u32;

    let mut crc_input = Vec::with_capacity(4 + chunk_data.len());
    crc_input.extend_from_slice(b"tEXt");
    crc_input.extend_from_slice(&chunk_data);
    let crc = crc32(&crc_input);

    let mut buf = Vec::with_capacity(4 + 4 + chunk_data.len() + 4);
    buf.extend_from_slice(&length.to_be_bytes());
    buf.extend_from_slice(b"tEXt");
    buf.extend_from_slice(&chunk_data);
    buf.extend_from_slice(&crc.to_be_bytes());
    buf
}
```

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

### scan_text_chunks

Source: https://docs.rs/pngmeta/latest/pngmeta/fn.scan_text_chunks.html

Scans tEXt chunks in a PNG file and applies a predicate to their raw byte data. It allows for early exit if the predicate returns true.

```APIDOC
## scan_text_chunks

### Description
Scan tEXt chunks with a caller-supplied predicate on raw bytes. Iterates over tEXt chunks in the PNG file, passing each chunk’s raw data (keyword + null + text) to `predicate`. Returns `Ok(true)` as soon as any call returns `true` (early exit).
This is the low-level building block for binary-level searches. No UTF-8 decoding, JSON parsing, or collection construction occurs.

### Signature
```rust
pub fn scan_text_chunks<F>(path: &Path, predicate: F) -> Result<bool>
where
    F: FnMut(&[u8]) -> bool,
```

### Parameters
#### Path Parameter
- **path** (`&Path`) - The path to the PNG file to scan.

#### Function Parameter
- **predicate** (`F: FnMut(&[u8]) -> bool`) - A mutable closure that takes a byte slice (`&[u8]`) representing the raw tEXt chunk data (keyword + null + text) and returns a boolean. If the closure returns `true`, the scan will stop early.

### Returns
- `Result<bool>` - Returns `Ok(true)` if the predicate returned `true` for any chunk, `Ok(false)` if the predicate returned `false` for all chunks, or an error if the file could not be processed.
```

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

### Handle PNG Without Text Chunks

Source: https://docs.rs/pngmeta/latest/src/pngmeta/read.rs.html

Tests the behavior when reading a PNG file that contains no text chunks. Asserts that the returned chunk map is empty.

```rust
    #[test]
    fn returns_empty_for_png_without_text() {
        let path = write_test_png("pngmeta_test_notext.png", &[]);
        let chunks = read_text_chunks(&path).unwrap();
        assert!(chunks.is_empty());
        std::fs::remove_file(&path).ok();
    }
```

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

### Scan Text Chunks for Pattern Match

Source: https://docs.rs/pngmeta/latest/src/pngmeta/read.rs.html

Scans the text chunks of a PNG file for a specific byte pattern using a predicate. Returns true if the pattern is found.

```rust
    #[test]
    fn scan_returns_true_on_predicate_match() {
        let path = write_test_png("pngmeta_scan_match.png", &[("key", "value")]);
        let result =
            scan_text_chunks(&path, |data| data.windows(5).any(|w| w == b"value")).unwrap();
        assert!(result);
        std::fs::remove_file(&path).ok();
    }
```

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

### Check for Keyword in Text Chunks

Source: https://docs.rs/pngmeta/latest/src/pngmeta/read.rs.html

Checks if a given byte slice exists within the keys of any text chunks in a PNG file. Asserts true if found.

```rust
    #[test]
    fn contains_finds_in_keyword() {
        let path = write_test_png("pngmeta_contains_kw.png", &[("workflow", "data")]);
        assert!(contains_in_text_chunks(&path, b"workflow").unwrap());
        std::fs::remove_file(&path).ok();
    }
```

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

### Test: Reject Missing File

Source: https://docs.rs/pngmeta/latest/src/pngmeta/read.rs.html

Tests that `read_text_chunks` returns an error when the specified PNG file does not exist.

```rust
#[test]
fn rejects_missing_file() {
    let result = read_text_chunks(Path::new("/nonexistent/file.png"));
    assert!(result.is_err());
}
```

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

### Extract Multiple Text Chunks

Source: https://docs.rs/pngmeta/latest/src/pngmeta/read.rs.html

Reads a PNG file and extracts multiple text chunks. Asserts that the correct number of chunks are extracted and their values match the expected data.

```rust
    #[test]
    fn extracts_multiple_text_chunks() {
        let path = write_test_png(
            "pngmeta_test_multi.png",
            &[("prompt", "hello"), ("workflow", r#"{"nodes":[]}""#)],
        );
        let chunks = read_text_chunks(&path).unwrap();
        assert_eq!(chunks.len(), 2);
        assert_eq!(chunks["prompt"], "hello");
        assert_eq!(chunks["workflow"], r#"{"nodes":[]}""#);
        std::fs::remove_file(&path).ok();
    }
```

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

### Scan Text Chunks When No Match

Source: https://docs.rs/pngmeta/latest/src/pngmeta/read.rs.html

Scans the text chunks of a PNG file for a specific byte pattern. Returns false if the pattern is not found.

```rust
    #[test]
    fn scan_returns_false_when_no_match() {
        let path = write_test_png("pngmeta_scan_nomatch.png", &[("key", "value")]);
        let result =
            scan_text_chunks(&path, |data| data.windows(6).any(|w| w == b"absent")).unwrap();
        assert!(!result);
        std::fs::remove_file(&path).ok();
    }
```

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

### Scan tEXt Chunks with Predicate

Source: https://docs.rs/pngmeta/latest/src/pngmeta/read.rs.html

Iterates over tEXt chunks in a PNG file, passing raw chunk data to a predicate function for custom processing. Exits early if the predicate returns true. Useful for binary-level searches.

```rust
pub fn scan_text_chunks<F>(path: &Path, mut predicate: F) -> io::Result<bool>
where
    F: FnMut(&[u8]) -> bool,
{
    let file = File::open(path)?;
    let mut reader = BufReader::new(file);

    let mut sig = [0u8; 8];
    reader.read_exact(&mut sig)?;
    if sig != PNG_SIGNATURE {
        return Err(io::Error::new(io::ErrorKind::InvalidData, "not a PNG file"));
    }

    let mut header = [0u8; 8];

    while reader.read_exact(&mut header).is_ok() {
        let length = u32::from_be_bytes([header[0], header[1], header[2], header[3]]);

        if &header[4..8] == b"tEXt" {
            let mut data = vec![0u8; length as usize];
            reader.read_exact(&mut data)?;
            reader.seek(SeekFrom::Current(4))?; // skip CRC

            if predicate(&data) {
                return Ok(true);
            }
        } else if &header[4..8] == b"IEND" {
            break;
        } else {
            reader.seek(SeekFrom::Current(i64::from(length) + 4))?;
        }
    }

    Ok(false)
}
```

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

### Extract Single Text Chunk

Source: https://docs.rs/pngmeta/latest/src/pngmeta/read.rs.html

Reads a PNG file and extracts a single text chunk by its key. Asserts that exactly one chunk exists and matches the expected value.

```rust
    #[test]
    fn extracts_single_text_chunk() {
        let path = write_test_png("pngmeta_test_single.png", &[("vdsl", r#"{"seed":42}""#)]);
        let chunks = read_text_chunks(&path).unwrap();
        assert_eq!(chunks.len(), 1);
        assert_eq!(chunks["vdsl"], r#"{"seed":42}""#);
        std::fs::remove_file(&path).ok();
    }
```

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

### Test: Reject Non-PNG File

Source: https://docs.rs/pngmeta/latest/src/pngmeta/read.rs.html

Tests that `read_text_chunks` returns an error when attempting to read a file that is not a valid PNG.

```rust
#[test]
fn rejects_non_png() {
    let path = std::env::temp_dir().join("pngmeta_test_not_a_png.txt");
    std::fs::write(&path, b"hello world").unwrap();
    let result = read_text_chunks(&path);
    assert!(result.is_err());
    std::fs::remove_file(&path).ok();
}
```

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

### Test: Reject Non-PNG File

Source: https://docs.rs/pngmeta/latest/src/pngmeta/write.rs.html

Tests that the `write_text_chunk` function returns an error when attempting to write to a file that is not a valid PNG.

```rust
#[test]
fn write_rejects_non_png() {
    let path = std::env::temp_dir().join("pngmeta_write_not_png.txt");
    std::fs::write(&path, b"not a png").unwrap();

    let result = write_text_chunk(&path, "key", "value");
    assert!(result.is_err());
}
```

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

### Test: Preserve Existing Chunks

Source: https://docs.rs/pngmeta/latest/src/pngmeta/write.rs.html

Tests writing a new tEXt chunk while preserving any pre-existing chunks in the PNG file. Verifies that both old and new chunks are present after the operation.

```rust
#[test]
fn write_preserves_existing_chunks() {
    let path = write_test_png("pngmeta_write_preserve.png", &[("prompt", "hello")]);
    write_text_chunk(&path, "vdsl", r#"{"seed":1}"#).unwrap();

    let chunks = read_text_chunks(&path).unwrap();
    assert_eq!(chunks.len(), 2);
    assert_eq!(chunks["prompt"], "hello");
    assert_eq!(chunks["vdsl"], r#"{"seed":1}"#);
    std::fs::remove_file(&path).ok();
}
```

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

### Read tEXt Chunks from PNG

Source: https://docs.rs/pngmeta/latest/pngmeta/fn.read_text_chunks.html

Extracts all tEXt chunks from a PNG file. Returns keyword → text pairs in sorted order. Reads chunk headers sequentially; non-tEXt data is seeked over without loading into memory.

```rust
pub fn read_text_chunks(path: &Path) -> Result<BTreeMap<String, String>>
```

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

### Test: Extract Single Text Chunk

Source: https://docs.rs/pngmeta/latest/src/pngmeta/read.rs.html

Tests the extraction of a single tEXt chunk from a PNG file. Verifies that the keyword and text are correctly parsed and stored.

```rust
#[test]
fn extracts_single_text_chunk() {
    let path = write_test_png("pngmeta_test_single.png", &[("vdsl", r#"{"seed":42}""#)]);
    let chunks = read_text_chunks(&path).unwrap();

```

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

### Write Text Chunk to PNG

Source: https://docs.rs/pngmeta/latest/pngmeta/fn.write_text_chunk.html

Writes a tEXt chunk into an existing PNG file. The chunk is inserted before the IEND marker. CRC-32 is computed according to the PNG specification. Returns an error if the file is not a valid PNG or if I/O fails.

```rust
pub fn write_text_chunk(path: &Path, keyword: &str, text: &str) -> Result<()>
```

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

### read_text_chunks

Source: https://docs.rs/pngmeta/latest/pngmeta/fn.read_text_chunks.html

Extracts all tEXt chunks from a PNG file. Returns keyword → text pairs in sorted order. Reads chunk headers sequentially; non-tEXt data is seeked over without loading into memory.

```APIDOC
## read_text_chunks

### Description
Extracts all tEXt chunks from a PNG file. Returns keyword → text pairs in sorted order. Reads chunk headers sequentially; non-tEXt data is seeked over without loading into memory.

### Function Signature
```rust
pub fn read_text_chunks(path: &Path) -> Result<BTreeMap<String, String>>
```

### Parameters
#### Path Parameters
- **path** (*&Path*) - The path to the PNG file.

### Returns
- **Result<BTreeMap<String, String>>** - A Result containing a BTreeMap of keyword-text pairs if successful, or an error otherwise.
```

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

### Scan Text Chunks with Early Exit

Source: https://docs.rs/pngmeta/latest/src/pngmeta/read.rs.html

Tests that the `scan_text_chunks` function exits early as soon as the predicate returns true, counting the number of predicate calls.

```rust
    #[test]
    fn scan_early_exits() {
        let path = write_test_png(
            "pngmeta_scan_early.png",
            &[("a", "hit"), ("b", "hit"), ("c", "miss")],
        );
        let mut call_count = 0usize;
        let result = scan_text_chunks(&path, |data| {
            call_count += 1;
            data.windows(3).any(|w| w == b"hit")
        })
        .unwrap();
        assert!(result);
        assert_eq!(call_count, 1);
        std::fs::remove_file(&path).ok();
    }
```

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

### Scan Text Chunks Rejects Non-PNG

Source: https://docs.rs/pngmeta/latest/src/pngmeta/read.rs.html

Tests that `scan_text_chunks` returns an error when provided with a file that is not a valid PNG.

```rust
    #[test]
    fn scan_rejects_non_png() {
        let path = std::env::temp_dir().join("pngmeta_scan_bad.txt");
        std::fs::write(&path, b"not png").unwrap();
        assert!(scan_text_chunks(&path, |_| true).is_err());
        std::fs::remove_file(&path).ok();
    }
```

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

### Verify CRC32 Known Value

Source: https://docs.rs/pngmeta/latest/src/pngmeta/write.rs.html

Asserts that the CRC32 calculation for the 'IEND' chunk matches the expected value specified in the PNG standard.

```Rust
    #[test]
    fn crc32_known_value() {
        // "IEND" → 0xAE426082 per PNG spec
        assert_eq!(crc32(b"IEND"), 0xAE42_6082);
    }
```

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

### CRC-32 Calculation

Source: https://docs.rs/pngmeta/latest/src/pngmeta/write.rs.html

Computes the CRC-32 checksum for a given byte slice according to the PNG specification (ISO 3309 / ITU-T V.42).

```rust
fn crc32(data: &[u8]) -> u32 {
    let mut crc: u32 = 0xFFFF_FFFF;
    for &byte in data {
        crc ^= u32::from(byte);
        for _ in 0..8 {
            if crc & 1 != 0 {
                crc = (crc >> 1) ^ 0xEDB8_8320;
            } else {
                crc >>= 1;
            }
        }
    }
    crc ^ 0xFFFF_FFFF
}
```

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

### write_text_chunk

Source: https://docs.rs/pngmeta/latest/pngmeta/fn.write_text_chunk.html

Writes a tEXt chunk into an existing PNG file. The chunk is inserted immediately before the IEND marker. CRC-32 is computed per the PNG specification (over type + data).

```APIDOC
## Function write_text_chunk

### Description
Writes a tEXt chunk into an existing PNG file. The chunk is inserted immediately before the IEND marker. CRC-32 is computed per the PNG specification (over type + data).

### Signature
```rust
pub fn write_text_chunk(path: &Path, keyword: &str, text: &str) -> Result<()>
```

### Parameters
* `path` (*Path) - The path to the PNG file.
* `keyword` (*str) - The keyword for the tEXt chunk.
* `text` (*str) - The text content for the tEXt chunk.

### Errors
Returns an error if the file is not a valid PNG or if I/O fails.
```

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

### Check for Value in Text Chunks

Source: https://docs.rs/pngmeta/latest/src/pngmeta/read.rs.html

Checks if a given byte slice exists within the values of any text chunks in a PNG file. Asserts true if found.

```rust
    #[test]
    fn contains_finds_in_text_value() {
        let path = write_test_png("pngmeta_contains_val.png", &[("vdsl", r#"{"seed":42}""#)]);
        assert!(contains_in_text_chunks(&path, b"seed").unwrap());
        std::fs::remove_file(&path).ok();
    }
```

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

### scan_text_chunks

Source: https://docs.rs/pngmeta/latest/pngmeta

Scans tEXt chunks with a caller-supplied predicate on raw bytes. This offers a flexible way to process tEXt chunks based on custom criteria.

```APIDOC
## Function: scan_text_chunks

### Description
Scans tEXt chunks with a caller-supplied predicate on raw bytes. This offers a flexible way to process tEXt chunks based on custom criteria.

### Signature
```rust
pub fn scan_text_chunks<F>(png: &[u8], mut predicate: F) -> bool where F: FnMut(&str, &str) -> bool
```

### Parameters
#### Path Parameters
- **png** (bytes) - Required - The raw bytes of the PNG file.
- **predicate** (closure) - Required - A closure that takes the keyword and text of a tEXt chunk and returns `true` if the chunk matches the criteria.

### Returns
- **bool** - Returns `true` if the `predicate` returns `true` for any tEXt chunk, `false` otherwise.
```

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

### scan_text_chunks

Source: https://docs.rs/pngmeta/latest/index.html

Scans tEXt chunks with a caller-supplied predicate on raw bytes. This offers a flexible way to process tEXt chunks based on custom criteria applied directly to the raw byte data.

```APIDOC
## Function: scan_text_chunks

### Description
Scans tEXt chunks with a caller-supplied predicate on raw bytes.

### Signature
```rust
pub fn scan_text_chunks<F>(png: &[u8], mut predicate: F) -> bool
where
    F: FnMut(&[u8]) -> bool,
```

### Parameters
* `png` (*&[u8]*) - The byte slice representing the PNG file.
* `predicate` (*F*) - A closure that takes a byte slice (representing tEXt chunk data) and returns a boolean. The scan stops and returns `true` if the predicate returns `true` for any chunk.
```

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

### write_text_chunk

Source: https://docs.rs/pngmeta/latest/index.html

Writes a tEXt chunk into an existing PNG file. This function allows for the modification or addition of metadata to a PNG file without altering the image data itself.

```APIDOC
## Function: write_text_chunk

### Description
Write a tEXt chunk into an existing PNG file.

### Signature
```rust
pub fn write_text_chunk(png: &mut [u8], chunk: (&str, &str))
```

### Parameters
* `png` (*&mut [u8]*) - A mutable byte slice representing the PNG file to be modified.
* `chunk` (*(&str, &str)*) - A tuple containing the key and value for the tEXt chunk to be written.
```

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

### scan_text_chunks Function Signature

Source: https://docs.rs/pngmeta/latest/pngmeta/fn.scan_text_chunks.html

Signature for the scan_text_chunks function. It takes a file path and a mutable closure that operates on byte slices. The closure determines if the scan should exit early.

```rust
pub fn scan_text_chunks<F>(path: &Path, predicate: F) -> Result<bool>
where
    F: FnMut(&[u8]) -> bool,

```

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

### write_text_chunk

Source: https://docs.rs/pngmeta/latest/pngmeta/index.html

Writes a tEXt chunk into an existing PNG file. This function enables adding or updating metadata within a PNG image.

```APIDOC
## Function: write_text_chunk

### Description
Writes a tEXt chunk into an existing PNG file.

### Parameters
* `png_bytes` (*bytes) - The raw bytes of the PNG file.
* `chunk` (*TextChunk) - The tEXt chunk to write. This includes the keyword and text value.

### Returns
* `Vec<u8>` - The modified PNG file bytes with the new tEXt chunk written.
```

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

### write_text_chunk

Source: https://docs.rs/pngmeta/latest/pngmeta

Writes a tEXt chunk into an existing PNG file. This function allows for the modification or addition of metadata to a PNG image.

```APIDOC
## Function: write_text_chunk

### Description
Writes a tEXt chunk into an existing PNG file. This function allows for the modification or addition of metadata to a PNG image.

### Signature
```rust
pub fn write_text_chunk(png: &mut [u8], keyword: &str, text: &str) -> Result<(), pngmeta::Error>
```

### Parameters
#### Path Parameters
- **png** (mutable bytes) - Required - A mutable slice representing the PNG file data.
- **keyword** (string) - Required - The keyword for the tEXt chunk.
- **text** (string) - Required - The text content for the tEXt chunk.

### Returns
- **Result<(), pngmeta::Error>** - Returns `Ok(())` on success, or an `Err` containing a `pngmeta::Error` if the operation fails.
```

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

### Check for Value in Empty PNG

Source: https://docs.rs/pngmeta/latest/src/pngmeta/read.rs.html

Tests that `contains_in_text_chunks` returns false when checking a PNG file that has no text chunks.

```rust
    #[test]
    fn contains_returns_false_for_empty_png() {
        let path = write_test_png("pngmeta_contains_empty.png", &[]);
        assert!(!contains_in_text_chunks(&path, b"anything").unwrap());
        std::fs::remove_file(&path).ok();
    }
```

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

### contains_in_text_chunks Function Signature

Source: https://docs.rs/pngmeta/latest/pngmeta/fn.contains_in_text_chunks.html

This is the function signature for contains_in_text_chunks. It takes a file path and a byte slice as input and returns a Result indicating whether the byte pattern was found.

```rust
pub fn contains_in_text_chunks(path: &Path, needle: &[u8]) -> Result<bool>
```

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

### contains_in_text_chunks

Source: https://docs.rs/pngmeta/latest/src/pngmeta/read.rs.html

Searches for a specific byte pattern within the raw data of all tEXt chunks in a PNG file using SIMD acceleration. Returns true upon the first match.

```APIDOC
## contains_in_text_chunks

### Description
Searches for a byte pattern (`needle`) within the raw data of all tEXt chunks in a PNG file. Utilizes SIMD-accelerated searching for efficiency and provides early exit on match.

### Function Signature
`pub fn contains_in_text_chunks(path: &Path, needle: &[u8]) -> io::Result<bool>`

### Parameters
- **path** (`&Path`): The path to the PNG file.
- **needle** (`&[u8]`): The byte slice to search for within the tEXt chunk data.

### Returns
- `io::Result<bool>`: `Ok(true)` if the `needle` is found in any tEXt chunk, `Ok(false)` if the pattern is not found after scanning all chunks, or an `io::Error` if file operations fail or the file is not a valid PNG.
```

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

### Check for Value Rejects Non-PNG

Source: https://docs.rs/pngmeta/latest/src/pngmeta/read.rs.html

Tests that `contains_in_text_chunks` returns an error when provided with a file that is not a valid PNG.

```rust
    #[test]
    fn contains_rejects_non_png() {
        let path = std::env::temp_dir().join("pngmeta_contains_bad.txt");
        std::fs::write(&path, b"not png").unwrap();
        assert!(contains_in_text_chunks(&path, b"x").is_err());
        std::fs::remove_file(&path).ok();
    }
```

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

### Check for Absent Value in Text Chunks

Source: https://docs.rs/pngmeta/latest/src/pngmeta/read.rs.html

Checks if a given byte slice exists within the text chunks of a PNG file. Asserts false if the byte slice is not found.

```rust
    #[test]
    fn contains_returns_false_when_absent() {
        let path = write_test_png("pngmeta_contains_miss.png", &[("vdsl", r#"{"seed":1}""#)]);
        assert!(!contains_in_text_chunks(&path, b"nonexistent").unwrap());
        std::fs::remove_file(&path).ok();
    }
```

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

### scan_text_chunks

Source: https://docs.rs/pngmeta/latest/pngmeta/index.html

Scans tEXt chunks with a caller-supplied predicate on raw bytes. This provides a flexible way to filter or process tEXt chunks based on custom criteria applied to their raw byte content.

```APIDOC
## Function: scan_text_chunks

### Description
Scans tEXt chunks with a caller-supplied predicate on raw bytes.

### Parameters
* `png_bytes` (*bytes) - The raw bytes of the PNG file.
* `predicate` (*function) - A function that takes raw chunk bytes and returns a boolean.

### Returns
* `Vec<TextChunk>` - A vector of tEXt chunks that satisfy the predicate.
```

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

### Check for Value with Early Exit

Source: https://docs.rs/pngmeta/latest/src/pngmeta/read.rs.html

Tests that `contains_in_text_chunks` exits early upon finding the first match, optimizing the search.

```rust
    #[test]
    fn contains_early_exits_on_first_match() {
        let path = write_test_png(
            "pngmeta_contains_early.png",
            &[("a", "needle"), ("b", "needle"), ("c", "other")],
        );
        assert!(contains_in_text_chunks(&path, b"needle").unwrap());
        std::fs::remove_file(&path).ok();
    }
```

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

### contains_in_text_chunks

Source: https://docs.rs/pngmeta/latest/pngmeta/fn.contains_in_text_chunks.html

Searches tEXt chunk data for a byte pattern without decoding. This function uses SIMD-accelerated (`memmem`) search over each chunk’s raw bytes and returns `true` on the first match for early exit. It is a wrapper around `scan_text_chunks`.

```APIDOC
## Function contains_in_text_chunks

### Description
Searches tEXt chunk data for a byte pattern without decoding. This function uses SIMD-accelerated (`memmem`) search over each chunk’s raw bytes and returns `true` on the first match for early exit. It is a wrapper around `scan_text_chunks`.

### Signature
```rust
pub fn contains_in_text_chunks(path: &Path, needle: &[u8]) -> Result<bool>
```

### Parameters
* `path` (*Path) - The path to the PNG file.
* `needle` (*&[u8]) - The byte slice to search for within the tEXt chunks.

### Returns
* `Result<bool>` - Returns `Ok(true)` if the `needle` is found in any tEXt chunk, `Ok(false)` if not found, or an `Err` if an I/O error occurs.
```

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

### read_text_chunks

Source: https://docs.rs/pngmeta/latest/pngmeta/index.html

Extracts all tEXt chunks from a PNG file. This function allows retrieval of all metadata stored in tEXt chunks for further processing.

```APIDOC
## Function: read_text_chunks

### Description
Extracts all tEXt chunks from a PNG file.

### Parameters
* `png_bytes` (*bytes) - The raw bytes of the PNG file.

### Returns
* `Vec<TextChunk>` - A vector containing all extracted tEXt chunks. Each chunk typically includes a keyword and a text value.
```

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

### contains_in_text_chunks

Source: https://docs.rs/pngmeta/latest/pngmeta/index.html

Searches tEXt chunk data for a byte pattern without decoding the image. This function is useful for quickly checking for the presence of specific metadata within the PNG file.

```APIDOC
## Function: contains_in_text_chunks

### Description
Searches tEXt chunk data for a byte pattern without decoding.

### Parameters
* `png_bytes` (*bytes) - The raw bytes of the PNG file.
* `pattern` (*bytes) - The byte pattern to search for within the tEXt chunks.

### Returns
* `bool` - True if the pattern is found in any tEXt chunk, false otherwise.
```

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

### read_text_chunks

Source: https://docs.rs/pngmeta/latest/pngmeta

Extracts all tEXt chunks from a PNG file. This function provides a way to retrieve all metadata stored in tEXt chunks for further processing.

```APIDOC
## Function: read_text_chunks

### Description
Extracts all tEXt chunks from a PNG file. This function provides a way to retrieve all metadata stored in tEXt chunks for further processing.

### Signature
```rust
pub fn read_text_chunks(png: &[u8]) -> Vec<(String, String)>
```

### Parameters
#### Path Parameters
- **png** (bytes) - Required - The raw bytes of the PNG file.

### Returns
- **Vec<(String, String)>** - A vector of tuples, where each tuple contains the keyword and the text content of a tEXt chunk.
```

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

### contains_in_text_chunks

Source: https://docs.rs/pngmeta/latest/index.html

Searches tEXt chunk data for a byte pattern without decoding the image. This function allows for efficient searching within metadata without the overhead of image processing.

```APIDOC
## Function: contains_in_text_chunks

### Description
Searches tEXt chunk data for a byte pattern without decoding.

### Signature
```rust
pub fn contains_in_text_chunks(png: &[u8], needle: &[u8]) -> bool
```

### Parameters
* `png` (*&[u8]*) - The byte slice representing the PNG file.
* `needle` (*&[u8]*) - The byte pattern to search for within the tEXt chunks.
```

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

### contains_in_text_chunks

Source: https://docs.rs/pngmeta/latest/pngmeta

Searches tEXt chunk data for a byte pattern without decoding the image. This function allows for efficient searching within metadata without the overhead of image processing.

```APIDOC
## Function: contains_in_text_chunks

### Description
Searches tEXt chunk data for a byte pattern without decoding the image. This function allows for efficient searching within metadata without the overhead of image processing.

### Signature
```rust
pub fn contains_in_text_chunks(png: &[u8], needle: &[u8]) -> bool
```

### Parameters
#### Path Parameters
- **png** (bytes) - Required - The raw bytes of the PNG file.
- **needle** (bytes) - Required - The byte pattern to search for within the tEXt chunks.

### Returns
- **bool** - Returns `true` if the `needle` is found in any tEXt chunk, `false` otherwise.
```
Tokens:
Raw