lz_str/
lib.rs

1#![forbid(unsafe_code)]
2#![deny(missing_docs)]
3#![warn(clippy::cast_lossless)]
4#![warn(clippy::cast_possible_wrap)]
5#![warn(clippy::cast_possible_truncation)]
6
7//! A port of [lz-string](https://github.com/pieroxy/lz-string) to Rust.
8//!
9//!
10//! # Example
11//! ```rust
12//! # // The demonstrated functions correspond with `LZString.compress` and `LZString.decompress` from the JS version.
13//! # fn main() {
14//!     let data = "The quick brown fox jumps over the lazy dog";
15//!
16//!     // Compress the data. This cannot fail.
17//!     let compressed_data = lz_str::compress(data);
18//!
19//!     // Decompress the data.
20//!     // This may return `Option::None` if it fails.
21//!     // Make sure to do error-checking in a real application to prevent crashes!
22//!     let decompressed_data =
23//!         lz_str::decompress(compressed_data).expect("`compressed_data` is invalid");
24//!
25//!     // The decompressed_data should be the same as data, except encoded as UTF16.
26//!     // We undo that here.
27//!     // In a real application,
28//!     // you will want to do error checking to prevent users from causing crashes with invalid data.
29//!     let decompressed_data =
30//!         String::from_utf16(&decompressed_data).expect("`decompressed_data` is not valid UTF16");
31//!
32//!     assert!(data == decompressed_data);
33//! # }
34//! ```
35//!
36//! # Passing and Recieving Data
37//! The original library uses invalid UTF16 strings to represent data.
38//! To maintain compatability, this library uses a [`Vec`] of [`u16`]s instead of Rust strings where applicable.
39//! The [`IntoWideIter`] trait exists to ease the passing of data into functions.
40//! Most functions accept this generic parameter instead of a concrete type.
41//! Look at this trait's documentation to see what types this trait is implemented for.
42
43mod compress;
44mod constants;
45mod decompress;
46
47pub use crate::compress::compress;
48pub use crate::compress::compress_internal;
49pub use crate::compress::compress_to_base64;
50pub use crate::compress::compress_to_encoded_uri_component;
51pub use crate::compress::compress_to_uint8_array;
52pub use crate::compress::compress_to_utf16;
53pub use crate::decompress::decompress;
54pub use crate::decompress::decompress_from_base64;
55pub use crate::decompress::decompress_from_encoded_uri_component;
56pub use crate::decompress::decompress_from_uint8_array;
57pub use crate::decompress::decompress_from_utf16;
58pub use crate::decompress::decompress_internal;
59
60/// A trait to make it easier to pass arguments to functions.
61pub trait IntoWideIter {
62    /// The Iterator type
63    type Iter: Iterator<Item = u16>;
64
65    /// Convert this object into something that yields possibly invalid wide characters.
66    fn into_wide_iter(self) -> Self::Iter;
67}
68
69impl<'a> IntoWideIter for &'a str {
70    type Iter = std::str::EncodeUtf16<'a>;
71
72    #[inline]
73    fn into_wide_iter(self) -> Self::Iter {
74        self.encode_utf16()
75    }
76}
77
78impl<'a> IntoWideIter for &&'a str {
79    type Iter = std::str::EncodeUtf16<'a>;
80
81    #[inline]
82    fn into_wide_iter(self) -> Self::Iter {
83        self.encode_utf16()
84    }
85}
86
87impl<'a> IntoWideIter for &'a String {
88    type Iter = std::str::EncodeUtf16<'a>;
89
90    #[inline]
91    fn into_wide_iter(self) -> Self::Iter {
92        self.as_str().encode_utf16()
93    }
94}
95
96impl<'a> IntoWideIter for &'a [u16] {
97    type Iter = std::iter::Copied<std::slice::Iter<'a, u16>>;
98
99    #[inline]
100    fn into_wide_iter(self) -> Self::Iter {
101        self.iter().copied()
102    }
103}
104
105// TODO: Remove this in the next version.
106// We do not benefit from taking ownership of the buffer.
107impl IntoWideIter for Vec<u16> {
108    type Iter = std::vec::IntoIter<u16>;
109
110    #[inline]
111    fn into_wide_iter(self) -> Self::Iter {
112        self.into_iter()
113    }
114}
115
116impl<'a> IntoWideIter for &'a Vec<u16> {
117    type Iter = std::iter::Copied<std::slice::Iter<'a, u16>>;
118
119    #[inline]
120    fn into_wide_iter(self) -> Self::Iter {
121        self.iter().copied()
122    }
123}
124
125#[cfg(test)]
126mod test {
127    use super::*;
128
129    #[test]
130    fn into_wide_iter_check() {
131        const DATA: &str = "test argument";
132        let expected: Vec<u16> = DATA.encode_utf16().collect();
133
134        fn check(arg: impl IntoWideIter, expected: &[u16]) {
135            let arg: Vec<u16> = arg.into_wide_iter().collect();
136            assert!(arg == expected);
137        }
138
139        {
140            let data: &str = DATA;
141            check(data, &expected);
142        }
143
144        {
145            let data: &&str = &DATA;
146            check(data, &expected);
147        }
148
149        // TODO: Should IntoWideIter be implemented for String?
150        // It's always better to pass an &str or an &String, so users should be forced to do that?
151        // {
152        //     let data: String = DATA.into();
153        //     check(data, &expected);
154        // }
155
156        {
157            let data: String = DATA.into();
158            let data: &String = &data;
159            check(data, &expected);
160        }
161
162        {
163            let data: Vec<u16> = DATA.encode_utf16().collect();
164            let data: &[u16] = &data;
165            check(data, &expected);
166        }
167
168        {
169            let data: Vec<u16> = DATA.encode_utf16().collect();
170            check(data, &expected);
171        }
172
173        {
174            let data: Vec<u16> = DATA.encode_utf16().collect();
175            let data: &Vec<u16> = &data;
176            check(data, &expected);
177        }
178    }
179}
lz_str/lib.rs

lz_str/
lib.rs
