Merge pull request #7 from MidasLamb/forward-to-string

Added delegates

Author: MidasLamb

CHANGELOG.md

@@ -6,19 +6,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 ### Added
+* Add & delegate all non-length-reducing methods of `std::string::String` to the inner `String`.
 
 ### Changed
+* README has some more examples and explanations. It is also no longer included in the doc (except for doctests).
 
 ### Removed
 
 ## [0.2.1]
-### Added
-
 ### Changed
 * The error message when using `serde` now indicates that the empty string could not be deserialized.
 * Bumped rust edition to `2021`
 
-### Removed
 ## [0.2.0]
 ### Added
 * `serde` support behind the `serde` feature flag.
@@ -28,8 +27,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 * `new` constructor now returns a `Result` rather than an `Option`, which contains the original string 
 
-### Removed
-
 [Unreleased]: https://github.com/MidasLamb/non-empty-string/v0.2.1...HEAD
 [0.2.1]: https://github.com/MidasLamb/non-empty-string/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/MidasLamb/non-empty-string/compare/v0.1.0...v0.2.0

Cargo.toml

@@ -13,10 +13,12 @@ name = "non_empty_string"
 
 [dependencies]
 serde = { version = "1", optional = true }
+delegate = { version = "0.8" }
 
 [dev-dependencies]
 assert_matches = "1.5.0"
 serde_json = { version = "1" }
+serde = { version = "1", features = ["derive"] }
 
 [features]
 default = []

README.md

