serde_urlencoded/ser/
mod.rs

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

serde_urlencoded/ser/
mod.rs
