Merge pull request #197 from greyblake/const

Const

Author: greyblake

CHANGELOG.md

@@ -1,6 +1,5 @@
 ### v0.x.x - 2025-xx-xx
-
-* Placeholder
+* **[FEATURE]** Ability to instantiate types in `const` context, when declared with `const_fn` flag.
 
 ### v0.5.1 - 2024-12-20
 

Cargo.lock

@@ -22,4 +22,5 @@ members = [
     "examples/string_arbitrary",
     "examples/any_generics",
     "examples/custom_error",
+    "examples/const_example",
 ]

Cargo.toml

@@ -21,6 +21,7 @@ Nutype is a proc macro that allows adding extra constraints like _sanitization_
 * [Quick start](#quick-start)
 * [Inner types](#inner-types) ([String](#string) | [Integer](#integer) | [Float](#float) | [Other](#other-inner-types-and-generics))
 * [Custom](#custom-sanitizers) ([sanitizers](#custom-sanitizers) | [validators](#custom-validators) | [errors](#custom-validation-with-a-custom-error-type))
+* [Constants](#constants)
 * [Recipes](#recipes)
 * [Breaking constraints with new_unchecked](#breaking-constraints-with-new_unchecked)
 * [Feature Flags](#feature-flags)
@@ -345,6 +346,46 @@ struct Name(String);
 
 It's important to ensure that the type specified in the `error` attribute matches the error type returned by the validation function.
 
+## Constants
+
+You can mark a type with the `const_fn` flag. In that case, its `new` and `try_new` functions will be declared as `const`:
+
+```rust
+#[nutype(
+    const_fn,
+    derive(Debug),
+    validate(greater_or_equal = -273.15),
+)]
+pub struct Celsius(f64);
+```
+
+Since `Result::unwrap()` is not allowed in `const` contexts, we must manually handle the `Result` when creating constants. Any attempt to instantiate an invalid `Celsius` at compile time will trigger a compilation error:
+
+```rust
+const FREEZING_POINT: Celsius = match Celsius::try_new(0.0) {
+    Ok(value) => value,
+    Err(_) => panic!("Invalid value"),
+};
+```
+
+Alternatively, you can use a helper macro like this:
+
+```rust
+macro_rules! nutype_const {
+    ($name:ident, $ty:ty, $value:expr) => {
+        const $name: $ty = match <$ty>::try_new($value) {
+            Ok(value) => value,
+            Err(_) => panic!("Invalid value"),
+        };
+    };
+}
+
+nutype_const!(WATER_BOILING_POINT, Celsius, 100.0);
+```
+
+Note that `const` works only for stack allocated types.
+If you are dealing with a heap allocated type (e.g. `String`) you should consider using `static` with [`LazyLock`](https://doc.rust-lang.org/beta/std/sync/struct.LazyLock.html).
+
 ## Recipes
 
 ### Derive `Default`

README.md

@@ -1,35 +1,23 @@
 use nutype::nutype;
 
-fn validate_name(name: &str) -> Result<(), NameError> {
-    if name.len() < 3 {
-        Err(NameError::TooShort)
-    } else if name.len() > 10 {
-        Err(NameError::TooLong)
-    } else {
-        Ok(())
-    }
-}
-
-#[derive(Debug, PartialEq)]
-enum NameError {
-    TooShort,
-    TooLong,
-}
-
 #[nutype(
-    validate(with = validate_name, error = NameError),
-    derive(Debug, AsRef, PartialEq),
+    const_fn,
+    derive(Debug),
+    validate(greater_or_equal = -273.15),
 )]
-struct Name(String);
+pub struct Celsius(f64);
 
-fn main() {
-    let name = Name::try_new("John").unwrap();
-    assert_eq!(name.as_ref(), "John");
+macro_rules! nutype_const {
+    ($name:ident, $ty:ty, $value:expr) => {
+        const $name: $ty = match <$ty>::try_new($value) {
+            Ok(value) => value,
+            Err(_) => panic!("Invalid value"),
+        };
+    };
+}
 
-    assert_eq!(
-        Name::try_new("JohnJohnJohnJohnJohn"),
-        Err(NameError::TooLong)
-    );
+nutype_const!(WATER_BOILING_POINT, Celsius, 100.0);
 
-    assert_eq!(Name::try_new("Jo"), Err(NameError::TooShort));
+fn main() {
+    println!("{:?}", WATER_BOILING_POINT);
 }

dummy/src/main.rs

@@ -0,0 +1,7 @@
+[package]
+name = "const_example"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+nutype = { path = "../../nutype", features = ["new_unchecked"] }

examples/const_example/Cargo.toml

@@ -0,0 +1,52 @@
+// Adding `const_fn` flag to #[nutype] macro will make the generated `new` and `try_new` functions
+// be marked with `const` keyword.
+use nutype::nutype;
+
+#[nutype(const_fn, validate(greater_or_equal = 18))]
+pub struct Age(u8);
+
+// Unfortunately `Result::unwrap` is not a `const` function, so we have
+// to unwrap it ourselves.
+const DRINKING_AGE: Age = match Age::try_new(21) {
+    Ok(age) => age,
+    Err(_) => panic!("Invalid Age"),
+};
+
+// Until `const` functions are stabilized, we recommend to  define in application
+// and reuse `nutype_const!` macro to create constants from `nutype` types
+#[nutype(
+    const_fn,
+    validate(greater_or_equal = -1.0, less_or_equal = 1.0)
+)]
+struct Correlation(f32);
+
+macro_rules! nutype_const {
+    ($name:ident, $ty:ty, $value:expr) => {
+        const $name: $ty = match <$ty>::try_new($value) {
+            Ok(value) => value,
+            Err(_) => panic!("Invalid value"),
+        };
+    };
+}
+
+nutype_const!(MAX_CORRELATION, Correlation, 1.0);
+
+// Not recommended, but it's possible to use `new_unchecked` with `const_fn` flag.
+#[nutype(
+    const_fn,
+    new_unchecked,
+    validate(greater_or_equal = 1, less_or_equal = 6,)
+)]
+struct TaxClass(u8);
+
+const DEFAULT_TAX_CLASS: TaxClass = unsafe { TaxClass::new_unchecked(1) };
+
+// Note: `into_inner()` is const function as well.
+nutype_const!(DOUBLE_AGE, Age, DRINKING_AGE.into_inner() * 2);
+
+fn main() {
+    assert_eq!(DRINKING_AGE.into_inner(), 21);
+    assert_eq!(DEFAULT_TAX_CLASS.into_inner(), 1);
+    assert_eq!(MAX_CORRELATION.into_inner(), 1.0);
+    assert_eq!(DOUBLE_AGE.into_inner(), 42);
+}

examples/const_example/src/main.rs

@@ -396,6 +396,49 @@
 //!
 //! It's important to ensure that the type specified in the `error` attribute matches the error type returned by the validation function.
 //!
+//!
+//! ## Constants
+//!
+//! You can mark a type with the `const_fn` flag. In that case, its `new` and `try_new` functions will be declared as `const`:
+//!
+//! ```
+//! use nutype::nutype;
+//!
+//! #[nutype(
+//!     const_fn,
+//!     derive(Debug),
+//!     validate(greater_or_equal = -273.15),
+//! )]
+//! pub struct Celsius(f64);
+//!
+//! // Since `Result::unwrap()` is not allowed in `const` contexts,
+//! // we must manually handle the `Result` when creating constants.
+//! // Any attempt to instantiate an invalid `Celsius` at compile time
+//! // will trigger a compilation error:
+//! const FREEZING_POINT: Celsius = match Celsius::try_new(0.0) {
+//!     Ok(value) => value,
+//!     Err(_) => panic!("Invalid value"),
+//! };
+//!
+//! assert_eq!(FREEZING_POINT.into_inner(), 0.0);
+//!
+//! // Alternatively, you can use a helper macro like this:
+//! macro_rules! nutype_const {
+//!     ($name:ident, $ty:ty, $value:expr) => {
+//!         const $name: $ty = match <$ty>::try_new($value) {
+//!             Ok(value) => value,
+//!             Err(_) => panic!("Invalid value"),
+//!         };
+//!     };
+//! }
+//!
+//! nutype_const!(WATER_BOILING_POINT, Celsius, 100.0);
+//!
+//! assert_eq!(WATER_BOILING_POINT.into_inner(), 100.0);
+//! ```
+//! Note that `const` works only for stack allocated types.
+//! If you are dealing with a heap allocated type (e.g. `String`) you should consider using `static` with [`LazyLock`](https://doc.rust-lang.org/beta/std/sync/struct.LazyLock.html).
+//!
 //! ## Recipes
 //!
 //! ### Derive `Default`

nutype/src/lib.rs

@@ -11,7 +11,7 @@ use crate::common::{
     gen::{
         tests::gen_test_should_have_valid_default_value, traits::GeneratedTraits, GenerateNewtype,
     },
-    models::{ErrorTypePath, Guard, TypeName, TypedCustomFunction},
+    models::{ConstFn, ErrorTypePath, Guard, TypeName, TypedCustomFunction},
 };
 
 use self::error::gen_validation_error_type;
@@ -32,6 +32,7 @@ impl GenerateNewtype for AnyNewtype {
     fn gen_fn_sanitize(
         inner_type: &Self::InnerType,
         sanitizers: &[Self::Sanitizer],
+        const_fn: ConstFn,
     ) -> TokenStream {
         let transformations: TokenStream = sanitizers
             .iter()
@@ -52,7 +53,7 @@ impl GenerateNewtype for AnyNewtype {
             .collect();
 
         quote!(
-            fn __sanitize__(mut value: #inner_type) -> #inner_type {
+            #const_fn fn __sanitize__(mut value: #inner_type) -> #inner_type {
                 #transformations
                 value
             }
@@ -63,6 +64,7 @@ impl GenerateNewtype for AnyNewtype {
         inner_type: &Self::InnerType,
         error_type_path: &ErrorTypePath,
         validators: &[Self::Validator],
+        const_fn: ConstFn,
     ) -> TokenStream {
         let validations: TokenStream = validators
             .iter()
@@ -98,7 +100,7 @@ impl GenerateNewtype for AnyNewtype {
             // Since this code is generic which is used for different inner types (not only Cow), we cannot easily fix it to make
             // clippy happy.
             #[allow(clippy::ptr_arg)]
-            fn __validate__<'nutype_a>(val: &'nutype_a #inner_type) -> ::core::result::Result<(), #error_type_path> {
+            #const_fn fn __validate__<'nutype_a>(val: &'nutype_a #inner_type) -> ::core::result::Result<(), #error_type_path> {
                 #validations
                 Ok(())
             }

nutype_macros/src/any/gen/mod.rs

@@ -26,6 +26,7 @@ pub fn parse_attributes(
         sanitizers,
         validation,
         new_unchecked,
+        const_fn,
         default,
         derive_traits,
     } = attrs;
@@ -36,6 +37,7 @@ pub fn parse_attributes(
     let guard = validate_any_guard(raw_guard, type_name)?;
     Ok(Attributes {
         new_unchecked,
+        const_fn,
         guard,
         default,
         derive_traits,