refactor!: properly handle chained fit file and improve control flow (#9)

Author: muktihari

Cargo.lock

@@ -19,53 +19,74 @@ Missing features, test completeness, and more robust documentation may be added
 
 #### Decode
 
-Decoder's `decode` allows us to interact with FIT files directly through their original protocol messages' structure.
+Decoder's `decode` allows us to interact with FIT files directly through their original protocol messages' structure. 
+First call will return either Ok(Some(fit)) or Err(err), never Ok(None).
+On next call, it may return Ok(None) to indicate that no more FIT sequence in the file.
 
 ```rust
-use rustyfit::{
-    Decoder,
-    profile::{mesgdef, typedef},
-};
-use std::{fs::File, io::BufReader};
+use rustyfit::{Decoder, profile::{mesgdef, typedef}};
+use std::{error::Error, fs::File, io::BufReader};
 
-fn main() {
+fn main() -> Result<(), Box<dyn Error>> {
     let name = "Activity.fit";
-    let f = File::open(name).unwrap();
+    let f = File::open(name)?;
     let br = BufReader::new(f);
     let mut dec = Decoder::new(br);
 
-    let fit = dec.decode().unwrap();
+    let fit = dec.decode()?.unwrap(); // First decode call is either Ok(Some(fit)) or Err(err), never Ok(None).
 
     println!("file_header's data_size: {}", fit.file_header.data_size);
     println!("messages count: {}", fit.messages.len());
-    for field in &fit.messages[0].fields { // first message: file_id
+    for field in &fit.messages[0].fields {
+        // first message: file_id
         if field.num == mesgdef::FileId::TYPE {
             println!("file type: {}", typedef::File(field.value.as_u8()));
         }
     }
+    
+    Ok(())
+    
     // # Output:
     // file_header's data_size: 94080
     // messages count: 3611
     // file type: activity
 }
+```
+
+The `decode` method can be invoked multiple times to decode chained FIT file until it return Ok(None) or Err(err). 
+We can decode chained FIT file using `while let`, e.g:
 
+```rust
+    while let Some(fit) = dec.decode()? {
+        println!("file_header's data_size: {}", fit.file_header.data_size);
+        println!("messages count: {}", fit.messages.len());
+        for field in &fit.messages[0].fields {
+            // first message: file_id
+            if field.num == mesgdef::FileId::TYPE {
+                println!("file type: {}", typedef::File(field.value.as_u8()));
+            }
+        }
+    }
 ```
 
 #### Decode with Closure
 
-Decoder's `decode_fn` allow us to retrieve message definition or message data event as soon as it is being decoded. This way, users can have fine-grained control on how to interact with the data.
+Decoder's `decode_with` allow us to retrieve event data (FileHeader, MessageDefinition, Message, CRC) as soon as it is being decoded. 
+This way, users can have fine-grained control on how to interact with the data.
 
 ```rust
 use rustyfit::{Decoder, DecoderEvent,profile::{mesgdef, typedef}};
-use std::{fs::File, io::BufReader};
+use std::{error::Error, fs::File, io::BufReader};
 
-fn main() {
+fn main() -> Result<(), Box<dyn Error>> {
     let name = "Activity.fit";
-    let f = File::open(name).unwrap();
+    let f = File::open(name)?;
     let br = BufReader::new(f);
     let mut dec = Decoder::new(br);
 
-    dec.decode_fn(|event| match event {
+    dec.decode_with(|event| match event {
+        DecoderEvent::FileHeader(_) => {},
+        DecoderEvent::MessageDefinition(_) => {},
         DecoderEvent::Message(mesg) => {
             if mesg.num == typedef::MesgNum::SESSION {
                 // Convert mesg into Session struct
@@ -76,17 +97,34 @@ fn main() {
                 );
             }
         }
-        DecoderEvent::MessageDefinition(_) => {}
-    })
-    .unwrap();
+        DecoderEvent::Crc(_) => {}
+    })?;
+    
+    Ok(())
 
     // # Output
     // session:
     //  start_time: 995749880
     //  sport: stand_up_paddleboarding
     //  num_laps: 1
 }
+```
+
+The `decode_with` method can be invoked multiple times to decode chained FIT file until it return Ok(false) or Err(err). 
 
+```rust
+    while dec.decode_with(|event| {
+        if let DecoderEvent::Message(mesg) = event {
+            if mesg.num == typedef::MesgNum::SESSION {
+                // Convert mesg into Session struct
+                let ses = mesgdef::Session::from(mesg);
+                println!(
+                    "session:\n start_time: {}\n sport: {}\n num_laps: {}",
+                    ses.start_time.0, ses.sport, ses.num_laps
+                );
+            }
+        }
+    })? {}
 ```
 
 #### DecoderBuilder
@@ -107,25 +145,14 @@ let mut dec: Decoder = DecoderBuilder::new(br)
 Here is the example of manually encode FIT protocol using this library to give the idea how it works.
 
 ```rust
-use std::{
-    fs::File,
-    io::{BufWriter, Write},
-};
-
-use rustyfit::{
-    Encoder,
-    profile::{
-        ProfileType, mesgdef,
-        typedef::{self},
-    },
-    proto::{FIT, Field, Message, Value},
-};
-
-fn main() {
+use std::{error::Error, fs::File, io::{BufWriter, Write}};
+use rustyfit::{Encoder, profile::{ProfileType, mesgdef, typedef::{self}}, proto::{FIT, Field, Message, Value}};
+
+fn main() -> Result<(), Box<dyn Error>> {
     let fout_name = "output.fit";
-    let fout = File::create(fout_name).unwrap();
-    let bw = BufWriter::new(fout);
-    let mut enc = Encoder::new(bw);
+    let fout = File::create(fout_name)?;
+    let mut bw = BufWriter::new(fout);
+    let mut enc = Encoder::new(&mut bw);
 
     let mut fit = FIT {
         messages: vec![
@@ -159,7 +186,7 @@ fn main() {
                     Field {
                         num: mesgdef::Record::DISTANCE,
                         profile_type: ProfileType::UINT32,
-                        value: Value::Uint16(100 * 100), // 100 m
+                        value: Value::Uint32(100 * 100), // 100 m
                         is_expanded: false,
                     },
                     Field {
@@ -181,36 +208,26 @@ fn main() {
         ..Default::default()
     };
 
-    enc.encode(&mut fit).unwrap();
-    bw.flush().unwrap();
-}
+    enc.encode(&mut fit)?;
+    bw.flush()?;
 
+    Ok(())
+}
 ```
 
 #### Encode using mesgdef module
 
 Alternatively, users can create messages using the mesgdef module for convenience.
 
 ```rust
-use std::{
-    fs::File,
-    io::{BufWriter, Write},
-};
-
-use rustyfit::{
-    Encoder,
-    profile::{
-        mesgdef,
-        typedef::{self},
-    },
-    proto::{FIT, Message},
-};
-
-fn main() {
+use std::{error::Error, fs::File, io::{BufWriter, Write}};
+use rustyfit::{Encoder, profile::{mesgdef, typedef::{self}}, proto::{FIT, Message}};
+
+fn main() -> Result<(), Box<dyn Error>> {
     let fout_name = "output.fit";
-    let fout = File::create(fout_name).unwrap();
-    let bw = BufWriter::new(fout);
-    let mut enc = Encoder::new(bw);
+    let fout = File::create(fout_name)?;
+    let mut bw = BufWriter::new(fout);
+    let mut enc = Encoder::new(&mut bw);
 
     let mut fit = FIT {
         messages: vec![
@@ -232,10 +249,11 @@ fn main() {
         ..Default::default()
     };
 
-    enc.encode(&mut fit).unwrap();
-    bw.flush().unwrap();
-}
+    enc.encode(&mut fit)?;
+    bw.flush()?;
 
+    Ok(())
+}
 ```
 
 #### EncoderBuilder

README.md

@@ -1,6 +1,6 @@
 [package]
 name = "rustyfit"
-version = "0.3.0"
+version = "0.4.0"
 edition = "2024"
 description = "This project hosts the Rust implementation for The Flexible and Interoperable Data Transfer (FIT) Protocol"
 authors = ["Hikmatulloh Hari Mukti <muktihaz@gmail.com>"]

rustyfit/Cargo.toml

@@ -25,20 +25,20 @@ pub fn bench_decode(c: &mut Criterion) {
         })
     });
 
