serde_urlencoded/ser/
mod.rs

Help
1//! Serialization support for the `application/x-www-form-urlencoded` format.
2
3mod key;
4mod pair;
5mod part;
6mod value;
7
8use form_urlencoded::Serializer as UrlEncodedSerializer;
9use form_urlencoded::Target as UrlEncodedTarget;
10use serde::ser;
11use std::borrow::Cow;
12use std::error;
13use std::fmt;
14use std::str;
15
16/// Serializes a value into a `application/x-www-form-urlencoded` `String` buffer.
17///
18/// ```
19/// let meal = &[
20///     ("bread", "baguette"),
21///     ("cheese", "comté"),
22///     ("meat", "ham"),
23///     ("fat", "butter"),
24/// ];
25///
26/// assert_eq!(
27///     serde_urlencoded::to_string(meal),
28///     Ok("bread=baguette&cheese=comt%C3%A9&meat=ham&fat=butter".to_owned()));
29/// ```
30pub fn to_string<T: ser::Serialize>(input: T) -> Result<String, Error> {
31    let mut urlencoder = UrlEncodedSerializer::new("".to_owned());
32    input.serialize(Serializer::new(&mut urlencoder))?;
33    Ok(urlencoder.finish())
34}
35
36/// A serializer for the `application/x-www-form-urlencoded` format.
37///
38/// * Supported top-level inputs are structs, maps and sequences of pairs,
39///   with or without a given length.
40///
41/// * Supported keys and values are integers, bytes (if convertible to strings),
42///   unit structs and unit variants.
43///
44/// * Newtype structs defer to their inner values.
45pub struct Serializer<'input, 'output, Target: UrlEncodedTarget> {
46    urlencoder: &'output mut UrlEncodedSerializer<'input, Target>,
47}
48
49impl<'input, 'output, Target: 'output + UrlEncodedTarget>
50    Serializer<'input, 'output, Target>
51{
52    /// Returns a new `Serializer`.
53    pub fn new(
54        urlencoder: &'output mut UrlEncodedSerializer<'input, Target>,
55    ) -> Self {
56        Serializer { urlencoder }
57    }
58}
59
60/// Errors returned during serializing to `application/x-www-form-urlencoded`.
61#[derive(Clone, Debug, PartialEq, Eq)]
62pub enum Error {
63    Custom(Cow<'static, str>),
64    Utf8(str::Utf8Error),
65}
66
67impl fmt::Display for Error {
68    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
69        match *self {
70            Error::Custom(ref msg) => msg.fmt(f),
71            Error::Utf8(ref err) => write!(f, "invalid UTF-8: {}", err),
72        }
73    }
74}
75
76impl error::Error for Error {
77    fn description(&self) -> &str {
78        match *self {
79            Error::Custom(ref msg) => msg,
80            Error::Utf8(ref err) => error::Error::description(err),
81        }
82    }
83
84    /// The lower-level cause of this error, in the case of a `Utf8` error.
85    fn cause(&self) -> Option<&dyn error::Error> {
86        match *self {
87            Error::Custom(_) => None,
88            Error::Utf8(ref err) => Some(err),
89        }
90    }
91
92    /// The lower-level source of this error, in the case of a `Utf8` error.
93    fn source(&self) -> Option<&(dyn error::Error + 'static)> {
94        match *self {
95            Error::Custom(_) => None,
96            Error::Utf8(ref err) => Some(err),
97        }
98    }
99}
100
101impl ser::Error for Error {
102    fn custom<T: fmt::Display>(msg: T) -> Self {
103        Error::Custom(format!("{}", msg).into())
104    }
105}
106
107/// Sequence serializer.
108pub struct SeqSerializer<'input, 'output, Target: UrlEncodedTarget> {
109    urlencoder: &'output mut UrlEncodedSerializer<'input, Target>,
110}
111
112/// Tuple serializer.
113///
114/// Mostly used for arrays.
115pub struct TupleSerializer<'input, 'output, Target: UrlEncodedTarget> {
116    urlencoder: &'output mut UrlEncodedSerializer<'input, Target>,
117}
118
119/// Tuple struct serializer.
120///
121/// Never instantiated, tuple structs are not supported.
122pub struct TupleStructSerializer<'input, 'output, T: UrlEncodedTarget> {
123    inner: ser::Impossible<&'output mut UrlEncodedSerializer<'input, T>, Error>,
124}
125
126/// Tuple variant serializer.
127///
128/// Never instantiated, tuple variants are not supported.
129pub struct TupleVariantSerializer<'input, 'output, T: UrlEncodedTarget> {
130    inner: ser::Impossible<&'output mut UrlEncodedSerializer<'input, T>, Error>,
131}
132
133/// Map serializer.
134pub struct MapSerializer<'input, 'output, Target: UrlEncodedTarget> {
135    urlencoder: &'output mut UrlEncodedSerializer<'input, Target>,
136    key: Option<Cow<'static, str>>,
137}
138
139/// Struct serializer.
140pub struct StructSerializer<'input, 'output, Target: UrlEncodedTarget> {
141    urlencoder: &'output mut UrlEncodedSerializer<'input, Target>,
142}
143
144/// Struct variant serializer.
145///
146/// Never instantiated, struct variants are not supported.
147pub struct StructVariantSerializer<'input, 'output, T: UrlEncodedTarget> {
148    inner: ser::Impossible<&'output mut UrlEncodedSerializer<'input, T>, Error>,
149}
150
151impl<'input, 'output, Target> ser::Serializer
152    for Serializer<'input, 'output, Target>
153where
154    Target: 'output + UrlEncodedTarget,
155{
156    type Ok = &'output mut UrlEncodedSerializer<'input, Target>;
157    type Error = Error;
158    type SerializeSeq = SeqSerializer<'input, 'output, Target>;
159    type SerializeTuple = TupleSerializer<'input, 'output, Target>;
160    type SerializeTupleStruct = TupleStructSerializer<'input, 'output, Target>;
161    type SerializeTupleVariant =
162        TupleVariantSerializer<'input, 'output, Target>;
163    type SerializeMap = MapSerializer<'input, 'output, Target>;
164    type SerializeStruct = StructSerializer<'input, 'output, Target>;
165    type SerializeStructVariant =
166        StructVariantSerializer<'input, 'output, Target>;
167
168    /// Returns an error.
169    fn serialize_bool(self, _v: bool) -> Result<Self::Ok, Error> {
170        Err(Error::top_level())
171    }
172
173    /// Returns an error.
174    fn serialize_i8(self, _v: i8) -> Result<Self::Ok, Error> {
175        Err(Error::top_level())
176    }
177
178    /// Returns an error.
179    fn serialize_i16(self, _v: i16) -> Result<Self::Ok, Error> {
180        Err(Error::top_level())
181    }
182
183    /// Returns an error.
184    fn serialize_i32(self, _v: i32) -> Result<Self::Ok, Error> {
185        Err(Error::top_level())
186    }
187
188    /// Returns an error.
189    fn serialize_i64(self, _v: i64) -> Result<Self::Ok, Error> {
190        Err(Error::top_level())
191    }
192
193    /// Returns an error.
194    fn serialize_u8(self, _v: u8) -> Result<Self::Ok, Error> {
195        Err(Error::top_level())
196    }
197
198    /// Returns an error.
199    fn serialize_u16(self, _v: u16) -> Result<Self::Ok, Error> {
200        Err(Error::top_level())
201    }
202
203    /// Returns an error.
204    fn serialize_u32(self, _v: u32) -> Result<Self::Ok, Error> {
205        Err(Error::top_level())
206    }
207
208    /// Returns an error.
209    fn serialize_u64(self, _v: u64) -> Result<Self::Ok, Error> {
210        Err(Error::top_level())
211    }
212
213    /// Returns an error.
214    fn serialize_f32(self, _v: f32) -> Result<Self::Ok, Error> {
215        Err(Error::top_level())
216    }
217
218    /// Returns an error.
219    fn serialize_f64(self, _v: f64) -> Result<Self::Ok, Error> {
220        Err(Error::top_level())
221    }
222
223    /// Returns an error.
224    fn serialize_char(self, _v: char) -> Result<Self::Ok, Error> {
225        Err(Error::top_level())
226    }
227
228    /// Returns an error.
229    fn serialize_str(self, _value: &str) -> Result<Self::Ok, Error> {
230        Err(Error::top_level())
231    }
232
233    /// Returns an error.
234    fn serialize_bytes(self, _value: &[u8]) -> Result<Self::Ok, Error> {
235        Err(Error::top_level())
236    }
237
238    /// Returns `Ok`.
239    fn serialize_unit(self) -> Result<Self::Ok, Error> {
240        Ok(self.urlencoder)
241    }
242
243    /// Returns `Ok`.
244    fn serialize_unit_struct(
245        self,
246        _name: &'static str,
247    ) -> Result<Self::Ok, Error> {
248        Ok(self.urlencoder)
249    }
250
251    /// Returns an error.
252    fn serialize_unit_variant(
253        self,
254        _name: &'static str,
255        _variant_index: u32,
256        _variant: &'static str,
257    ) -> Result<Self::Ok, Error> {
258        Err(Error::top_level())
259    }
260
261    /// Serializes the inner value, ignoring the newtype name.
262    fn serialize_newtype_struct<T: ?Sized + ser::Serialize>(
263        self,
264        _name: &'static str,
265        value: &T,
266    ) -> Result<Self::Ok, Error> {
267        value.serialize(self)
268    }
269
270    /// Returns an error.
271    fn serialize_newtype_variant<T: ?Sized + ser::Serialize>(
272        self,
273        _name: &'static str,
274        _variant_index: u32,
275        _variant: &'static str,
276        _value: &T,
277    ) -> Result<Self::Ok, Error> {
278        Err(Error::top_level())
279    }
280
281    /// Returns `Ok`.
282    fn serialize_none(self) -> Result<Self::Ok, Error> {
283        Ok(self.urlencoder)
284    }
285
286    /// Serializes the given value.
287    fn serialize_some<T: ?Sized + ser::Serialize>(
288        self,
289        value: &T,
290    ) -> Result<Self::Ok, Error> {
291        value.serialize(self)
292    }
293
294    /// Serialize a sequence, given length (if any) is ignored.
295    fn serialize_seq(
296        self,
297        _len: Option<usize>,
298    ) -> Result<Self::SerializeSeq, Error> {
299        Ok(SeqSerializer {
300            urlencoder: self.urlencoder,
301        })
302    }
303
304    /// Returns an error.
305    fn serialize_tuple(
306        self,
307        _len: usize,
308    ) -> Result<Self::SerializeTuple, Error> {
309        Ok(TupleSerializer {
310            urlencoder: self.urlencoder,
311        })
312    }
313
314    /// Returns an error.
315    fn serialize_tuple_struct(
316        self,
317        _name: &'static str,
318        _len: usize,
319    ) -> Result<Self::SerializeTupleStruct, Error> {
320        Err(Error::top_level())
321    }
322
323    /// Returns an error.
324    fn serialize_tuple_variant(
325        self,
326        _name: &'static str,
327        _variant_index: u32,
328        _variant: &'static str,
329        _len: usize,
330    ) -> Result<Self::SerializeTupleVariant, Error> {
331        Err(Error::top_level())
332    }
333
334    /// Serializes a map, given length is ignored.
335    fn serialize_map(
336        self,
337        _len: Option<usize>,
338    ) -> Result<Self::SerializeMap, Error> {
339        Ok(MapSerializer {
340            urlencoder: self.urlencoder,
341            key: None,
342        })
343    }
344
345    /// Serializes a struct, given length is ignored.
346    fn serialize_struct(
347        self,
348        _name: &'static str,
349        _len: usize,
350    ) -> Result<Self::SerializeStruct, Error> {
351        Ok(StructSerializer {
352            urlencoder: self.urlencoder,
353        })
354    }
355
356    /// Returns an error.
357    fn serialize_struct_variant(
358        self,
359        _name: &'static str,
360        _variant_index: u32,
361        _variant: &'static str,
362        _len: usize,
363    ) -> Result<Self::SerializeStructVariant, Error> {
364        Err(Error::top_level())
365    }
366}
367
368impl<'input, 'output, Target> ser::SerializeSeq
369    for SeqSerializer<'input, 'output, Target>
370where
371    Target: 'output + UrlEncodedTarget,
372{
373    type Ok = &'output mut UrlEncodedSerializer<'input, Target>;
374    type Error = Error;
375
376    fn serialize_element<T: ?Sized + ser::Serialize>(
377        &mut self,
378        value: &T,
379    ) -> Result<(), Error> {
380        value.serialize(pair::PairSerializer::new(self.urlencoder))
381    }
382
383    fn end(self) -> Result<Self::Ok, Error> {
384        Ok(self.urlencoder)
385    }
386}
387
388impl<'input, 'output, Target> ser::SerializeTuple
389    for TupleSerializer<'input, 'output, Target>
390where
391    Target: 'output + UrlEncodedTarget,
392{
393    type Ok = &'output mut UrlEncodedSerializer<'input, Target>;
394    type Error = Error;
395
396    fn serialize_element<T: ?Sized + ser::Serialize>(
397        &mut self,
398        value: &T,
399    ) -> Result<(), Error> {
400        value.serialize(pair::PairSerializer::new(self.urlencoder))
401    }
402
403    fn end(self) -> Result<Self::Ok, Error> {
404        Ok(self.urlencoder)
405    }
406}
407
408impl<'input, 'output, Target> ser::SerializeTupleStruct
409    for TupleStructSerializer<'input, 'output, Target>
410where
411    Target: 'output + UrlEncodedTarget,
412{
413    type Ok = &'output mut UrlEncodedSerializer<'input, Target>;
414    type Error = Error;
415
416    fn serialize_field<T: ?Sized + ser::Serialize>(
417        &mut self,
418        value: &T,
419    ) -> Result<(), Error> {
420        self.inner.serialize_field(value)
421    }
422
423    fn end(self) -> Result<Self::Ok, Error> {
424        self.inner.end()
425    }
426}
427
428impl<'input, 'output, Target> ser::SerializeTupleVariant
429    for TupleVariantSerializer<'input, 'output, Target>
430where
431    Target: 'output + UrlEncodedTarget,
432{
433    type Ok = &'output mut UrlEncodedSerializer<'input, Target>;
434    type Error = Error;
435
436    fn serialize_field<T: ?Sized + ser::Serialize>(
437        &mut self,
438        value: &T,
439    ) -> Result<(), Error> {
440        self.inner.serialize_field(value)
441    }
442
443    fn end(self) -> Result<Self::Ok, Error> {
444        self.inner.end()
445    }
446}
447
448impl<'input, 'output, Target> ser::SerializeMap
449    for MapSerializer<'input, 'output, Target>
450where
451    Target: 'output + UrlEncodedTarget,
452{
453    type Ok = &'output mut UrlEncodedSerializer<'input, Target>;
454    type Error = Error;
455
456    fn serialize_entry<
457        K: ?Sized + ser::Serialize,
458        V: ?Sized + ser::Serialize,
459    >(
460        &mut self,
461        key: &K,
462        value: &V,
463    ) -> Result<(), Error> {
464        let key_sink = key::KeySink::new(|key| {
465            let value_sink = value::ValueSink::new(self.urlencoder, &key);
466            value.serialize(part::PartSerializer::new(value_sink))?;
467            self.key = None;
468            Ok(())
469        });
470        let entry_serializer = part::PartSerializer::new(key_sink);
471        key.serialize(entry_serializer)
472    }
473
474    fn serialize_key<T: ?Sized + ser::Serialize>(
475        &mut self,
476        key: &T,
477    ) -> Result<(), Error> {
478        let key_sink = key::KeySink::new(|key| Ok(key.into()));
479        let key_serializer = part::PartSerializer::new(key_sink);
480        self.key = Some(key.serialize(key_serializer)?);
481        Ok(())
482    }
483
484    fn serialize_value<T: ?Sized + ser::Serialize>(
485        &mut self,
486        value: &T,
487    ) -> Result<(), Error> {
488        {
489            let key = self.key.as_ref().ok_or_else(Error::no_key)?;
490            let value_sink = value::ValueSink::new(self.urlencoder, &key);
491            value.serialize(part::PartSerializer::new(value_sink))?;
492        }
493        self.key = None;
494        Ok(())
495    }
496
497    fn end(self) -> Result<Self::Ok, Error> {
498        Ok(self.urlencoder)
499    }
500}
501
502impl<'input, 'output, Target> ser::SerializeStruct
503    for StructSerializer<'input, 'output, Target>
504where
505    Target: 'output + UrlEncodedTarget,
506{
507    type Ok = &'output mut UrlEncodedSerializer<'input, Target>;
508    type Error = Error;
509
510    fn serialize_field<T: ?Sized + ser::Serialize>(
511        &mut self,
512        key: &'static str,
513        value: &T,
514    ) -> Result<(), Error> {
515        let value_sink = value::ValueSink::new(self.urlencoder, key);
516        value.serialize(part::PartSerializer::new(value_sink))
517    }
518
519    fn end(self) -> Result<Self::Ok, Error> {
520        Ok(self.urlencoder)
521    }
522}
523
524impl<'input, 'output, Target> ser::SerializeStructVariant
525    for StructVariantSerializer<'input, 'output, Target>
526where
527    Target: 'output + UrlEncodedTarget,
528{
529    type Ok = &'output mut UrlEncodedSerializer<'input, Target>;
530    type Error = Error;
531
532    fn serialize_field<T: ?Sized + ser::Serialize>(
533        &mut self,
534        key: &'static str,
535        value: &T,
536    ) -> Result<(), Error> {
537        self.inner.serialize_field(key, value)
538    }
539
540    fn end(self) -> Result<Self::Ok, Error> {
541        self.inner.end()
542    }
543}
544
545impl Error {
546    fn top_level() -> Self {
547        let msg = "top-level serializer supports only maps and structs";
548        Error::Custom(msg.into())
549    }
550
551    fn no_key() -> Self {
552        let msg = "tried to serialize a value before serializing key";
553        Error::Custom(msg.into())
554    }
555}
serde_urlencoded/ser/mod.rs

serde_urlencoded/ser/
mod.rs
