Struct Coordinate

pub struct Coordinate<S: System> { /* private fields */ }

A coordinate within a genome consisting of a contig, a strand, and a position.

Implementations

impl Coordinate<Zero>

pub fn lower_bound<C: TryInto<Contig>>(contig: C) -> Self

where <C as TryInto<Contig>>::Error: Error,

Creates a new Coordinate with a Value::LowerBound.

Note that a lower bound position can only sit on the Strand::Negative, so this hardcodes the strand to Strand::Negative.

Examples

use omics_coordinate::Coordinate;
use omics_coordinate::Strand;
use omics_coordinate::system::Zero;

let coordinate = Coordinate::<Zero>::lower_bound("seq0");

impl<S: System> Coordinate<S>

pub fn try_new<C: TryInto<Contig>, Q: TryInto<Strand>, P: TryInto<Position<S>>>( contig: C, strand: Q, position: P, ) -> Result<Self>

where <C as TryInto<Contig>>::Error: Error, <Q as TryInto<Strand>>::Error: Error, <P as TryInto<Position<S>>>::Error: Error,

Attempts to create a new Coordinate.

Note that a lower bound position can only sit on the Strand::Negative, so trying to create a Coordinate with a lower bound position on any non-negative strand will result in an Error::LowerBoundOnNonNegativeStrand.

Examples

use omics_coordinate::Coordinate;
use omics_coordinate::Strand;
use omics_coordinate::system::Zero;

let coordinate = Coordinate::<Zero>::try_new("seq0", "+", 1)?;

pub fn contig(&self) -> &Contig

Gets the Contig for this Coordinate by reference.

Examples

use omics_coordinate::Coordinate;
use omics_coordinate::system::Zero;

let coordinate = "seq0:+:1".parse::<Coordinate<Zero>>()?;
assert_eq!(coordinate.contig().inner(), "seq0");

pub fn into_contig(self) -> Contig

Consumes self and returns the inner Contig from this Coordinate.

Examples

use omics_coordinate::Coordinate;
use omics_coordinate::system::Zero;

let coordinate = "seq0:+:1".parse::<Coordinate<Zero>>()?;
assert_eq!(coordinate.into_contig().inner(), "seq0");

pub fn strand(&self) -> &Strand

Gets the Strand for this Coordinate by reference.

Examples

use omics_coordinate::Coordinate;
use omics_coordinate::Strand;
use omics_coordinate::system::Zero;

let coordinate = "seq0:+:1".parse::<Coordinate<Zero>>()?;
assert_eq!(coordinate.strand(), &Strand::Positive);

pub fn into_strand(self) -> Strand

Consumes self and returns the inner Strand from this Coordinate.

Examples

use omics_coordinate::Coordinate;
use omics_coordinate::Strand;
use omics_coordinate::system::Zero;

let coordinate = "seq0:+:1".parse::<Coordinate<Zero>>()?;
assert_eq!(coordinate.into_strand(), Strand::Positive);

pub fn position(&self) -> &Position<S>

Gets the Position for this Coordinate by reference.

Examples

use omics_coordinate::Coordinate;
use omics_coordinate::Position;
use omics_coordinate::system::Zero;

let coordinate = "seq0:+:1".parse::<Coordinate<Zero>>()?;
assert_eq!(coordinate.position(), &"1".parse::<Position<Zero>>()?);

pub fn into_position(self) -> Position<S>

Consumes self and returns the inner Position from this Coordinate.

Examples

use omics_coordinate::Coordinate;
use omics_coordinate::Strand;
use omics_coordinate::position::Value;
use omics_coordinate::system::Zero;

let coordinate = "seq0:+:1".parse::<Coordinate<Zero>>()?;

let (contig, strand, position) = coordinate.into_parts();
assert_eq!(contig.inner(), "seq0");
assert_eq!(strand, Strand::Positive);
assert_eq!(position.inner(), &Value::Usize(1));

pub fn into_parts(self) -> (Contig, Strand, Position<S>)

Consumes self to return the parts that comprise this Coordinate.

Examples

use omics_coordinate::Coordinate;
use omics_coordinate::position::Value;
use omics_coordinate::system::Zero;

let coordinate = "seq0:+:1".parse::<Coordinate<Zero>>()?;
assert_eq!(coordinate.into_position().inner(), &Value::Usize(1));

pub fn move_forward(self, magnitude: usize) -> Result<Option<Coordinate<S>>>

where Position<S>: Position<S>,

Consumes the Coordinate to attempt to move the coordinate forward by a specified magnitude.

A checked add (for positive strand) or subtract (for negative strand) is performed to ensure we don’t overflow.

