Note positions are 1-based, inclusive

noodles uses the 1-based coordinate system with closed intervals. All
positions are 1-based, inclusive.

Closes #226 and closes #281.

noodles-bam/src/record.rs

@@ -47,6 +47,8 @@ impl Record {
 
     /// Returns the alignment start.
     ///
+    /// This position is 1-based, inclusive.
+    ///
     /// # Examples
     ///
     /// ```
@@ -102,6 +104,8 @@ impl Record {
 
     /// Returns the mate alignment start.
     ///
+    /// This position is 1-based, inclusive.
+    ///
     /// # Examples
     ///
     /// ```

noodles-bcf/src/record.rs

@@ -85,8 +85,7 @@ impl Record {
 
     /// Returns the variant start position.
     ///
-    /// Despite the BCF format using 0-based positions, this normalizes the value as a 1-based
-    /// position.
+    /// This position is 1-based, inclusive.
     ///
     /// # Examples
     ///
@@ -113,7 +112,7 @@ impl Record {
 
     /// Returns the end position of this record.
     ///
-    /// This value is 1-based.
+    /// This position is 1-based, inclusive.
     ///
     /// # Examples
     ///

noodles-cram/src/record.rs

@@ -99,6 +99,8 @@ impl Record {
     }
 
     /// Returns the alignment start.
+    ///
+    /// This position is 1-based, inclusive.
     pub fn alignment_start(&self) -> Option<Position> {
         self.alignment_start
     }
@@ -109,6 +111,8 @@ impl Record {
     }
 
     /// Returns the alignment end.
+    ///
+    /// This position is 1-based, inclusive.
     pub fn alignment_end(&self) -> Option<Position> {
         self.alignment_start().and_then(|alignment_start| {
             let end = usize::from(alignment_start) + self.alignment_span() - 1;

noodles-gff/src/record.rs

@@ -91,7 +91,7 @@ impl Record {
 
     /// Returns the start position of the record.
     ///
-    /// This value is 1-based.
+    /// This position is 1-based, inclusive.
     ///
     /// # Examples
     ///
@@ -107,7 +107,7 @@ impl Record {
 
     /// Returns the end position of the record.
     ///
-    /// This value is 1-based.
+    /// This position is 1-based, inclusive.
     ///
     /// # Examples
     ///

noodles-gtf/src/record.rs

@@ -85,7 +85,7 @@ impl Record {
 
     /// Returns the start position.
     ///
-    /// This value is 1-based.
+    /// This position is 1-based, inclusive.
     ///
     /// # Examples
     ///
@@ -101,7 +101,7 @@ impl Record {
 
     /// Returns the end position.
     ///
-    /// This value is 1-based.
+    /// This position is 1-based, inclusive.
     ///
     /// # Examples
     ///

noodles-sam/src/alignment/record.rs

@@ -38,6 +38,8 @@ pub trait Record {
         -> Option<io::Result<usize>>;
 
     /// Returns the alignment start.
+    ///
+    /// This position is 1-based, inclusive.
     fn alignment_start(&self) -> Option<io::Result<core::Position>>;
 
     /// Returns the mapping quality.
@@ -53,6 +55,8 @@ pub trait Record {
     ) -> Option<io::Result<usize>>;
 
     /// Returns the mate alignment start.
+    ///
+    /// This position is 1-based, inclusive.
     fn mate_alignment_start(&self) -> Option<io::Result<core::Position>>;
 
     /// Returns the template length.
@@ -102,6 +106,8 @@ pub trait Record {
     }
 
     /// Calculates the end position.
+    ///
+    /// This position is 1-based, inclusive.
     fn alignment_end(&self) -> Option<io::Result<core::Position>> {
         let start = match self.alignment_start().transpose() {
             Ok(position) => position?,

noodles-sam/src/alignment/record_buf.rs

@@ -145,6 +145,8 @@ impl RecordBuf {
 
     /// Returns the alignment start.
     ///
+    /// This position is 1-based, inclusive.
+    ///
     /// # Examples
     ///
     /// ```
@@ -158,6 +160,8 @@ impl RecordBuf {
 
     /// Returns a mutable reference to the alignment start.
     ///
+    /// This position is 1-based, inclusive.
+    ///
     /// # Examples
     ///
     /// ```
@@ -264,6 +268,8 @@ impl RecordBuf {
 
     /// Returns the mate alignment start.
     ///
+    /// This position is 1-based, inclusive.
+    ///
     /// # Examples
     ///
     /// ```
@@ -277,6 +283,8 @@ impl RecordBuf {
 
     /// Returns a mutable reference to the mate alignment start.
     ///
+    /// This position is 1-based, inclusive.
+    ///
     /// # Examples
     ///
     /// ```

noodles-sam/src/record.rs

@@ -92,6 +92,8 @@ impl Record {
 
     /// Returns the alignment start.
     ///
+    /// This position is 1-based, inclusive.
+    ///
     /// # Examples
     ///
     /// ```
@@ -163,6 +165,8 @@ impl Record {
 
     /// Returns the mate alignment start.
     ///
+    /// This position is 1-based, inclusive.
+    ///
     /// # Examples
     ///
     /// ```

noodles-vcf/src/variant/record.rs

@@ -23,6 +23,8 @@ pub trait Record {
     fn reference_sequence_name<'a, 'h: 'a>(&'a self, header: &'h Header) -> io::Result<&'a str>;
 
     /// Returns the variant start position.
+    ///
+    /// This position is 1-based, inclusive.
     fn variant_start(&self) -> Option<io::Result<Position>>;
 
     /// Returns the IDs.
@@ -58,6 +60,8 @@ pub trait Record {
     /// If available, this returns the value of the `END` INFO field. Otherwise, it is calculated
     /// using the [variant start position] and [reference bases length].
     ///
+    /// This position is 1-based, inclusive.
+    ///
     /// [variant start position]: `Self::variant_start`
     /// [reference bases length]: `ReferenceBases::len`
     fn variant_end(&self, header: &Header) -> io::Result<Position> {

noodles-vcf/src/variant/record_buf.rs

@@ -83,7 +83,8 @@ impl RecordBuf {
 
     /// Returns the variant start position.
     ///
-    /// If the record represents the start of a telomeric breakend, this returns `None`.
+    /// This position is 1-based, inclusive. If the record represents the start of a telomeric
+    /// breakend, this returns `None`.
     ///
     /// # Examples
     ///
@@ -103,7 +104,8 @@ impl RecordBuf {
 
     /// Returns a mutable reference to the variant start position.
     ///
-    /// If the record represents the start of a telomeric breakend, this returns `None`.
+    /// This position is 1-based, inclusive. If the record represents the start of a telomeric
+    /// breakend, this returns `None`.
     ///
     /// # Examples
     ///