chore: release v0.2.0

Cargo.toml

@@ -6,7 +6,7 @@ categories = ["web-programming"]
 homepage = "https://github.com/EstebanBorai/local-ip-address"
 keywords = ["local", "ip", "address", "web", "network"]
 license = "MIT OR Apache-2.0"
-version = "0.1.0"
+version = "0.2.0"
 authors = ["Esteban Borai <[email protected]>"]
 edition = "2018"
 readme = "README.md"

README.md

@@ -13,28 +13,36 @@
 
 </div>
 
-Provides utility functions to get system's local network IP address by executing
-OS commands in the host machine.
-
-The output from the executed command is then parsed and an instance of a `IpAddr`
-is returned from the function.
+A wrapper on `getifaddrs` which retrieves host's
+network interfaces.
+Handy functions are provided such as `local_ip` which retrieve the local IP
+address based on the host system
 
 ```rust
+use std::net::IpAddr;
 use local_ip_address::local_ip;
 
-fn main() {
-    let my_local_ip_address = local_ip().unwrap();
-
-    println!("{:?}", my_local_ip_address);
-}
+assert!(matches!(local_ip().unwrap(), IpAddr));
 ```
 
-Every host may or may not have a different approach on gathering the local IP
+You are able to iterate over a vector of tuples where the first element of
+the tuple is the name of the network interface and the second is the IP
 address.
 
-`local-ip-address` crate implements [Conditional Compilation](https://doc.rust-lang.org/reference/conditional-compilation.html#conditional-compilation)
-to execute different approaches based on host machine operative system.
+```rust
+use std::net::IpAddr;
+use local_ip_address::find_af_inet;
 
+let ifas = find_af_inet().unwrap();
+
+if let Some((_, ipaddr)) = ifas
+.iter()
+.find(|(name, ipaddr)| *name == "en0" && matches!(ipaddr, IpAddr::V4(_))) {
+    println!("This is your local IP address: {:?}", ipaddr);
+    // This is your local IP address: 192.168.1.111
+    assert!(matches!(ipaddr, IpAddr));
+}
+```
 
 ## Release
 

src/lib.rs

@@ -1,3 +1,35 @@
+//! `local-ip-address` is a wrapper on `getifaddrs` which retrieves host's
+//! network interfaces.
+//!
+//! Handy functions are provided such as `local_ip` which retrieve the local IP
+//! address based on the host system
+//!
+//! ```
+//! use std::net::IpAddr;
+//! use local_ip_address::local_ip;
+//!
+//! assert!(matches!(local_ip().unwrap(), IpAddr));
+//! ```
+//!
+//! You are able to iterate over a vector of tuples where the first element of
+//! the tuple is the name of the network interface and the second is the IP
+//! address.
+//!
+//! ```
+//! use std::net::IpAddr;
+//! use local_ip_address::find_af_inet;
+//!
+//! let ifas = find_af_inet().unwrap();
+//!
+//! if let Some((_, ipaddr)) = ifas
+//! .iter()
+//! .find(|(name, ipaddr)| *name == "en0" && matches!(ipaddr, IpAddr::V4(_))) {
+//!     println!("This is your local IP address: {:?}", ipaddr);
+//!     // This is your local IP address: 192.168.1.111
+//!     assert!(matches!(ipaddr, IpAddr));
+//! }
+//! ```
+//!
 use libc::{getifaddrs, ifaddrs, sockaddr_in, sockaddr_in6, AF_INET, AF_INET6};
 use std::env;
 use std::ffi::CStr;
@@ -132,8 +164,10 @@ pub fn local_ip() -> Result<IpAddr, Error> {
     Err(Error::PlatformNotSupported(env::consts::OS.to_string()))
 }
 
+/// Finds the network interface with the provided name in the vector of network
+/// interfaces provided
 pub fn find_ifa<'a>(
-    ifas: &'a Vec<(&'a str, IpAddr)>,
+    ifas: &'a [(&'a str, IpAddr)],
     ifa_name: &str,
 ) -> Option<&'a (&'a str, IpAddr)> {
     ifas.iter()