Improve error handling ergonomics (and docs around it)

README.md

@@ -1,29 +1,18 @@
-## WHATWG URL parser for Rust
+# WHATWG URL parser for Rust
 
 Fast [WHATWG URL Specification](https://url.spec.whatwg.org) compliant URL parser for Rust.
 Well-tested and widely used by Node.js since [Node 18](https://nodejs.org/en/blog/release/v18.17.0).
 
 The Ada library passes the full range of tests from the specification, across a wide range of platforms (e.g., Windows, Linux, macOS).
 It fully supports the relevant [Unicode Technical Standard](https://www.unicode.org/reports/tr46/#ToUnicode).
 
-### Usage
-
-Here is an example illustrating a common usage:
-
-```Rust
-use ada_url::Url;
-fn main() {
-    let u = Url::parse("http://www.google:8080/love#drug", None).expect("bad url");
-    println!("port: {:?}", u.port());
-    println!("hash: {:?}", u.hash());
-    println!("pathname: {:?}", u.pathname());
-    println!("href: {:?}", u.href());
-    u.set_port("9999");
-    println!("href: {:?}", u.href());
-}
-```
+## Usage
+
+See [here](examples/simple.rs) for a usage example.
+You can run it locally with `cargo run --example simple`.
+Feel free to adjust it for exploring this crate further.
 
-#### Features
+### Features
 
 **std:** Functionalities that require `std`.
 This feature is enabled by default, set `no-default-features` to `true` if you want `no-std`.
@@ -38,7 +27,7 @@ Enabling this feature without `libc++` installed would cause compile error.
 
 Ada is fast. The benchmark below shows **3.34 times** faster URL parsing compared to `url`
 
-```
+```text
 parse/ada_url           time:   [2.0790 µs 2.0812 µs 2.0835 µs]
                         thrpt:  [369.84 MiB/s 370.25 MiB/s 370.65 MiB/s]
 
@@ -65,9 +54,9 @@ parse/url               time:   [6.9266 µs 6.9677 µs 7.0199 µs]
 | **[`Send`](https://doc.rust-lang.org/std/marker/trait.Send.html)**                                                                                    | Used to declare that the type can be transferred across thread boundaries.                                                                                                                                    |
 | **[`Sync`](https://doc.rust-lang.org/stable/std/marker/trait.Sync.html)**                                                                             | Used to declare that the type is thread-safe.                                                                                                                                                                 |
 
-### Development
+## Development
 
-#### `justfile`
+### `justfile`
 
 The [`justfile`](./justfile) contains commands (called "recipes") that can be executed by [just](https://github.com/casey/just) for convenience.
 
@@ -83,7 +72,7 @@ just all
 just all --skip=libcpp,serde
 ```
 
-### License
+## License
 
 This code is made available under the Apache License 2.0 as well as the MIT license.
 

examples/simple.rs

@@ -0,0 +1,14 @@
+use ada_url::Url;
+
+fn main() {
+    let url = Url::parse("http://www.google:8080/love#drug", None).expect("bad url");
+
+    println!("port: {:?}", url.port());
+    println!("hash: {:?}", url.hash());
+    println!("pathname: {:?}", url.pathname());
+    println!("href: {:?}", url.href());
+
+    let mut url = url;
+    url.set_port(Some("9999")).expect("bad port");
+    println!("href: {:?}", url.href());
+}

src/ffi.rs

@@ -14,7 +14,8 @@ pub struct ada_string {
 }
 
 impl ada_string {
-    pub fn as_str(&self) -> &'static str {
+    #[must_use]
+    pub const fn as_str(&self) -> &'static str {
         unsafe {
             let slice = core::slice::from_raw_parts(self.data.cast(), self.length);
             core::str::from_utf8_unchecked(slice)

src/idna.rs

@@ -1,6 +1,6 @@
 use crate::ffi;
 
-/// IDNA struct implements the to_ascii and to_unicode functions from the Unicode Technical
+/// IDNA struct implements the `to_ascii` and `to_unicode` functions from the Unicode Technical
 /// Standard supporting a wide range of systems. It is suitable for URL parsing.
 /// For more information, [read the specification](https://www.unicode.org/reports/tr46/#ToUnicode)
 pub struct Idna {}
@@ -15,6 +15,7 @@ impl Idna {
     /// use ada_url::Idna;
     /// assert_eq!(Idna::unicode("xn--meagefactory-m9a.ca"), "meßagefactory.ca");
     /// ```
+    #[must_use]
     pub fn unicode(input: &str) -> &str {
         unsafe {
             let out = ffi::ada_idna_to_unicode(input.as_ptr().cast(), input.len());
@@ -32,6 +33,7 @@ impl Idna {
     /// use ada_url::Idna;
     /// assert_eq!(Idna::ascii("meßagefactory.ca"), "xn--meagefactory-m9a.ca");
     /// ```
+    #[must_use]
     pub fn ascii(input: &str) -> &str {
         unsafe {
             let out = ffi::ada_idna_to_ascii(input.as_ptr().cast(), input.len());