qs_rust 1.0.0

A query string encoding and decoding library for Rust. Ported from qs for JavaScript.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

//! Public query-string decoding entrypoints.

mod accumulate;
mod flat;
mod keys;
mod scalar;
mod scan;
mod structured;

use crate::error::DecodeError;
use crate::options::DecodeOptions;
use crate::structured_scan::scan_structured_keys;
use crate::value::{Object, Value};

use self::flat::{collect_pair_values, finalize_flat};
pub(crate) use self::keys::split_key_into_segments;
use self::scan::parse_query_string_values;
use self::structured::decode_from_pairs_map;

#[cfg(test)]
use self::accumulate::combine_with_limit;
#[cfg(test)]
use self::flat::{FlatValues, ParsedFlatValue};
#[cfg(test)]
use self::keys::{dot_to_bracket_top_level, find_recoverable_balanced_open};
#[cfg(test)]
use self::scalar::{decode_scalar, interpret_numeric_entities};
#[cfg(test)]
use self::scan::ScannedPart;

/// Decodes a query string into an ordered object map.
///
/// The result preserves flat outputs when the input contains no structured key
/// syntax, and falls back to the structured merge pipeline when bracket or dot
/// notation is present.
///
/// # Errors
///
/// Returns [`DecodeError`] when the supplied [`DecodeOptions`] are invalid or
/// when the input exceeds a configured limit that is enforced strictly.
///
/// # Examples
///
/// ```
/// use qs_rust::{DecodeOptions, Value, decode};
///
/// let value = decode("a=1&b=2", &DecodeOptions::new()).unwrap();
/// assert_eq!(value["a"], Value::String("1".to_owned()));
/// assert_eq!(value["b"], Value::String("2".to_owned()));
/// ```
pub fn decode(input: &str, options: &DecodeOptions) -> Result<Object, DecodeError> {
    options.validate()?;

    if input.is_empty() {
        return Ok(Object::new());
    }

    let parsed = parse_query_string_values(input, options)?;
    if parsed.values.is_empty() {
        return Ok(Object::new());
    }

    if !parsed.has_any_structured_syntax {
        return finalize_flat(parsed.values, options);
    }

    let structured_scan = scan_structured_keys(parsed.values.key_refs(), options)?;
    if !structured_scan.has_any_structured_syntax {
        return finalize_flat(parsed.values, options);
    }

    decode_from_pairs_map(parsed.values, options, &structured_scan)
}

/// Decodes an iterator of already-separated key/value pairs into an ordered
/// object map.
///
/// This entrypoint skips raw query-string scanning but otherwise applies the
/// same flat-finalization and structured-merge rules as [`decode`].
///
/// # Errors
///
/// Returns [`DecodeError`] when the supplied [`DecodeOptions`] are invalid or
/// when a configured list or depth limit is exceeded during reconstruction.
pub fn decode_pairs<I>(pairs: I, options: &DecodeOptions) -> Result<Object, DecodeError>
where
    I: IntoIterator<Item = (String, Value)>,
{
    options.validate()?;

    let parsed = collect_pair_values(pairs, options)?;
    if parsed.values.is_empty() {
        return Ok(Object::new());
    }

    if !parsed.has_any_structured_syntax {
        return finalize_flat(parsed.values, options);
    }

    let structured_scan = scan_structured_keys(parsed.values.key_refs(), options)?;
    if !structured_scan.has_any_structured_syntax {
        return finalize_flat(parsed.values, options);
    }

    decode_from_pairs_map(parsed.values, options, &structured_scan)
}

#[cfg(test)]
mod tests;