hyperx/header/shared/
quality_item.rs

1use std::cmp;
2use std::default::Default;
3use std::fmt;
4use std::str;
5
6use self::internal::IntoQuality;
7
8/// Represents a quality used in quality values.
9///
10/// Can be created with the `q` function.
11///
12/// # Implementation notes
13///
14/// The quality value is defined as a number between 0 and 1 with three decimal places. This means
15/// there are 1001 possible values. Since floating point numbers are not exact and the smallest
16/// floating point data type (`f32`) consumes four bytes, hyper uses an `u16` value to store the
17/// quality internally. For performance reasons you may set quality directly to a value between
18/// 0 and 1000 e.g. `Quality(532)` matches the quality `q=0.532`.
19///
20/// [RFC7231 Section 5.3.1](https://tools.ietf.org/html/rfc7231#section-5.3.1)
21/// gives more information on quality values in HTTP header fields.
22#[derive(Copy, Clone, Debug, Eq, Ord, PartialEq, PartialOrd)]
23pub struct Quality(u16);
24
25impl Default for Quality {
26    fn default() -> Quality {
27        Quality(1000)
28    }
29}
30
31/// Represents an item with a quality value as defined in
32/// [RFC7231](https://tools.ietf.org/html/rfc7231#section-5.3.1).
33#[derive(Clone, PartialEq, Debug)]
34pub struct QualityItem<T> {
35    /// The actual contents of the field.
36    pub item: T,
37    /// The quality (client or server preference) for the value.
38    pub quality: Quality,
39}
40
41impl<T> QualityItem<T> {
42    /// Creates a new `QualityItem` from an item and a quality.
43    /// The item can be of any type.
44    /// The quality should be a value in the range [0, 1].
45    pub fn new(item: T, quality: Quality) -> QualityItem<T> {
46        QualityItem {
47            item: item,
48            quality: quality
49        }
50    }
51}
52
53impl<T: PartialEq> cmp::PartialOrd for QualityItem<T> {
54    fn partial_cmp(&self, other: &QualityItem<T>) -> Option<cmp::Ordering> {
55        self.quality.partial_cmp(&other.quality)
56    }
57}
58
59impl<T: fmt::Display> fmt::Display for QualityItem<T> {
60
61    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
62        fmt::Display::fmt(&self.item, f)?;
63        match self.quality.0 {
64            1000 => Ok(()),
65            0 => f.write_str("; q=0"),
66            x => write!(f, "; q=0.{}", format!("{:03}", x).trim_end_matches('0'))
67        }
68    }
69}
70
71impl<T: str::FromStr> str::FromStr for QualityItem<T> {
72    type Err = ::Error;
73    fn from_str(s: &str) -> ::Result<QualityItem<T>> {
74        if !s.is_ascii() {
75            return Err(::Error::Header);
76        }
77        // Set defaults used if parsing fails.
78        let mut raw_item = s;
79        let mut quality = 1f32;
80
81        let parts: Vec<&str> = s.rsplitn(2, ';').map(|x| x.trim()).collect();
82        if parts.len() == 2 {
83            if parts[0].len() < 2 {
84                return Err(::Error::Header);
85            }
86            let start = &parts[0][0..2];
87            if start == "q=" || start == "Q=" {
88                let q_part = &parts[0][2..parts[0].len()];
89                if q_part.len() > 5 {
90                    return Err(::Error::Header);
91                }
92                match q_part.parse::<f32>() {
93                    Ok(q_value) => {
94                        if 0f32 <= q_value && q_value <= 1f32 {
95                            quality = q_value;
96                            raw_item = parts[1];
97                            } else {
98                                return Err(::Error::Header);
99                            }
100                        },
101                    Err(_) => return Err(::Error::Header),
102                }
103            }
104        }
105        match raw_item.parse::<T>() {
106            // we already checked above that the quality is within range
107            Ok(item) => Ok(QualityItem::new(item, from_f32(quality))),
108            Err(_) => Err(::Error::Header),
109        }
110    }
111}
112
113#[inline]
114fn from_f32(f: f32) -> Quality {
115    // this function is only used internally. A check that `f` is within range
116    // should be done before calling this method. Just in case, this
117    // debug_assert should catch if we were forgetful
118    debug_assert!(f >= 0f32 && f <= 1f32, "q value must be between 0.0 and 1.0");
119    Quality((f * 1000f32) as u16)
120}
121
122/// Convenience function to wrap a value in a `QualityItem`
123/// Sets `q` to the default 1.0
124pub fn qitem<T>(item: T) -> QualityItem<T> {
125    QualityItem::new(item, Default::default())
126}
127
128/// Convenience function to create a `Quality` from a float or integer.
129///
130/// Implemented for `u16` and `f32`. Panics if value is out of range.
131pub fn q<T: IntoQuality>(val: T) -> Quality {
132    val.into_quality()
133}
134
135mod internal {
136    use super::Quality;
137
138    // TryFrom is probably better, but it's not stable. For now, we want to
139    // keep the functionality of the `q` function, while allowing it to be
140    // generic over `f32` and `u16`.
141    //
142    // `q` would panic before, so keep that behavior. `TryFrom` can be
143    // introduced later for a non-panicking conversion.
144
145    pub trait IntoQuality: Sealed + Sized {
146        fn into_quality(self) -> Quality;
147    }
148
149    impl IntoQuality for f32 {
150        fn into_quality(self) -> Quality {
151            assert!(self >= 0f32 && self <= 1f32, "float must be between 0.0 and 1.0");
152            super::from_f32(self)
153        }
154    }
155
156    impl IntoQuality for u16 {
157        fn into_quality(self) -> Quality {
158            assert!(self <= 1000, "u16 must be between 0 and 1000");
159            Quality(self)
160        }
161    }
162
163    pub trait Sealed {}
164    impl Sealed for u16 {}
165    impl Sealed for f32 {}
166}
167
168#[cfg(test)]
169mod tests {
170    use super::*;
171    use super::super::encoding::*;
172
173    #[test]
174    fn test_quality_item_fmt_q_1() {
175        let x = qitem(Chunked);
176        assert_eq!(format!("{}", x), "chunked");
177    }
178    #[test]
179    fn test_quality_item_fmt_q_0001() {
180        let x = QualityItem::new(Chunked, Quality(1));
181        assert_eq!(format!("{}", x), "chunked; q=0.001");
182    }
183    #[test]
184    fn test_quality_item_fmt_q_05() {
185        // Custom value
186        let x = QualityItem{
187            item: EncodingExt("identity".to_owned()),
188            quality: Quality(500),
189        };
190        assert_eq!(format!("{}", x), "identity; q=0.5");
191    }
192
193    #[test]
194    fn test_quality_item_fmt_q_0() {
195        // Custom value
196        let x = QualityItem{
197            item: EncodingExt("identity".to_owned()),
198            quality: Quality(0),
199        };
200        assert_eq!(x.to_string(), "identity; q=0");
201    }
202
203    #[test]
204    fn test_quality_item_from_str1() {
205        let x: ::Result<QualityItem<Encoding>> = "chunked".parse();
206        assert_eq!(x.unwrap(), QualityItem{ item: Chunked, quality: Quality(1000), });
207    }
208    #[test]
209    fn test_quality_item_from_str2() {
210        let x: ::Result<QualityItem<Encoding>> = "chunked; q=1".parse();
211        assert_eq!(x.unwrap(), QualityItem{ item: Chunked, quality: Quality(1000), });
212    }
213    #[test]
214    fn test_quality_item_from_str3() {
215        let x: ::Result<QualityItem<Encoding>> = "gzip; q=0.5".parse();
216        assert_eq!(x.unwrap(), QualityItem{ item: Gzip, quality: Quality(500), });
217    }
218    #[test]
219    fn test_quality_item_from_str4() {
220        let x: ::Result<QualityItem<Encoding>> = "gzip; q=0.273".parse();
221        assert_eq!(x.unwrap(), QualityItem{ item: Gzip, quality: Quality(273), });
222    }
223    #[test]
224    fn test_quality_item_from_str5() {
225        let x: ::Result<QualityItem<Encoding>> = "gzip; q=0.2739999".parse();
226        assert!(x.is_err());
227    }
228    #[test]
229    fn test_quality_item_from_str6() {
230        let x: ::Result<QualityItem<Encoding>> = "gzip; q=2".parse();
231        assert!(x.is_err());
232    }
233    #[test]
234    fn test_quality_item_ordering() {
235        let x: QualityItem<Encoding> = "gzip; q=0.5".parse().ok().unwrap();
236        let y: QualityItem<Encoding> = "gzip; q=0.273".parse().ok().unwrap();
237        let comparision_result: bool = x.gt(&y);
238        assert!(comparision_result)
239    }
240
241    #[test]
242    fn test_quality() {
243        assert_eq!(q(0.5), Quality(500));
244    }
245
246    #[test]
247    #[should_panic] // FIXME - 32-bit msvc unwinding broken
248    #[cfg_attr(all(target_arch="x86", target_env="msvc"), ignore)]
249    fn test_quality_invalid() {
250        q(-1.0);
251    }
252
253    #[test]
254    #[should_panic] // FIXME - 32-bit msvc unwinding broken
255    #[cfg_attr(all(target_arch="x86", target_env="msvc"), ignore)]
256    fn test_quality_invalid2() {
257        q(2.0);
258    }
259
260    #[test]
261    fn test_fuzzing_bugs() {
262        assert!("99999;".parse::<QualityItem<String>>().is_err());
263        assert!("\x0d;;;=\u{d6aa}==".parse::<QualityItem<String>>().is_err())
264    }
265}
hyperx/header/shared/quality_item.rs

hyperx/header/shared/
quality_item.rs
