Change row and column numbers to be reported with NonZeroU64.

This allows for more compact representation of their values (the return values of line() and column() should both be representable in a single u64 now) and makes it clear to users that Some(0) and ColumnType::Column(0) are never returned.

CHANGELOG.md

@@ -2,6 +2,18 @@
 
 --------------------------------------------------------------------------------
 
+## 0.24.0
+
+Not yet released
+
+### Breaking changes
+
+* `read::LineRow::line` now returns Option<NonZeroU64>.
+  The `read::ColumnType::Column` variant now contains a NonZeroU64.
+  [#551](https://github.com/gimli-rs/gimli/pull/551)
+
+--------------------------------------------------------------------------------
+
 ## 0.23.0
 
 Released 2020/10/27.

examples/dwarfdump.rs

@@ -1991,9 +1991,12 @@ fn dump_line_program<R: Reader, W: Write>(
         let mut rows = program.rows();
         let mut file_index = 0;
         while let Some((header, row)) = rows.next_row()? {
-            let line = row.line().unwrap_or(0);
+            let line = match row.line() {
+                Some(line) => line.get(),
+                None => 0,
+            };
             let column = match row.column() {
-                gimli::ColumnType::Column(column) => column,
+                gimli::ColumnType::Column(column) => column.get(),
                 gimli::ColumnType::LeftEdge => 0,
             };
             write!(w, "0x{:08x}  [{:4},{:2}]", row.address(), line, column)?;

examples/simple_line.rs

@@ -84,10 +84,13 @@ fn dump_file(object: &object::File, endian: gimli::RunTimeEndian) -> Result<(),
 
                     // Determine line/column. DWARF line/column is never 0, so we use that
                     // but other applications may want to display this differently.
-                    let line = row.line().unwrap_or(0);
+                    let line = match row.line() {
+                        Some(line) => line.get(),
+                        None => 0,
+                    };
                     let column = match row.column() {
                         gimli::ColumnType::LeftEdge => 0,
-                        gimli::ColumnType::Column(x) => x,
+                        gimli::ColumnType::Column(column) => column.get(),
                     };
 
                     println!("{:x} {}:{}:{}", row.address(), path.display(), line, column);

src/read/line.rs

@@ -1,6 +1,6 @@
 use alloc::vec::Vec;
 use core::fmt;
-use core::num::Wrapping;
+use core::num::{NonZeroU64, Wrapping};
 use core::result;
 
 use crate::common::{
@@ -713,25 +713,20 @@ impl LineRow {
     /// "An unsigned integer indicating a source line number. Lines are numbered
     /// beginning at 1. The compiler may emit the value 0 in cases where an
     /// instruction cannot be attributed to any source line."
+    /// Line number values of 0 are represented as `None`.
     #[inline]
-    pub fn line(&self) -> Option<u64> {
-        if self.line.0 == 0 {
-            None
-        } else {
-            Some(self.line.0)
-        }
+    pub fn line(&self) -> Option<NonZeroU64> {
+        NonZeroU64::new(self.line.0)
     }
 
     /// "An unsigned integer indicating a column number within a source
     /// line. Columns are numbered beginning at 1. The value 0 is reserved to
     /// indicate that a statement begins at the “left edge” of the line."
     #[inline]
     pub fn column(&self) -> ColumnType {
-        if self.column == 0 {
-            ColumnType::LeftEdge
-        } else {
-            ColumnType::Column(self.column)
-        }
+        NonZeroU64::new(self.column)
+            .map(ColumnType::Column)
+            .unwrap_or(ColumnType::LeftEdge)
     }
 
     /// "A boolean indicating that the current instruction is a recommended
@@ -996,7 +991,7 @@ pub enum ColumnType {
     /// line.
     LeftEdge,
     /// A column number, whose range begins at 1.
-    Column(u64),
+    Column(NonZeroU64),
 }
 
 /// Deprecated. `LineNumberSequence` has been renamed to `LineSequence`.

src/write/line.rs

@@ -1102,10 +1102,13 @@ mod convert {
                                     }
                                     files[file as usize]
                                 };
-                                program.row().line = from_row.line().unwrap_or(0);
+                                program.row().line = match from_row.line() {
+                                    Some(line) => line.get(),
+                                    None => 0,
+                                };
                                 program.row().column = match from_row.column() {
                                     read::ColumnType::LeftEdge => 0,
-                                    read::ColumnType::Column(val) => val,
+                                    read::ColumnType::Column(val) => val.get(),
                                 };
                                 program.row().discriminator = from_row.discriminator();
                                 program.row().is_statement = from_row.is_stmt();
@@ -1801,7 +1804,7 @@ mod tests {
                             {
                                 let row = rows.next_row().unwrap().unwrap().1;
                                 address = row.address();
-                                line = row.line().unwrap();
+                                line = row.line().unwrap().get();
                             }
                             assert_eq!(address, 0x1000);
                             assert_eq!(line, 0x10000);
@@ -1812,11 +1815,11 @@ mod tests {
                                     address_advance * u64::from(minimum_instruction_length)
                                 );
                                 assert_eq!(
-                                    (row.line().unwrap() as i64) - (line as i64),
+                                    (row.line().unwrap().get() as i64) - (line as i64),
                                     line_advance
                                 );
                                 address = row.address();
-                                line = row.line().unwrap();
+                                line = row.line().unwrap().get();
                             }
                             let row = rows.next_row().unwrap().unwrap().1;
                             assert!(row.end_sequence());