Crate sanitise_file_name[−][src]

Expand description

Sanitise names for use in file systems and the likes.

The output string is guaranteed to be shorter than or equal to the input string in length, except for file names that are reserved on Windows (see Options::windows_safe), in which case an underscore is appended to the base name (e.g. NUL → NUL_, aux.h → aux_.h).

The key parts of the API:

  • sanitise(input: &str) -> String: the simplest thing to call;

  • sanitise_with_options(input: &str, options: &Options<_>) -> String: when you want to tweak the nature of the sanitisation; and

  • Options, with detailed descriptions of each option.

And for advanced users that want to control allocations or other similar things:

  • sanitise_to(input: &str, options: &Options<_>, out: &mut String), sanitising into a String or tinyvec_string::ArrayString (when enabled) that you provide, for which the following methods may help:

  • max_alloc_size(options: &Options<_>) or max_alloc_size_const(options: &Options<Option<char>>), to suggest a size for scratch buffer or ArrayString applications; and

  • sufficient_alloc_size(input: &str, options: &Options<_>) -> usize, to suggest a size that will definitely be sufficient for one given input (mainly useful when you are crafting a path with stuff before and after it).

… but that’s dangerous territory, deep rabbit holes; ask if you actually need them—don’t be like me. (When I am laid in earth, may my wrongs create no trouble in thy breast. Remember me, but ah! forget my fate.)

Conditional compilation/Cargo features

This crate has several features:

  • std, enabled by default. Implies alloc. Disable it to get #![no_std] operation.

  • alloc, enabled by default via std. Provides the ability to sanitise to a String in sanitise_to, and the sanitise and sanitise_with_options functions.

  • tinyvec_string, disabled by default. Provides the ability to sanitise to tinyvec_string::ArrayString, which works without alloc.

  • const-fn-trait-bound, disabled by default, requires rustc nightly at the time of writing. Makes max_alloc_size const.

These docs were built with these features enabled: std alloc tinyvec_string const-fn-trait-bound

… and these features disabled: (none of them)

Re-exports

pub use sanitise as sanitize;
alloc
pub use sanitise_with_options as sanitize_with_options;
alloc
pub use sanitise_to as sanitize_to;

Structs

Options

Sanitisation options. Defaults marked on each field.

Traits

Replace

See Options::replace_with.

Stringy

A target for sanitisation: essentially the subset of String functionality used.

Functions

max_alloc_size

Calculate the maximum allocation size required for a given set of options, to correctly handle any input.

max_alloc_size_const

A const variant of max_alloc_size.

sanitisealloc

Sanitise a file name with the default options. See Options for a description of what all the options do.

sanitise_to

Sanitise a file name into an existing String. Intended for power users only.

sanitise_with_optionsalloc

Sanitise a file name. See Options for a description of what all the options do.

sufficient_alloc_size

Calculate a sufficient allocation size for the string used. This number will never exceed input.len() + 1 + options.reserve_extra, and will be less on ridiculously long inputs.