Struct fog_pack::validator::StrValidator

pub struct StrValidator {
    pub comment: String,
    pub in_list: Vec<String>,
    pub nin_list: Vec<String>,
    pub matches: Option<Box<Regex>>,
    pub max_len: u32,
    pub min_len: u32,
    pub max_char: u32,
    pub min_char: u32,
    pub normalize: Normalize,
    pub query: bool,
    pub regex: bool,
    pub size: bool,
}

Validator for UTF-8 strings.

This validator type will only pass string values. Validation passes if:

• The value’s length in bytes is less than or equal to the value in max_len.
• The value’s length in bytes is greater than or equal to the value in min_len.
• The value’s number of unicode characters is less than or equal to the value in max_char.
• The value’s number of unicode characters is greater than or equal to the value in min_char.
• If a regular expression is present in matches, the possibly-normalized value must match against the expression.
• If the in list is not empty, the possibly-normalized value must be among the values in the list.
• The possibly-normalized value must not be among the values in the nin list.

The normalize field may be set to None, NFC, or NFKC, corresponding to Unicode normalization forms. When checked for in, nin, and matches, the value is first put into the selected normalization form, and any in and nin list strings are normalized as well.

Defaults

Fields that aren’t specified for the validator use their defaults instead. The defaults for each field are:

• comment: “”
• in_list: empty
• nin_list: empty
• matches: None
• max_len: u32::MAX
• min_len: 0
• max_char: u32::MAX
• min_char: 0
• normalize: Normalize::None
• query: false
• regex: false
• size: false

Regular Expressions

Regular expressions can be set for StrValidator using the matches field, but should be used sparingly, and should generally be avoided if possible. If they must be used, be aware of their limitations due to their memory, computation, and general consistency issues.

Regular expression can rapidly use up a lot of memory when compiled. This is one of the reasons why it is inadvisable to accept and use unknown schemas. For queries, a schema will have some upper limit on the number of allowed regular expressions, in order to mitigate possible memory exhaustion.

Beyond their memory cost, regular expressions have a second problem: there’s not really a universal standard for regular expressions; at least, not one that is rigidly followed in implementations. The Rust fog-pack library uses the regex crate for regular expressions, supporting Perl-style expression syntax, unicode character classes, and flags for unicode support and case insensitivity. Look around and backreferences are not supported. It is hoped that other implementations will support the same syntax, with the same limitations on look around and backreferences.

Finally, because unicode support is enabled, it is possible to have a string that fails on one library version and succeeds on another due to Unicode versions changing their character class definitions. This is a corner case, but any schema writer should be aware of it as a possibility.

Unicode NFC and NFKC

Unicode normalization can be tricky to get right. Strings are never required to be in a particular normalization form, as it may be that the creator or user of a string specifically wants no normalization, but a query or schema may desire it. To this end, normalization of the string being validated, as well as the in and nin lists’ strings can all be done before running validation. This is settable through the normalization field, which can be None, NFC, or NFKC.

Fields

comment: String

An optional comment explaining the validator.

in_list: Vec<String>

A vector of specific allowed values, stored under the in field. If empty, this vector is not checked against.

nin_list: Vec<String>

A vector of specific unallowed values, stored under the nin field.

matches: Option<Box<Regex>>

A regular expression that the value must match against.

max_len: u32

The maximum allowed number of bytes in the string value.

min_len: u32

The minimum allowed number of bytes in the string value.

max_char: u32

The maximum allowed number of unicode characters in the string value.

min_char: u32

The minimum allowed number of unicode characters in the string value.

normalize: Normalize

The Unicode normalization setting.

query: bool

If true, queries against matching spots may have values in the in or nin lists.

regex: bool

If true, queries against matching spots may use the matches value.

size: bool

If true, queries against matching spots may set the max_len, min_len, max_char, and min_char values to non-defaults.

Implementations

impl StrValidator

pub fn new() -> Self

Make a new validator with the default configuration.

pub fn comment(self, comment: impl Into<String>) -> Self

Set a comment for the validator.

pub fn max_len(self, max_len: u32) -> Self

Set the maximum number of allowed bytes.

pub fn min_len(self, min_len: u32) -> Self

Set the minimum number of allowed bytes.

pub fn max_char(self, max_char: u32) -> Self

Set the maximum number of allowed characters.

pub fn min_char(self, min_char: u32) -> Self

Set the minimum number of allowed characters.

pub fn normalize(self, normalize: Normalize) -> Self

Set the unicode normalization form to use for in, nin, and matches checks.

pub fn matches(self, matches: Regex) -> Self

Set the regular expression to check against.

pub fn in_add(self, add: impl Into<String>) -> Self

Add a value to the in list.

pub fn nin_add(self, add: impl Into<String>) -> Self

Add a value to the nin list.

pub fn query(self, query: bool) -> Self

Set whether or not queries can use the in and nin lists.

pub fn regex(self, regex: bool) -> Self

Set whether or not queries can use the bits_clr and bits_set values.

pub fn size(self, ord: bool) -> Self

Set whether or not queries can use the max_len, min_len, max_char, and min_char values.

pub fn build(self) -> Validator

Build this into a Validator enum.

Trait Implementations

impl Clone for StrValidator

fn clone(&self) -> StrValidator

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for StrValidator

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for StrValidator

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for StrValidator where
    StrValidator: Default, 

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error> where
    __D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl PartialEq<StrValidator> for StrValidator

fn eq(&self, rhs: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl Serialize for StrValidator

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error> where
    __S: Serializer, 

Serialize this value into the given Serde serializer.