codepage-437

Code page 437 transcoding for Rust.

Documentation

lib.rs:

Conversion to and from codepage 437.

Use the {Borrow,}FromCp437 traits to convert series of cp437 bytes to Unicode, and the cp437_to_unicode() function to decode a single codepoint.

Use the {Into,To}Cp437 traits to convert Unicode to a series of cp437 bytes, and the unicode_to_cp437() function to encode a single codepoint.

Examples

Borrowing from a buffer:

let data = &[/* buffer acquired somewhere */];

/// in_unicode will be Cow::Borrowed if data only contains overlapping characters,
///                 or Cow::Owned if a conversion needed to have been made.
let in_unicode = Cow::borrow_from_cp437(data, &CP437_CONTROL);

// Also valid:
let in_unicode = String::borrow_from_cp437(data, &CP437_CONTROL);

Moving out of a buffer:

let data = vec![/* buffer moved in from somewhere */];

/// data is moved out of and zero-alloced into in_unicode
///      if it only contains overlapping characters
let in_unicode = String::from_cp437(data, &CP437_CONTROL);

Borrowing from a &str:

let data = "Some string.";

/// in_cp437 will be Cow::Borrowed if data only contains overlapping characters,
///                  Cow::Owned if a conversion needed to have been made,
///               or Err, if data can't be represented as cp437
let in_cp437 = data.to_cp437(&CP437_CONTROL);

// Also valid (String is AsRef<str>):
let data = "Some string.".to_string();
let in_cp437 = data.to_cp437(&CP437_CONTROL);

Moving out of a String:

let data = "Some string.".to_string();

/// data is moved out of and zero-alloced into in_cp437
///      if it only contains overlapping characters
let in_cp437 = data.into_cp437(&CP437_CONTROL);

Unrepresentable Unicode:

// Ż has no representation in cp437
let data = "Jurek żelaznym żurkiem żre żupan.";

let result = data.to_cp437(&CP437_CONTROL);
assert!(result.is_err());
// result.unwrap_err() is Cp437Error (or IntoCp437Error for into_cp437()),
//   with an API modeled after libstd's {From,}Utf8Error