Table

Table — container for rows and columns

Functions

struct libscols_table * scols_copy_table ()
struct libscols_table * scols_new_table ()
void scols_ref_table ()
int scols_sort_table ()
int scols_sort_table_by_tree ()
int scols_table_add_column ()
int scols_table_add_line ()
int scols_table_colors_wanted ()
int scols_table_enable_ascii ()
int scols_table_enable_colors ()
int scols_table_enable_export ()
int scols_table_enable_json ()
int scols_table_enable_maxout ()
int scols_table_enable_noheadings ()
int scols_table_enable_nolinesep ()
int scols_table_enable_nowrap ()
int scols_table_enable_raw ()
struct libscols_column * scols_table_get_column ()
const char * scols_table_get_column_separator ()
struct libscols_line * scols_table_get_line ()
const char * scols_table_get_line_separator ()
const char * scols_table_get_name ()
size_t scols_table_get_ncols ()
size_t scols_table_get_nlines ()
FILE * scols_table_get_stream ()
struct libscols_symbols * scols_table_get_symbols ()
int scols_table_get_termforce ()
size_t scols_table_get_termwidth ()
struct libscols_cell * scols_table_get_title ()
int scols_table_is_ascii ()
int scols_table_is_empty ()
int scols_table_is_export ()
int scols_table_is_json ()
int scols_table_is_maxout ()
int scols_table_is_noheadings ()
int scols_table_is_nolinesep ()
int scols_table_is_nowrap ()
int scols_table_is_raw ()
int scols_table_is_tree ()
int scols_table_move_column ()
struct libscols_column * scols_table_new_column ()
struct libscols_line * scols_table_new_line ()
int scols_table_next_column ()
int scols_table_next_line ()
int scols_table_reduce_termwidth ()
int scols_table_remove_column ()
int scols_table_remove_columns ()
int scols_table_remove_line ()
void scols_table_remove_lines ()
int scols_table_set_column_separator ()
int scols_table_set_default_symbols ()
int scols_table_set_line_separator ()
int scols_table_set_name ()
int scols_table_set_stream ()
int scols_table_set_symbols ()
int scols_table_set_termforce ()
int scols_table_set_termwidth ()
void scols_unref_table ()

Types and Values

Description

Table data manipulation API.

Functions

scols_copy_table ()

struct libscols_table *
scols_copy_table (struct libscols_table *tb);

Creates a new independent table copy, except struct libscols_symbols that are shared between the tables.

Parameters

tb

table

 

Returns

a newly allocated copy of tb


scols_new_table ()

struct libscols_table *
scols_new_table (void);

Returns

A newly allocated table.


scols_ref_table ()

void
scols_ref_table (struct libscols_table *tb);

Increases the refcount of tb .

Parameters

tb

a pointer to a struct libscols_table instance

 

scols_sort_table ()

int
scols_sort_table (struct libscols_table *tb,
                  struct libscols_column *cl);

Orders the table by the column. See also scols_column_set_cmpfunc(). If the tree output is enabled then children in the tree are recursively sorted too.

Parameters

tb

table

 

cl

order by this column

 

Returns

0, a negative value in case of an error.


scols_sort_table_by_tree ()

int
scols_sort_table_by_tree (struct libscols_table *tb);

Reorders lines in the table by parent->child relation. Note that order of the lines in the table is independent on the tree hierarchy.

Parameters

tb

table

 

Returns

0, a negative value in case of an error.

Since: 2.30


scols_table_add_column ()

int
scols_table_add_column (struct libscols_table *tb,
                        struct libscols_column *cl);

Adds cl to tb 's column list. The column cannot be shared between more tables.

Parameters

tb

a pointer to a struct libscols_table instance

 

cl

a pointer to a struct libscols_column instance

 

Returns

0, a negative number in case of an error.


scols_table_add_line ()

int
scols_table_add_line (struct libscols_table *tb,
                      struct libscols_line *ln);