@@ -1,6 +1,55 @@
-# NonEmptyString
+# Non Empty String
+
+[![Crates.io](https://img.shields.io/crates/v/non-empty-string.svg)](https://crates.io/crates/non-empty-string)
+[![Documentation](https://docs.rs/non-empty-string/badge.svg)](https://docs.rs/non-empty-string/)
+
 A simple wrapper type for `String`s that ensures that the string inside is not `.empty()`, meaning that the length > 0.
 
+## Example
+
+```rust
+use non_empty_string::NonEmptyString;
+
+// Constructing it from a normal (non-zero-length) String works fine.
+let s = "A string with a length".to_owned();
+assert!(NonEmptyString::new(s).is_ok());
+
+// But constructing it from a non-zero-length String results in an `Err`, where we get the `String` back that we passed in.
+let empty = "".to_owned();
+let result = NonEmptyString::new(empty);
+assert!(result.is_err());
+assert_eq!(result.unwrap_err(), "".to_owned())
+
+```
+
+## Methods of std::string::String
+`NonEmptyString` implements a subset of the functions of `std::string::String`, only the ones which are guaranteed to leave the `NonEmptyString` in a valid state.
+This means i.e. `push()` is implemented, but `pop()` is not.
+
+This allows you to mostly treat it as a String without having to constantly turn it into the inner `String` before you can do any sort of operation on it and then having to reconstruct a `NonEmptyString` afterwards.
+
+
+## Serde Support
+
+[serde] support is available behind the `serde` feature flag:
+```toml
+[dependencies]
+serde = { version = "1", features = ["derive"] }
+non-empty-string = { version = "*", features = ["serde"]}
+```
+
+Afterwards you can use it in a struct:
+```rust
+use serde::{Serialize, Deserialize};
+use non_empty_string::NonEmptyString;
+
+#[derive(Serialize, Deserialize)]
+struct MyApiObject {
+  username: NonEmptyString,
+}
+```
+
+Deserialization will fail if the field is present as a String, but the length of the `String` is 0.
 
 ## License
 
@@ -17,4 +66,6 @@ at your option.
 
 Unless you explicitly state otherwise, any contribution intentionally submitted
 for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
-dual licensed as above, without any additional terms or conditions.
+dual licensed as above, without any additional terms or conditions.
+
+[serde]: https://docs.rs/serde

src/lib.rs

@@ -1,4 +1,16 @@
-#![doc = include_str!("../README.md")]
+#![doc(issue_tracker_base_url = "https://github.com/MidasLamb/non-empty-string/issues/")]
+
+//! # NonEmptyString
+//! A simple wrapper type for `String`s that ensures that the string inside is not `.empty()`, meaning that the length > 0.
+
+// Test the items in the readme file.
+#[cfg(doctest)]
+mod test_readme {
+    #[doc = include_str!("../README.md")]
+    mod something {}
+}
+
+use delegate::delegate;
 
 #[cfg(feature = "serde")]
 mod serde_support;
@@ -9,6 +21,7 @@ mod serde_support;
 #[repr(transparent)]
 pub struct NonEmptyString(String);
 
+#[allow(clippy::len_without_is_empty)] // is_empty would always returns false so it seems a bit silly to have it.
 impl NonEmptyString {
     /// Attempts to create a new NonEmptyString.
     /// If the given `string` is empty, `Err` is returned, containing the original `String`, `Ok` otherwise.
@@ -29,6 +42,77 @@ impl NonEmptyString {
     pub fn into_inner(self) -> String {
         self.0
     }
+
+    // These are safe methods that can simply be forwarded.
+    delegate! {
+        to self.0 {
+            /// Is forwarded to the inner String.
+            /// See [`std::string::String::into_bytes`]
+            pub fn into_bytes(self) -> Vec<u8>;
+
+            /// Is forwarded to the inner String.
+            /// See [`std::string::String::as_str`]
+            pub fn as_str(&self) -> &str;
+
+            /// Is forwarded to the inner String.
+            /// See [`std::string::String::push_str`]
+            pub fn push_str(&mut self, string: &str);
+
+            /// Is forwarded to the inner String.
+            /// See [`std::string::String::capacity`]
+            pub fn capacity(&self) -> usize;
+
+            /// Is forwarded to the inner String.
+            /// See [`std::string::String::reserve`]
+            pub fn reserve(&mut self, additional: usize);
+
+            /// Is forwarded to the inner String.
+            /// See [`std::string::String::reserve_exact`]
+            pub fn reserve_exact(&mut self, additional: usize);
+
+            // For some reason we cannot delegate the following:
+            // pub fn try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError>
+
+            /// Is forwarded to the inner String.
+            /// See [`std::string::String::try_reserve_exact`]
+            pub fn try_reserve_exact(
+                &mut self,
+                additional: usize
+            ) -> Result<(), std::collections::TryReserveError>;
+
+            /// Is forwarded to the inner String.
+            /// See std::string::String::[`(&`]
+            pub fn shrink_to_fit(&mut self);
+
+            /// Is forwarded to the inner String.
+            /// See [`std::string::String::shrink_to`]
+            pub fn shrink_to(&mut self, min_capacity: usize);
+
+            /// Is forwarded to the inner String.
+            /// See [`std::string::String::push`]
+            pub fn push(&mut self, ch: char);
+
+            /// Is forwarded to the inner String.
+            /// See [`std::string::String::as_bytes`]
+            pub fn as_bytes(&self) -> &[u8];
+
+            /// Is forwarded to the inner String.
+            /// See [`std::string::String::insert`]
+            pub fn insert(&mut self, idx: usize, ch: char);
+
+            /// Is forwarded to the inner String.
+            /// See [`std::string::String::insert_str`]
+            pub fn insert_str(&mut self, idx: usize, string: &str);
+
+            /// Is forwarded to the inner String.
+            /// See [`std::string::String::len`]
+            pub fn len(&self) -> usize;
+
+            /// Is forwarded to the inner String.
+            /// See [`std::string::String::into_boxed_str`]
+            pub fn into_boxed_str(self) -> Box<str>;
+        }
+    }
 }
 
 impl std::convert::AsRef<str> for NonEmptyString {
@@ -55,6 +139,14 @@ impl<'s> std::convert::TryFrom<&'s str> for NonEmptyString {
     }
 }
 
+impl std::convert::TryFrom<String> for NonEmptyString {
+    type Error = String;
+
+    fn try_from(value: String) -> Result<Self, Self::Error> {
+        NonEmptyString::new(value)
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -98,6 +190,6 @@ mod tests {
     fn calling_string_methods_works() {
         let nes = NonEmptyString::new("string".to_owned()).unwrap();
         // `len` is a `String` method.
-        assert!(nes.get().len() > 0);
+        assert!(nes.len() > 0);
     }
 }