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 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])])
)?;

Examples found in repository

src/tag_writer.rs (line 209)

    pub fn write<TSpec: EbmlSpecification<TSpec> + EbmlTag<TSpec> + Clone>(&mut self, tag: &TSpec) -> Result<(), TagWriterError> {
        let tag_id = tag.get_id();
        match TSpec::get_tag_data_type(tag_id) {
            TagDataType::UnsignedInt => {
                let val = tag.as_unsigned_int().unwrap_or_else(|| panic!("Bad specification implementation: Tag id {} type was unsigned int, but could not get tag!", tag_id));
                self.write_unsigned_int_tag(tag_id, val)?
            },
            TagDataType::Integer => {
                let val = tag.as_signed_int().unwrap_or_else(|| panic!("Bad specification implementation: Tag id {} type was integer, but could not get tag!", tag_id));
                self.write_signed_int_tag(tag_id, val)?
            },
            TagDataType::Utf8 => {
                let val = tag.as_utf8().unwrap_or_else(|| panic!("Bad specification implementation: Tag id {} type was utf8, but could not get tag!", tag_id));
                self.write_utf8_tag(tag_id, val)?
            },
            TagDataType::Binary => {
                let val = tag.as_binary().unwrap_or_else(|| panic!("Bad specification implementation: Tag id {} type was binary, but could not get tag!", tag_id));
                self.write_binary_tag(tag_id, val)?
            },
            TagDataType::Float => {
                let val = tag.as_float().unwrap_or_else(|| panic!("Bad specification implementation: Tag id {} type was float, but could not get tag!", tag_id));
                self.write_float_tag(tag_id, val)?
            },
            TagDataType::Master => {
                let position = tag.as_master().unwrap_or_else(|| panic!("Bad specification implementation: Tag id {} type was master, but could not get tag!", tag_id));

                match position {
                    Master::Start => self.start_tag(tag_id),
                    Master::End => self.end_tag(tag_id)?,
                    Master::Full(children) => {
                        self.start_tag(tag_id);
                        for child in children {
                            self.write(child)?;
                        }
                        self.end_tag(tag_id)?;
                    }
                }
            }
        }

        if !self.open_tags.iter().any(|t| matches!(t.1, Known(_))) {
            self.private_flush()
        } else {
            Ok(())
        }
    }

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

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

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.