Note that this function calls scols_line_alloc_cells() if number of the cells in the line is too small for tb .

Parameters

tb

table

 

ln

line

 

Returns

0, a negative value in case of an error.


scols_table_colors_wanted ()

int
scols_table_colors_wanted (const struct libscols_table *tb);

Parameters

tb

table

 

Returns

1 if colors are enabled.


scols_table_enable_ascii ()

int
scols_table_enable_ascii (struct libscols_table *tb,
                          int enable);

The ASCII-only output is relevant for tree-like outputs. The library checks if the current environment is UTF8 compatible by default. This function overrides this check and force the library to use ASCII chars for the tree.

If a custom libcols_symbols are specified (see scols_table_set_symbols() then ASCII flag setting is ignored.

Parameters

tb

table

 

enable

1 or 0

 

Returns

0 on success, negative number in case of an error.


scols_table_enable_colors ()

int
scols_table_enable_colors (struct libscols_table *tb,
                           int enable);

Enable/disable colors.

Parameters

tb

table

 

enable

1 or 0

 

Returns

0 on success, negative number in case of an error.


scols_table_enable_export ()

int
scols_table_enable_export (struct libscols_table *tb,
                           int enable);

Enable/disable export output format (COLUMNAME="value" ...). The parsable output formats (export and raw) are mutually exclusive.

Parameters

tb

table

 

enable

1 or 0

 

Returns

0 on success, negative number in case of an error.


scols_table_enable_json ()

int
scols_table_enable_json (struct libscols_table *tb,
                         int enable);

Enable/disable JSON output format. The parsable output formats (export, raw, JSON, ...) are mutually exclusive.

Parameters

tb

table

 

enable

1 or 0

 

Returns

0 on success, negative number in case of an error.

Since: 2.27


scols_table_enable_maxout ()

int
scols_table_enable_maxout (struct libscols_table *tb,
                           int enable);

The extra space after last column is ignored by default. The output maximization use the extra space for all columns.

Parameters

tb

table

 

enable

1 or 0

 

Returns

0 on success, negative number in case of an error.


scols_table_enable_noheadings ()

int
scols_table_enable_noheadings (struct libscols_table *tb,
                               int enable);

Enable/disable header line.

Parameters

tb

table

 

enable

1 or 0

 

Returns

0 on success, negative number in case of an error.


scols_table_enable_nolinesep ()

int
scols_table_enable_nolinesep (struct libscols_table *tb,
                              int enable);

Enable/disable line separator printing. This is useful if you want to re-printing the same line more than once (e.g. progress bar). Don't use it if you're not sure.

Parameters

tb

table

 

enable

1 or 0

 

Returns

0 on success, negative number in case of an error.


scols_table_enable_nowrap ()

int
scols_table_enable_nowrap (struct libscols_table *tb,
                           int enable);

Never continue on next line, remove last column(s) when too large, truncate last column.

Parameters

tb

table

 

enable

1 or 0

 

Returns

0 on success, negative number in case of an error.

Since: 2.28


scols_table_enable_raw ()

int
scols_table_enable_raw (struct libscols_table *tb,
                        int enable);

Enable/disable raw output format. The parsable output formats (export, raw, JSON, ...) are mutually exclusive.

Parameters

tb

table

 

enable

1 or 0

 

Returns

0 on success, negative number in case of an error.


scols_table_get_column ()

struct libscols_column *
scols_table_get_column (struct libscols_table *tb,
                        size_t n);

Parameters

tb

table

 

n

number of column (0..N)

 

Returns

pointer to column or NULL


scols_table_get_column_separator ()

const char *
scols_table_get_column_separator (const struct libscols_table *tb);

Parameters

tb

table

 

Returns

tb column separator, NULL in case of an error


scols_table_get_line ()

struct libscols_line *
scols_table_get_line (struct libscols_table *tb,
                      size_t n);

Parameters

tb

table

 

n

column number (0..N)

 

Returns

a line or NULL


scols_table_get_line_separator ()

const char *
scols_table_get_line_separator (const struct libscols_table *tb);

Parameters

tb

table

 

Returns

tb line separator, NULL in case of an error


scols_table_get_name ()

const char *
scols_table_get_name (const struct libscols_table *tb);

Parameters

tb

a pointer to a struct libscols_table instance

 

Returns

The current name setting of the table tb

Since: 2.29


scols_table_get_ncols ()

size_t
scols_table_get_ncols (const struct libscols_table *tb);

Parameters

tb

table

 

Returns

the ncols table member.


scols_table_get_nlines ()

size_t
scols_table_get_nlines (const struct libscols_table *tb);

Parameters

tb

table

 

Returns

the nlines table member.


scols_table_get_stream ()

FILE *
scols_table_get_stream (const struct libscols_table *tb);

Gets the output stream for table tb .

Parameters

tb

table

 

Returns

stream pointer, NULL in case of an error or an unset stream.


scols_table_get_symbols ()

struct libscols_symbols *
scols_table_get_symbols (const struct libscols_table *tb);

Parameters

tb

table

 

Returns

pointer to symbols table.

Since: 2.29


scols_table_get_termforce ()

int
scols_table_get_termforce (const struct libscols_table *tb);

Parameters

tb

table

 

Returns

SCOLS_TERMFORCE_{NEVER,ALWAYS,AUTO} or a negative value in case of an error.

Since: 2.29


scols_table_get_termwidth ()

size_t
scols_table_get_termwidth (const struct libscols_table *tb);

Parameters

tb

table

 

Returns

terminal width or a negative value in case of an error.


scols_table_get_title ()

struct libscols_cell *
scols_table_get_title (struct libscols_table *tb);

The returned pointer is possible to modify by cell functions. Note that title output alignment on non-tty is hardcoded to 80 output chars. For the regular terminal it's based on terminal width.

Parameters

tb

a pointer to a struct libscols_table instance

 

Returns

Title of the table, or NULL in case of blank title.

Since: 2.28


scols_table_is_ascii ()

int
scols_table_is_ascii (const struct libscols_table *tb);

Parameters

tb

table

 

Returns

1 if ASCII tree is enabled.


scols_table_is_empty ()

int
scols_table_is_empty (const struct libscols_table *tb);

Parameters

tb

table

 

Returns

1 if the table is empty.


scols_table_is_export ()

int
scols_table_is_export (const struct libscols_table *tb);

Parameters

tb

table

 

Returns

1 if export output format is enabled.


scols_table_is_json ()

int
scols_table_is_json (const struct libscols_table *tb);

Parameters

tb

table

 

Returns

1 if JSON output format is enabled.

Since: 2.27


scols_table_is_maxout ()

int
scols_table_is_maxout (const struct libscols_table *tb);

Parameters

tb

table

 

Returns

1 if output maximization is enabled or 0


scols_table_is_noheadings ()

int
scols_table_is_noheadings (const struct libscols_table *tb);

Parameters

tb

table

 

Returns

1 if header output is disabled.


scols_table_is_nolinesep ()

int
scols_table_is_nolinesep (const struct libscols_table *tb);

Parameters

tb

a pointer to a struct libscols_table instance

 

Returns

1 if line separator printing is disabled.

Since: 2.29


scols_table_is_nowrap ()

int
scols_table_is_nowrap (const struct libscols_table *tb);

Parameters

tb

a pointer to a struct libscols_table instance

 

Returns

1 if nowrap is enabled.

Since: 2.29


scols_table_is_raw ()

int
scols_table_is_raw (const struct libscols_table *tb);

Parameters

tb

table

 

Returns

1 if raw output format is enabled.


scols_table_is_tree ()

int
scols_table_is_tree (const struct libscols_table *tb);

Parameters

tb

table

 

Returns

returns 1 tree-like output is expected.


scols_table_move_column ()

int
scols_table_move_column (struct libscols_table *tb,
                         struct libscols_column *pre,
                         struct libscols_column *cl);

Move the cl behind pre . If the pre is NULL then the col is the first column in the table.

Parameters

tb

table

 

pre

column before the column

 

cl

colum to move

 

Returns

0, a negative number in case of an error.

Since: 2.30


scols_table_new_column ()

struct libscols_column *
scols_table_new_column (struct libscols_table *tb,
                        const char *name,
                        double whint,
                        int flags);

This is shortcut for

cl = scols_new_column(); scols_column_set_....(cl, ...); scols_table_add_column(tb, cl);

The column width is possible to define by:

whint : 0 < N < 1 : relative width, percent of terminal width

whint : N >= 1 : absolute width, empty column will be truncated to the column header width if no specified STRICTWIDTH flag

Note that if table has disabled "maxout" flag (disabled by default) than relative width is used as a hint only. It's possible that column will be narrow if the specified size is too large for column data.

If the width of all columns is greater than terminal width then library tries to reduce width of the individual columns. It's done in three stages:

#1 reduce columns with SCOLS_FL_TRUNC flag and with relative width if the width is greater than width defined by whint (whint * terminal_width)

#2 reduce all columns with SCOLS_FL_TRUNC flag

#3 reduce all columns with relative width

The next stage is always used if the previous stage is unsuccessful. Note that SCOLS_FL_WRAP is interpreted as SCOLS_FL_TRUNC when calculate column width (if custom wrap function is not specified), but the final text is not truncated, but wrapped to multi-line cell.

The column is necessary to address by sequential number. The first defined column has the colnum = 0. For example:

scols_table_new_column(tab, "FOO", 0.5, 0); // colnum = 0 scols_table_new_column(tab, "BAR", 0.5, 0); // colnum = 1 . . scols_line_get_cell(line, 0); // FOO column scols_line_get_cell(line, 1); // BAR column

Parameters

tb

table

 

name

column header

 

whint

column width hint (absolute width: N > 1; relative width: 0 < N < 1)

 

flags

flags integer

 

Returns

newly allocated column


scols_table_new_line ()

struct libscols_line *
scols_table_new_line (struct libscols_table *tb,
                      struct libscols_line *parent);

This is shortcut for

ln = scols_new_line(); scols_table_add_line(tb, ln); scols_line_add_child(parent, ln);

Parameters

tb

table

 

parent

parental line or NULL

 

Returns

newly allocate line


scols_table_next_column ()

int
scols_table_next_column (struct libscols_table *tb,
                         struct libscols_iter *itr,
                         struct libscols_column **cl);

Returns the next column of tb via cl .

Parameters

tb

a pointer to a struct libscols_table instance

 

itr

a pointer to a struct libscols_iter instance

 

cl

a pointer to a pointer to a struct libscols_column instance

 

Returns

0, a negative value in case of an error.


scols_table_next_line ()

int
scols_table_next_line (struct libscols_table *tb,
                       struct libscols_iter *itr,
                       struct libscols_line **ln);

Finds the next line and returns a pointer to it via ln .

Parameters

tb

a pointer to a struct libscols_table instance

 

itr

a pointer to a struct libscols_iter instance

 

ln

a pointer to a pointer to a struct libscols_line instance

 

Returns

0, a negative value in case of an error.


scols_table_reduce_termwidth ()

int
scols_table_reduce_termwidth (struct libscols_table *tb,
                              size_t reduce);

If necessary then libsmartcols use all terminal width, the reduce setting provides extra space (for example for borders in ncurses applications).

The reduce must be smaller than terminal width, otherwise it's silently ignored. The reduction is not applied when STDOUT_FILENO is not terminal.

Parameters

tb

table

 

reduce

width

 

Returns

0, a negative value in case of an error.


scols_table_remove_column ()

int
scols_table_remove_column (struct libscols_table *tb,
                           struct libscols_column *cl);

Removes cl from tb .

Parameters

tb

a pointer to a struct libscols_table instance

 

cl

a pointer to a struct libscols_column instance

 

Returns

0, a negative number in case of an error.


scols_table_remove_columns ()

int
scols_table_remove_columns (struct libscols_table *tb);

Removes all of tb 's columns.

Parameters

tb

a pointer to a struct libscols_table instance

 

Returns

0, a negative number in case of an error.


scols_table_remove_line ()

int
scols_table_remove_line (struct libscols_table *tb,
                         struct libscols_line *ln);

Note that this function does not destroy the parent<->child relationship between lines. You have to call scols_line_remove_child()

Parameters

tb

table

 

ln

line

 

Returns

0, a negative value in case of an error.


scols_table_remove_lines ()

void
scols_table_remove_lines (struct libscols_table *tb);

This empties the table and also destroys all the parent<->child relationships.

Parameters

tb

table

 

scols_table_set_column_separator ()

int
scols_table_set_column_separator (struct libscols_table *tb,
                                  const char *sep);

Sets the column separator of tb to sep .

Parameters

tb

table

 

sep

separator

 

Returns

0, a negative value in case of an error.


scols_table_set_default_symbols ()

int
scols_table_set_default_symbols (struct libscols_table *tb);

The library check the current environment to select ASCII or UTF8 symbols. This default behavior could be controlled by scols_table_enable_ascii().

Use scols_table_set_symbols() to unset symbols or use your own setting.

Parameters

tb

table

 

Returns

0, a negative value in case of an error.

Since: 2.29


scols_table_set_line_separator ()

int
scols_table_set_line_separator (struct libscols_table *tb,
                                const char *sep);

Sets the line separator of tb to sep .

Parameters

tb

table

 

sep

separator

 

Returns

0, a negative value in case of an error.


scols_table_set_name ()

int
scols_table_set_name (struct libscols_table *tb,
                      const char *name);

The table name is used for example for JSON top level object name.

Parameters

tb

a pointer to a struct libscols_table instance

 

name

a name

 

Returns

0, a negative number in case of an error.

Since: 2.27


scols_table_set_stream ()

int
scols_table_set_stream (struct libscols_table *tb,
                        FILE *stream);

Sets the output stream for table tb .

Parameters

tb

table

 

stream

output stream

 

Returns

0, a negative number in case of an error.


scols_table_set_symbols ()

int
scols_table_set_symbols (struct libscols_table *tb,
                         struct libscols_symbols *sy);

Add a reference to sy from the table. The symbols are used by library to draw tree output. If no symbols are used for the table then library creates default temporary symbols to draw output by scols_table_set_default_symbols().

If sy is NULL then remove reference from the currently used symbols.

Parameters

tb

table

 

sy

symbols or NULL

 

Returns

0, a negative value in case of an error.


scols_table_set_termforce ()

int
scols_table_set_termforce (struct libscols_table *tb,
                           int force);

Forces library to use stdout as terminal, non-terminal or use automatic detection (default).

Parameters

tb

table

 

force

SCOLS_TERMFORCE_{NEVER,ALWAYS,AUTO}

 

Returns

0, a negative value in case of an error.

Since: 2.29


scols_table_set_termwidth ()

int
scols_table_set_termwidth (struct libscols_table *tb,
                           size_t width);

The library automatically detects terminal width or defaults to 80 chars if detections is unsuccessful. This function override this behaviour.

Parameters

tb

table

 

width

terminal width

 

Returns

0, a negative value in case of an error.

Since: 2.29


scols_unref_table ()

void
scols_unref_table (struct libscols_table *tb);

Decreases the refcount of tb . When the count falls to zero, the instance is automatically deallocated.

Parameters

tb

a pointer to a struct libscols_table instance

 

Types and Values

struct libscols_table

struct libscols_table;

A table - The most abstract object, encapsulating lines, columns, symbols and cells