🪪 id_newtype

Implements logic for a Cow<'static, str> newtype where only [A-Za-z0-9_] are valid characters.

Implementations are provided for:

• IdType::new
• IdType::new_unchecked (with #[doc(hidden)])
• IdType::is_valid_id
• IdType::into_inner
• std::borrow::Borrow<str>
• std::convert::AsRef<str>
• std::convert::TryFrom<String>
• std::convert::TryFrom<&'static str>
• std::fmt::Display
• std::ops::Deref
• std::ops::DerefMut
• std::str::FromStr

A separate error type is also generated, which indicates an invalid value when the ID type is instantiated with new.

Usage

In Cargo.toml:

id_newtype = "0.3.0" # or
id_newtype = { version = "0.3.0", features = ["macros"] }

In code:

// in lib.rs
#[macro_use]
extern crate id_newtype;

// in your ID module, e.g. `my_id.rs`
use std::borrow::Cow;

// Rename your ID type
#[derive(Clone, Debug, Hash, PartialEq, Eq)]
pub struct MyId(Cow<'static, str>);

id_newtype::id_newtype!(
    MyId,           // Name of the ID type
    MyIdInvalidFmt  // Name of the invalid value error
);

If you have a procedural macro that checks for ID validity¹ at compile time, you may pass in its name as follows:

#[macro_use]
extern crate id_newtype;

use std::borrow::Cow;

// Either use `id_newtype::id`, or replace this with your own proc macro.
use id_newtype::id;
// use my_crate_static_check_macros::my_id;

// Rename your ID type
#[derive(Clone, Debug, Hash, PartialEq, Eq)]
pub struct MyId(Cow<'static, str>);

id_newtype::id_newtype!(
    MyId,           // Name of the ID type
    MyIdInvalidFmt, // Name of the invalid value error
    my_id           // Name of the proc macro
);

Finally, if you pass in a lifetime parameter (4th param) to the macro, the generated type can hold borrowed data:

#[macro_use]
extern crate id_newtype;

use std::borrow::Cow;

// Either use `id_newtype::id`, or replace this with your own proc macro.
use id_newtype::id;
// use my_crate_static_check_macros::my_id;

// Rename your ID type
#[derive(Clone, Debug, Hash, PartialEq, Eq)]
pub struct MyId<'id>(Cow<'id, str>);

id_newtype::id_newtype!(
    MyId,           // Name of the ID type
    MyIdInvalidFmt, // Name of the invalid value error
    my_id           // Name of the proc macro
    'id             // Lifetime parameter
);

Features

• "macros" This feature enables the id! compile-time checked proc macro for safe construction of IDs at compile time.

  # #[cfg(feature = "my_feature")]
  # {
  #[macro_use]
  extern crate id_newtype;
  use id_newtype::id;
  
  // Define a new ID type
  #[derive(Clone, Debug, Hash, PartialEq, Eq)]
  pub struct MyId(Cow<'static, str>);
  id_newtype::id_newtype!(MyId, MyIdInvalidFmt, id);
  
  // ok!
  let id = id!("my_id");
  
  // `id` is not a valid `Id`
  // `Id`s must begin with a letter or underscore, and contain only
  // letters, numbers, or underscores.
  let id = id!("invalid id");
  # }
  

License

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Contribution

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.