basic_usage/
basic_usage.rs

1//! Basic usage examples for http_encoding_headers
2//!
3//! This example demonstrates:
4//! - Encoding and decoding Accept-Encoding headers
5//! - Encoding and decoding Content-Encoding headers
6//! - Using AcceptEncoding methods like preferred() and sorting
7
8use http_encoding_headers::{
9    AcceptEncoding, ContentEncoding, Encoding, decode_header_value, encode_header_value,
10};
11
12#[cfg(feature = "http_crates")]
13use headers::{Header, HeaderMapExt};
14#[cfg(feature = "http_crates")]
15use http::{HeaderMap, HeaderValue};
16
17fn main() {
18    println!("=== HTTP Encoding Headers Examples ===\n");
19
20    // Example 1: Accept-Encoding header encoding and decoding
21    accept_encoding_examples();
22
23    // Example 2: Content-Encoding header encoding and decoding
24    content_encoding_examples();
25
26    // Example 3: AcceptEncoding advanced usage
27    accept_encoding_advanced_examples();
28}
29
30/// Examples for Accept-Encoding header encode/decode functionality
31fn accept_encoding_examples() {
32    println!("1. Accept-Encoding Header Examples");
33    println!("==================================");
34
35    // Example 1a: Encoding Accept-Encoding header values
36    println!("\n1a. Encoding Accept-Encoding header values:");
37    let encodings = vec![
38        (Encoding::Gzip, 1.0),
39        (Encoding::Deflate, 0.8),
40        (Encoding::Br, 0.6),
41        (Encoding::Identity, 0.1),
42    ];
43
44    match encode_header_value(&encodings) {
45        Ok(header_value) => {
46            println!("   Input: {:?}", encodings);
47            println!("   Encoded header: {}", header_value);
48        }
49        Err(e) => println!("   Error encoding: {}", e),
50    }
51
52    // Example 1b: Decoding Accept-Encoding header values
53    println!("\n1b. Decoding Accept-Encoding header values:");
54    let header_string = "gzip, deflate;q=0.8, br;q=0.6, identity;q=0.1";
55    println!("   Input header: {}", header_string);
56
57    match decode_header_value(header_string) {
58        Ok(parsed) => {
59            println!("   Decoded encodings:");
60            for (encoding, quality) in parsed {
61                println!("     {} (q={})", encoding, quality);
62            }
63        }
64        Err(e) => println!("   Error decoding: {}", e),
65    }
66
67    // Example 1c: Working with complex Accept-Encoding values
68    println!("\n1c. Complex Accept-Encoding example:");
69    let complex_header = "gzip;q=1.0, deflate;q=0.5, br;q=0.25, *;q=0.1";
70    println!("   Input: {}", complex_header);
71
72    if let Ok(parsed) = decode_header_value(complex_header) {
73        // Create AcceptEncoding instance
74        if let Ok(accept_encoding) = AcceptEncoding::new(parsed) {
75            println!(
76                "   Created AcceptEncoding with {} encodings",
77                accept_encoding.items().len()
78            );
79
80            // Re-encode it
81            if let Ok(re_encoded) = encode_header_value(accept_encoding.items()) {
82                println!("   Re-encoded: {}", re_encoded);
83            }
84        }
85    }
86}
87
88/// Examples for Content-Encoding header encode/decode functionality  
89#[cfg(feature = "http_crates")]
90fn content_encoding_examples() {
91    println!("\n\n2. Content-Encoding Header Examples");
92    println!("===================================");
93
94    // Example 2a: Creating and encoding Content-Encoding headers
95    println!("\n2a. Creating and encoding Content-Encoding:");
96    let content_encoding = ContentEncoding::new(Encoding::Gzip);
97    println!("   Created ContentEncoding: {:?}", content_encoding);
98
99    // Use with HeaderMap
100    let mut headers = HeaderMap::new();
101    headers.typed_insert(content_encoding);
102
103    if let Some(header_value) = headers.get(http::header::CONTENT_ENCODING) {
104        println!(
105            "   Header value: {}",
106            header_value.to_str().unwrap_or("invalid")
107        );
108    }
109
110    // Example 2b: Decoding Content-Encoding headers
111    println!("\n2b. Decoding Content-Encoding headers:");
112    let test_values = vec!["gzip", "deflate", "br", "zstd"];
113
114    for encoding_str in test_values {
115        println!("   Testing: {}", encoding_str);
116        let header_values = vec![HeaderValue::from_str(encoding_str).unwrap()];
117
118        match ContentEncoding::decode(&mut header_values.iter()) {
119            Ok(decoded) => println!("     Decoded: {:?}", decoded),
120            Err(e) => println!("     Error: {:?}", e),
121        }
122    }
123
124    // Example 2c: Multiple identical values (valid)
125    println!("\n2c. Multiple identical Content-Encoding values:");
126    let identical_values = vec![
127        HeaderValue::from_str("gzip").unwrap(),
128        HeaderValue::from_str("gzip").unwrap(),
129    ];
130
131    match ContentEncoding::decode(&mut identical_values.iter()) {
132        Ok(decoded) => println!("   Multiple identical values decoded: {:?}", decoded),
133        Err(e) => println!("   Error: {:?}", e),
134    }
135
136    // Example 2d: Conflicting values (should error)
137    println!("\n2d. Conflicting Content-Encoding values (should error):");
138    let conflicting_values = vec![
139        HeaderValue::from_str("gzip").unwrap(),
140        HeaderValue::from_str("deflate").unwrap(),
141    ];
142
143    match ContentEncoding::decode(&mut conflicting_values.iter()) {
144        Ok(decoded) => println!("   Unexpectedly decoded: {:?}", decoded),
145        Err(_) => println!("   Correctly rejected conflicting values"),
146    }
147}
148
149#[cfg(not(feature = "http_crates"))]
150fn content_encoding_examples() {
151    println!("\n\n2. Content-Encoding Header Examples");
152    println!("===================================");
153    println!("   (Skipped - http_crates feature not enabled)");
154}
155
156/// Examples for AcceptEncoding advanced functionality
157fn accept_encoding_advanced_examples() {
158    println!("\n\n3. AcceptEncoding Advanced Usage");
159    println!("===============================");
160
161    // Create an AcceptEncoding instance with various encodings
162    let encodings = vec![
163        (Encoding::Gzip, 0.9),
164        (Encoding::Deflate, 0.8),
165        (Encoding::Br, 1.0),       // Highest quality
166        (Encoding::Identity, 0.1), // Lowest quality
167        (Encoding::Zstd, 0.7),
168    ];
169
170    let mut accept_encoding = AcceptEncoding::new(encodings).unwrap();
171    println!("\n3a. Original AcceptEncoding:");
172    println!("   Encodings: {:?}", accept_encoding.items());
173
174    // Example 3a: Finding preferred encoding
175    println!("\n3b. Finding preferred encoding:");
176    if let Some(preferred) = accept_encoding.preferred() {
177        println!("   Preferred encoding: {}", preferred);
178        println!("   (Highest quality value from unsorted list)");
179    }
180
181    // Example 3b: Sorting in descending order (highest quality first)
182    println!("\n3c. Sorting in descending order (highest quality first):");
183    accept_encoding.sort_descending();
184    println!("   After sort_descending():");
185    for (encoding, quality) in accept_encoding.items() {
186        println!("     {} (q={})", encoding, quality);
187    }
188
189    // Now preferred should be first item
190    if let Some(preferred) = accept_encoding.preferred() {
191        println!("   Preferred encoding after sorting: {}", preferred);
192        println!("   (First item in descending sorted list)");
193    }
194
195    // Example 3c: Sorting in ascending order (lowest quality first)
196    println!("\n3d. Sorting in ascending order (lowest quality first):");
197    accept_encoding.sort_ascending();
198    println!("   After sort_ascending():");
199    for (encoding, quality) in accept_encoding.items() {
200        println!("     {} (q={})", encoding, quality);
201    }
202
203    // Now preferred should be last item
204    if let Some(preferred) = accept_encoding.preferred() {
205        println!("   Preferred encoding after ascending sort: {}", preferred);
206        println!("   (Last item in ascending sorted list)");
207    }
208
209    // Example 3d: Demonstrating in-place sorting behavior
210    println!("\n3e. Demonstrating in-place sorting chain:");
211    let encodings2 = vec![
212        (Encoding::Gzip, 0.5),
213        (Encoding::Deflate, 0.9),
214        (Encoding::Br, 0.3),
215    ];
216
217    let mut accept_encoding2 = AcceptEncoding::new(encodings2).unwrap();
218    println!("   Original: {:?}", accept_encoding2.items());
219
220    // Chain sorting operations (returns &mut Self for chaining)
221    accept_encoding2.sort_descending();
222    println!("   Descending: {:?}", accept_encoding2.items());
223
224    // Sort back to ascending
225    accept_encoding2.sort_ascending();
226    println!("   Ascending: {:?}", accept_encoding2.items());
227
228    println!("\n3f. Practical example - Content negotiation:");
229    practical_content_negotiation_example();
230}
231
232/// A practical example showing how to use these functions for content negotiation
233fn practical_content_negotiation_example() {
234    // Simulate a client's Accept-Encoding header
235    let client_header = "br;q=1.0, gzip;q=0.8, deflate;q=0.6, *;q=0.1";
236    println!("   Client Accept-Encoding: {}", client_header);
237
238    // Server supported encodings (in order of preference)
239    let server_supported = vec![Encoding::Gzip, Encoding::Deflate, Encoding::Identity];
240    println!("   Server supported: {:?}", server_supported);
241
242    // Parse client preferences
243    if let Ok(client_encodings) = decode_header_value(client_header) {
244        if let Ok(mut accept_encoding) = AcceptEncoding::new(client_encodings) {
245            // Sort by client preference (highest quality first)
246            accept_encoding.sort_descending();
247
248            // Find the best match
249            let mut selected_encoding = None;
250            for (encoding, quality) in accept_encoding.items() {
251                if server_supported.contains(encoding) && *quality > 0.0 {
252                    selected_encoding = Some(encoding);
253                    break;
254                }
255            }
256
257            match selected_encoding {
258                Some(encoding) => {
259                    println!("   Selected encoding: {}", encoding);
260                    println!("   Server should use Content-Encoding: {}", encoding);
261                }
262                None => println!("   No acceptable encoding found"),
263            }
264        }
265    }
266}
basic_usage/basic_usage.rs

basic_usage/
basic_usage.rs
