Struct admerge::RsMerger

pub struct RsMerger<'a> { /* fields omitted */ }

A Merger that can merge multiple sources that implement Read and Seek into one.

Generally speaking, when using RsMerger, you’ll first call new to create a merger builder, then call configuration methods to set each option. And eventually, call merge_sources_into to actually merge multiple sources into a given writer.

Behaviours

The current algorithm to merge sources is described as following:

1. If any leading padding is given by pad_with, writes it into the writer.
2. For each source, if skip range is given by skip_head and skip_tail, writes the contents remaining into the writer.
3. For each source, if forcing ending newline option is set by force_ending_newline, writes a ending newline into the writer if this source is not ends with a newline.
4. For each source, if any inner padding is given by pad_with, writes it into the writer.
5. If any ending padding is given by pad_with, writes it into the writer.

Examples

use admerge::{RsMerger, Skip, Pad, Newline, Result};
use std::io::Cursor;

fn main() -> Result<()> {
    // Cursor implements `Read` and `Seek`.
    let mut c1 = Cursor::new(" record 1\n date created: 2000/01/01\n");
    let mut c2 = Cursor::new(" record 2\n date created: 2000/01/01\n");
    let mut c3 = Cursor::new(" record 3\n date created: 2000/01/01\n");
    let mut buf = Vec::new();

    // Configures merger.
    let mut merger = RsMerger::new();
    merger.skip_tail(Skip::LinesOnce(1));
    merger.pad_with(Pad::Before(b"header\n"));
    merger.force_ending_newline(Newline::Lf);

    // Merges sources into one.
    merger.merge_sources_into(vec![&mut c1, &mut c2, &mut c3], &mut buf)?;
    assert_eq!(
        std::str::from_utf8(&buf).unwrap(),
        "header\n record 1\n record 2\n record 3\n date created: 2000/01/01\n"
    );

    Ok(())
}

Implementations

impl<'a> RsMerger<'a>

pub fn new() -> Self

Creates a new RsMerger builder.

Examples

use admerge::{RsMerger, Result};
use std::io::Cursor;

fn main() -> Result<()> {
    let c1 = Cursor::new("foo ");
    let c2 = Cursor::new("bar ");
    let c3 = Cursor::new("baz ");
    let mut buf = Vec::new();

    let merger = RsMerger::new();
    merger.merge_sources_into(vec![c1, c2, c3], &mut buf)?;

    Ok(())
}

