Make the README useful

Cargo.toml

@@ -4,12 +4,12 @@ version = "0.1.0"
 authors = ["Alexander Batischev <[email protected]>"]
 edition = "2021"
 license = "MIT"
-# ==============
 readme = "README.md"
-description = """ Safe wrapper for [POSIX regular expressions API][regex-h] (provided by libc on POSIX-compliant OSes).
-Part of libnewsboat lib dependencies"""
+description = "Safe wrapper for POSIX regular expressions API"
 homepage = "https://github.com/newsboat/regex-rs"
 repository = "https://github.com/newsboat/regex-rs"
+keywords = ["posix", "regex", "bindings"]
+categories = ["api-bindings", "os"]
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 

README.md

@@ -1,7 +1,31 @@
-# regex-rs (part of libnewsboat library)
+# regex-rs: safe wrapper for [POSIX regular expressions API][regex-h] (provided by libc on POSIX-compliant OSes)
 
-__Disclaimer:__ This project is part of [Newsboat](https://github.com/newsboat/newsboat) Rust libraries, I'm not it's author - merely maintaining up to date versions on Crates.io.
+[regex-h]: https://pubs.opengroup.org/onlinepubs/9699919799.2008edition/basedefs/regex.h.html#tag_13_37
 
-## Description
+Example usage:
 
-Safe wrapper for [POSIX regular expressions API][regex-h] (provided by libc on POSIX-compliant OSes).
+```rust
+use regex_rs::*;
+
+let pattern = "This( often)? repeats time and again(, and again)*\\.";
+let compilation_flags = CompFlags::EXTENDED;
+let regex = Regex::new(pattern, compilation_flags)
+    .expect("Failed to compile pattern as POSIX extended regular expression");
+
+let input = "This repeats time and again, and again, and again.";
+// We're only interested in the first match, i.e. the part of text
+// that's matched by the whole regex
+let max_matches = 1;
+let match_flags = MatchFlags::empty();
+let matches = regex
+    .matches(input, max_matches, match_flags)
+    .expect("Error matching input against regex");
+
+// Found a match
+assert_eq!(matches.len(), 1);
+
+// Match spans from the beginning to the end of the input
+assert_eq!(matches[0].start_pos, 0);
+// `end_pos` holds one-past-the-end index
+assert_eq!(matches[0].end_pos, input.len());
+```

src/lib.rs

@@ -2,6 +2,8 @@
 //!
 //! [regex-h]: https://pubs.opengroup.org/onlinepubs/9699919799.2008edition/basedefs/regex.h.html#tag_13_37
 //!
+//! Example usage:
+//!
 //! ```
 //! use regex_rs::*;
 //!