bwrap/
lib.rs

1// Copyright (C) 2023 Michael Lee <micl2e2@proton.me>
2//
3// Licensed under the MIT License <LICENSE-MIT or
4// https://opensource.org/license/mit> or the GNU General Public License,
5// Version 3.0 or any later version <LICENSE-GPL or
6// https://www.gnu.org/licenses/gpl-3.0.txt>, at your option.
7//
8// This file may not be copied, modified, or distributed except except in
9// compliance with either of the licenses.
10//
11
12//!
13//! A fast, lightweight, embedded systems-friendly library for wrapping text.
14//!
15//! While Bwrap offers great flexibility in wrapping text, neither resource
16//! consumption nor performance compromises:
17//!
18//! 1. No heap allocation happens by default.
19//! 2. The time/space complexity is *O(n)* by default, or *O(n(p+a))* if there
20//! is appending/prepending. (n, p, a is the number of input/prepended/appended
21//! bytes respectively)
22//!
23//! For the sake of readability, we (**b**)etter **wrap** our text.
24//!
25//! # Features
26//!
27//! `use_std`: Use standard library for automatic memory management. (disable by default)
28//!
29//! # Examples
30//!
31//! _Note: These examples require `use_std` feature_.
32//!
33//! ---
34//!
35//! Wrap a long line of text:
36//!
37//! ```
38//! let original = "
39//! one two three one two three one two three
40//! ";
41//! let wrapped = bwrap::wrap!(original, 13);
42//!
43//! let expected = "
44//! one two three
45//! one two three
46//! one two three
47//! ";
48//! assert_eq!(wrapped, expected);
49//! ```
50//!
51//! Format CLI error messages:
52//!
53//! ```
54//! let original = "
55//! error: TLS handshake erorr.
56//!   tip: Probably because of instable network connection, please try these solutions: Retry the connection; Use another different network; Use another version of TLS; Reboot your system; Reinstall your system; Give up.
57//! ";
58//! let wrapped = bwrap::wrap_nobrk!(original, 38, "       ");
59//!
60//! let expected = "
61//! error: TLS handshake erorr.
62//!   tip: Probably because of instable
63//!        network connection, please try these
64//!        solutions: Retry the connection; Use
65//!        another different network; Use another
66//!        version of TLS; Reboot your system;
67//!        Reinstall your system; Give up.
68//! ";
69//! assert_eq!(wrapped, expected);
70//! ```
71//!
72//! Format a bullet list:
73//! ```
74//! let original = "
75//! Here is our schedule:
76//! - Do A, and do B, and do C, and do D, and do E, and do F
77//! - Do G, and do H, and do I, and do J, and do K, and do L
78//! ";
79//! let wrapped = bwrap::wrap_nobrk!(original, 35, "  ");
80//!
81//! let expected = "
82//! Here is our schedule:
83//! - Do A, and do B, and do C, and do
84//!   D, and do E, and do F
85//! - Do G, and do H, and do I, and do
86//!   J, and do K, and do L
87//! ";
88//! assert_eq!(wrapped, expected);
89//! ```
90//!
91//! Trailing notation:
92//!
93//! ```
94//! let original = "
95//! VGhpcyBpcyBhIHNlY3JldCBtZXNzYWdlLCBwbGVhc2UgZGVsZXRlIGFmdGVyIHJlYWQK
96//! ";
97//! let wrapped = bwrap::wrap_maybrk!(original, 10, " |");
98//!
99//! let expected = "
100//! VGhpcyBpcy |
101//! BhIHNlY3Jl |
102//! dCBtZXNzYW |
103//! dlLCBwbGVh |
104//! c2UgZGVsZX |
105//! RlIGFmdGVy |
106//! IHJlYWQK
107//! ";
108//! assert_eq!(wrapped, expected);
109//! ```
110//!
111//! More exmaples/benchmark can be found in [repository](https://github.com/micl2e2/bwrap).
112//!
113//!
114
115#![no_std]
116#![cfg_attr(doc_cfg, feature(doc_cfg))]
117// #![feature(doc_auto_cfg)] // DEBUG ONLY
118
119#[cfg(any(feature = "use_std"))]
120extern crate std;
121
122mod error;
123
124pub use error::Result;
125pub use error::WrapError;
126
127mod auxbuf;
128#[cfg_attr(doc_cfg, doc(cfg(feature = "use_std")))]
129#[cfg(feature = "use_std")]
130mod easy_wrapper;
131mod wrapper;
132
133pub use wrapper::ExistNlPref;
134pub use wrapper::WrapStyle;
135pub use wrapper::Wrapper;
136
137#[cfg_attr(doc_cfg, doc(cfg(feature = "use_std")))]
138#[cfg(feature = "use_std")]
139pub use easy_wrapper::EasyWrapper;
140
141#[macro_use]
142mod public_macros;
bwrap/lib.rs

bwrap/
lib.rs
