Struct FileName

Source

pub struct FileName<'a> { /* private fields */ }

Expand description

The client’s file name, with a view for each way a caller might want it.

form-net never uses a client file name as a path or as part of one. Debug prints the length only: file names are user data.

§Examples

let body = b"--X\r\nContent-Disposition: form-data; name=\"doc\"; filename=\"C:\\Users\\me\\a b.pdf\"\r\n\r\nx\r\n--X--";
let mp = form_net::parse_multipart(b"multipart/form-data; boundary=X", body)?;
let name = mp.file("doc").unwrap().filename().unwrap();
assert_eq!(name.raw(), b"C:\\Users\\me\\a b.pdf");
assert_eq!(name.basename(), b"a b.pdf");

Implementations§

Source §

impl<'a> FileName<'a>

Source

pub const fn raw(&self) -> &'a [u8] ⓘ

The bytes as sent between the quotes of filename, untouched; or the decoded bytes of an accepted filename*.

§Examples

let name = mp.file("f").unwrap().filename().unwrap();
assert_eq!(name.raw(), b"a%22b.txt");

Source

pub fn as_str(&self) -> Result<&'a str, FormError>

The raw bytes as UTF-8.

§Errors

Encoding { InvalidUtf8 }.

§Examples

assert_eq!(mp.file("f").unwrap().filename().unwrap().as_str()?, "café.txt");

Source

pub const fn is_empty(&self) -> bool

Whether the name is empty: a file input left empty.

§Examples

assert!(mp.file("f").unwrap().filename().unwrap().is_empty());

Source

pub const fn source(&self) -> FileNameSource

Plain for filename, Extended for filename*.

§Examples

use form_net::FileNameSource;
assert_eq!(mp.file("f").unwrap().filename().unwrap().source(), FileNameSource::Plain);

Source

pub fn basename(&self) -> &'a [u8] ⓘ

The bytes after the last / or \ (some non-browser clients send full client paths).

§Examples

assert_eq!(mp.file("f").unwrap().filename().unwrap().basename(), b"c.txt");

Source

pub fn extension(&self) -> Option<&'a str>

The text after the last . of the base name, when it is 1 to 16 ASCII letters or digits. A hint that proves nothing about the content: only the bytes tell what a file is.

§Examples

assert_eq!(mp.file("f").unwrap().filename().unwrap().extension(), Some("gz"));

Source

pub fn html_unescape_into<'b>( &self, out: &'b mut [u8], ) -> Result<&'b str, FormError>

Writes the name into out with the HTML escapes %0A, %0D, %22 decoded to LF, CR, ", and nothing else, and returns it as text. Browsers do not escape % itself, so a file the user named a%22b reads as a"b; that ambiguity is inherent in the HTML encoding.

§Errors

BufferTooSmall when out is shorter than raw; Encoding { InvalidUtf8 }.

§Examples

let mut out = [0u8; 32];
let name = mp.file("f").unwrap().filename().unwrap();
assert_eq!(name.html_unescape_into(&mut out)?, "a\"b.txt");

Source

pub fn html_unescaped(&self) -> Result<Cow<'a, str>, FormError>

Available on crate feature alloc only.

As html_unescape_into, borrowed when the name has nothing to decode.

§Errors

Encoding { InvalidUtf8 }.

§Examples

assert_eq!(mp.file("f").unwrap().filename().unwrap().html_unescaped()?, "a\nb");

Source §

impl FileName<'_>

Source

pub fn sanitized(&self) -> Result<String, FormError>

Available on crate feature fs only.

One portable file name from the client’s: the HTML-unescaped base name with every default-ignorable character (zero width spaces and joiners, soft hyphens, variation selectors, tags, bidirectional controls) replaced by _ (D-084), then passed through path_lib::sanitize, which replaces separators, control characters, Windows-reserved characters and device names, and trims trailing dots and spaces. Unicode normalization is not applied; it arrives with the unicode feature in 0.5. It is still a name the client chose: never let it overwrite anything (StoredFile::persist refuses to).

§Errors

Encoding { InvalidUtf8 }.

§Examples

let body = b"--X\r\nContent-Disposition: form-data; name=f; filename=\"C:\\x\\Q3 report: final?.pdf\"\r\n\r\n\r\n--X--";
let mp = form_net::parse_multipart(b"multipart/form-data; boundary=X", body)?;
let name = mp.file("f").unwrap().filename().unwrap();
assert_eq!(name.sanitized()?, "Q3 report_ final_.pdf");