Improve and strengthen your strings
Strongly-typed APIs reduce errors and confusion over passing around un-typed strings. Braid helps in that endeavor by making it painless to create wrappers around your string values, ensuring that you use them in the right way every time.
Examples of the documentation and implementations provided for braids are available
below and in the [aliri_braid_examples] crate documentation.
A braid is created by attaching #[braid] to a struct definition. The macro will take
care of automatically updating the representation of the struct to wrap a string and
generate the borrowed form of the strong type.
```rust use aliri_braid::braid;
pub struct DatabaseName; ```
Braids of custom string types are also supported, so long as they implement a set of
expected traits. If not specified, the type named String in the current namespace
will be used. See the section on [custom string types] for more information.
```rust use aliri_braid::braid; use smartstring::alias::String;
pub struct UserId; ```
Once created, braids can be passed around as strongly-typed, immutable strings.
```rust fn takestrongstring(n: DatabaseName) {} fn borrowstrongstring(n: &DatabaseNameRef) {}
let owned = DatabaseName::new(String::from("mongo")); borrowstrongstring(&owned); takestrongstring(owned); ```
A braid can also be untyped for use in stringly-typed interfaces.
```rust fn takerawstring(s: String) {} fn borrowrawstr(s: &str) {}
let owned = DatabaseName::new(String::from("mongo")); borrowrawstr(owned.asstr()); takeraw_string(owned.take()); ```
By default, the name of the borrowed form will be the same as the owned form
with Ref appended to the end.
```rust
pub struct DatabaseName;
let owned = DatabaseName::fromstatic("mongo"); let borrowed = DatabaseNameRef::fromstatic("mongo"); ```
If the name ends with Buf, however, then the borrowed form will drop the Buf, similar
to the relationship between
PathBuf and Path.
```rust
pub struct DatabaseNameBuf;
let owned = DatabaseNameBuf::fromstatic("mongo"); let borrowed = DatabaseName::fromstatic("mongo"); ```
If a different name is desired, this behavior can be
overridden by specifying the name of the reference type to create using the ref
parameter.
```rust
pub struct DatabaseNameBuf;
let owned = DatabaseNameBuf::fromstatic("mongo"); let borrowed = TempDb::fromstatic("mongo"); let toowned: DatabaseNameBuf = borrowed.toowned(); ```
A default doc comment is added to the borrowed form that refers back to the owned form.
If a custom doc comment is desired, the ref_doc parameter allows supplying custom
documentation.
```rust
pub struct DatabaseName; ```
Attributes added to the braid will be applied to both the owned and borrowed forms
with the exception of /// and #[doc = ""] attributes. To add an attribute to
only the owned form, use the owned_attr parameter. Similarly, use ref_attr to
add an attribute to only the borrowed form.
```rust use aliri_braid::braid;
ownedattr(mustuse = "database name should always be used"), refattr(mustuse = "created a reference, but never used it"), )]
pub struct DatabaseName; ```
The types created by the braid macro are placed in the same module where declared.
This means additional functionality, including mutations, can be implemented easily.
As a basic example, here is a type built to hold Amazon ARNs. The type has been extended to support some mutation and introspection.
```rust
pub struct AmazonArnBuf;
impl AmazonArnBuf { /// Append an ARN segment pub fn addsegment(&mut self, segment: &str) { self.0.pushstr(":"); self.0.push_str(segment); } }
impl AmazonArn {
/// Returns an iterator of all ARN segments
pub fn get_segments(&self) -> std::str::Split
/// Returns the service segment of the ARN
pub fn get_service(&self) -> &str {
self.get_segments().nth(2).unwrap_or("")
}
} ```
Because code within the same module where the braid is defined are allowed to access the internal value, you can use a module in order to more strictly enforce encapsulation and limit accessibility that might otherwise violate established invariants. This may be particularly desired when the wrapped type requires validation.
```rust mod amazonarn { #[aliribraid::braid] pub struct AmazonArnBuf;
/* Additional impls that need access to the inner values */
}
pub use amazon_arn::{AmazonArnBuf, AmazonArn};
let x = AmazonArnBuf::fromstatic("arn:aws:iam::123456789012:user/Development"); asserteq!("iam", x.get_service()); ```
This crate ensures that the from_str implementation provided for wrapping
borrowed str slices does not extend lifetimes.
In the example below, we verify that the borrowed DatabaseNameRef is unable
to escape the lifetime of data. The following code snippet will fail to
compile, because data will go out of scope and be dropped at the end of
the block creating ex_ref.
``compile_fail
let ex_ref = {
let data = DatabaseName::new("test string");
DatabaseNameRef::from_str(data.as_str())
}; //data` is dropped at this point
// Which means that ex_ref would be invalid if allowed.
println!("{}", ex_ref);
```
Types can be configured to only contain certain values. This can be used to strongly enforce domain type boundaries, thus making invalid values unrepresentable.
For example, if you wanted to have a username type that did not accept the root user,
you have a few options:
root at known entry points.Braided strings give the strongest, third guarantee. The other two methods require constant
vigilance to ensure that an unexpected root value doesn't sneak in through other backdoors.
By default, Rust's module system allows items within the same module to have access to each other's non-public members. If not handled properly, this can lead to unintentionally violating invariants. Thus, for the strongest guarantees, it is recommended to use the module system to further control access to the interior values held by the braided type as described in the section on encapsulation.
As a convenience, from_static functions are provided that accept &'static str. For fallible
braids and the owned form of normalized braids, this function will panic if the value is not
valid. For borrowed form of normalized braids, the function will panic if the value is not
normalized.
```rust
pub struct InvalidUsername; // Error implementation elided
pub struct NonRootUsername;
impl aliribraid::Validator for NonRootUsername { type Error = InvalidUsername; fn validate(s: &str) -> Result<(), Self::Error> { if s.isempty() || s.eqignoreascii_case("root") { Err(InvalidUsername) } else { Ok(()) } } }
assert!(NonRootUsername::new("".tostring()).iserr()); assert!(NonRootUsername::new("root".tostring()).iserr()); assert!(NonRootUsername::new("nobody".tostring()).isok());
NonRootUsername::from_static("nobody");
assert!(NonRootUsernameRef::fromstr("").iserr()); assert!(NonRootUsernameRef::fromstr("root").iserr()); assert!(NonRootUsernameRef::fromstr("nobody").isok());
NonRootUsernameRef::from_static("nobody"); ```
Foreign validators can also be used by specifying the name of the type that implements the validation logic.
```rust
pub struct NonRootUsername;
pub struct UsernameValidator;
impl aliri_braid::Validator for UsernameValidator { /* … */ }
assert!(NonRootUsername::new("".tostring()).iserr()); assert!(NonRootUsername::new("root".tostring()).iserr()); assert!(NonRootUsername::new("nobody".tostring()).isok());
NonRootUsername::from_static("nobody");
assert!(NonRootUsernameRef::fromstr("").iserr()); assert!(NonRootUsernameRef::fromstr("root").iserr()); assert!(NonRootUsernameRef::fromstr("nobody").isok());
NonRootUsernameRef::from_static("nobody"); ```
Braided strings can also have enforced normalization, which is carried out at the creation
boundary. In this case, the .from_str() function on the borrowed form will return a
Cow<Borrowed>, which can be inspected to determine whether
normalization and conversion to an owned value was required. In cases where the incoming
value is expected to already be normalized, the .from_normalized_str() function can
be used. This function will return an error if the value required normalization.
Note that when implementing Validator for a braided type, the validate method
must ensure that the value is already in normalized form and return an error if it is
not.
When using serde to deserialze directly to the borrowed form, care must be taken, as
only already normalized values will be able to be deserialized. If normalization is
expected, deserialize into the owned form or Cow<Borrowed>.
Here is a toy example where the value must not be empty and must be composed of ASCII characters, but that is also normalized to use lowercase ASCII letters.
```rust use std::borrow::Cow;
pub struct InvalidHeaderName; // Error implementation elided
pub struct HeaderName;
impl aliribraid::Validator for HeaderName { type Error = InvalidHeaderName; fn validate(s: &str) -> Result<(), Self::Error> { if s.isempty() || !s.isascii() || s.asbytes().iter().any(|&b| b'A' <= b && b <= b'Z') { Err(InvalidHeaderName) } else { Ok(()) } } }
impl aliribraid::Normalizer for HeaderName {
fn normalize(s: &str) -> Result
assert!(HeaderName::new("".tostring()).iserr()); asserteq!("mixedcase", HeaderName::new("MixedCase".tostring()).unwrap().asstr()); asserteq!("lowercase", HeaderName::new("lowercase".tostring()).unwrap().asstr());
asserteq!("mixedcase", HeaderName::fromstatic("MixedCase").asstr()); asserteq!("lowercase", HeaderName::fromstatic("lowercase").asstr());
assert!(HeaderNameRef::fromstr("").iserr()); asserteq!("mixedcase", HeaderNameRef::fromstr("MixedCase").unwrap().asstr()); asserteq!("lowercase", HeaderNameRef::fromstr("lowercase").unwrap().asstr());
assert!(HeaderNameRef::fromnormalizedstr("").iserr()); assert!(HeaderNameRef::fromnormalizedstr("MixedCase").iserr()); asserteq!("lowercase", HeaderNameRef::fromnormalizedstr("lowercase").unwrap().asstr());
asserteq!("lowercase", HeaderNameRef::fromstatic("lowercase").as_str()); ```
Where necessary for efficiency, it is possible to bypass the validations on creation through
the use of the .new_unchecked() or from_str_unchecked() functions. These functions are
marked as unsafe, as they require the caller to assert that they are fulfilling the
implicit contract that the value be both valid and in normal form. If either of these
constraints are violated, undefined behavior could result when downstream consumers depend
on these constraints being upheld.
compile_fail
NonRootUsername::new_unchecked("");
NonRootUsernameRef::from_str_unchecked("nobody");
If you find violations of your guarantees, you can look specifically for uses of unsafe.
rust
unsafe {
NonRootUsername::new_unchecked(String::from(""));
NonRootUsernameRef::from_str_unchecked("root");
}
By default, the following traits will be automatically implemented.
For the Owned type
* [std::clone::Clone]
* [std::fmt::Debug]
* [std::fmt::Display]
* [std::hash::Hash]
* [std::cmp::Eq]
* [std::cmp::Ord]
* [std::cmp::PartialEq<Owned>]
* [std::cmp::PartialEq<Borrowed>]
* [std::cmp::PartialEq<&Borrowed>]
* [std::cmp::PartialEq<Box<Borrowed>>]
* [std::cmp::PartialOrd]
* [std::convert::AsRef<Borrowed>]
* [std::convert::AsRef<str>]
* [std::convert::From<&Borrowed>]
* [std::convert::From<Box<Borrowed>>]
* [std::convert::From<Cow<Borrowed>>]
* [std::borrow::Borrow<Borrowed>]
* [std::str::FromStr]
* [std::ops::Deref] where Target = Borrowed
Additionally, unvalidated owned types implement
* [std::convert::From<String>]
* [std::convert::From<&str>]
Validated and normalized owned types will instead implement
* [std::convert::TryFrom<String>]
* [std::convert::TryFrom<&str>]
When normalized, the above conversions will normalize values.
For the Borrowed type
* [std::fmt::Debug]
* [std::fmt::Display]
* [std::hash::Hash]
* [std::cmp::Eq]
* [std::cmp::Ord]
* [std::cmp::PartialEq<Owned>]
* [std::cmp::PartialEq<Borrowed>]
* [std::cmp::PartialEq<&Borrowed>]
* [std::cmp::PartialEq<Box<Borrowed>>]
* [std::cmp::PartialOrd]
* [std::convert::From<&Cow<Borrowed>>]
* [std::borrow::ToOwned] where Owned = Owned
Additionally, unvalidated borrowed types implement
* [std::convert::From<&str>]
Validated and normalize borrowed types will instead implement
* [std::convert::TryFrom<&str>]
For Cow<'static, Borrowed>
* [std::convert::From<Owned>]
For Cow<Borrowed>
* [std::convert::From<&Borrowed>]
For Box<Borrowed>
* [std::convert::From<Owned>]
The above conversion will fail if the value is not already normalized.
Types that are not normalized will additionally implement
* [std::borrow::Borrow<str>]
Borrow<str> cannot be implemented for normalized braids because equality and hashing
of equivalent braid values will have differing results for equality, which violates the
contract implied by the Borrow trait.
Deref to a str is explicitly not implemented. This means that an explicit call is
required to treat a value as an untyped string, whether .as_str(), .to_string(), or
.into_string()
CloneFor some types, it may be desirable to prevent arbitrary cloning of a type. In that case,
the clone parameter can be used to prevent automatically deriving Clone.
```rust
pub struct Sensitive;
assertnotimpl_any!(Sensitive: Clone); ```
Display, Debug, and PartialOrd/Ord implementationsBy default, the implementations of Display, Debug
PartialOrd, and Ord
provided by a braid delegate directly to the underlying String or str types. If a
custom implementation is desired, the automatic derivation of these traits can be controlled
by the display, debug, and ord parameters. Both of these parameters accept one of
impl, owned, or omit. By default, the impl derivation mode is used.
The modes have the following effects:
impl: Format the owned and reference type transparently as the underlying string (slice) type.owned: Automatically provide an owned implementation that transparently delegates to the
implementation of the borrowed form. The consumer must provide their custom implementation on
the borrowed form.omit: No implementations are provided for the owned or borrowed forms. These must be
implemented by the consumer if they are desired.Note: Omitting a PartialOrd and Ord implementation will make the braid unable to be
used as a key in a BTreeMap or BTreeSet.
As an example:
```rust use std::fmt;
pub struct Sensitive;
impl fmt::Debug for SensitiveRef { fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { f.write_str("SENSITIVE") } }
impl fmt::Display for SensitiveRef { fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { f.write_str("SENSITIVE DISPLAY") } }
let owned = Sensitive::fromstatic("secret value"); asserteq!("SENSITIVE", format!("{:?}", owned)); asserteq!("SENSITIVE DISPLAY", format!("{}", owned)); asserteq!("secret value", owned.as_str());
let borrowed: &SensitiveRef = &owned; asserteq!("SENSITIVE", format!("{:?}", borrowed)); asserteq!("SENSITIVE DISPLAY", format!("{}", borrowed)); asserteq!("secret value", borrowed.asstr()); ```
[Serialize] and [Deserialize] implementations from the [serde] crate
can be automatically generated by including serde in the argument list for the macro.
```rust
pub struct Username;
let username = Username::fromstatic("root"); let json = serdejson::tostring(&username).unwrap(); let newusername: Username = serdejson::fromstr(&json).unwrap(); ```
Such automatic implementations will also properly handle string values that require validation. This automatic validation has the benefit of easing use with Serde while still protecting the integrity of the type.
```rust
pub struct InvalidUsername; // Error implementation elided
pub struct Username;
impl aliribraid::Validator for Username { type Error = InvalidUsername; fn validate(s: &str) -> Result<(), Self::Error> { if s.isempty() || s.eqignoreascii_case("root") { Err(InvalidUsername) } else { Ok(()) } } }
assert!(serdejson::fromstr::
assert!(serdejson::fromstr::<&UsernameRef>("\"\"").iserr()); assert!(serdejson::fromstr::<&UsernameRef>("\"root\"").iserr()); assert!(serdejson::fromstr::<&UsernameRef>("\"nobody\"").is_ok()); ```
The braid macro can be used to define a custom string type that wraps types
other than the standard String. This allows defining a braid that is backed
by a type that offers small-string optimizations, such as [SmartString].
```rust use smartstring::{SmartString, LazyCompact};
pub struct UserId(SmartString
It can also be used to wrap a [ByteString], which is a string backed by
[Bytes], which may be useful if the type is primarily used in contexts
where a zero-copy implementation is preferred.
```rust use bytestring::ByteString;
pub struct ZeroCopyIdentifier(ByteString); ```
In order to be used as a custom string type, the type must implement the following traits:
std::clone::Clone] (unless clone is omit)std::fmt::Debug] (unless debug is omit)std::fmt::Display] (unless display is omit)std::cmp::Eq]std::cmp::PartialEq]std::hash::Hash]std::cmp::Ord] (unless ord is omit)std::cmp::PartialOrd] (unless ord is omit)serde::Serialize] (unless serde is omit)serde::Deserialize] (unless serde is omit)std::convert::From<&str>]std::convert::From<Box<str>>]std::convert::AsRef<str>]std::convert::Into<String>]no_std supportBraids can be implemented in no_std environments with alloc. By adding the
no_std parameter to the macro, all impls will reference the core or alloc
crates instead of the std crate, as appropriate.
```rust extern crate alloc;
use aliri_braid::braid; use alloc::string::String;
pub struct NoStdLibWrapper; ```
In environments without an allocator, braid_ref can be used to create a
reference-only braid. In order to remove the alloc dependency in aliri_braid,
specify default-features = "false" in the Cargo.toml file.
```rust use aliribraid::braidref;
pub struct NoStdValue; ```
Braid uses limited unsafe in order to be able to reinterpret string slices
(&str) as the borrowed form. Because this functionality is provided as a
macro, using the #![forbid(unsafe_code)] lint level on a crate that generates
braids will result in compiler errors. Instead, the crate can be annotated with
#![deny(unsafe_code)], which allows for overrides as appropriate. The functions
that require unsafe to work correctly are annotated with #[allow(unsafe_code)],
and all usages of unsafe that the macro generates are annotated with SAFETY
code comments.
If strict adherence to forbid unsafe code is required, then the types can be segregated into an accessory crate without the prohibition, and then consumed safely from crates that otherwise forbid unsafe code.