Struct Header

pub struct Header { /* private fields */ }

A SAM header.

Records are grouped by their types: header, reference sequence, read group, program, and comment.

Implementations

impl Header

pub fn builder() -> Builder

Returns a builder to create a SAM header.

Examples

use noodles_sam as sam;
let builder = sam::Header::builder();

pub fn header(&self) -> Option<&Map<Header>>

Returns the SAM header header if it is set.

Examples

use noodles_sam::{
    self as sam,
    header::record::value::{map::Header, Map},
};

let header = sam::Header::default();
assert!(header.header().is_none());

let header = sam::Header::builder()
    .set_header(Map::<Header>::default())
    .build();

assert!(header.header().is_some());

pub fn header_mut(&mut self) -> &mut Option<Map<Header>>

Returns a mutable reference to the SAM header header if it is set.

Examples

use noodles_sam::{self as sam, header::record::value::{map, Map}};

let mut header = sam::Header::default();
assert!(header.header().is_none());

let hd = Map::<map::Header>::default();
*header.header_mut() = Some(hd.clone());
assert_eq!(header.header(), Some(&hd));

pub fn reference_sequences(&self) -> &ReferenceSequences

Returns the SAM header reference sequences.

This is also called the reference sequence dictionary.

Examples

use std::num::NonZeroUsize;

use noodles_sam::{
    self as sam,
    header::record::value::{map::ReferenceSequence, Map},
};

let header = sam::Header::builder()
    .add_reference_sequence(
        "sq0",
        Map::<ReferenceSequence>::new(NonZeroUsize::try_from(13)?)
    )
    .build();

let reference_sequences = header.reference_sequences();
assert_eq!(reference_sequences.len(), 1);
assert!(reference_sequences.contains_key(&b"sq0"[..]));

pub fn reference_sequences_mut(&mut self) -> &mut ReferenceSequences

Returns a mutable reference to the SAM header reference sequences.

This is also called the reference sequence dictionary.

Examples

use std::num::NonZeroUsize;

use noodles_sam::{
    self as sam,
    header::record::value::{map::ReferenceSequence, Map},
};

let mut header = sam::Header::default();

header.reference_sequences_mut().insert(
    String::from("sq0").into(),
    Map::<ReferenceSequence>::new(NonZeroUsize::try_from(13)?),
);

let reference_sequences = header.reference_sequences();
assert_eq!(reference_sequences.len(), 1);
assert!(reference_sequences.contains_key(&b"sq0"[..]));

pub fn read_groups(&self) -> &ReadGroups

Returns the SAM header read groups.

Examples

use noodles_sam::{
    self as sam,
    header::record::value::{map::ReadGroup, Map},
};

let header = sam::Header::builder()
    .add_read_group("rg0", Map::<ReadGroup>::default())
    .build();

let read_groups = header.read_groups();
assert_eq!(read_groups.len(), 1);
assert!(read_groups.contains_key(&b"rg0"[..]));

pub fn read_groups_mut(&mut self) -> &mut ReadGroups

Returns a mutable reference to the SAM header read groups.

Examples

use noodles_sam::{
    self as sam,
    header::record::value::{map::ReadGroup, Map},
};

let mut header = sam::Header::default();
assert!(header.read_groups().is_empty());

let read_group = Map::<ReadGroup>::default();
header.read_groups_mut().insert(String::from("rg0").into(), read_group);

let read_groups = header.read_groups();
assert_eq!(read_groups.len(), 1);
assert!(read_groups.contains_key(&b"rg0"[..]));

pub fn programs(&self) -> &Programs

Returns the SAM header programs.

Examples

use noodles_sam::{self as sam, header::record::value::{map::Program, Map}};

let program = Map::<Program>::default();
let header = sam::Header::builder().add_program("noodles-sam", program).build();

let programs = header.programs();
assert_eq!(programs.as_ref().len(), 1);
assert!(programs.as_ref().contains_key(&b"noodles-sam"[..]));

pub fn programs_mut(&mut self) -> &mut Programs

Returns a mutable reference to the SAM header programs.

Examples

use noodles_sam::{self as sam, header::record::value::{map::Program, Map}};

let mut header = sam::Header::default();

let program = Map::<Program>::default();
header
    .programs_mut()
    .as_mut()
    .insert(String::from("noodles-sam").into(), program);

let programs = header.programs();
assert_eq!(programs.as_ref().len(), 1);
assert!(programs.as_ref().contains_key(&b"noodles-sam"[..]));

pub fn comments(&self) -> &[BString]

Returns the SAM header comments.

Examples

use bstr::BString;
use noodles_sam as sam;
let header = sam::Header::builder().add_comment("noodles-sam").build();
let comments = header.comments();
assert_eq!(header.comments(), [BString::from("noodles-sam")]);

pub fn comments_mut(&mut self) -> &mut Vec<BString>

Returns a mutable reference to the SAM header comments.

To simply append a comment record, consider using Self::add_comment instead.

Examples

use bstr::BString;
use noodles_sam as sam;
let mut header = sam::Header::default();
header.comments_mut().push(BString::from("noodles-sam"));
assert_eq!(header.comments(), [BString::from("noodles-sam")]);

pub fn add_comment<C>(&mut self, comment: C)

where C: Into<BString>,

Adds a comment.

Examples

use bstr::BString;
use noodles_sam as sam;
let mut header = sam::Header::default();
header.add_comment("noodles-sam");
assert_eq!(header.comments(), [BString::from("noodles-sam")]);

pub fn is_empty(&self) -> bool

Returns whether there are no records in this SAM header.

Examples

use noodles_sam as sam;

let header = sam::Header::default();
assert!(header.is_empty());

let header = sam::Header::builder().add_comment("noodles-sam").build();
assert!(!header.is_empty());

pub fn clear(&mut self)

Removes all records from the header.

Examples

use noodles_sam as sam;

let mut header = sam::Header::builder().add_comment("ndls").build();
assert!(!header.is_empty());

header.clear();
assert!(header.is_empty());

Trait Implementations

impl Clone for Header

fn clone(&self) -> Header

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Header

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

Formats the value using the given formatter.

impl Default for Header

fn default() -> Header

Returns the “default value” for a type.

impl FromStr for Header

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a raw SAM header.

Examples

use noodles_sam as sam;

let s = "\
@HD\tVN:1.6\tSO:coordinate
@SQ\tSN:sq0\tLN:8
@SQ\tSN:sq1\tLN:13
";

let header: sam::Header = s.parse()?;

assert!(header.header().is_some());
assert_eq!(header.reference_sequences().len(), 2);
assert!(header.read_groups().is_empty());
assert!(header.programs().as_ref().is_empty());
assert!(header.comments().is_empty());

type Err = ParseError

The associated error which can be returned from parsing.

impl PartialEq for Header

fn eq(&self, other: &Header) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for Header

impl StructuralPartialEq for Header