chore(examples): add example of library usage

.gitignore

@@ -9,3 +9,7 @@ package-lock.json
 node_modules/
 yarn.lock
 yarn-error.log
+
+# outputs that may be created by running the examples
+*.jpg
+*.png

.pre-commit-config.yaml

@@ -2,7 +2,7 @@ repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.5.0
     hooks:
-      - id: check-byte-order-marker
+      - id: fix-byte-order-marker
       - id: check-case-conflict
       - id: check-merge-conflict
       - id: check-symlinks

README.md

@@ -52,7 +52,19 @@ Most (if not all) vips operations don't mutate the `VipsImage` object, so they'l
 
 ### Example
 
+The below example can be run from the console using cargo.
+
+```console
+$ cargo run --examples jpeg_to_png.rs
+   Compiling libvips v1.6.1 (<REDACTED>/libvips-rust-bindings)
+    Finished dev [unoptimized + debuginfo] target(s) in 3.29s
+     Running `target/debug/examples/jpeg_to_png`
+./output.png was created in the repository root!
+```
+
+
 ```rust
+// examples/jpeg_to_png.rs
 use libvips::{ops, VipsImage, VipsApp};
 
 fn main() {

examples/jpeg_to_png.rs

@@ -0,0 +1,71 @@
+use libvips::{ops, VipsApp, VipsImage};
+use std::env;
+use std::path::Path;
+
+// Load a JPEG file, transform and convert it to PNG
+// Use the following cargo command to run this example
+// cargo run --examples jpeg_to_png
+
+fn main() {
+    // this initializes the libvips library. it has to live as long as the application lives (or as long as you want to use the library within your app)
+    // you can't have multiple objects of this type and when it is dropped it will call the libvips functions to free all internal structures.
+    let app = VipsApp::new(
+        "Test Libvips",
+        false,
+    )
+    .expect("Cannot initialize libvips");
+
+    //set number of threads in libvips's threadpool
+    app.concurrency_set(2);
+    let cargo_toml_dir = env::current_dir()
+        .expect("Where is my Cargo.toml file?")
+        .display()
+        .to_string();
+    let image_path = Path::new("resources/test.png")
+        .display()
+        .to_string();
+
+    // loads an image from file
+    let image = VipsImage::new_from_file(&format!(
+        "{}/{}",
+        cargo_toml_dir, image_path
+    ))
+    .unwrap();
+
+    // will resize the image and return a new instance.
+    // libvips works most of the time with immutable objects, so it will return a new object
+    // the VipsImage struct implements Drop, which will free the memory
+    let resized = ops::resize(
+        &image,
+        0.5,
+    )
+    .unwrap();
+
+    //optional parameters
+    let options = ops::JpegsaveOptions {
+        q: 90,
+        background: vec![255.0],
+        strip: true,
+        interlace: true,
+        optimize_coding: true,
+        optimize_scans: true,
+        ..ops::JpegsaveOptions::default()
+    };
+
+    // alternatively you can use `jpegsave` that will use the default options
+    match ops::jpegsave_with_opts(
+        &resized,
+        &format!(
+            "{}/{}",
+            cargo_toml_dir, "output.png"
+        ),
+        &options,
+    ) {
+        Err(_) => println!(
+            "error: {}",
+            app.error_buffer()
+                .unwrap()
+        ),
+        Ok(_) => println!("./output.png was created in the repository root!"),
+    }
+}