codepage_437/
lib.rs

1//! Conversion to and from codepage 437.
2//!
3//! Use the `{Borrow,}FromCp437` traits to convert series of cp437 bytes to Unicode,
4//! and the `cp437_to_unicode()` function to decode a single codepoint.
5//!
6//! Use the `{Into,To}Cp437` traits to convert Unicode to a series of cp437 bytes,
7//! and the `unicode_to_cp437()` function to encode a single codepoint.
8//!
9//! # Examples
10//!
11//! Borrowing from a buffer:
12//!
13//! ```
14//! # use codepage_437::{CP437_CONTROL, BorrowFromCp437};
15//! # use std::borrow::Cow;
16//! # /*
17//! let data = &[/* buffer acquired somewhere */];
18//! # */
19//! # let data = &[0x4C, 0x6F, 0x63, 0x61, 0x6C, 0x20, 0x6E, 0x65, 0x77, 0x73];
20//!
21//! /// in_unicode will be Cow::Borrowed if data only contains overlapping characters,
22//! ///                 or Cow::Owned if a conversion needed to have been made.
23//! let in_unicode = Cow::borrow_from_cp437(data, &CP437_CONTROL);
24//! # assert_eq!(in_unicode, "Local news");
25//!
26//! // Also valid:
27//! let in_unicode = String::borrow_from_cp437(data, &CP437_CONTROL);
28//! # assert_eq!(in_unicode, "Local news");
29//! ```
30//!
31//! Moving out of a buffer:
32//!
33//! ```
34//! # use codepage_437::{CP437_CONTROL, FromCp437};
35//! # /*
36//! let data = vec![/* buffer moved in from somewhere */];
37//! # */
38//! # let data = vec![0x4C, 0x6F, 0x63, 0x61, 0x6C, 0x20, 0x6E, 0x65, 0x77, 0x73];
39//!
40//! /// data is moved out of and zero-alloced into in_unicode
41//! ///      if it only contains overlapping characters
42//! let in_unicode = String::from_cp437(data, &CP437_CONTROL);
43//! # assert_eq!(in_unicode, "Local news");
44//! ```
45//!
46//! Borrowing from a `&str`:
47//!
48//! ```
49//! # use codepage_437::{CP437_CONTROL, ToCp437};
50//! let data = "Some string.";
51//!
52//! /// in_cp437 will be Cow::Borrowed if data only contains overlapping characters,
53//! ///                  Cow::Owned if a conversion needed to have been made,
54//! ///               or Err, if data can't be represented as cp437
55//! let in_cp437 = data.to_cp437(&CP437_CONTROL);
56//! # assert_eq!(in_cp437, Ok([0x53, 0x6F, 0x6D, 0x65, 0x20, 0x73, 0x74, 0x72, 0x69, 0x6E, 0x67, 0x2E][..].into()));
57//!
58//! // Also valid (String is AsRef<str>):
59//! let data = "Some string.".to_string();
60//! let in_cp437 = data.to_cp437(&CP437_CONTROL);
61//! # assert_eq!(in_cp437, Ok([0x53, 0x6F, 0x6D, 0x65, 0x20, 0x73, 0x74, 0x72, 0x69, 0x6E, 0x67, 0x2E][..].into()));
62//! ```
63//!
64//! Moving out of a `String`:
65//!
66//! ```
67//! # use codepage_437::{CP437_CONTROL, IntoCp437};
68//! let data = "Some string.".to_string();
69//!
70//! /// data is moved out of and zero-alloced into in_cp437
71//! ///      if it only contains overlapping characters
72//! let in_cp437 = data.into_cp437(&CP437_CONTROL);
73//! # assert_eq!(in_cp437, Ok([0x53, 0x6F, 0x6D, 0x65, 0x20, 0x73, 0x74, 0x72, 0x69, 0x6E, 0x67, 0x2E][..].into()));
74//! ```
75//!
76//! Unrepresentable Unicode:
77//!
78//! ```
79//! # use codepage_437::{CP437_CONTROL, ToCp437};
80//! // Ż has no representation in cp437
81//! let data = "Jurek żelaznym żurkiem żre żupan.";
82//!
83//! let result = data.to_cp437(&CP437_CONTROL);
84//! assert!(result.is_err());
85//! // result.unwrap_err() is Cp437Error (or IntoCp437Error for into_cp437()),
86//! //   with an API modeled after libstd's {From,}Utf8Error
87//! # assert_eq!(result.unwrap_err().representable_up_to, 6);
88//! ```
89
90
91mod decode;
92mod encode;
93mod dialect;
94
95pub use self::dialect::*;
96pub use self::decode::{BorrowFromCp437, FromCp437};
97pub use self::encode::{IntoCp437Error, Cp437Error, IntoCp437, ToCp437};
codepage_437/lib.rs

codepage_437/
lib.rs
