- Notifications
You must be signed in to change notification settings - Fork11
Rust FFI bindings and safe interface to libpostal.
License
pnordahl/rust-postal
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
Bindings to the libpostal street address parsing/normalization C library.
This library providesrust-lang/rust-bindgen generated Rust <-> C bindings, and puts an ergonomic and safe Rust API on top of them.
This crate requires Rust 1.60 or newer.
Follow the README instructions atopenvenues/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.
Addpostal to yourCargo.toml:
Add this to your Cargo.toml:
[dependencies]postal = "0.2"Next, add this to your crate:
extern crate postal;Note:libpostal is not threadsafe. As a result, do not create more than onepostal::Context per process.Context::expand_address andContext::parse_address do internal locking, and are safe to call concurrently.
This is an example of using theexpand_address API:
externcrate postal;use postal::{Context,InitOptions,ExpandAddressOptions};// initialize a context to work withletmut ctx =Context::new();// enable address expansion for this contextctx.init(InitOptions{expand_address:true,parse_address:false}).unwrap();// these options are safe to persist and reuse between calls to `expand_address`letmut opts =ExpandAddressOptions::new();// (optional) set languages; this can improve runtime performance significantly, approximately 30% in benchmarksopts.set_languages(vec!["en"].as_slice());// expand a single address into a `postal::Expansions` iteratorlet exps = ctx.expand_address("1234 Cherry Ln, Podunk TX",&mut opts).unwrap();for ein exps{dbg!(e);}
This is how you might use theparse_address API:
externcrate postal;use postal::{Context,InitOptions,ParseAddressOptions};// initialize a context to work withletmut ctx =Context::new();// enable address parsing for this contextctx.init(InitOptions{expand_address:false,parse_address:true}).unwrap();// these options are safe to persist and reuse between calls to `parse_address`.// Note: `language` and `country` are technically options that libpostal will accept// for purposes of parsing addresses, but it ignores them at present.letmut opts =ParseAddressOptions::new();// parse a single address into a `postal::Components` iteratorlet comps = ctx.parse_address("1234 Cherry Ln, Podunk TX",&mut opts).unwrap();for cin comps{dbg!(c);}
For more examples and usage, please refer to the tests or benchmarks.
This will buildbindgen bindings, run the tests, and run the benchmarks.
cargo buildcargotest -- --nocapture --test-threads 1cargo benchNote:--test-threads 1 is required due to the single-threaded nature oflibpostal.
0.2.6
- Update bindgen and parking_lot, replace deprecated rustfmt_bindings with formatter for bindgen
0.2.2
- Resolve locking issue due to unbound Mutex guard.
0.2.1
- Make Component fields public.
0.2.0
- Added
parse_addresssupport.
- Added
0.1.0
- Initial release.
Distributed under the MIT license. SeeLICENSE for more information.
- Fork it (https://github.com/pnordahl/rust-postal/fork)
- Create your feature branch (
git checkout -b feature/fooBar) - Commit your changes (
git commit -am 'Add some fooBar') - Push to the branch (
git push origin feature/fooBar) - Create a new Pull Request