support finished

README.md

@@ -6,9 +6,6 @@
 
 This library provides [rust-lang/rust-bindgen](https://github.com/rust-lang/rust-bindgen) generated Rust <-> C bindings, and puts an ergonomic and safe Rust API on top of them.
 
-Still TODO:
-- [ ] parse_address support
-
 ## Installation
 
 Follow the README instructions at [openvenues/libpostal](https://github.com/openvenues/libpostal) to install the shared library for your platform. Currently, the compiled object is dynamically linked when your project runs - static linkage could be supported in the future.
@@ -30,7 +27,7 @@ extern crate postal;
 
 *Note*: `libpostal` is not threadsafe. As a result, do not create more than one `postal::Context` per process. `Context::expand_address` and `Context::parse_address` do internal locking, and are safe to call concurrently.
 
-This is a minimal example of using the `expand_address` API:
+This is an example of using the `expand_address` API:
 
 ```rust
 extern crate postal;
@@ -57,6 +54,32 @@ for e in exps {
 }
 ```
 
+This is how you might use the `parse_address` API:
+
+```rust
+extern crate postal;
+use postal::{Context, InitOptions, ParseAddressOptions};
+
+// initialize a context to work with
+let mut ctx = Context::new();
+
+// enable address expansion for this context
+ctx.init(InitOptions{parse_address: true}).unwrap();
+
+// these options are safe to persist and reuse between calls to `expand_address`.
+// Note: `language` and `country` are technically options that libpostal will accept
+// for purposes of parsing addresses, but it ignores them at present.
+let mut opts = ParseAddressOptions::new();
+
+// parse a single address into a `postal::Components` iterator
+let comps = ctx.parse_address(
+	"1234 Cherry Ln, Podunk TX", &mut opts)
+	.unwrap();
+for c in comps {
+	dbg!(c);
+}
+```
+
 _For more examples and usage, please refer to the tests or benchmarks._
 
 ## Development setup
@@ -73,6 +96,8 @@ Note: `--test-threads 1` is required due to the single-threaded nature of `libpo
 
 ## Release History
 
+* 0.1.1
+	* Added `parse_address` support.
 * 0.1.0
     * Initial release
 

benches/benches.rs

@@ -6,45 +6,41 @@ extern crate criterion;
 use criterion::black_box;
 use criterion::Criterion;
 use postal::{Context, ExpandAddressOptions, InitOptions, ParseAddressOptions};
+use std::rc::Rc;
 
 fn criterion_benchmark(c: &mut Criterion) {
-    // expand_address
-    let mut ctx = Context::new();
-    ctx.init(InitOptions {
-        expand_address: true,
-        parse_address: false,
-    })
-    .unwrap();
-
-    let mut opts = ExpandAddressOptions::new();
-    opts.set_languages(vec!["en"].as_slice());
-    let mut bbopts = black_box(opts);
-
-    c.bench_function("expand_address address 1", move |b| {
-        let addr = black_box("1234 Cherry Ln Podunk TX");
-        b.iter(|| {
-            ctx.expand_address(addr, &mut bbopts).unwrap();
-        })
-    });
-
-    // parse_address
-    println!("loading address parser...");
-    let mut ctx2 = Context::new();
-    ctx2.init(InitOptions {
-        expand_address: false,
-        parse_address: true,
-    })
-    .unwrap();
-    println!("done");
-
-    let opts2 = ParseAddressOptions::new();
-    let mut bbopts2 = black_box(opts2);
-    c.bench_function("parse_address address 1", move |b| {
-        let addr = black_box("1234 Cherry Ln Podunk TX");
-        b.iter(|| {
-            ctx2.parse_address(addr, &mut bbopts2).unwrap();
-        })
-    });
+	println!("Loading context with all initialization options...");
+	let mut ctx = Context::new();
+	ctx.init(InitOptions {
+		expand_address: true,
+		parse_address: true,
+	})
+	.unwrap();
+	let ctx_rc = Rc::new(ctx);
+	println!("Done, running benchmarks...");
+
+	// expand_address
+	let ctx2 = Rc::clone(&ctx_rc);
+	let mut opts = ExpandAddressOptions::new();
+	opts.set_languages(vec!["en"].as_slice());
+	let mut bbopts = black_box(opts);
+	c.bench_function("expand_address address 1", move |b| {
+		let addr = black_box("1234 Cherry Ln Podunk TX");
+		b.iter(|| {
+			ctx2.expand_address(addr, &mut bbopts).unwrap();
+		})
+	});
+
+	// parse_address
+	let ctx3 = Rc::clone(&ctx_rc);
+	let opts2 = ParseAddressOptions::new();
+	let mut bbopts2 = black_box(opts2);
+	c.bench_function("parse_address, default options", move |b| {
+		let addr = black_box("1234 Cherry Ln Podunk TX");
+		b.iter(|| {
+			ctx3.parse_address(addr, &mut bbopts2).unwrap();
+		})
+	});
 }
 
 criterion_group!(benches, criterion_benchmark);