Struct ebml_iterable::TagWriter

pub struct TagWriter<W: Write> { /* private fields */ }

Provides a tool to write EBML files based on Tags. Writes to a destination that implements std::io::Write.

Unlike the TagIterator, this does not require a specification to write data. This writer provides the write_raw() method which can be used to write data that is outside of any specification. The regular write() method can be used to write any TSpec objects regardless of whether they came from a TagIterator or not.

Implementations

impl<W: Write> TagWriter<W>

pub fn new(dest: W) -> Self

Returns a new TagWriter instance.

The dest parameter can be anything that implements std::io::Write.

pub fn into_inner(self) -> Result<W, TagWriterError>

Consumes self and returns the underlying write stream.

Any incomplete tags are written out before returning the stream.

pub fn get_mut(&mut self) -> &mut W

Gets a mutable reference to the underlying write stream.

pub fn get_ref(&self) -> &W

Gets a reference to the underlying write stream.

pub fn write<TSpec: EbmlSpecification<TSpec> + EbmlTag<TSpec> + Clone>( &mut self, tag: &TSpec ) -> Result<(), TagWriterError>

Write a tag to this instance’s destination.

This method writes a tag from any specification. There are no restrictions on the type of specification being written - it simply needs to implement the EbmlSpecification and EbmlTag traits.

Errors

This method can error if there is a problem writing the input tag. The different possible error states are enumerated in TagWriterError.

Panics

This method can panic if <TSpec> is an internally inconsistent specification (i.e. it claims that a specific tag variant is a specific data type but it is not). This won’t happen if the specification being used was created using the #[ebml_specification] attribute macro.

Examples

use std::fs::File;
use ebml_iterable::TagWriter;
use ebml_iterable::specs::Master;

let mut file = File::create("my_ebml_file.ebml")?;
let mut my_writer = TagWriter::new(&mut file);
my_writer.write(&EmptySpec::with_children(
  0x1a45dfa3, 
  vec![EmptySpec::with_data(0x18538067, &[0x01])])
)?;

pub fn write_advanced<TSpec: EbmlSpecification<TSpec> + EbmlTag<TSpec> + Clone>( &mut self, tag: &TSpec, options: WriteOptions ) -> Result<(), TagWriterError>

Write a tag to this instance’s destination using advanced options.

This method is just like the normal write() method, but allows for tailoring the output binary to better suit your needs. See WriteOptions for more detail on available options.

Errors

This method can error if there is a problem writing the input tag. The different possible error states are enumerated in TagWriterError.

Panics

This method can panic if <TSpec> is an internally inconsistent specification (i.e. it claims that a specific tag variant is a specific data type but it is not). This won’t happen if the specification being used was created using the #[ebml_specification] attribute macro.

pub fn write_unknown_size<TSpec: EbmlSpecification<TSpec> + EbmlTag<TSpec> + Clone>( &mut self, tag: &TSpec ) -> Result<(), TagWriterError>

👎Deprecated since 0.6.0: Please use ‘write_advanced’ with WriteOptions obtained using ‘is_unknown_sized_element’ instead

Write a tag with an unknown size to this instance’s destination.

DEPRECATED - Prefer using the write_advanced() method with WriteOptions obtained from their is_unknown_sized_element() instead.

This method allows you to start a tag that doesn’t have a known size. Useful for streaming, or when the data is expected to be too large to fit into memory. This method can only be used on Master type tags.

Errors

This method will return an error if the input tag is not a Master type tag, as those are the only types allowed to be of unknown size.

pub fn write_raw( &mut self, tag_id: u64, data: &[u8] ) -> Result<(), TagWriterError>

Write raw tag data to this instance’s destination.

This method allows writing any tag id with any arbitrary data without using a specification. Specifications should generally provide an Unknown variant to handle arbitrary unknown data which can be written through the regular write() method, so use of this method is typically discouraged.

Errors

This method can error if there is a problem writing the input tag. The different possible error states are enumerated in TagWriterError.

Examples

use std::fs::File;
use ebml_iterable::TagWriter;

let mut file = File::create("my_ebml_file.ebml")?;
let mut my_writer = TagWriter::new(&mut file);
my_writer.write_raw(0x1a45dfa3, &[0x18, 0x53, 0x80, 0x67, 0x81, 0x01])?;

pub fn flush(&mut self) -> Result<(), TagWriterError>

Attempts to flush all unwritten tags to the underlying destination.

This method can be used to finalize any open Master type tags that have not been ended. The writer makes an attempt to close every open tag and write all bytes to the instance’s destination.

Errors

This method can error if there is a problem writing to the destination.