Column

Column — defines output columns formats, headers, etc.

Functions

Types and Values

Description

An API to access and modify per-column data and information.

Functions

scols_column_get_color ()

const char *
scols_column_get_color (const struct libscols_column *cl);

Parameters

cl

a pointer to a struct libscols_column instance

 

Returns

The current color setting of the column cl .


scols_column_get_flags ()

int
scols_column_get_flags (const struct libscols_column *cl);

Parameters

cl

a pointer to a struct libscols_column instance

 

Returns

The flag mask of cl , a negative value in case of an error.


scols_column_get_header ()

struct libscols_cell *
scols_column_get_header (struct libscols_column *cl);

Parameters

cl

a pointer to a struct libscols_column instance

 

Returns

A pointer to a struct libscols_cell instance, representing the header info of column cl or NULL in case of an error.


scols_column_get_json_type ()

int
scols_column_get_json_type (const struct libscols_column *cl);

Note that SCOLS_JSON_BOOLEAN interprets NULL, empty strings, '0', 'N' and 'n' as "false"; and everything else as "true".

Parameters

cl

a pointer to a struct libscols_column instance

 

Returns

JSON type used for formatting or a negative value in case of an error.

Since: 2.33


scols_column_get_name ()

const char *
scols_column_get_name (struct libscols_column *cl);

Parameters

cl

a pointer to a struct libscols_column instance

 

Returns

A pointer to a column name, which is stored in column header

Since: 2.38


scols_column_get_name_as_shellvar ()

const char *
scols_column_get_name_as_shellvar (struct libscols_column *cl);

Like scols_column_get_name(), but column name is modified to be compatible with shells requirements for variable names.

Parameters

cl

a pointer to a struct libscols_column instance

 

Since: 2.38


scols_column_get_safechars ()

const char *
scols_column_get_safechars (const struct libscols_column *cl);

Parameters

cl

a pointer to a struct libscols_column instance

 

Returns

safe chars

Since: 2.29


scols_column_get_table ()

struct libscols_table *
scols_column_get_table (const struct libscols_column *cl);

Parameters

cl

a pointer to a struct libscols_column instance

 

Returns

pointer to the table where columns is used


scols_column_get_whint ()

double
scols_column_get_whint (const struct libscols_column *cl);

Parameters

cl

a pointer to a struct libscols_column instance

 

Returns

The width hint of column cl , a negative value in case of an error.


scols_column_get_width ()

size_t
scols_column_get_width (const struct libscols_column *cl);

Important note: the column width is unknown until library starts printing (width is calculated before printing). The function is usable for example in nextchunk() callback specified by scols_column_set_wrapfunc().

See also scols_column_get_whint(), it returns wanted size (!= final size).

Parameters

cl

a pointer to a struct libscols_column instance

 

Returns

column width

Since: 2.29


scols_column_is_customwrap ()

int
scols_column_is_customwrap (const struct libscols_column *cl);

Parameters

cl

a pointer to a struct libscols_column instance

 

Returns

0 or 1

Since: 2.29


scols_column_is_hidden ()

int
scols_column_is_hidden (const struct libscols_column *cl);

Gets the value of cl 's flag hidden.

Parameters

cl

a pointer to a struct libscols_column instance

 

Returns

0 or 1

Since: 2.27


scols_column_is_noextremes ()

int
scols_column_is_noextremes (const struct libscols_column *cl);

Gets the value of cl 's flag no_extremes.

Parameters

cl

a pointer to a struct libscols_column instance

 

Returns

0 or 1


scols_column_is_right ()

int
scols_column_is_right (const struct libscols_column *cl);

Gets the value of cl 's flag right.

Parameters

cl

a pointer to a struct libscols_column instance

 

Returns

0 or 1


scols_column_is_strict_width ()

int
scols_column_is_strict_width (const struct libscols_column *cl);

Gets the value of cl 's flag strict_width.

Parameters

cl

a pointer to a struct libscols_column instance

 

Returns

0 or 1


scols_column_is_tree ()

int
scols_column_is_tree (const struct libscols_column *cl);

Gets the value of cl 's flag tree.

Parameters

cl

a pointer to a struct libscols_column instance

 

Returns

0 or 1


scols_column_is_trunc ()

int
scols_column_is_trunc (const struct libscols_column *cl);

Gets the value of cl 's flag trunc.

Parameters

cl

a pointer to a struct libscols_column instance

 

Returns

0 or 1


scols_column_is_wrap ()

int
scols_column_is_wrap (const struct libscols_column *cl);

Gets the value of cl 's flag wrap.

Parameters

cl

a pointer to a struct libscols_column instance

 

Returns

0 or 1

Since: 2.28


scols_column_set_cmpfunc ()

int
scols_column_set_cmpfunc (struct libscols_column *cl,
                          int (*cmp) (struct libscols_cell *a, struct libscols_cell *b, void *),
                          void *data);

Parameters

cl

column

 

cmp

