Crate string_types

Defines a set of special string types that simplify validation. The string types chosen have characteristics that would be useful for basic validation of inputs and/or serve as the basis for more specific validations. The last two are more specific, but occur often enough in some programming problems to be worth including.

• 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
• IdentifierStr - cannot be empty, starts with a letter or underscore, the rest are alphanumeric or underscore.
• 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

The StringTypes included by the book_ids and card_ids features are not nearly as commonly useful as the default set, but are interesting enough to be good examples of how you might create StringTypes that extend the basic examples to do cover more interesting string types.

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

CreditCard

A StringType that defines most credit card strings. Guaranteed to be only digits, within a certain length, and that the check digit is correct.

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

IdentifierStr

Isbn10

String containing a 10-character ISBN code.

Isbn13

String containing a 13-character ISBN code.

Lccn

String representing a Library of Congress Control Number

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

CCParseError

ParseError

Enumeration specifying likely parsing errors for different string types.

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