1//! This module contains object which can be used to limit a cell to a given width:
2//!
3//! - [`Truncate`] cuts a cell content to limit width.
4//! - [`Wrap`] split the content via new lines in order to fit max width.
5//! - [`Justify`] sets columns width to the same value.
6//!
7//! To set a a table width, a combination of [`Width::truncate`] or [`Width::wrap`] and [`Width::increase`] can be used.
8//!
9//! ## Example
10//!
11//! ```
12//! use tabled::{Table, settings::Width};
13//!
14//! let table = Table::new(&["Hello World!"])
15//! .with(Width::wrap(7))
16//! .with(Width::increase(7))
17//! .to_string();
18//!
19//! assert_eq!(
20//! table,
21//! concat!(
22//! "+-----+\n",
23//! "| &st |\n",
24//! "| r |\n",
25//! "+-----+\n",
26//! "| Hel |\n",
27//! "| lo |\n",
28//! "| Wor |\n",
29//! "| ld! |\n",
30//! "+-----+",
31//! )
32//! );
33//! ```
34
35mod justify;
36mod min_width;
37mod truncate;
38mod util;
39mod width_list;
40mod wrap;
41
42use crate::settings::measurement::Measurement;
43
44pub use self::{
45 justify::Justify,
46 min_width::MinWidth,
47 truncate::{SuffixLimit, Truncate},
48 width_list::WidthList,
49 wrap::Wrap,
50};
51
52/// Width allows you to set a min and max width of an object on a [`Table`]
53/// using different strategies.
54///
55/// It also allows you to set a min and max width for a whole table.
56///
57/// You can apply a min and max strategy at the same time with the same value,
58/// the value will be a total table width.
59///
60/// It is an abstract factory.
61///
62/// Beware that borders are not removed when you set a size value to very small.
63/// For example if you set size to 0 the table still be rendered but with all content removed.
64///
65/// Also be aware that it doesn't changes [`Padding`] settings nor it considers them.
66///
67/// The function is color aware if a `color` feature is on.
68///
69/// ## Examples
70///
71/// ### Cell change
72///
73/// ```
74/// use tabled::{Table, settings::{object::Segment, Width, Style, Modify}};
75///
76/// let data = ["Hello", "World", "!"];
77///
78/// let table = Table::new(&data)
79/// .with(Style::markdown())
80/// .with(Modify::new(Segment::all()).with(Width::truncate(3).suffix("...")));
81/// ```
82///
83/// ### Table change
84///
85/// ```
86/// use tabled::{Table, settings::Width};
87///
88/// let table = Table::new(&["Hello World!"]).with(Width::wrap(5));
89/// ```
90///
91/// ### Total width
92///
93/// ```
94/// use tabled::{Table, settings::Width};
95///
96/// let table = Table::new(&["Hello World!"])
97/// .with(Width::wrap(5))
98/// .with(Width::increase(5));
99/// ```
100///
101/// [`Padding`]: crate::settings::Padding
102/// [`Table`]: crate::Table
103#[derive(Debug)]
104pub struct Width;
105
106impl Width {
107 /// Returns a [`Wrap`] structure.
108 pub fn wrap<W: Measurement<Width>>(width: W) -> Wrap<W> {
109 Wrap::new(width)
110 }
111
112 /// Returns a [`Truncate`] structure.
113 pub fn truncate<W: Measurement<Width>>(width: W) -> Truncate<'static, W> {
114 Truncate::new(width)
115 }
116
117 /// Returns a [`MinWidth`] structure.
118 pub fn increase<W: Measurement<Width>>(width: W) -> MinWidth<W> {
119 MinWidth::new(width)
120 }
121
122 /// Returns a [`Justify`] structure.
123 pub fn justify<W: Measurement<Width>>(width: W) -> Justify<W> {
124 Justify::new(width)
125 }
126
127 /// Create [`WidthList`] to set a table width to a constant list of column widths.
128 ///
129 /// Notice if you provide a list with `.len()` smaller than `Table::count_columns` then it will have no affect.
130 ///
131 /// Also notice that you must provide values bigger than or equal to a real content width, otherwise it may panic.
132 ///
133 /// # Example
134 ///
135 /// ```
136 /// use tabled::{Table, settings::Width};
137 ///
138 /// let data = vec![
139 /// ("Some\ndata", "here", "and here"),
140 /// ("Some\ndata on a next", "line", "right here"),
141 /// ];
142 ///
143 /// let table = Table::new(data)
144 /// .with(Width::list([20, 10, 12]))
145 /// .to_string();
146 ///
147 /// assert_eq!(
148 /// table,
149 /// "+--------------------+----------+------------+\n\
150 /// | &str | &str | &str |\n\
151 /// +--------------------+----------+------------+\n\
152 /// | Some | here | and here |\n\
153 /// | data | | |\n\
154 /// +--------------------+----------+------------+\n\
155 /// | Some | line | right here |\n\
156 /// | data on a next | | |\n\
157 /// +--------------------+----------+------------+"
158 /// )
159 /// ```
160 pub fn list<I: IntoIterator<Item = usize>>(rows: I) -> WidthList {
161 WidthList::new(rows.into_iter().collect())
162 }
163}
164