Welcome to NYCU CSIT Mirror site

Line: libsmartcols Reference Manual

Line

Line — cells container, also keeps tree (parent->child) information

Types and Values

struct libscols_line

Description

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

Functions

scols_copy_line ()

struct libscols_line *
scols_copy_line (const struct libscols_line *ln);

Parameters

ln

a pointer to a struct libscols_line instance

 

Returns

A newly allocated copy of ln , NULL in case of an error.


scols_line_add_child ()

int
scols_line_add_child (struct libscols_line *ln,
                      struct libscols_line *child);

Sets child as a child of ln .

Parameters

ln

a pointer to a struct libscols_line instance

 

child

a pointer to a struct libscols_line instance

 

Returns

0, a negative value in case of an error.


scols_line_alloc_cells ()

int
scols_line_alloc_cells (struct libscols_line *ln,
                        size_t n);

Allocates space for n cells. This function is optional, and libsmartcols automatically allocates necessary cells according to number of columns in the table when you add the line to the table. See scols_table_add_line().

Parameters

ln

a pointer to a struct libscols_line instance

 

n

the number of elements

 

Returns

0, a negative value in case of an error.


scols_line_free_cells ()

void
scols_line_free_cells (struct libscols_line *ln);

Frees the allocated cells referenced to by ln .

Parameters

ln

a pointer to a struct libscols_line instance

 

scols_line_get_cell ()

struct libscols_cell *
scols_line_get_cell (struct libscols_line *ln,
                     size_t n);

Parameters

ln

a pointer to a struct libscols_line instance

 

n

cell number to retrieve

 

Returns

the n -th cell in ln , NULL in case of an error.


scols_line_get_color ()

const char *
scols_line_get_color (const struct libscols_line *ln);

Parameters

ln

a pointer to a struct libscols_line instance

 

Returns

ln 's color string, NULL in case of an error.


scols_line_get_column_cell ()

struct libscols_cell *
scols_line_get_column_cell (struct libscols_line *ln,
                            struct libscols_column *cl);

Like scols_line_get_cell() by cell is referenced by column.

Parameters

ln

a pointer to a struct libscols_line instance

 

cl

pointer to cell

 

Returns

the n -th cell in ln , NULL in case of an error.


scols_line_get_column_data ()

const char *
scols_line_get_column_data (struct libscols_line *ln,
                            struct libscols_column *cl);

See also scols_cell_get_data()

Parameters

ln

a pointer to a struct libscols_line instance

 

cl

column, whose data is to be get

 

Returns

cell data or NULL.

Since: 2.38


scols_line_get_ncells ()

size_t
scols_line_get_ncells (const struct libscols_line *ln);

Parameters

ln

a pointer to a struct libscols_line instance

 

Returns

number of cells


scols_line_get_parent ()

struct libscols_line *
scols_line_get_parent (const struct libscols_line *ln);

Parameters

ln

a pointer to a struct libscols_line instance

 

Returns

a pointer to ln 's parent, NULL in case it has no parent or if there was an error.


scols_line_get_userdata ()

void *
scols_line_get_userdata (struct libscols_line *ln);

Parameters

ln

a pointer to a struct libscols_line instance

 

Returns

user data


scols_line_has_children ()

int
scols_line_has_children (struct libscols_line *ln);

Parameters

ln

a pointer to a struct libscols_line instance

 

Returns

1 if ln has any children, otherwise 0.


scols_line_is_ancestor ()

int
scols_line_is_ancestor (struct libscols_line *ln,
                        struct libscols_line *parent);

The function is designed to detect circular dependencies between ln and parent . It checks if ln is not any (grand) parent in the parent 's tree.

Parameters

ln

line

 

parent

potential parent

 

Returns

0 or 1

Since: 2.30


scols_line_next_child ()

int
scols_line_next_child (struct libscols_line *ln,
                       struct libscols_iter *itr,
                       struct libscols_line **chld);

Finds the next child and returns a pointer to it via chld .

Parameters

ln

a pointer to a struct libscols_line instance

 

itr

a pointer to a struct libscols_iter instance

 

chld

a pointer to a pointer to a struct libscols_line instance

 

Returns

0, a negative value in case of an error.


scols_line_refer_column_data ()

int
scols_line_refer_column_data (struct libscols_line *ln,
                              struct libscols_column *cl,
                              char *data);

The same as scols_line_refer_data() but cell is referenced by column object.

Parameters

ln

a pointer to a struct libscols_line instance

 

cl

column, whose data is to be set

 

data

actual data to refer to

 

Returns

0, a negative value in case of an error.

Since: 2.28


scols_line_refer_data ()

int
scols_line_refer_data (struct libscols_line *ln,
                       size_t n,
                       char *data);

Parameters

ln

a pointer to a struct libscols_line instance

 

n

number of the cell which will refer to data

 

data

actual data to refer to

 

Returns

0, a negative value in case of an error.


scols_line_remove_child ()

int
scols_line_remove_child (struct libscols_line *ln,
                         struct libscols_line *child);

Removes child as a child of ln .

Parameters

ln

a pointer to a struct libscols_line instance

 

child

a pointer to a struct libscols_line instance

 

Returns

0, a negative value in case of an error.


scols_line_set_color ()

int
scols_line_set_color (struct libscols_line *ln,
                      const char *color);

Parameters

ln

a pointer to a struct libscols_line instance

 

color

color name or ESC sequence

 

Returns

0, a negative value in case of an error.


scols_line_set_column_data ()

int
scols_line_set_column_data (struct libscols_line *ln,
                            struct libscols_column *cl,
                            const char *data);

The same as scols_line_set_data() but cell is referenced by column object.

Parameters

ln

a pointer to a struct libscols_line instance

 

cl

column, whose data is to be set

 

data

actual data to set

 

Returns

0, a negative value in case of an error.

Since: 2.28


scols_line_set_data ()

int
scols_line_set_data (struct libscols_line *ln,
                     size_t n,
                     const char *data);

Parameters

ln

a pointer to a struct libscols_line instance

 

n

number of the cell, whose data is to be set

 

data

actual data to set

 

Returns

0, a negative value in case of an error.


scols_line_set_userdata ()

int
scols_line_set_userdata (struct libscols_line *ln,
                         void *data);

Binds data to ln .

Parameters

ln

a pointer to a struct libscols_line instance

 

data

user data

 

Returns

0, a negative value in case of an error.


scols_new_line ()

struct libscols_line *
scols_new_line (void);

Note that the line is allocated without cells, the cells will be allocated later when you add the line to the table. If you want to use the line without table then you have to explicitly allocate the cells by scols_line_alloc_cells().

Returns

a pointer to a new struct libscols_line instance.


scols_ref_line ()

void
scols_ref_line (struct libscols_line *ln);

Increases the refcount of ln .

Parameters

ln

a pointer to a struct libscols_line instance

 

scols_unref_line ()

void
scols_unref_line (struct libscols_line *ln);

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

Parameters

ln

a pointer to a struct libscols_line instance

 

Types and Values

struct libscols_line

struct libscols_line;

A line - an array of cells