Note that, though the position is checked for usize overflow, we don’t do any bounds checking to make sure that the coordinates fall within any given interval.

Examples

use omics_coordinate::Coordinate;
use omics_coordinate::Strand;
use omics_coordinate::system::Zero;

let coordinate = "seq0:+:0".parse::<Coordinate<Zero>>()?;
let result = coordinate.move_forward(10)?.unwrap();

pub fn move_backward(self, magnitude: usize) -> Result<Option<Coordinate<S>>>

where Position<S>: Position<S>,

Consumes the Coordinate to attempt to move the coordinate backward by a specified magnitude.

A checked sub (for positive strand) or add (for negative strand) is performed to ensure we don’t overflow.

Note that, though the position is checked for usize overflow, we don’t do any bounds checking to make sure that the coordinates fall within any given interval.

Examples

use omics_coordinate::Coordinate;
use omics_coordinate::Strand;
use omics_coordinate::system::Zero;

let coordinate = "seq0:+:0".parse::<Coordinate<Zero>>()?;
let result = coordinate.move_forward(10)?.unwrap();

pub fn move_forward_checked_bounds( self, magnitude: usize, interval: &Interval<S>, ) -> Result<Option<Coordinate<S>>>

where Position<S>: Position<S>, Interval<S>: Interval<S>,

Consumes self to attempt to move the Coordinate forward by the specified magnitude while also performing a bounds check within the provided interval.

The following steps are performed:

• First, the coordinate is moved forward by the specified magnitude. During this move, the position is checked for overflows.
• Next, the calculated result is checked to ensure it falls within the specified interval. This is to ensure that, although the usize limits may not broken, the interval continues to contain the moved coordinate.

Examples

use omics_coordinate::system::Zero;
use omics_coordinate::Coordinate;
use omics_coordinate::Interval;
use omics_coordinate::position::Value;
use omics_coordinate::Strand;

// Positive-stranded coordinate that falls within the provided interval.

let mut coordinate = Coordinate::<Zero>::try_new("seq0", Strand::Positive, 0)?;
let interval = "seq0:+:0-1000".parse::<Interval<Zero>>()?;

let result = coordinate
    .move_forward_checked_bounds(10, &interval)
    .unwrap()
    .unwrap();

assert_eq!(result.contig().inner(), "seq0");
assert_eq!(result.position().inner(), &Value::Usize(10));
assert_eq!(result.strand(), &Strand::Positive);

// Negative-stranded position that falls within the provided interval.

let coordinate = Coordinate::try_new("seq0", Strand::Negative, 1000)?;
let interval = "seq0:-:1000-0".parse::<Interval<Zero>>()?;
let result = coordinate
    .move_forward_checked_bounds(10, &interval)
    .unwrap()
    .unwrap();

assert_eq!(result.contig().inner(), "seq0");
assert_eq!(result.position().inner(), &Value::Usize(990));
assert_eq!(result.strand(), &Strand::Negative);

// Positive-stranded position that _does not_ fall within the provided interval.

let coordinate = Coordinate::try_new("seq0", Strand::Positive, 0)?;
let interval = "seq0:+:0-10".parse::<Interval<Zero>>()?;
let result = coordinate.move_forward_checked_bounds(10, &interval).unwrap();

assert_eq!(result, None);

// Negative-stranded position that _does not_ fall within the provided interval.

let coordinate = Coordinate::try_new("seq0", Strand::Negative, 10)?;
let interval = "seq0:-:10-0".parse::<Interval<Zero>>()?;
let result = coordinate.move_forward_checked_bounds(10, &interval).unwrap();

assert_eq!(result, None);

// Lower-bound position that _does not_ fall within interval
// (and also would not move forward due to underflow).

let coordinate = Coordinate::<Zero>::lower_bound("seq0");
let interval = "seq0:-:10-[".parse::<Interval<Zero>>()?;
let result = coordinate.move_forward_checked_bounds(1, &interval).unwrap();

assert_eq!(result, None);

pub fn move_backward_checked_bounds( self, magnitude: usize, interval: &Interval<S>, ) -> Result<Option<Coordinate<S>>>

where Position<S>: Position<S>, Interval<S>: Interval<S>,

Consumes self to attempt to move the Coordinate backward by the specified magnitude while also performing a bounds check within the provided interval.

The following steps are performed:

• First, the coordinate is moved backward by the specified magnitude. During this move, the position is checked for overflows.
• Next, the calculated result is checked to ensure it falls within the specified interval. This is to ensure that, although the usize limits may not broken, the interval continues to contain the moved coordinate.

Examples