-    c.bench_function("decode fn", |b| {
+    c.bench_function("decode_with", |b| {
         b.iter(|| {
             let mut dec = Decoder::new(black_box(Cursor::new(&file_bytes)));
-            dec.decode_fn(|_| {}).unwrap();
+            dec.decode_with(|_| {}).unwrap();
         })
     });
 
-    c.bench_function("decode fn no checksum no expand", |b| {
+    c.bench_function("decode_with no checksum no expand", |b| {
         b.iter(|| {
             let mut dec = DecoderBuilder::new(black_box(Cursor::new(&file_bytes)))
                 .checksum(false)
                 .expand_components(false)
                 .build();
-            dec.decode_fn(|_| {}).unwrap();
+            dec.decode_with(|_| {}).unwrap();
         })
     });
 }

rustyfit/benches/decoder.rs

@@ -8,37 +8,40 @@ const TEST_FILE: &str = "tests/data/large.fit";
 pub fn bench_encode(c: &mut Criterion) {
     let file_bytes = std::fs::read(TEST_FILE).unwrap();
     let mut dec = Decoder::new(Cursor::new(&file_bytes));
-    let mut fit = dec.decode().unwrap();
-
     let mut buf = Vec::<u8>::with_capacity(10_000 >> 10); // 10 MB, large enough to avoid realloc.
 
-    c.bench_function("encode default", |b| {
-        b.iter(|| {
-            let cur = Cursor::new(&mut buf);
-            let mut enc = Encoder::new(black_box(cur));
-            enc.encode(&mut fit).unwrap();
-        })
-    });
-
-    c.bench_function("encode normal interleave 15", |b| {
-        b.iter(|| {
-            let cur = Cursor::new(&mut buf);
-            let mut enc = EncoderBuilder::new(black_box(cur))
-                .header_option(HeaderOption::Normal(15))
-                .build();
-            enc.encode(&mut fit).unwrap();
-        })
-    });
-
-    c.bench_function("encode compress interleave 3", |b| {
-        b.iter(|| {
-            let cur = Cursor::new(&mut buf);
-            let mut enc = EncoderBuilder::new(black_box(cur))
-                .header_option(HeaderOption::Compressed(3))
-                .build();
-            enc.encode(&mut fit).unwrap();
-        })
-    });
+    while let Some(fit) = &mut dec.decode().unwrap() {
+        c.bench_function("encode default", |b| {
+            b.iter(|| {
+                let cur = Cursor::new(&mut buf);
+                let mut enc = Encoder::new(black_box(cur));
+                enc.encode(fit).unwrap();
+                buf.clear();
+            })
+        });
+
+        c.bench_function("encode normal interleave 15", |b| {
+            b.iter(|| {
+                let cur = Cursor::new(&mut buf);
+                let mut enc = EncoderBuilder::new(black_box(cur))
+                    .header_option(HeaderOption::Normal(15))
+                    .build();
+                enc.encode(fit).unwrap();
+                buf.clear();
+            })
+        });
+
+        c.bench_function("encode compress interleave 3", |b| {
+            b.iter(|| {
+                let cur = Cursor::new(&mut buf);
+                let mut enc = EncoderBuilder::new(black_box(cur))
+                    .header_option(HeaderOption::Compressed(3))
+                    .build();
+                enc.encode(fit).unwrap();
+                buf.clear();
+            })
+        });
+    }
 }
 
 criterion_group!(benches, bench_encode);

rustyfit/benches/encoder.rs

@@ -24,7 +24,7 @@ impl Crc16 {
         self.0 = crc;
     }
 
-    pub fn sum16(&mut self) -> u16 {
+    pub fn sum16(&self) -> u16 {
         self.0
     }