Struct noodles_sam::header::Programs

pub struct Programs(/* private fields */);

SAM header programs.

SAM header programs are header records that form program chains. A program chain is a directed acyclic graph (DAG) starting at a root program and ending at a leaf program. Program edges are directed forward from a parent program to its linked program using the previous program ID (PP) field in the child program.

For example, take the following program records:

@PG	ID:pg0
@PG	ID:pg1	PP:pg0

This creates the program chain pg0 -> pg1.

There can exist more than one program chain in the SAM header programs, e.g.,

@PG	ID:pg0
@PG	ID:pg1
@PG	ID:pg2
@PG	ID:pg3	PP:pg0
@PG	ID:pg4	PP:pg1
@PG	ID:pg5	PP:pg4

This creates the program chains pg0 -> pg3, pg1 -> pg4 -> pg5, and pg2.

Implementations

impl Programs

pub fn add<P>(&mut self, id_prefix: P, map: Map<Program>) -> Result<()>

where P: Into<BString>,

Adds a program.

If the program is the first program in the graph, this is similar to calling IndexMap::insert on the inner graph. If no previous program is set, this attaches the program to all program chains using leaf programs as the given program’s previous program.

Examples

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

let mut header = sam::Header::default();
let programs = header.programs_mut();

programs.add("pg0", Map::default())?;
programs.add("pg1", Map::default())?;

let expected = sam::Header::builder()
    .add_program("pg0", Map::default())
    .add_program("pg1", Map::builder().insert(tag::PREVIOUS_PROGRAM_ID, "pg0").build()?)
    .build();

assert_eq!(programs, expected.programs());

pub fn roots(&self) -> impl Iterator<Item = (&BStr, &Map<Program>)>

Returns an iterator over root programs.

A root program is a first program of a program chain.

Examples

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

let header = sam::Header::builder()
    .add_program("pg0", Map::default())
    .add_program("pg1", Map::builder().insert(tag::PREVIOUS_PROGRAM_ID, "pg0").build()?)
    .add_program("pg2", Map::builder().insert(tag::PREVIOUS_PROGRAM_ID, "pg1").build()?)
    .add_program("pg3", Map::default())
    .build();

let mut roots = header.programs().roots();
assert_eq!(roots.next().map(|(id, _)| id.as_ref()), Some(&b"pg0"[..]));
assert_eq!(roots.next().map(|(id, _)| id.as_ref()), Some(&b"pg3"[..]));
assert!(roots.next().is_none());

pub fn leaves(&self) -> Result<impl Iterator<Item = (&BStr, &Map<Program>)>>

Returns an iterator over leaf programs.

A leaf program is the last program of a program chain.

Errors

This returns an io::Error if any program chain has a cycle.

Examples

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

let header = sam::Header::builder()
    .add_program("pg0", Map::default())
    .add_program("pg1", Map::builder().insert(tag::PREVIOUS_PROGRAM_ID, "pg0").build()?)
    .add_program("pg2", Map::builder().insert(tag::PREVIOUS_PROGRAM_ID, "pg1").build()?)
    .add_program("pg3", Map::default())
    .build();

let mut leaves = header.programs().leaves()?;
assert_eq!(leaves.next().map(|(id, _)| id.as_ref()), Some(&b"pg3"[..]));
assert_eq!(leaves.next().map(|(id, _)| id.as_ref()), Some(&b"pg2"[..]));
assert!(leaves.next().is_none());

Trait Implementations

impl AsMut<IndexMap<BString, Map<Program>>> for Programs

fn as_mut(&mut self) -> &mut IndexMap<BString, Map<Program>>

Converts this type into a mutable reference of the (usually inferred) input type.

impl AsRef<IndexMap<BString, Map<Program>>> for Programs

fn as_ref(&self) -> &IndexMap<BString, Map<Program>>

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for Programs

fn clone(&self) -> Programs

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Programs

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

Formats the value using the given formatter.

impl Default for Programs

fn default() -> Programs

Returns the “default value” for a type.

impl PartialEq for Programs

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

This method tests for self and other values to be equal, and is used by ==.

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

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

impl Eq for Programs

impl StructuralPartialEq for Programs