utf8_read/
lib.rs

1/*a Copyright
2
3Licensed under the Apache License, Version 2.0 (the "License");
4you may not use this file except in compliance with the License.
5You may obtain a copy of the License at
6
7  http://www.apache.org/licenses/LICENSE-2.0
8
9Unless required by applicable law or agreed to in writing, software
10distributed under the License is distributed on an "AS IS" BASIS,
11WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12See the License for the specific language governing permissions and
13limitations under the License.
14
15@file    lib.rs
16@brief   UTF-8 stream reader
17 */
18
19//a Documentation
20#![warn(missing_docs)]
21#![warn(missing_doc_code_examples)]
22
23/*!
24
25# UTF8 reader
26
27The `utf8-read` module provides a streaming `char` [Reader] that
28converts any stream with the [std::io::Read] into a stream of `char`
29values, performing UTF8 decoding incrementally.
30
31If the [std::io::Read] stream comes from a file then this is just a
32streaming version of (e.g.) std::fs::read_to_string, but if the it
33comes from, e.g., a [std::net::TcpStream] then it has more value:
34iterating through the characters of the stream will terminate when the
35TCP stream has stalled mid-UTF8, and can restart when the TCP stream
36gets more data.
37
38The [Reader] provided also allows for reading large UTF8 files
39piecewise; it only reads up to 2kB of data at a time from its stream.
40
41
42# Example
43
44An example use would be:
45
46```
47use utf8_read::Reader;
48let str = "This is a \u{1f600} string\nWith a newline\n";
49let mut buf_bytes = str.as_bytes();
50let mut reader    = Reader::new(&mut buf_bytes);
51for x in reader.into_iter() {
52    // use char x
53}
54
55```
56
57From a file, one could do:
58
59```
60use utf8_read::Reader;
61let in_file = std::fs::File::open("Cargo.toml").unwrap();
62let mut reader = Reader::new(&in_file);
63for x in reader.into_iter() {
64    // use char x
65}
66
67```
68
69!*/
70
71//a Imports
72mod types;
73mod stream_position;
74mod reader;
75
76//a Exports
77pub use types::{Char, Error, Result};
78pub use stream_position::StreamPosition;
79pub use reader::Reader;
utf8_read/lib.rs

utf8_read/
lib.rs
