Crate string_types

Defines a set of special string types that simplify validation.

• NonEmptyString - cannot be empty
• TrimmedString - string guaranteed to not have whitespace before or after the string
• TrimmedNonBlankString - cannot be empty or contain only whitespace, with both sides trimmed
• NonBlankString - cannot be empty or contain only whitespace, without trimming
• DigitString - cannot be empty and only contains ASCII digits
• NumericString - cannot be empty and only contains Unicode numeric characters
• HexString - cannot be empty, only contains hexadecimal digits, has an even length
• LowerHexString - cannot be empty, only contains lowercase hexadecimal digits, has an even length
• UpperHexString - cannot be empty, only contains uppercase hexadecimal digits, has an even length
• UnixUsername - cannot be empty, matches definition enforced by useradd.

There are three features supported by this crate.

• The serde feature adds [Serialize] and [Deserialize] support to the defined StringTypes
• The book_ids feature defines [Isbn10], [Isbn13], and [Lccn].
• The card_ids feature defines [CreditCard]

StringTypes are expected to be defined as a tuple struct with a single field. This field should be either a String or another StringType in order to work seamlessly. To simplify creating StringTypes, we make the following macros public in the macros module.

• string_type is an attribute macro that implements the StringType trait and appropriate From<T> traits for the tuple struct it is applied to. It also derives some standard traits: Debug, Clone, Hash, Eq, Ord, PartialEq, and PartialOrd.
• Display is a derive macro that implements the Display trait in a pretty obvious way.
• FromStr is a derive macro that implements the FromStr trait using ensure_valid.

Trait Reasoning

Any StringTypes implement a number of traits, automatically (if you use the macros). You might wonder why so many, despite the fact that we don’t implement all of the String interface.

• StringType - obvious
• EnsureValid - define the validation interface
• From<S> for String - Easy conversion of the StringType to raw String
• From<S> for StrType::Inner - Easy conversion to inner type, unless it’s a String
• Display - for formatted printing
• FromStr - for parsing a string slice into the StringType
• Debug - debug printing
• Clone - easily make a copy
• Hash - make the StringType hashable
• Eq and PartialEq - easy comparison of two objects of the same StringType
• Ord and PartialOrd - easy ordering of two objects of the same StringType

Much of the rest of the String interface is designed for changing the String. Most of those features would violate the guarantees of most StringTypes. If you need to manipulate the value of the StringType, you can either convert to String or grab the string slice with as_str. You can then read or manipulate the raw string. When you are finished, parse it back into the StringType, which reasserts the guarantees.

Structs

DigitString

String guaranteed to have at least one character, and all characters are ASCII digits

HexString

String guaranteed to have at least two characters, and all characters are hexadecimal digits

LowerHexString

String guaranteed to have at least two characters, and all characters are lowercase hexadecimal digits

NonBlankString

String guaranteed to have at least one non-whitespace character

NonEmptyString

String guaranteed to have at least one character

NumericString

String guaranteed to have at least one character, and all characters are Unicode numeric characters

TrimmedNonBlankString

String guaranteed to have at least one non-whitespace character

TrimmedString

String guaranteed to have at least one non-whitespace character, and no leading/trailing whitespace

UnixUsername

String guaranteed to have 1-32 characters that are lowercase alphanumeric, ‘’, or ‘-’. The first character is guaranteed to be lowercase letter or ‘’. For historical reasons, the final character is allowed to be a ‘$’.

UpperHexString

String guaranteed to have at least two characters, and all characters are uppercase hexadecimal digits

Enums

ParseError

Enumeration specifying likely parsing errors for different string types.

UsernameError

Traits

EnsureValid

The EnsureValid trait defines a method for checking the input string to ensure that it passes any validation checks. The method will not perform any modification of the supplied string slice, it just does validation.

StringType

The StringType trait defines the public interface for the StringType new types.

Attribute Macros

string_type

Expose the macros that simplify creating string types Generate the base implementations for a StringType including the StringType trait and the appropriate From<T> implementations.

Derive Macros

Display

Expose the macros that simplify creating string types Implement Derive macro for Display implementation

FromStr

Expose the macros that simplify creating string types Implement Derive macro for FromStr implementation Handles two variations: inner String and inner other-type