Struct bam::record::tags::TagViewer

pub struct TagViewer { /* fields omitted */ }

Wrapper around raw tags.

Allows to get and modify record tags. Method get returns a TagValue, which is a viewer of raw data (it does not copy the data, unless it has a numeric/char type).

// Read tag ZZ, which can be either u32 array or a char:
match record.tags().get(b"ZZ") {
    Some(TagValue::IntArray(array_view)) => {
        assert!(array_view.int_type() == IntegerType::U32);
        println!("Array[2] = {}", array_view.at(2));
    },
    Some(TagValue::Char(value)) => println!("Char = {}", value),
    _ => panic!("Unexpected type"),
}

Methods push and insert add a tag (or modify a tag), and they provide a convinient way to specify tag type. For numeric and string types, you can just write

// Add a new tag with name `AA`, type `i32` and value `10`.
record.tags_mut().push(b"AA", 10_i32);
// Add a new tag with name `ZZ`, type `string` and value `"abcd"`.
record.tags_mut().push(b"ZZ", "abcd");

To add a Hex value you need to wrap &[u8] in a Hex wrapper:

// Add a new tag with name `HH`, type `hex` and value `"FF00"`.
record.tags_mut().push(b"HH", Hex(b"FF00"));

Finally, to specify a numeric array, you may need to coerce the array to a splice:

// Add a new tag with name `BB`, type `i16 array` and value `[3, 4, 5, 6]`.
record.tags_mut().push(b"BB", &[3_i16, 4, 5, 6] as &[i16]);

Methods

impl TagViewer

pub fn raw(&self) -> &[u8]

Returns raw data.

pub fn clear(&mut self)

Clears the contents but does not touch capacity.

pub fn get<'a>(&'a self, name: &TagName) -> Option<TagValue<'a>>

Returns a value of a tag with name. Value integer/float types, returns copied value, for array and string types returns a wrapper over reference. Takes O(n_tags).

Important traits for TagIter<'a>

impl<'a> Iterator for TagIter<'a> type Item = (TagName, TagValue<'a>);

pub fn iter<'a>(&'a self) -> TagIter<'a>

Iterate over tuples (name, tag_value), where name: [u8; 2] and tag_value: TagValue.

pub fn push<V: WriteValue>(&mut self, name: &TagName, value: V) -> Result<()>

Appends a new tag. Trait WriteValue is implemented for possible tag values, so you can add new tags like this:

record.tags_mut().push(b"AA", 10)

Due to Rust constraints, you may need to explicitly coerce a numeric array to a slice, for example

record.tags_mut().push(b"BB", &[10_i16, 20, 30] as &[i16]).unwrap();

This function does not check if there is already a tag with the same name. Takes O(new_tag_len).

See WriteValue for more information.

pub fn insert<'a, V: WriteValue>(
    &'a mut self,
    name: &TagName,
    value: V
) -> Result<()>

Inserts a new tag instead of existing. If there is no tags with the same name, pushes to the end and returns None. Takes O(raw_tags_len + new_tag_len).

pub fn remove<'a>(&'a mut self, name: &TagName) -> bool

Removes a tag if present. Returns true if the tag existed and false otherwise. Takes O(raw_tags_len).

pub fn write_sam<W: Write>(&self, f: &mut W) -> Result<()>

Writes tags in a SAM format.

pub fn push_int(&mut self, name: &TagName, value: i64)

Pushes integer in a smallest possible format.

pub fn push_sam(&mut self, tag: &str) -> Result<()>

Adds a new tag in SAM format (name:type:value).