Merge pull request #12 from tomoikey/for_all

`ForAll` and `Exists` implemention

Author: tomoikey

Cargo.toml

@@ -4,9 +4,9 @@ description = "A library for imbuing rules into types and elevating them to more
 authors = ["Tomoikey"]
 repository = "https://github.com/tomoikey/refined-type"
 readme = "README.md"
-categories = ["accessibility", "development-tools"]
+categories = ["accessibility", "development-tools", "rust-patterns"]
 license = "MIT"
-version = "0.4.16"
+version = "0.5.0"
 edition = "2021"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

README.md

@@ -16,23 +16,17 @@ All rules can be arbitrarily combined and extended as long as the target type ma
 As an example, let's convert from JSON to a struct.
 
 ```rust
-use refined_type::Refined;
-use refined_type::rule::NonEmptyRule;
-use serde::Deserialize;
-use serde_json::json;
-
 // define the constraints you expect by combining 'Refined' and 'Rule'.
-pub type MyNonEmptyString = Refined<NonEmptyRule<String>>;
-pub type MyNonEmptyVec<T> = Refined<NonEmptyRule<Vec<T>>>;
+type MyNonEmptyString = Refined<NonEmptyRule<String>>;
+type MyNonEmptyVec<T> = Refined<NonEmptyRule<Vec<T>>>;
 
 // define a struct for converting from JSON.
 #[derive(Debug, Eq, PartialEq, Deserialize)]
 struct Human {
     name: MyNonEmptyString,
-    friends: MyNonEmptyVec<String>
+    friends: MyNonEmptyVec<String>,
 }
 
-// In the first example, both 'name' and 'friends' satisfy the rule, so the conversion from JSON will succeed.
 fn example_1() -> anyhow::Result<()> {
     let json = json! {{
         "name": "john",
@@ -43,7 +37,7 @@ fn example_1() -> anyhow::Result<()> {
     let actual = serde_json::from_str::<Human>(&json)?;
     let expected = Human {
         name: MyNonEmptyString::new("john".to_string())?,
-        friends: MyNonEmptyVec::new(vec!["tom".to_string(), "taro".to_string()])?
+        friends: MyNonEmptyVec::new(vec!["tom".to_string(), "taro".to_string()])?,
     };
     assert_eq!(actual, expected);
     Ok(())
@@ -91,7 +85,7 @@ Once the definition is complete, all you need to do is implement the Rule trait.
 Add your preferred conditions as you like.
 
 ```rust