pointer to compare function

 

data

private data for cmp function

 

Returns

0, a negative value in case of an error.


scols_column_set_color ()

int
scols_column_set_color (struct libscols_column *cl,
                        const char *color);

The default color for data cells and column header.

If you want to set header specific color then use scols_column_get_header() and scols_cell_set_color().

If you want to set data cell specific color the use scols_line_get_cell() + scols_cell_set_color().

Parameters

cl

a pointer to a struct libscols_column instance

 

color

color name or ESC sequence

 

Returns

0, a negative value in case of an error.


scols_column_set_flags ()

int
scols_column_set_flags (struct libscols_column *cl,
                        int flags);

Sets the flags of cl to flags .

Parameters

cl

a pointer to a struct libscols_column instance

 

flags

a flag mask

 

Returns

0, a negative value in case of an error.


scols_column_set_json_type ()

int
scols_column_set_json_type (struct libscols_column *cl,
                            int type);

Sets the type used for JSON formatting, the default is SCOLS_JSON_STRING.

Parameters

cl

a pointer to a struct libscols_column instance

 

type

SCOLS_JSON_* type

 

Returns

0, a negative value in case of an error.

Since: 2.33


scols_column_set_name ()

int
scols_column_set_name (struct libscols_column *cl,
                       const char *name);

Parameters

cl

a pointer to a struct libscols_column instance

 

name

column name

 

Returns

0, a negative value in case of an error.

Since: 2.38


scols_column_set_safechars ()

int
scols_column_set_safechars (struct libscols_column *cl,
                            const char *safe);

Use for bytes you don't want to encode on output. This is for example necessary if you want to use custom wrap function based on \n, in this case you have to set "\n" as a safe char.

Parameters

cl

a pointer to a struct libscols_column instance

 

safe

safe characters (e.g. "\n\t")

 

Returns

0, a negative value in case of an error.

Since: 2.29


scols_column_set_whint ()

int
scols_column_set_whint (struct libscols_column *cl,
                        double whint);

Sets the width hint of column cl to whint . See scols_table_new_column().

Parameters

cl

a pointer to a struct libscols_column instance

 

whint

a width hint

 

Returns

0, a negative value in case of an error.


scols_column_set_wrapfunc ()

int
scols_column_set_wrapfunc (struct libscols_column *cl,
                           size_t (*wrap_chunksize) (const struct libscols_column *, const char *, void *),
                           char* (*wrap_nextchunk) (const struct libscols_column *, char *, void *),
                           void *userdata);

Extends SCOLS_FL_WRAP and can be used to set custom wrap function. The default is to wrap by column size, but you can create functions to wrap for example after \n or after words, etc.

Parameters

cl

a pointer to a struct libscols_column instance

 

wrap_chunksize

function to return size of the largest chink of data

 

wrap_nextchunk

function to return next zero terminated data

 

userdata

optional stuff for callbacks

 

Returns

0, a negative value in case of an error.

Since: 2.29


scols_copy_column ()

struct libscols_column *
scols_copy_column (const struct libscols_column *cl);

Creates a new column and copies cl 's data over to it.

Parameters

cl

a pointer to a struct libscols_column instance

 

Returns

a pointer to a new struct libscols_column instance.


scols_new_column ()

struct libscols_column *
scols_new_column (void);

Allocates space for a new column.

Returns

a pointer to a new struct libscols_column instance, NULL in case of an ENOMEM error.


scols_ref_column ()

void
scols_ref_column (struct libscols_column *cl);

Increases the refcount of cl .

Parameters

cl

a pointer to a struct libscols_column instance

 

scols_unref_column ()

void
scols_unref_column (struct libscols_column *cl);

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

Parameters

cl

a pointer to a struct libscols_column instance

 

scols_wrapnl_chunksize ()

size_t
scols_wrapnl_chunksize (const struct libscols_column *cl,
                        const char *data,
                        void *userdata);

Analyzes data and returns size of the largest chunk. The chunks are based on \n. For example for data "AAA\nBBB\nCCCC" the largest chunk size is 4.

Note that the size has to be based on number of terminal cells rather than bytes to support multu-byte output.

Parameters

cl

a pointer to a struct libscols_column instance

 

data

string

 

userdata

callback private data

 

Returns

size of the largest chunk.

Since: 2.29


scols_wrapnl_nextchunk ()

char *
scols_wrapnl_nextchunk (const struct libscols_column *cl,
                        char *data,
                        void *userdata);

This is built-in function for scols_column_set_wrapfunc(). This function terminates the current chunk by \0 and returns pointer to the begin of the next chunk. The chunks are based on \n.

For example for data "AAA\nBBB\nCCC" the next chunk is "BBB".

Parameters

cl

a pointer to a struct libscols_column instance

 

data

string

 

userdata

callback private data

 

Returns

next chunk

Since: 2.29

Types and Values

struct libscols_column

struct libscols_column;

A column - defines the number of columns and column names