Crate basic_text[−][src]
Expand description
Basic Text strings and I/O streams
This crate provides several utilities for working with Basic Text.
-
TextString
andTextStr
are similar to the standard library’sString
andstr
, but use the Basic Text string format, along with atext!("...")
macro for Basic Text string literals. -
TextReader
andTextWriter
are input and output streams which use the Basic Text stream format. On input, content is converted in a way which is lossy with respect to the original bytestream. Output uses the “strict” conversion method, in which invalid content is diagnosed with errors. -
BufReadText
, an extension trait that addstext_lines
andtext_lines_lossy
toBufRead
implementations for reading lines from an input stream asBasicText
strings. -
TextDuplexer
is aDuplex
for reading and writing on an interactive stream using Basic Text.
Examples
Working with TextString
and company is overall similar to working with
String
and company, but with a little more syntax in some places:
use basic_text::{text, text_substr, ReadText, TextReader, TextString, TextWriter, WriteText};
use std::io::{stdin, stdout, Write};
// Wrap stdout in an output stream that ensures that the output is
// Basic Text.
let mut stream = TextWriter::new(stdout());
// Construct Basic Text literals.
let greeting = text!("Hello, World!");
// Write Basic Text directly.
stream.write_text(greeting).unwrap();
// `TextString` can't be split at arbitrary boundaries, so this crate has
// substring types, so you can work with Basic Text content incrementally.
// The following code prints the "Service Dog" ZWJ Sequence "🐕🦺" in
// parts, where splitting it would not be valid in Basic Text.
stream
.write_text_substr(text_substr!("🐕\u{200d}"))
.unwrap();
stream.write_text_substr(text_substr!("🦺")).unwrap();
// Regular strings with Basic Text content can be written.
writeln!(stream, "Valid!").unwrap();
// But invalid content is diagnosed as an error.
writeln!(stream, "\u{c}Invalid!\u{7}").unwrap_err();
// A Basic Text reader, on the other hand, always succeeds, by replacing
// invalid sequences with `�`s.
let mut s = TextString::new();
TextReader::new(stdin())
.read_to_text_string(&mut s)
.unwrap();
Macros
TextStr
literal support: text!("string literal")
.
TextSubstr
literal support: text_substr!("string literal\u{200e}")
.
Structs
FromTextError
is to TextString
as FromUtf8Error
is to String
.
A HalfDuplex
implementation which translates from an input HalfDuplex
implementation producing an arbitrary byte sequence into a valid Basic Text
stream.
TextError
is to TextString
as Utf8Error
is to String
.
An iterator over the lines of an instance of BufReadText
.
An iterator over the lines of an instance of BufReadText
.
A Read
implementation which translates from an input Read
implementation producing an arbitrary byte sequence into a valid Basic Text
stream.
Text slices.
A Basic Text encoded, growable string.
Text substring slices.
A substring of a Basic Text string or stream.
A WriteLayered
implementation which translates to an output
WriteLayered
producing a valid Basic Text stream from an arbitrary
byte sequence.
Constants
The minimum size of a buffer needed to perform NFC normalization, and thus
the minimum size needed to pass to TextReader
’s read
.
Traits
An extension trait for BufRead
which adds functions for reading
lines as TextString
s.
Add a convenience method for reading Basic Text content.
Extend the ReadLayered
trait with read_text_with_status
, a method for
reading text data.
Add a convenience method for reading into TextStr
.
Functions
Like std::io::copy
, but for streams that can operate directly on text
strings, so we can avoid re-validating them as text.
Like std::io::copy
, but for streams that can operate directly on text
strings, so we can avoid re-validating them as text.
Default implementation of ReadText::read_exact_text_substr
.
Default implementation of ReadText::read_to_text_string
.
Default implementation of WriteText::write_text_substr
.