Idiomatic safe Rust

[kodemartin]

Description

This first issue aims at discussing the first release of rustpostal, the underlying problems as a candidate idiomatic Rust codebase, and outlining the way ahead for this small project.

Motivation for this project

The motivation behind this project was twofold:

1. To serve as an educational project after finishing the Rust Programming Language book. After all, practicing with problems for which there is a demonstrated solution is quite different from digging your way through the docs to resolve any issues that come along when implementing something new.
2. To make myself useful in the open-source community, and especially in relation to a project that I had bookmarked as a very well developed and documented work. I am referring to libpostal, by @albarrentine. The fact that there are no references to Rust bindings to the project as yet made the idea seem worthwhile.

As it turned out, there is already a similar solution to the problem, developed by @pnordahl (see rust-postal), so the second aspect of my original motivation is rather downscaled.

Development, release, and feedback

This solution is significanly influenced by the existing official bindings in Python, and Go. I wanted to get as close as possible to the API provided there, which seems consistent as to the basic utilities exposed on a level higher than the C-library.

Conceptually, this marked the first release goal: Expose parse_address and expand_address with signatures similar to the ones used by the Python, and Go bindings. At the same time, however, it directed the development process a bit off the tracks of the educational aspects of this work.

Thankfully, Rust has a magnificent community, and I was lucky enough to receive an elaborate and very helpful review by @H2CO3 when I asked for it in https://users.rust-lang.org/.

Evidently this project is far off from being considered an idiomatic and safe Rust specimen.

The way ahead

Nevertheless, the review can mark a change of priorities for the next steps of development. The goal is to focus on following best practices for writing safe Rust code.

As a matter of fact, the specific comments from the review can serve as a roadmap:

1. Follow Rust API guidelines and best practices in general.
2. Use RAII-enabled wrappers for the unsafe ffi functions.
3. Use a dedicated -sys crate to maintain the unsafe ffi to libpostal.

Hopefully, this will result in a better implementation.

References to be used

• Using C libraries in Rust
• The Rustonomicon