Crate sanitise_file_name

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.