Struct colonnade::Colonnade

pub struct Colonnade { /* fields omitted */ }

A struct holding formatting information. This is the object which tabulates data.

Methods

impl Colonnade

pub fn new(columns: usize, width: usize) -> Result<Colonnade, ColonnadeError>

Construct a Colonnade with default values: left alignment, no column size constraints, no blank lines between rows, 1 space margin between columns.

Arguments

• columns - The number of columns of data to expect
• width - Viewport size in characters

Errors

• ColonnadeError::InsufficientSpace - the viewport isn't wide enough for the columns and their margins

Example

let colonnade = Colonnade::new(4, 100);

pub fn tabulate(
    &mut self,
    table: &Vec<Vec<&str>>
) -> Result<Vec<String>, ColonnadeError>

Construct a Colonnade with default values: left alignment, no column size constraints, no blank lines between rows, 1 space margin between columns.

Arguments

• table - The data to display.

Errors

Any errors of lay_out. If the data has already been laid out, this method will throw no errors.

Example

let mut colonnade = Colonnade::new(4, 100)?;
let data = vec![vec!["some", "words", "for", "example"]];
let lines = colonnade.tabulate(&data)?;

pub fn lay_out(&mut self, table: &Vec<Vec<&str>>) -> Result<(), ColonnadeError>

Determine column widths given data.

Normally you do not need to call this method because it is called when you tabulate the first batch of data. However, this initial layout will then be used for every subsequent batch of data regardless of its size. If you want to re-flow the table to better fit the new data, you acn call layout.

Arguments

• table - The data to display.

Errors

• ColonnadeError::InconsistentColumns - The number of columns in some row of table does not match the spec.

Example

let mut colonnade = Colonnade::new(4, 100)?;
let data = vec![vec!["some", "words", "for", "example"]];
let lines = colonnade.tabulate(&data)?;
// ... later
let data = vec![vec!["a very different, wider", "set of", "words that won't fit comfortably in the old layout"]];
// reflow table
colonnade.lay_out(&data)?;
let lines = colonnade.tabulate(&data)?;

pub fn spaces_between_rows(&mut self, n: usize)

Specify a number of blank lines to insert between table rows.

Arguments

• n - A number of spaces.

Example

let mut colonnade = Colonnade::new(4, 100)?;
// we want rows to be separated by a single blank line
colonnade.spaces_between_rows(1);

pub fn priority_all(&mut self, priority: usize)

Assign the same priority to all columns. By default, all columns have the lowest priority.

Priority determines the order in which columns give up space when the viewport lacks sufficient space to display all columns without wrapping. Lower priority columns give up space first.

Arguments

• priority - The common priority. Lower numbers confer higher priority; 0 is the highest priority.

Example

let mut colonnade = Colonnade::new(4, 100)?;
// assign all columns the highest priority
colonnade.priority_all(0);
// now demote the last column
colonnade.priority(3, 1);

pub fn priority(
    &mut self,
    index: usize,
    priority: usize
) -> Result<(), ColonnadeError>

Assign a particular priority to a particular column.

Priority determines the order in which columns give up space when the viewport lacks sufficient space to display all columns without wrapping. Lower priority columns give up space first.

Arguments

• index - Which column to which you wish to assign priority.
• priority - The column's priority. Lower numbers confer higher priority; 0 is the highest priority.

Error

• ColonnadeError::OutOfBounds - The index is beyond the bounds of the spec.

Example

let mut colonnade = Colonnade::new(4, 100)?;
// assign all columns the highest priority
colonnade.priority_all(0);
// now demote the last column
colonnade.priority(3, 1)?;

pub fn max_width_all(&mut self, max_width: usize) -> Result<(), ColonnadeError>

Assign the same maximum width to all columns. By default columns have no maximum width.

Arguments

• max_width - The common maximum width.

Errors

• ColonnadeError::MinGreaterThanMax - Assigning a maximum width in conflict with some assigned minimum width.

Example

let mut colonnade = Colonnade::new(4, 100)?;
// assign all columns a maximum width of 20
colonnade.max_width_all(20)?;
// at most we will now use only 83 of the characters provided by the viewport (until we mess with margins)

pub fn max_width(
    &mut self,
    index: usize,
    max_width: usize
) -> Result<(), ColonnadeError>

Assign the same maximum width to all columns. By default columns have no maximum width.

Arguments

• max_width - The common maximum width.

Errors

• ColonnadeError::MinGreaterThanMax - Assigning a maximum width in conflict with some assigned minimum width.
• ColonnadeError::OutOfBounds - Attemping to assign a maximum width to a column that does not exist.

Example

let mut colonnade = Colonnade::new(4, 100)?;
// assign the first column a maximum width of 20
colonnade.max_width(0, 20)?;

pub fn min_width_all(&mut self, min_width: usize) -> Result<(), ColonnadeError>

Assign the same minimum width to all columns. By default columns have no minimum width.

Arguments

• min_width - The common minimum width.

Errors

• ColonnadeError::MinGreaterThanMax - Assigning a maximum width in conflict with some assigned minimum width.
• ColonnadeError::InsufficientSpace - Assigning this minimum width means the columns require more space than the viewport provides.