pub fn skip_head(&mut self, skip: Skip<'a>) -> &mut Self

Configures this merger to skip partial of contents from the head of each source.

Examples

Keeps the first given source untouched, but skips first line from the rest sources.

use admerge::{RsMerger, Skip, Result};
use std::io::Cursor;

fn main() -> Result<()> {
    // Cursor implements `Read` and `Seek`.
    let mut c1 = Cursor::new("header\n record 1\n");
    let mut c2 = Cursor::new("header\n record 2\n");
    let mut c3 = Cursor::new("header\n record 3\n");
    let mut buf = Vec::new();

    // Configures merger.
    let mut merger = RsMerger::new();
    merger.skip_head(Skip::LinesOnce(1));

    // Merges sources into one.
    merger.merge_sources_into(vec![&mut c1, &mut c2, &mut c3], &mut buf)?;
    assert_eq!(
        std::str::from_utf8(&buf).unwrap(),
        "header\n record 1\n record 2\n record 3\n"
    );

    Ok(())
}

pub fn skip_tail(&mut self, skip: Skip<'a>) -> &mut Self

Configures this merger to skip partial of contents from the tail of each source.

Examples

Keeps the last given source untouched, but skips last line from the rest sources.

use admerge::{RsMerger, Skip, Result};
use std::io::Cursor;

fn main() -> Result<()> {
    // Cursor implements `Read` and `Seek`.
    let mut c1 = Cursor::new(" record 1\n date created: 2000/01/01\n");
    let mut c2 = Cursor::new(" record 2\n date created: 2000/01/01\n");
    let mut c3 = Cursor::new(" record 3\n date created: 2000/01/01\n");
    let mut buf = Vec::new();

    // Configures merger.
    let mut merger = RsMerger::new();
    merger.skip_tail(Skip::LinesOnce(1));

    // Merges sources into one.
    merger.merge_sources_into(vec![&mut c1, &mut c2, &mut c3], &mut buf)?;
    assert_eq!(
        std::str::from_utf8(&buf).unwrap(),
        " record 1\n record 2\n record 3\n date created: 2000/01/01\n"
    );

    Ok(())
}

pub fn pad_with(&mut self, padding: Pad<'a>) -> &mut Self

Configures this merger to fill some padding before, between or after the given sources.

Examples

use admerge::{RsMerger, Pad, Result};
use std::io::Cursor;

fn main() -> Result<()> {
    // Cursor implements `Read` and `Seek`.
    let mut c1 = Cursor::new(" record 1 ");
    let mut c2 = Cursor::new(" record 2 ");
    let mut c3 = Cursor::new(" record 3 ");
    let mut buf = Vec::new();

    // Configures merger.
    let mut merger = RsMerger::new();
    merger.pad_with(Pad::Custom(
        Some(b"header"),
        Some(b"padding"),
        Some(b"date created: 2000/01/01")
    ));

    // Merges sources into one.
    merger.merge_sources_into(vec![&mut c1, &mut c2, &mut c3], &mut buf)?;
    assert_eq!(
        std::str::from_utf8(&buf).unwrap(),
        "header record 1 padding record 2 padding record 3 date created: 2000/01/01"
    );

    Ok(())
}

pub fn force_ending_newline(&mut self, newline: Newline) -> &mut Self

Configures this merger to force the presence of ending newline after each source.

Noting that ending newlines are given after sources, not after paddings.

Examples

use admerge::{RsMerger, Newline, Result};
use std::io::Cursor;

fn main() -> Result<()> {
    // Cursor implements `Read` and `Seek`.
    let mut c1 = Cursor::new(" line 1 ");
    let mut c2 = Cursor::new(" line 2 ");
    let mut c3 = Cursor::new(" line 3 ");
    let mut buf = Vec::new();

    // Configures merger.
    let mut merger = RsMerger::new();
    merger.force_ending_newline(Newline::Crlf);

    // Merges sources into one.
    merger.merge_sources_into(vec![&mut c1, &mut c2, &mut c3], &mut buf)?;
    assert_eq!(
        std::str::from_utf8(&buf).unwrap(),
        " line 1 \r\n line 2 \r\n line 3 \r\n"
    );

    Ok(())
}

pub fn merge_sources_into<RS, W>(
    &self,
    sources: Vec<RS>,
    writer: &mut W
) -> Result<()> where
    RS: Read + Seek,
    W: Write, 

Merges the given sources into the given writer according to the given configurations.

Errors

Returns an error variant of ErrorKind::NothingPassed if the given source vector is empty;

Returns an error variant of ErrorKind::InvalidSkip if the given Skips cannot applied to the given sources;

Returns an error variant of ErrorKind::Io if any I/O errors were encountered.

Examples

use admerge::{RsMerger, Skip, Pad, Newline, Result};
use std::io::Cursor;

fn main() -> Result<()> {
    // Cursor implements `Read` and `Seek`.
    let mut c1 = Cursor::new(" record 1\n date created: 2000/01/01\n");
    let mut c2 = Cursor::new(" record 2\n date created: 2000/01/01\n");
    let mut c3 = Cursor::new(" record 3\n date created: 2000/01/01\n");
    let mut buf = Vec::new();

    // Configures merger.
    let mut merger = RsMerger::new();
    merger.skip_tail(Skip::LinesOnce(1));
    merger.pad_with(Pad::Before(b"header\n"));
    merger.force_ending_newline(Newline::Lf);

    // Merges sources into one.
    merger.merge_sources_into(vec![&mut c1, &mut c2, &mut c3], &mut buf)?;
    assert_eq!(
        std::str::from_utf8(&buf).unwrap(),
        "header\n record 1\n record 2\n record 3\n date created: 2000/01/01\n"
    );

    Ok(())
}

Trait Implementations

impl<'a> Clone for RsMerger<'a>

fn clone(&self) -> RsMerger<'a>

Returns a copy of the value.

pub fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for RsMerger<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> Default for RsMerger<'a>

fn default() -> Self

Returns the “default value” for a type.