Crate basic_text

source ·
Expand description

Basic Text strings and I/O streams

This crate provides several utilities for working with Basic Text.

  • TextString and TextStr are similar to the standard library’s String and str, but use the Basic Text string format, along with a text!("...") macro for Basic Text string literals.

  • TextReader and TextWriter 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 adds text_lines and text_lines_lossy to BufRead implementations for reading lines from an input stream as BasicText strings.

  • TextDuplexer is a Duplex 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§

  • text
    TextStr literal support: text!("string literal").
  • text_substr
    TextSubstr literal support: text_substr!("string literal\u{200e}").

Structs§

  • FromTextError
    FromTextError is to TextString as FromUtf8Error is to String.
  • TextDuplexer
    A HalfDuplex implementation which translates from an input HalfDuplex implementation producing an arbitrary byte sequence into a valid Basic Text stream.
  • TextError
    TextError is to TextString as Utf8Error is to String.
  • TextLines
    An iterator over the lines of an instance of BufReadText.
  • TextLinesLossy
    An iterator over the lines of an instance of BufReadText.
  • TextReader
    A Read implementation which translates from an input Read implementation producing an arbitrary byte sequence into a valid Basic Text stream.
  • TextStr
    Text slices.
  • TextString
    A Basic Text encoded, growable string.
  • TextSubstr
    Text substring slices.
  • TextSubstring
    A substring of a Basic Text string or stream.
  • TextWriter
    A WriteLayered implementation which translates to an output WriteLayered producing a valid Basic Text stream from an arbitrary byte sequence.

Constants§

Traits§

  • BufReadText
    An extension trait for BufRead which adds functions for reading lines as TextStrings.
  • ReadText
    Add a convenience method for reading Basic Text content.
  • ReadTextLayered
    Extend the ReadLayered trait with read_text_with_status, a method for reading text data.
  • WriteText
    Add a convenience method for reading into TextStr.

Functions§