utf8_iter/lib.rs
1// Copyright Mozilla Foundation
2//
3// Licensed under the Apache License (Version 2.0), or the MIT license,
4// (the "Licenses") at your option. You may not use this file except in
5// compliance with one of the Licenses. You may obtain copies of the
6// Licenses at:
7//
8// https://www.apache.org/licenses/LICENSE-2.0
9// https://opensource.org/licenses/MIT
10//
11// Unless required by applicable law or agreed to in writing, software
12// distributed under the Licenses is distributed on an "AS IS" BASIS,
13// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14// See the Licenses for the specific language governing permissions and
15// limitations under the Licenses.
16
17#![no_std]
18#![warn(missing_docs)]
19#![deny(unsafe_code)] // overridden in `str.rs`
20
21//! Provides iteration by `char` over `&[u8]` containing potentially-invalid
22//! UTF-8 such that errors are handled according to the [WHATWG Encoding
23//! Standard](https://encoding.spec.whatwg.org/#utf-8-decoder) (i.e. the same
24//! way as in `String::from_utf8_lossy`).
25//!
26//! The trait `Utf8CharsEx` provides the convenience method `chars()` on
27//! byte slices themselves instead of having to use the more verbose
28//! `Utf8Chars::new(slice)`.
29//!
30//! ```rust
31//! use utf8_iter::Utf8CharsEx;
32//! let data = b"\xFF\xC2\xE2\xE2\x98\xF0\xF0\x9F\xF0\x9F\x92\xE2\x98\x83";
33//! let from_iter: String = data.chars().collect();
34//! let from_std = String::from_utf8_lossy(data);
35//! assert_eq!(from_iter, from_std);
36//! ```
37
38mod basic;
39mod handler;
40mod indices;
41mod macros;
42mod report;
43mod str;
44
45pub use crate::basic::DefaultHandler;
46pub use crate::basic::Utf8CharIndices;
47pub use crate::basic::Utf8Chars;
48pub use crate::basic::Utf8CharsEx;
49pub use crate::handler::Utf8CharsWithHandler;
50pub use crate::handler::Utf8Handler;
51pub use crate::indices::CharIndicesWithHandler;
52pub use crate::indices::Utf8CharIndicesWithHandler;
53pub use crate::report::ErrorReportingUtf8CharIndices;
54pub use crate::report::ErrorReportingUtf8Chars;
55pub use crate::report::Utf8CharsError;
56pub use crate::str::CharsWithHandler;