Struct Options

pub struct Options<Extra: ExtraOptions = DefaultExtraOptions> { /* private fields */ }

Options for deserialization.

The most important methods are:

• Options::deserialize_from_json_str for JSON,
• [Options::deserialize_from_yaml_str] for YAML,
• Options::deserialize_source for a generic source.

Implementations

impl Options

pub fn new_json() -> Options<JsonExtraOptions>

Available on crate features rand and serde_json only.

Default config for JSON.

This will currently generate a short extra trailer on inputs for improved deserialization of incomplete JSON.

pub fn new_nonce() -> Options<DefaultExtraOptions>

Available on crate feature rand only.

Basic config, suitable for any data format.

These options support adding a randomized trailer to the input. However, you should probably call Options::set_random_trailer to specify how this trailer should be removed from parsed strings.

pub fn new_no_nonce() -> Options<DefaultExtraOptions>

Basic config, suitable for any data format. However, this config does not allow adding a randomized trailer to the input, which tends to benefit many formats.

• For serde_json, this means you won’t get incomplete strings deserialized

• For serde_yaml, this means that your output will flicker, as it seems to buffer lines somehow, and if a line has an unterminated string, then the whole line will be missing.

impl<Extra: ExtraOptions> Options<Extra>

pub fn with_max_n_backtracks(self, max_n_backtracks: Option<usize>) -> Self

pub fn deserialize_from_json_str<T>( self, json: Cow<'_, str>, ) -> Result<T, Error<Error>>

where T: for<'de> Deserialize<'de>,

Available on crate features rand and serde_json only.

Like crate::from_json_str, but with options. This applies the random trailer.

pub fn deserialize_from_json_slice<T>( self, json: Cow<'_, [u8]>, ) -> Result<T, Error<Error>>

where T: for<'de> Deserialize<'de>,

Available on crate features rand and serde_json only.

Like crate::from_json_slice, but with options. This applies the random trailer.

pub fn deserialize_from_json_slice_plain_return_borrowed<'de, T>( self, json: &'de impl AsRef<[u8]>, ) -> Result<T, Error<Error>>

where T: Deserialize<'de>,

Available on crate feature serde_json only.

Like Self::deserialize_from_json_slice, but can deserialize borrowed strings and return them directly.

This comes at the cost that we cannot use the random trailer technique that gives us access to the contents of incomplete strings.

If you need incomplete strings as well, then use Self::deserialize_from_json_slice_borrowed.

#[derive(Debug, Deserialize, PartialEq)]
struct TravelMode {
   #[serde(default)]
   mode: String,
   benefit: Option<String>
}

let json = r#"[{"mode": "foot", "benefit": "healthy"}, {"mode": "incomplete"#;
let modes: Vec<TravelMode> = deser_incomplete::Options::new_json().deserialize_from_json_slice_plain_return_borrowed(&json).unwrap();
assert_eq!(modes, [
   TravelMode { mode: "foot".to_string(), benefit: Some("healthy".to_string()) },
   TravelMode { mode: "".to_string(), benefit: None },
   // Note: this function fails on incomplete strings, because
   // the randomized trailer is needed for those.
]);

pub fn deserialize_from_json_str_borrowed<'de, T>( self, InputPlusTrailer: &'de InputPlusTrailer<impl AsRef<str>>, ) -> Result<T, Error<Error>>

where T: Deserialize<'de>,

Available on crate feature serde_json only.

Advanced API. Lets you deserialize into borrowed types like &str, while supporting the random trailer that gives us access to the contents of incomplete strings.

(The difference is that this only needs T: serde::de::Deserialize<'de>, which is weaker.)

Note: This API is relatively likely to change (more unstable) compared to Self::deserialize_from_json_str.

/// Note: `&'a str` instead of `String`.
///
/// Like with serde_json, deserializing to &str can fail. Instead, you should probably
/// use `Cow<str>`, or just `String`.
#[derive(Debug, Deserialize, PartialEq)]
struct TravelMode<'a> {
   mode: &'a str,
   benefit: Option<&'a str>
}

let json = r#"[{"mode": "foot", "benefit": "healthy"}, {"mode": "aeropl"#;
let options = deser_incomplete::Options::new_json();
let prepared = options.prepare_str_for_borrowed_deserialization(json.into());
let modes: Vec<TravelMode> = options.deserialize_from_json_str_borrowed(&prepared).unwrap();
assert_eq!(modes, [
   TravelMode { mode: "foot", benefit: Some("healthy") },
   TravelMode { mode: "aeropl", benefit: None }
]);

pub fn deserialize_from_json_slice_borrowed<'de, T>( self, InputPlusTrailer: &'de InputPlusTrailer<impl AsRef<[u8]>>, ) -> Result<T, Error<Error>>

where T: Deserialize<'de>,

Available on crate feature serde_json only.

Advanced API. See Self::deserialize_from_json_str_borrowed, or use Self::deserialize_from_json_slice for a simpler API.

Note: This API is relatively likely to change (more unstable) compared to Self::deserialize_from_json_slice.

pub fn prepare_str_for_borrowed_deserialization<'a>( &self, input: Cow<'a, str>, ) -> InputPlusTrailer<Cow<'a, str>>

Available on crate feature rand only.

Prepare a string for borrowed deserialization with a method like Self::deserialize_from_json_str_borrowed, by appending the random trailer.

This returns a newtype wrapper, so you can undo the effects yourself.

pub fn prepare_slice_for_borrowed_deserialization<'a>( &self, input: Cow<'a, [u8]>, ) -> InputPlusTrailer<Cow<'a, [u8]>>

Available on crate feature rand only.

Prepare a slice for borrowed deserialization with a method like Self::deserialize_from_json_slice_borrowed, by appending the random trailer.

This returns a newtype wrapper, so you can undo the effects yourself.

pub fn disable_random_tag(self) -> Self

Available on crate feature rand only.

Don’t use a random tag. This can make deserialization a tiny bit cheaper, because the input does not have to be reallocated.

impl<R, F, RT> Options<ExtraOptionsStruct<R, F, RT>>

where R: MakeReporter, F: MakeFallbackProvider, RT: RandomTrailer,

pub fn set_random_trailer<RT2>( self, random_trailer: RT2, ) -> Options<ExtraOptionsStruct<R, F, RT2>>

where RT2: RandomTrailer,

Available on crate feature rand only.

Set a different method for randomized trailers.

impl<Extra: ExtraOptions> Options<Extra>

pub fn deserialize_source<'de, T, S>( self, source: S, ) -> Result<T, Error<S::Error>>

where T: Deserialize<'de>, S: Source<'de>,

Deserialize from a generic Source.

Unlike Self::deserialize_from_json_str etc, this method does not automatically append a random trailer. If you want that, then you can use Self::prepare_str_for_borrowed_deserialization.

You can use Options::deserialize_seed instead if you need to pass a seed.

pub fn deserialize_seed<'de, T, S>( self, seed: T, source: S, ) -> Result<T::Value, Error<S::Error>>

where T: DeserializeSeed<'de> + Clone, S: Source<'de>,

Deserialize from a seed.

Unlike Self::deserialize_from_json_str etc, this method does not automatically append a random trailer. If you want that, then you can use Self::prepare_str_for_borrowed_deserialization.

If you don’t need a seed, then you can use Options::deserialize_source.

Trait Implementations

impl<Extra: Clone + ExtraOptions> Clone for Options<Extra>

fn clone(&self) -> Options<Extra>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<Extra: Debug + ExtraOptions> Debug for Options<Extra>

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

Formats the value using the given formatter.