[doc] improve examples

README.md

@@ -14,7 +14,8 @@ This repository regroups crates that offer enabler-libraries and binaries to
 convert and enrich transit data.
 
 Additionally, `transit_model` is itself a library providing various
-functionalities. Please refer to the code and documentation to discover them.
+functionalities. Please refer to the code, [examples](examples) and
+[documentation](https://docs.rs/transit_model) to discover them.
 
 Please check documentation attached to each crate:
 

examples/README.md

@@ -0,0 +1,15 @@
+# `transit_model` library usage examples
+
+This directory provides simple examples about the usage of the `transit_model` library.
+
+To check output, launch examples in the desired data-directory:
+
+```sh
+cd ../tests/fixtures/ntfs
+cargo run --example ntfs_crawler
+```
+
+```sh
+cd ../tests/fixtures/gtfs
+cargo run --example gtfs_reader
+```

examples/gtfs_reader.rs

@@ -1,4 +1,4 @@
-// Copyright (C) 2017 Kisio Digital and/or its affiliates.
+// Copyright (C) 2020 Kisio Digital and/or its affiliates.
 //
 // This program is free software: you can redistribute it and/or modify it
 // under the terms of the GNU Affero General Public License as published by the
@@ -29,9 +29,11 @@ fn run() -> Result<()> {
         on_demand_transport: false,
         on_demand_transport_comment: None,
     };
+    // read GTFS from current directory
     let objects = gtfs::read_from_path(".", configuration)?;
+    // output internal model as JSON
     let json_objs = json!(objects);
-    println!("{:?}", json_objs.to_string());
+    println!("{}", json_objs.to_string());
     Ok(())
 }
 

examples/test.rs → examples/ntfs_crawler.rs

@@ -1,4 +1,4 @@
-// Copyright (C) 2017 Kisio Digital and/or its affiliates.
+// Copyright (C) 2020 Kisio Digital and/or its affiliates.
 //
 // This program is free software: you can redistribute it and/or modify it
 // under the terms of the GNU Affero General Public License as published by the
@@ -30,16 +30,30 @@ where
 }
 
 fn run() -> Result<()> {
-    let objects = transit_model::ntfs::read(".")?;
+    // load ntfs from current directory
+    let transit_objects = transit_model::ntfs::read(".")?;
 
-    for (from, stop_area) in &objects.stop_areas {
-        let cms = get(from, &objects.commercial_modes, &objects);
-        let pms = get(from, &objects.physical_modes, &objects);
-        let ns = get(from, &objects.networks, &objects);
-        let cs = get(from, &objects.contributors, &objects);
+    // stop_area by stop_area, print PT objects related to it
+    for (idx, stop_area) in &transit_objects.stop_areas {
+        // retrieve idx from id
+        assert_eq!(
+            transit_objects.stop_areas.get_idx(&stop_area.id).unwrap(),
+            idx
+        );
+
+        // lines passing by stop
+        let lines = get(idx, &transit_objects.lines, &transit_objects);
+        // physical_modes stopping at stop
+        let pms = get(idx, &transit_objects.physical_modes, &transit_objects);
+        // networks using stop
+        let ns = get(idx, &transit_objects.networks, &transit_objects);
+        // contributors providing the data for stop
+        let cs = get(idx, &transit_objects.contributors, &transit_objects);
+        // access stop_area through its idx to get name
+        let stop_name = &transit_objects.stop_areas[idx].name;
         println!(
-            "{}: cms: {:?}, pms: {:?}, ns: {:?}, cs: {:?}, codes: {:?}",
-            stop_area.id, cms, pms, ns, cs, stop_area.codes
+            "stop_area {} ({}): lines: {:?}, physical_modes: {:?}, networks: {:?}, contributors: {:?}, codes: {:?}",
+            stop_area.id, stop_name, lines, pms, ns, cs, stop_area.codes
         );
     }
     Ok(())

src/model.rs

@@ -26,7 +26,7 @@ use relational_types::{GetCorresponding, IdxSet, ManyToMany, OneToMany, Relation
 use serde::{Deserialize, Serialize};
 use skip_error::skip_error_and_log;
 use std::{
-    cmp::{self, Ordering},
+    cmp::{self, Ordering, Reverse},
     collections::{BTreeMap, HashMap, HashSet},
     convert::TryFrom,
     iter::FromIterator,
@@ -655,8 +655,9 @@ impl Collections {
             // [[9,10],[12,13,14],[23,0,1]] --> [[12,13,14],[23,0,1],[9,10]]
             // *** then, in case of equal width, sorts by taking the segment early in the morning (smallest index)
             // --> [[23,0,1],[12,13,14],[9,10]]
+            #[allow(clippy::unnecessary_sort_by)] // key borrows, so lint is "wrong"
             holes.sort_unstable_by(|l, r| l.iter().min().cmp(&r.iter().min()));
-            holes.sort_unstable_by(|l, r| r.len().cmp(&l.len()));
+            holes.sort_by_key(|v| Reverse(v.len()));
             holes.first().and_then(|mh| {
                 let first_idx = mh.first();
                 let last_idx = mh.last();

src/utils.rs

@@ -85,7 +85,6 @@ where
 }
 
 // The signature of the function must pass by reference for 'serde' to be able to use the function
-#[allow(clippy::trivially_copy_pass_by_ref)]
 pub fn ser_from_bool<S>(v: &bool, serializer: S) -> Result<S::Ok, S::Error>
 where
     S: serde::Serializer,
@@ -104,7 +103,6 @@ where
 }
 
 // The signature of the function must pass by reference for 'serde' to be able to use the function
-#[allow(clippy::trivially_copy_pass_by_ref)]
 pub fn ser_from_naive_date<S>(date: &Date, serializer: S) -> Result<S::Ok, S::Error>
 where
     S: serde::Serializer,

src/vptranslator.rs

@@ -437,7 +437,7 @@ mod tests {
                 date: Date::from_ymd(2012, 7, 13),
                 exception_type: ExceptionType::Remove,
             },
-            res.exceptions.iter().next().unwrap()
+            res.exceptions.get(0).unwrap()
         );
         assert_eq!(
             ValidityPeriod {
@@ -462,7 +462,7 @@ mod tests {
                 date: Date::from_ymd(2012, 7, 12),
                 exception_type: ExceptionType::Add,
             },
-            res.exceptions.iter().next().unwrap()
+            res.exceptions.get(0).unwrap()
         );
         assert_eq!(
             ValidityPeriod {

tests/read_ntfs.rs

@@ -35,7 +35,6 @@ where
 }
 
 #[test]
-#[allow(clippy::cognitive_complexity)]
 fn minimal() {
     let ntm = transit_model::ntfs::read("tests/fixtures/minimal_ntfs/").unwrap();