bwrap 1.3.0

A fast, lightweight, embedded systems-friendly library for wrapping text.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

// Copyright (C) 2023 Michael Lee <micl2e2@proton.me>
//
// Licensed under the MIT License <LICENSE-MIT or
// https://opensource.org/license/mit> or the GNU General Public License,
// Version 3.0 or any later version <LICENSE-GPL or
// https://www.gnu.org/licenses/gpl-3.0.txt>, at your option.
//
// This file may not be copied, modified, or distributed except except in
// compliance with either of the licenses.
//

//!
//! A fast, lightweight, embedded systems-friendly library for wrapping text.
//!
//! While Bwrap offers great flexibility in wrapping text, neither resource
//! consumption nor performance compromises:
//!
//! 1. No heap allocation happens by default.
//! 2. The time/space complexity is *O(n)* by default, or *O(n(p+a))* if there
//! is appending/prepending. (n, p, a is the number of input/prepended/appended
//! bytes respectively)
//!
//! For the sake of readability, we (**b**)etter **wrap** our text.
//!
//! # Features
//!
//! `use_std`: Use standard library for automatic memory management. (disable by default)
//!
//! # Examples
//!
//! _Note: These examples require `use_std` feature_.
//!
//! ---
//!
//! Wrap a long line of text:
//!
//! ```
//! let original = "
//! one two three one two three one two three
//! ";
//! let wrapped = bwrap::wrap!(original, 13);
//!
//! let expected = "
//! one two three
//! one two three
//! one two three
//! ";
//! assert_eq!(wrapped, expected);
//! ```
//!
//! Format CLI error messages:
//!
//! ```
//! let original = "
//! error: TLS handshake erorr.
//!   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.
//! ";
//! let wrapped = bwrap::wrap_nobrk!(original, 38, "       ");
//!
//! let expected = "
//! error: TLS handshake erorr.
//!   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.
//! ";
//! assert_eq!(wrapped, expected);
//! ```
//!
//! Format a bullet list:
//! ```
//! let original = "
//! Here is our schedule:
//! - Do A, and do B, and do C, and do D, and do E, and do F
//! - Do G, and do H, and do I, and do J, and do K, and do L
//! ";
//! let wrapped = bwrap::wrap_nobrk!(original, 35, "  ");
//!
//! let expected = "
//! Here is our schedule:
//! - Do A, and do B, and do C, and do
//!   D, and do E, and do F
//! - Do G, and do H, and do I, and do
//!   J, and do K, and do L
//! ";
//! assert_eq!(wrapped, expected);
//! ```
//!
//! Trailing notation:
//!
//! ```
//! let original = "
//! VGhpcyBpcyBhIHNlY3JldCBtZXNzYWdlLCBwbGVhc2UgZGVsZXRlIGFmdGVyIHJlYWQK
//! ";
//! let wrapped = bwrap::wrap_maybrk!(original, 10, " |");
//!
//! let expected = "
//! VGhpcyBpcy |
//! BhIHNlY3Jl |
//! dCBtZXNzYW |
//! dlLCBwbGVh |
//! c2UgZGVsZX |
//! RlIGFmdGVy |
//! IHJlYWQK
//! ";
//! assert_eq!(wrapped, expected);
//! ```
//!
//! More exmaples/benchmark can be found in [repository](https://github.com/micl2e2/bwrap).
//!
//!

#![no_std]
#![cfg_attr(doc_cfg, feature(doc_cfg))]
// #![feature(doc_auto_cfg)] // DEBUG ONLY

#[cfg(any(feature = "use_std"))]
extern crate std;

mod error;

pub use error::Result;
pub use error::WrapError;

mod auxbuf;
#[cfg_attr(doc_cfg, doc(cfg(feature = "use_std")))]
#[cfg(feature = "use_std")]
mod easy_wrapper;
mod wrapper;

pub use wrapper::ExistNlPref;
pub use wrapper::WrapStyle;
pub use wrapper::Wrapper;

#[cfg_attr(doc_cfg, doc(cfg(feature = "use_std")))]
#[cfg(feature = "use_std")]
pub use easy_wrapper::EasyWrapper;

#[macro_use]
mod public_macros;