-fn main() {
+fn example_4() {
     let non_empty_string_result = Refined::<NonEmptyStringRule>::new("Hello World".to_string());
     assert_eq!(non_empty_string_result.unwrap().deref(), "Hello World");
 
@@ -112,15 +106,14 @@ By using Rule Composer, composite rules can be easily created.
 
 ```rust
 struct ContainsHelloRule;
-
 struct ContainsWorldRule;
 
 impl Rule for ContainsHelloRule {
     type Item = String;
 
-    fn validate(target: Self::Item) -> Result<Self::Item, Error<Self::Item>> {
+    fn validate(target: &Self::Item) -> Result<(), Error> {
         if target.contains("Hello") {
-            Ok(target)
+            Ok(())
         } else {
             Err(Error::new(format!("{} does not contain `Hello`", target)))
         }
@@ -130,9 +123,9 @@ impl Rule for ContainsHelloRule {
 impl Rule for ContainsWorldRule {
     type Item = String;
 
-    fn validate(target: Self::Item) -> Result<Self::Item, Error<Self::Item>> {
+    fn validate(target: &Self::Item) -> Result<(), Error> {
         if target.contains("World") {
-            Ok(target)
+            Ok(())
         } else {
             Err(Error::new(format!("{} does not contain `World`", target)))
         }
@@ -146,7 +139,7 @@ impl Rule for ContainsWorldRule {
 It is generally effective when you want to narrow down the condition range.
 
 ```rust
-fn main() {
+fn example_5() {
     type HelloAndWorldRule = And<ContainsHelloRule, ContainsWorldRule>;
 
     let rule_ok = Refined::<HelloAndWorldRule>::new("Hello! World!".to_string());
@@ -163,7 +156,7 @@ fn main() {
 It is generally effective when you want to expand the condition range.
 
 ```rust
-fn main() {
+fn example_6() {
     type HelloOrWorldRule = Or<ContainsHelloRule, ContainsWorldRule>;
 
     let rule_ok_1 = Refined::<HelloOrWorldRule>::new("Hello! World!".to_string());
@@ -183,7 +176,7 @@ fn main() {
 It is generally effective when you want to discard only certain situations.
 
 ```rust
-fn main() {
+fn example_7() {
     type NotHelloRule = Not<ContainsHelloRule>;
 
     let rule_ok = Refined::<NotHelloRule>::new("hello! World!".to_string());
@@ -200,18 +193,16 @@ Rule Composer is also a rule.
 Therefore, it can be treated much like a composite function
 
 ```rust
-struct StartWithHelloRule;
-
-struct StartWithByeRule;
-
-struct EndWithJohnRule;
+struct StartsWithHelloRule;
+struct StartsWithByeRule;
+struct EndsWithJohnRule;
 
 impl Rule for StartsWithHelloRule {
     type Item = String;
 
-    fn validate(target: Self::Item) -> Result<Self::Item, Error<Self::Item>> {
+    fn validate(target: &Self::Item) -> Result<(), Error> {
         if target.starts_with("Hello") {
-            Ok(target)
+            Ok(())
         } else {
             Err(Error::new(format!("{} does not start with `Hello`", target)))
         }
@@ -221,34 +212,34 @@ impl Rule for StartsWithHelloRule {
 impl Rule for StartsWithByeRule {
     type Item = String;
 
-    fn validate(target: Self::Item) -> Result<Self::Item, Error<Self::Item>> {
+    fn validate(target: &Self::Item) -> Result<(), Error> {
         if target.starts_with("Bye") {
-            Ok(target)
+            Ok(())
         } else {
             Err(Error::new(format!("{} does not start with `Bye`", target)))
         }
     }
 }
 
-impl Rule for EndWithJohnRule {
+impl Rule for EndsWithJohnRule {
     type Item = String;
 
-    fn validate(target: Self::Item) -> Result<Self::Item, Error<Self::Item>> {
+    fn validate(target: &Self::Item) -> Result<(), Error> {
         if target.ends_with("John") {
-            Ok(target)
+            Ok(())
         } else {
             Err(Error::new(format!("{} does not end with `John`", target)))
         }
     }
 }
 
-fn main() {
-    type GreetingRule = And<Or<StartWithHelloRule, StartWithByeRule>, EndWithJohnRule>;
+fn example_8() {
+    type GreetingRule = And<Or<StartsWithHelloRule, StartsWithByeRule>, EndsWithJohnRule>;
 
-    assert!(GreetingRule::validate("Hello! Nice to meet you John".to_string()).is_ok());
-    assert!(GreetingRule::validate("Bye! Have a good day John".to_string()).is_ok());
-    assert!(GreetingRule::validate("How are you? Have a good day John".to_string()).is_err());
-    assert!(GreetingRule::validate("Bye! Have a good day Tom".to_string()).is_err());
+    assert!(GreetingRule::validate(&"Hello! Nice to meet you John".to_string()).is_ok());
+    assert!(GreetingRule::validate(&"Bye! Have a good day John".to_string()).is_ok());
+    assert!(GreetingRule::validate(&"How are you? Have a good day John".to_string()).is_err());
+    assert!(GreetingRule::validate(&"Bye! Have a good day Tom".to_string()).is_err());
 }
 ```
 
@@ -261,16 +252,14 @@ and `Deserialize`.
 ### Serialize
 
 ```rust
-type NonEmptyString = Refined<NonEmptyStringRule>;
-
-#[derive(Serialize)]
-struct Human {
+#[derive(Debug, Eq, PartialEq, Deserialize, Serialize)]
+struct Human2 {
     name: NonEmptyString,
     age: u8,
 }
 
-fn main() -> anyhow::Result<()> {
-    let john = Human {
+fn example_9() -> anyhow::Result<()> {
+    let john = Human2 {
         name: NonEmptyString::new("john".to_string())?,
         age: 8,
     };
@@ -288,24 +277,16 @@ fn main() -> anyhow::Result<()> {
 ### Deserialize
 
 ```rust
-type NonEmptyString = Refined<NonEmptyStringRule>;
-
-#[derive(Debug, Eq, PartialEq, Deserialize)]
-struct Human {
-    name: NonEmptyString,
-    age: u8,
-}
-
-fn main() -> anyhow::Result<()> {
+fn example_10() -> anyhow::Result<()> {
     let json = json! {{
         "name": "john",
         "age": 8
     }}
         .to_string();
 
-    let actual = serde_json::from_str::<Human>(&json)?;
+    let actual = serde_json::from_str::<Human2>(&json)?;
 
-    let expected = Human {
+    let expected = Human2 {
         name: NonEmptyString::new("john".to_string())?,
         age: 8,
     };
@@ -338,15 +319,46 @@ type TargetAgeRule = And<TargetAge18OrMore, TargetAge80OrLess>;
 ```
 
 # Iterator
+I have also prepared several useful refined types for Iterators.
+## `ForAll`
+`ForAll` is a rule that applies a specific rule to all elements in the Iterator.
+```rust
+fn example_11() -> anyhow::Result<()> {
+    let vec = vec!["Hello".to_string(), "World".to_string()];
+    let for_all_ok = ForAll::<NonEmptyStringRule, _>::new(vec.clone())?;
+    assert_eq!(vec, for_all_ok.into_value());
+    
+    let vec = vec!["Hello".to_string(), "".to_string()];
+    let for_all_err = ForAll::<NonEmptyStringRule, _>::new(vec.clone());
+    assert!(for_all_err.is_err());
+    Ok(())
+}
+```
 
+## `Exists`
+`Exists` is a rule that applies a specific rule to at least one element in the Iterator.
+```rust
+fn example_12() -> anyhow::Result<()> {
+    let vec = vec!["Hello".to_string(), "".to_string()];
+    let exists_ok = Exists::<NonEmptyStringRule, _>::new(vec.clone())?;
+    assert_eq!(vec, exists_ok.into_value());
+
+    let vec = vec!["".to_string(), "".to_string()];
+    let exists_err = Exists::<NonEmptyStringRule, _>::new(vec.clone());
+    assert!(exists_err.is_err());
+    Ok(())
+}
+```
+---
+## `into_iter()` and `iter()`
 The Iterator I’ve prepared has `into_iter` and `iter` implemented.
 Therefore, you can easily map or convert it to a different Iterator using `collect`.
 Feel free to explore the capabilities of the Iterator you’ve been given!
 
 ### `into_iter()`
 
 ```rust
-fn main() -> anyhow::Result<()> {
+fn example_11() -> anyhow::Result<()> {
     let ne_vec = NonEmptyVec::new(vec![1, 2, 3])?;
     let ne_vec: NonEmptyVec<i32> = ne_vec.into_iter().map(|n| n * 2).map(|n| n * 3).collect();
     assert_eq!(ne_vec.into_value(), vec![6, 12, 18]);
@@ -357,7 +369,7 @@ fn main() -> anyhow::Result<()> {
 ### `iter()`
 
 ```rust
-fn main() -> anyhow::Result<()> {
+fn example_12() -> anyhow::Result<()> {
     let ne_vec = NonEmptyVec::new(vec![1, 2, 3])?;
     let ne_vec: NonEmptyVec<i32> = ne_vec.iter().map(|n| n * 2).map(|n| n * 3).collect();
     assert_eq!(ne_vec.into_value(), vec![6, 12, 18]);
@@ -368,7 +380,7 @@ fn main() -> anyhow::Result<()> {
 ### `NonEmptyVec` to `NonEmptyVecDeque` using `collect()`
 
 ```rust
-fn main() -> anyhow::Result<()> {
+fn example_13() -> anyhow::Result<()> {
     let ne_vec = NonEmptyVec::new(vec![1, 2, 3])?;
     let ne_vec_deque: NonEmptyVecDeque<i32> = ne_vec.into_iter().collect();
     assert_eq!(ne_vec_deque.into_value(), vec![1, 2, 3]);
@@ -384,7 +396,7 @@ without downgrading the type level.
 ### NonEmptyString
 
 ```rust
-fn main() -> anyhow::Result<()> {
+fn example_14() -> anyhow::Result<()> {
     let non_empty_string_1 = NonEmptyString::new("Hello".to_string())?;
     let non_empty_string_2 = NonEmptyString::new("World".to_string())?;
     let non_empty_string = non_empty_string_1 + non_empty_string_2; // This is also `NonEmptyString` type
@@ -397,7 +409,7 @@ fn main() -> anyhow::Result<()> {
 ### NonEmptyVec
 
 ```rust
-fn main() -> anyhow::Result<()> {
+fn example_15() -> anyhow::Result<()> {
     let ne_vec_1 = NonEmptyVec::new(vec![1, 2, 3])?;
     let ne_vec_2 = NonEmptyVec::new(vec![4, 5, 6])?;
     let ne_vec = ne_vec_1 + ne_vec_2; // This is also `NonEmptyVec` type

src/refined.rs

@@ -3,6 +3,7 @@ use crate::rule::Rule;
 use serde::{Deserialize, Deserializer, Serialize, Serializer};
 use std::fmt::{Display, Formatter};
 use std::marker::PhantomData;
+use std::ops::Deref;
 
 /// Refined is a versatile type in ensuring that `T` satisfies the conditions of `RULE` (predicate type)
 /// # Example
@@ -58,18 +59,18 @@ impl<RULE, T> Refined<RULE>
 where
     RULE: Rule<Item = T>,
 {
-    pub fn new(value: T) -> Result<Self, Error<T>> {
+    pub fn new(value: T) -> Result<Self, Error> {
+        RULE::validate(&value).map_err(|e| Error::new(e.to_string()))?;
         Ok(Self {
-            value: RULE::validate(value)?,
+            value,
             _rule: Default::default(),
         })
     }
 
     pub fn unsafe_new(value: T) -> Self {
+        RULE::validate(&value).expect("initialization by `unsafe_new` failed");
         Self {
-            value: RULE::validate(value)
-                .ok()
-                .expect("initialization by `unsafe_new` failed"),
+            value,
             _rule: Default::default(),
         }
     }
@@ -93,6 +94,17 @@ where
     }
 }
 
+impl<RULE> Deref for Refined<RULE>
+where
+    RULE: Rule,
+{
+    type Target = RULE::Item;
+
+    fn deref(&self) -> &Self::Target {
+        &self.value
+    }
+}
+
 #[cfg(test)]
 mod test {
     use crate::refined::Refined;
@@ -115,7 +127,7 @@ mod test {
     }
 
     #[test]
-    fn test_refined_non_empty_string_ok() -> Result<(), Error<String>> {
+    fn test_refined_non_empty_string_ok() -> Result<(), Error> {
         let non_empty_string = Refined::<NonEmptyStringRule>::new("Hello".to_string())?;
         assert_eq!(non_empty_string.value, "Hello");
         Ok(())
@@ -129,7 +141,7 @@ mod test {
     }
 
     #[test]
-    fn test_refined_display() -> Result<(), Error<String>> {
+    fn test_refined_display() -> Result<(), Error> {
         let non_empty_string = Refined::<NonEmptyStringRule>::new("Hello".to_string())?;
         assert_eq!(format!("{}", non_empty_string), "Hello");
         Ok(())