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_data_type ()

int
scols_column_get_data_type (const struct libscols_column *cl);

Parameters

cl

a pointer to a struct libscols_column instance

 

Returns

The current datatype setting of the column cl .

Since: 2.40


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_get_wrap_data ()

int
scols_column_get_wrap_data (const struct libscols_column *cl,
                            char **data,
                            size_t *datasiz,
                            char **cur,
                            char **next);

This function returns the current status of wrapping cell data (for multi-line cells).

Parameters

cl

column

 

data

return wrap data

 

datasiz

return wrap buffer size

 

cur

the current pozition in the buffer

 

next

the next pozition

 

Returns

0, a negative value in case of an error.

Since: 2.40


scols_column_has_data_func ()

int
scols_column_has_data_func (struct libscols_column *cl);

See scols_column_set_data_func() for more details.

Parameters

cl

a pointer to a struct libscols_column instance

 

Returns

1 if data function defined, or 0

Since: 2.40


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_data_func ()

int
scols_column_set_data_func (struct libscols_column *cl,
                            void* (*datafunc) (const struct libscols_column *, struct libscols_cell *, void *),
                            void *userdata);

scols_column_set_data_type ()

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

The table always keep data in strings in form that is printed on output, but for some internal operations (like filters or counters) it needs to convert the strings to usable data format. This data format is possible to specify, by this function. If the format is not specified then filter and counters try to use SCOLS_JSON_* types, if also not define than defaults to string.

If a simple string conversion is not possible then application (which want to use filters and counters) needs to define data function to do the conversion. See scols_column_set_data_func().

Parameters

cl

a pointer to a struct libscols_column instance

 

type

SCOLS_DATA_*

 

Returns

0, a negative value in case of an error.

Since: 2.40


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_properties ()

int
scols_column_set_properties (struct libscols_column *cl,
                             const char *opts);

Set properties from string, the string is comma seprated list, like "trunc,right,json=number", ...

Parameters

cl

a pointer to a struct libscols_column instance

 

opts

options string

 

Returns

0 on success, <0 on error

Since: 2.39


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.

Note that since 2.40 the wrap_chunksize is unnecessary. The library calculates the size itself.

The wrap functions do not work directly with cell data, but with buffer used by library to compose output data. The wrap_nextchunk() function can access additional details about wrap data by scols_column_get_wrap_data().

Parameters

cl

a pointer to a struct libscols_column instance

 

wrap_chunksize

function to return size of the largest chink of data (deprecated)

 

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_shellvar_name ()

int
scols_shellvar_name (const char *name,
                     char **buf,
                     size_t *bufsz);

Converts name to a name compatible with shell. The buffer is reallocated if not large enough.

Parameters

name

raw (column) name

 

buf

buffer to returns normalized name

 

bufsz

size of the buffer

 

Returns

0 in case of conversion, 1 if conversion unnecessary, <0 on error.

Since: 2.40


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.

Deprecated since 2.40.

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


scols_wrapzero_nextchunk ()

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

This is built-in function for scols_column_set_wrapfunc(). This function walk string separated by \0.

For example for data "AAA\0BBB\0CCC\0" 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.40

Types and Values

struct libscols_column

struct libscols_column;

A column - defines the number of columns and column names