Merge #100

100: Update documentation to include write examples r=lnicola a=wtchen - [x] I agree to follow the project's [code of conduct](https://github.com/georust/geo/blob/master/CODE_OF_CONDUCT.md). - [x] I added an entry to `CHANGELOG.md` if knowledge of this change could be valuable to users. --- Fixes #98 Co-authored-by: William Chen <[email protected]>
georust · Oct 22, 2023 · 46fc38d · 46fc38d
2 parents 98da8cc + b16cde6
commit 46fc38d
Show file tree

Hide file tree

Showing 3 changed files with 61 additions and 1 deletion.
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,4 @@
 /target
 /Cargo.lock
 *.bk
+.idea
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,7 @@
 
 ## Unreleased
 
+- [#100](https://github.com/georust/gpx/pull/100): Add write examples to `README.md`
 - [#97](https://github.com/georust/gpx/pull/97): Allow empty strings in `<name>` within `<metadata>`
 - [#94](https://github.com/georust/gpx/pull/94): Bump MSRV to 1.67.
 - [#93](https://github.com/georust/gpx/pull/93): Allow empty strings in `<text>` and `<type>` of `<link>`

diff --git a/README.md b/README.md
@@ -8,7 +8,9 @@ gpx is a library for reading and writing GPX (GPS Exchange Format) files. It use
 primitives provided by [geo-types](https://github.com/georust/geo) to allow for storage
 of GPS data.
 
-## Example
+## Examples
+
+### Read a GPX file
 ```rust
 extern crate gpx;
 
@@ -41,6 +43,62 @@ fn main() {
 }
 ```
 
+### Generate a new GPX file
+This example only generates tracks. You can add waypoints and routes as well by instantiating new ``Waypoint``s and ``Route``s.
+
+```rust
+use geo_types::{coord, Point};
+use gpx::{Gpx, GpxVersion, Track, TrackSegment, Waypoint};
+use std::{error::Error, fs::File, io::BufWriter, path::Path};
+
+pub fn to_gpx<P: AsRef<Path>>(out_path: P) -> Result<(), Box<dyn Error>> {
+    // Instantiate Gpx struct
+    let track_segment = TrackSegment {
+        points: vec![]
+    };
+    let track = Track {
+        name: Some("Track 1".to_string()),
+        comment: None,
+        description: None,
+        source: None,
+        links: vec![],
+        type_: None,
+        number: None,
+        segments: vec![track_segment],
+    };
+    let mut gpx = Gpx {
+        version: GpxVersion::Gpx11,
+        creator: None,
+        metadata: None,
+        waypoints: vec![],
+        tracks: vec![track],
+        routes: vec![],
+    };
+
+    // Create file at path
+    let gpx_file = File::create(out_path)?;
+    let buf = BufWriter::new(gpx_file);
+
+    // Add track point
+    let geo_coord = coord! { x: -121.1, y: 38.82 };
+    let geo_point: Point = geo_coord.into();
+    gpx.tracks[0].segments[0].points.push(Waypoint::new(geo_point));
+
+    // Write to file
+    gpx::write(&gpx, buf)?;
+
+    Ok(())
+}
+```
+
+### Write to string
+`write` will write the GPX output to anything that implements `std::io::Write`. To save the output to a string, write it to a `u8` vector, and then convert the vector to a string.
+```rust
+let mut vec = Vec::new();
+gpx::write(&gpx, &mut vec)?;
+let string = String::from_utf8(vec)?;
+```
+
 ## Current Status
 
 rust-gpx currently supports reading and writing both GPX 1.1 and 1.0.