use omics_coordinate::system::Zero;
use omics_coordinate::Coordinate;
use omics_coordinate::Interval;
use omics_coordinate::position::Value;
use omics_coordinate::Strand;

// Positive-stranded coordinate that falls within the provided interval.

let mut coordinate = Coordinate::<Zero>::try_new("seq0", Strand::Positive, 10)?;
let interval = "seq0:+:0-1000".parse::<Interval<Zero>>()?;

let result = coordinate
    .move_backward_checked_bounds(10, &interval)
    .unwrap()
    .unwrap();

assert_eq!(result.contig().inner(), "seq0");
assert_eq!(result.position().inner(), &Value::Usize(0));
assert_eq!(result.strand(), &Strand::Positive);

// Negative-stranded position that falls within the provided interval.

let coordinate = Coordinate::try_new("seq0", Strand::Negative, 990)?;
let interval = "seq0:-:1000-0".parse::<Interval<Zero>>()?;
let result = coordinate
    .move_backward_checked_bounds(10, &interval)
    .unwrap()
    .unwrap();

assert_eq!(result.contig().inner(), "seq0");
assert_eq!(result.position().inner(), &Value::Usize(1000));
assert_eq!(result.strand(), &Strand::Negative);

// Positive-stranded position that _does not_ fall within the provided interval.

let coordinate = Coordinate::try_new("seq0", Strand::Positive, 0)?;
let interval = "seq0:+:0-10".parse::<Interval<Zero>>()?;
let result = coordinate.move_backward_checked_bounds(1, &interval).unwrap();

assert_eq!(result, None);

// Negative-stranded position that _does not_ fall within the provided interval.

let coordinate = Coordinate::try_new("seq0", Strand::Negative, 10)?;
let interval = "seq0:-:10-0".parse::<Interval<Zero>>()?;
let result = coordinate.move_backward_checked_bounds(1, &interval).unwrap();

assert_eq!(result, None);

// Lower-bound position that _does not_ fall within interval
// (and also would not move forward due to underflow).

let coordinate = Coordinate::<Zero>::lower_bound("seq0");
let interval = "seq0:-:10-[".parse::<Interval<Zero>>()?;
let result = coordinate
    .move_backward_checked_bounds(1, &interval)
    .unwrap()
    .unwrap();

assert_eq!(result.contig().inner(), "seq0");
assert_eq!(result.position().inner(), &Value::Usize(0));
assert_eq!(result.strand(), &Strand::Negative);

pub fn swap_strand(self) -> Result<Coordinate<S>>

Consumes self to swap the Strand of the Coordinate without modifying the contig or the position.

Examples

use omics_coordinate::Coordinate;
use omics_coordinate::Strand;
use omics_coordinate::position::Value;
use omics_coordinate::system::Zero;

// Swapping a positive-stranded position to a negative-stranded position.

let coordinate = "seq0:+:1000".parse::<Coordinate<Zero>>()?;
let swapped = coordinate.swap_strand()?;

assert_eq!(swapped.contig().inner(), "seq0");
assert_eq!(swapped.strand(), &Strand::Negative);
assert_eq!(swapped.position().inner(), &Value::Usize(1000));

// Swapping a negative-stranded position to a positive-stranded position.

let coordinate = "seq0:-:1000".parse::<Coordinate<Zero>>()?;
let swapped = coordinate.swap_strand()?;

assert_eq!(swapped.contig().inner(), "seq0");
assert_eq!(swapped.strand(), &Strand::Positive);
assert_eq!(swapped.position().inner(), &Value::Usize(1000));

// Failing to swap the lower bound.

let coordinate = "seq0:-:[".parse::<Coordinate<Zero>>()?;
let err = coordinate.swap_strand().unwrap_err();

assert_eq!(
    err.to_string(),
    String::from(
        "attempted to place lower bound position on non-negative strand for coordinate"
    )
);

Trait Implementations

impl<S: Clone + System> Clone for Coordinate<S>

fn clone(&self) -> Coordinate<S>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<S: Debug + System> Debug for Coordinate<S>

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

Formats the value using the given formatter.

impl<S: System> Display for Coordinate<S>

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

Formats the value using the given formatter.

impl<S: System> FromStr for Coordinate<S>

where Position<S>: Position<S>,

type Err = Error

The associated error which can be returned from parsing.

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

Parses a string s to return a value of this type.

impl<S: PartialEq + System> PartialEq for Coordinate<S>

fn eq(&self, other: &Coordinate<S>) -> 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<S: Eq + System> Eq for Coordinate<S>

impl<S: System> StructuralPartialEq for Coordinate<S>