tabled/settings/width/
mod.rs

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}
tabled/settings/width/mod.rs

tabled/settings/width/
mod.rs