Example

let mut colonnade = Colonnade::new(4, 100)?;
// assign all columns a minimum width of 20
colonnade.min_width_all(20)?;
// we will now use at least 83 of the characters provided by the viewport (until we mess with margins)

pub fn min_width(
    &mut self,
    index: usize,
    min_width: usize
) -> Result<(), ColonnadeError>

Assign a particular minimum width to a particular column. By default columns have no minimum width.

Arguments

• index - The column to which we wish to assign a minimum width.
• min_width - The common minimum width.

Errors

• ColonnadeError::MinGreaterThanMax - Assigning a maximum width in conflict with some assigned minimum width.
• ColonnadeError::InsufficientSpace - Assigning this minimum width means the columns require more space than the viewport provides.
• ColonnadeError::OutOfBounds - The index is outside the columns in the spec.

Example

let mut colonnade = Colonnade::new(4, 100)?;
// assign the first column a minimum width of 20
colonnade.min_width(0, 20)?;

pub fn fixed_width_all(&mut self, width: usize) -> Result<(), ColonnadeError>

Assign the same maximum and minimum width to all columns. By default columns have neither a maximum nor a minimum width.

Arguments

• width - The common width.

Errors

This method is a convenience method which assigns all columns the same maximum and minimum width. Therefore the errors thrown are those thrown by max_width_all and min_width_all.

Example

let mut colonnade = Colonnade::new(4, 100)?;
// assign all columns a width of 20
colonnade.fixed_width_all(20)?;
// we will now use at exactly 83 of the characters provided by the viewport (until we mess with margins)

pub fn fixed_width(
    &mut self,
    index: usize,
    min_width: usize
) -> Result<(), ColonnadeError>

Assign a particular maximum and minimum width to a particular column. By default columns have neither a maximum nor a minimum width.

Arguments

• index - The column to configure.
• width - The common width.

Errors

This method is a convenience method which assigns the column in question the same maximum and minimum width. Therefore the errors thrown are those thrown by max_width and min_width.

Example

let mut colonnade = Colonnade::new(4, 100)?;
// assign the first column a width of 20
colonnade.fixed_width(0, 20)?;

pub fn clear_limits_all(&mut self)

Remove any maximum or minimum column widths.

Example

let mut colonnade = Colonnade::new(4, 100)?;
// assign all columns a width of 20
colonnade.fixed_width_all(20)?;
// later ...
colonnade.clear_limits_all();

pub fn clear_limits(&mut self, index: usize) -> Result<(), ColonnadeError>

Remove maximum or minimum column widths from a particular column.

Errors

• ColonnadeError::OutOfBounds - The column specified does not exist in the spec.

Example

let mut colonnade = Colonnade::new(4, 100)?;
// initially assign all columns a width of 20
colonnade.fixed_width_all(20);
// but we want the first column to be flexible
colonnade.clear_limits(0)?;

pub fn alignment_all(&mut self, alignment: Alignment)

Assign all columns the same alignment. The default alignment is left.

Arguments

• alignment - The desired alignment.

Example

let mut colonnade = Colonnade::new(4, 100)?;
// all columns should be right-aligned (they're numeric)
colonnade.alignment_all(Alignment::Right);

pub fn alignment(
    &mut self,
    index: usize,
    alignment: Alignment
) -> Result<(), ColonnadeError>

Assign a particular column a particular alignment. The default alignment is left.

Arguments

• index - The column to modify.
• alignment - The desired alignment.

Errors

• ColonnadeError::OutOfBounds - The column specified does not exist in the spec.

Example

let mut colonnade = Colonnade::new(4, 100)?;
// the first column should be right-aligned (it's numeric)
colonnade.alignment(0, Alignment::Right)?;

pub fn left_margin_all(
    &mut self,
    left_margin: usize
) -> Result<(), ColonnadeError>

Assign all columns the same left margin. The left margin is a number of blank spaces before the content of the column. By default the first column has a left margin of 0 and the other columns have a left margin of 1.

Arguments

• left_margin - The width in blank spaces of the desired margin.

Errors

• ColonnadeError::InsufficientSpace - This margin will require more space than is available in the viewport.

Example

let mut colonnade = Colonnade::new(4, 100)?;
// all columns should be preceded by 2 blank spaces
colonnade.left_margin_all(2)?;

pub fn left_margin(
    &mut self,
    index: usize,
    left_margin: usize
) -> Result<(), ColonnadeError>

Assign a particular column a particular left margin. The left margin is a number of blank spaces before the content of the column. By default the first column has a left margin of 0 and the other columns have a left margin of 1.

Arguments

• index - The column to configure.
• left_margin - The width in blank spaces of the desired margin.

Errors

• ColonnadeError::InsufficientSpace - This margin will require more space than is available in the viewport.
• ColonnadeError::OutOfBounds - The column specified does not exist in the spec.

Example

let mut colonnade = Colonnade::new(4, 100)?;
// the first column should be preceded by 2 blank spaces
colonnade.left_margin(0, 2)?;

Trait Implementations

impl Clone for Colonnade

fn clone(&self) -> Colonnade

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Colonnade

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.