Typedefs
typedef struct M_table	M_table_t

Enumerations
enum	M_table_insert_flags_t { M_TABLE_INSERT_NONE = 0 , M_TABLE_INSERT_COLADD = 1 << 0 , M_TABLE_INSERT_COLIGNORE = 1 << 1 }

enum	M_table_flags_t { M_TABLE_NONE = 0 , M_TABLE_COLNAME_CASECMP = 1 << 0 }

enum	M_table_markdown_flags_t { M_TABLE_MARKDOWN_NONE = 0 , M_TABLE_MARKDOWN_PRETTYPRINT = 1 << 0 , M_TABLE_MARKDOWN_OUTERPIPE = 1 << 1 , M_TABLE_MARKDOWN_LINEEND_UNX = 1 << 2 , M_TABLE_MARKDOWN_LINEEND_WIN = 1 << 3 }

Functions
M_table_t *	M_table_create (M_uint32 flags) M_MALLOC

void	M_table_destroy (M_table_t *table) M_FREE(1)

M_bool	M_table_column_insert (M_table_t table, const char colname)

M_bool	M_table_column_insert_at (M_table_t table, size_t idx, const char colname)

const char *	M_table_column_name (const M_table_t *table, size_t idx)

M_bool	M_table_column_set_name (M_table_t table, size_t idx, const char colname)

M_bool	M_table_column_idx (const M_table_t table, const char colname, size_t *idx)

void	M_table_column_sort_data (M_table_t table, const char colname, M_sort_compar_t primary_sort, const char secondary_colname, M_sort_compar_t secondary_sort, void thunk)

void	M_table_column_sort_data_at (M_table_t table, size_t idx, M_sort_compar_t primary_sort, size_t secondary_idx, M_sort_compar_t secondary_sort, void thunk)

void	M_table_column_order (M_table_t table, M_sort_compar_t sort, void thunk)

void	M_table_column_remove (M_table_t table, const char colname)

void	M_table_column_remove_at (M_table_t *table, size_t idx)

size_t	M_table_column_remove_empty_columns (M_table_t *table)

size_t	M_table_column_count (const M_table_t *table)

size_t	M_table_row_insert (M_table_t *table)

M_bool	M_table_row_insert_at (M_table_t *table, size_t idx)

M_bool	M_table_row_insert_dict (M_table_t table, const M_hash_dict_t data, M_uint32 flags, size_t *idx)

M_bool	M_table_row_insert_dict_at (M_table_t table, size_t idx, const M_hash_dict_t data, M_uint32 flags)

void	M_table_row_remove (M_table_t *table, size_t idx)

size_t	M_table_row_remove_empty_rows (M_table_t *table)

size_t	M_table_row_count (const M_table_t *table)

M_bool	M_table_cell_set (M_table_t table, size_t row, const char colname, const char *val, M_uint32 flags)

M_bool	M_table_cell_set_at (M_table_t table, size_t row, size_t col, const char val)

M_bool	M_table_cell_set_dict (M_table_t table, size_t row, const M_hash_dict_t data, M_uint32 flags)

M_bool	M_table_cell_clear (M_table_t table, size_t row, const char colname)

M_bool	M_table_cell_clear_at (M_table_t *table, size_t row, size_t col)

const char *	M_table_cell (const M_table_t table, size_t row, const char colname)

const char *	M_table_cell_at (const M_table_t *table, size_t row, size_t col)

M_bool	M_table_merge (M_table_t *dest, M_table_t src) M_FREE(2)

M_table_t *	M_table_duplicate (const M_table_t *table) M_MALLOC

M_bool	M_table_load_csv (M_table_t table, const char data, size_t len, char delim, char quote, M_uint32 flags, M_bool have_header)

char *	M_table_write_csv (const M_table_t *table, char delim, char quote, M_bool write_header)

M_bool	M_table_load_json (M_table_t table, const char data, size_t len)

M_json_node_t *	M_table_create_json (const M_table_t *table)

char *	M_table_write_json (const M_table_t *table, M_uint32 flags)

M_bool	M_table_load_markdown (M_table_t table, const char data, size_t len)

char *	M_table_write_markdown (const M_table_t *table, M_uint32 flags)

Detailed Description

Generic table construction and manipulation.

JSON input and output conform to csv2json Minimal Mode format.

Typedef Documentation

◆ M_table_t

typedef struct M_table M_table_t

Enumeration Type Documentation

◆ M_table_insert_flags_t

enum M_table_insert_flags_t

Flags controlling behavior of insert by column name operations.

Enumerator
M_TABLE_INSERT_NONE	Fail the insert if the header, or index does not exist.
M_TABLE_INSERT_COLADD	Add a named column if it does not exist.
M_TABLE_INSERT_COLIGNORE	Ignore names if a corresponding named header does not exist.

◆ M_table_flags_t

enum M_table_flags_t

Flags controlling table construction.

Enumerator
M_TABLE_NONE	Default operation.
M_TABLE_COLNAME_CASECMP	Compare column names case insensitive.

◆ M_table_markdown_flags_t

enum M_table_markdown_flags_t

Flags controlling behavior of Markdown output.

Enumerator
M_TABLE_MARKDOWN_NONE	No special formatting.
M_TABLE_MARKDOWN_PRETTYPRINT	Pretty print output.
M_TABLE_MARKDOWN_OUTERPIPE	Write outer pipes around rows, framing characters.
M_TABLE_MARKDOWN_LINEEND_UNX	Use Unix line endings (\n).
M_TABLE_MARKDOWN_LINEEND_WIN	Use Windows line endings (\r\n).

Function Documentation

◆ M_table_create()

M_table_t * M_table_create ( M_uint32 flags )

Create a table.

Parameters

[in] flags M_table_flags_t controlling behavior of the table.

return Table.

◆ M_table_destroy()

void M_table_destroy ( M_table_t * table )

Destroy a table.

Parameters

[in] table Table.

◆ M_table_column_insert()

M_bool M_table_column_insert	(	M_table_t *	table,
		const char *	colname
	)

Insert a new column into the table.

Parameters

[in]	table	Table.
[in]	colname	Optional name associated with the column.

Returns: M_TRUE when the column is successfully added. Otherwise, M_FALSE.

◆ M_table_column_insert_at()

M_bool M_table_column_insert_at	(	M_table_t *	table,
		size_t	idx,
		const char *	colname
	)

Insert a new column into the table at a specified index.

Parameters

[in]	table	Table.
[in]	idx	Index to insert at. Cannot be larger than the number of columns (last idx+1).
[in]	colname	Optional name associated with the column.

Returns: M_TRUE when the column is successfully added. Otherwise, M_FALSE.

◆ M_table_column_name()

const char * M_table_column_name	(	const M_table_t *	table,
		size_t	idx
	)

Get the name associated with a column.

Parameters

[in]	table	Table.
[in]	idx	Column index.

Returns: NULL if no name associated. Otherwise, name. Name can be an empty string is it was set to an empty string.

◆ M_table_column_set_name()

M_bool M_table_column_set_name	(	M_table_t *	table,
		size_t	idx,
		const char *	colname
	)

Associate a name with a column.

Parameters

[in]	table	Table.
[in]	idx	Column index.
[in]	colname	Name.

Returns: M_TRUE on success. Otherwise, M_FALSE. Can fail if a column with the given name already exists.

◆ M_table_column_idx()

M_bool M_table_column_idx	(	const M_table_t *	table,
		const char *	colname,
		size_t *	idx
	)

Get the index for a column with a given name.

Parameters

[in]	table	Table.
[in]	colname	Column name.
[out]	idx	Index of column

Returns: M_TRUE if the column exists. Otherwise, M_FALSE.

◆ M_table_column_sort_data()

void M_table_column_sort_data	(	M_table_t *	table,
		const char *	colname,
		M_sort_compar_t	primary_sort,
		const char *	secondary_colname,
		M_sort_compar_t	secondary_sort,
		void *	thunk
	)

Sort rows based on data in a given column name.

Supports secondary column sorting when values in the primary column are equivalent.

Parameters

[in]	table	Table.
[in]	colname	Column name for primary sorting.
[in]	primary_sort	Sort comparison function for `colname`.
[in]	secondary_colname	Column name for secondary sorting. Only used when values from primary sort are equivalent.
[in]	secondary_sort	Sort comparison function for `secondary_colname`.
[in]	thunk	Thunk passed to comparison functions.

◆ M_table_column_sort_data_at()

void M_table_column_sort_data_at	(	M_table_t *	table,
		size_t	idx,
		M_sort_compar_t	primary_sort,
		size_t	secondary_idx,
		M_sort_compar_t	secondary_sort,
		void *	thunk
	)

Sort rows based on data in a given column index.

Parameters

[in]	table	Table.
[in]	idx	Column index used for sorting.
[in]	primary_sort	Sort comparison function for `colname`.
[in]	secondary_idx	Column index for secondary sorting. Only used when values from primary sort are equivalent.
[in]	secondary_sort	Sort comparison function for `secondary_colname`.
[in]	thunk	Thunk passed to comparison functions.

◆ M_table_column_order()

void M_table_column_order	(	M_table_t *	table,
		M_sort_compar_t	sort,
		void *	thunk
	)

Sort column based on names.

It is not required for all columns to be named. Unnamed columns will be passed to the sort function as an empty string ("").

Parameters

[in]	table	Table.
[in]	sort	Sort comparison function.
[in]	thunk	Thunk passed to comparison function.

◆ M_table_column_remove()

void M_table_column_remove	(	M_table_t *	table,
		const char *	colname
	)

Remove a column with a given name.

Parameters

[in]	table	Table.
[in]	colname	Column name.

◆ M_table_column_remove_at()

void M_table_column_remove_at	(	M_table_t *	table,
		size_t	idx
	)

Remove a column at a given index.

Parameters

[in]	table	Table.
[in]	idx	Column index.

◆ M_table_column_remove_empty_columns()

size_t M_table_column_remove_empty_columns ( M_table_t * table )

Remove empty columns.

A column is empty when no rows have data for that column.

param[in] table Table.

Returns: Number of columns removed.

◆ M_table_column_count()

size_t M_table_column_count ( const M_table_t * table )

Get the number of columns in the table.

Parameters

[in] table Table.

Returns: Column count.

◆ M_table_row_insert()

size_t M_table_row_insert ( M_table_t * table )

Inset a row into the table.

Parameters

[in] table Table.

Returns: Index the row was inserted at.

◆ M_table_row_insert_at()

M_bool M_table_row_insert_at	(	M_table_t *	table,
		size_t	idx
	)

Insert a row into the table at a given index.

Parameters

[in]	table	Table.
[in]	idx	Index to insert at. Cannot be larger than the number of rows (last idx+1).

Returns: M_TRUE if the row was inserted. Otherwise, M_FALSE.

◆ M_table_row_insert_dict()

M_bool M_table_row_insert_dict	(	M_table_t *	table,
		const M_hash_dict_t *	data,
		M_uint32	flags,
		size_t *	idx
	)

Insert data from a dict into the table creating a new row.

Dictionary key is the column name and the value is the cell value.

Parameters

[in]	table	Table.
[in]	data	Data to insert.
[in]	flags	M_table_insert_flags_t flags controlling insert behavior. Specifically handling of situations where the key in data is not a current column.
[out]	idx	Index the row was inserted at. Will always be last idx+1 before insertion.

Returns: M_TRUE if the row was inserted. Otherwise, M_FALSE.

◆ M_table_row_insert_dict_at()

M_bool M_table_row_insert_dict_at	(	M_table_t *	table,
		size_t	idx,
		const M_hash_dict_t *	data,
		M_uint32	flags
	)

Insert data from a dict into the table at a given idex.

Dictionary key is the column name and the value is the cell value.

Parameters

[in]	table	Table.
[in]	idx	Index to insert at. Cannot be larger than the number of rows (last idx+1).
[in]	data	Data to insert.
[in]	flags	M_table_insert_flags_t flags controlling insert behavior. Specifically handling of situations where the key in data is not a current column.

Returns: M_TRUE if the row was inserted. Otherwise, M_FALSE.

◆ M_table_row_remove()

void M_table_row_remove	(	M_table_t *	table,
		size_t	idx
	)

Remove a row.

Parameters

[in]	table	Table.
[in]	idx	Row index.

◆ M_table_row_remove_empty_rows()

size_t M_table_row_remove_empty_rows ( M_table_t * table )

Remove all empty rows from the table.

A row is considered empty if there is no data in any column. An empty string is considered data and the row will not be removed.

Parameters

[in] table Table.

Returns: Number of rows removed.

◆ M_table_row_count()

size_t M_table_row_count ( const M_table_t * table )

Get the number of rows in the table.

Parameters

[in] table Table.

Returns: Number of rows.

◆ M_table_cell_set()

M_bool M_table_cell_set	(	M_table_t *	table,
		size_t	row,
		const char *	colname,
		const char *	val,
		M_uint32	flags
	)

Set data in a given cell by column name.

Parameters

[in]	table	Table.
[in]	row	Row index.
[in]	colname	Column name.
[in]	val	Value to set. NULL will clear.
[in]	flags	M_table_insert_flags_t flags controlling insert behavior. Specifically handling of situations where the `colname` is not a current column.

Returns: M_TRUE if the value was set. Otherwise, M_FALSE.

◆ M_table_cell_set_at()

M_bool M_table_cell_set_at	(	M_table_t *	table,
		size_t	row,
		size_t	col,
		const char *	val
	)

Set data in a given cell by index.

Parameters

[in]	table	Table.
[in]	row	Row index.
[in]	col	Column index.
[in]	val	Value to set. NULL will clear.

Returns: M_TRUE if the value was set. Otherwise, M_FALSE.

◆ M_table_cell_set_dict()

M_bool M_table_cell_set_dict	(	M_table_t *	table,
		size_t	row,
		const M_hash_dict_t *	data,
		M_uint32	flags
	)

Insert data from a dict into the table.

Dictionary key is the column name and the value is the cell value.

Parameters

[in]	table	Table.
[in]	row	Row index.
[in]	data	Data to insert.
[in]	flags	M_table_insert_flags_t flags controlling insert behavior. Specifically handling of situations where the key in data is not a current column.

Returns: M_TRUE if the row was inserted. Otherwise, M_FALSE.

◆ M_table_cell_clear()

M_bool M_table_cell_clear	(	M_table_t *	table,
		size_t	row,
		const char *	colname
	)

Clear the data from a cell by column name.

This is the equivalent to calling M_table_cell_set with a NULL value.

Parameters

[in]	table	Table.
[in]	row	Row index.
[in]	colname	Column name.

Returns: M_TRUE if the cell was cleared. Otherwise, M_FALSE. Clearing a column that does not exist is considered success.

◆ M_table_cell_clear_at()

M_bool M_table_cell_clear_at	(	M_table_t *	table,
		size_t	row,
		size_t	col
	)

Clear the data from a cell by column index.

This is the equivalent to calling M_table_cell_set with a NULL value.

Parameters

[in]	table	Table.
[in]	row	Row index.
[in]	col	Column index.

Returns: M_TRUE if the cell was cleared. Otherwise, M_FALSE.

◆ M_table_cell()

const char * M_table_cell	(	const M_table_t *	table,
		size_t	row,
		const char *	colname
	)

Get the data for a cell by column name.

Parameters

[in]	table	Table.
[in]	row	Row index.
[in]	colname	Column name.

Returns: Cell value. NULL is returned if there is no cell value and on error.

◆ M_table_cell_at()

const char * M_table_cell_at	(	const M_table_t *	table,
		size_t	row,
		size_t	col
	)

Get the data for a cell by column index.

Parameters

[in]	table	Table.
[in]	row	Row index.
[in]	col	Column index.

Returns: Cell value. NULL is returned if there is no cell value and on error.

◆ M_table_merge()

M_bool M_table_merge	(	M_table_t **	dest,
		M_table_t *	src
	)

Merge two tables together.

The second (src) table will be destroyed automatically upon completion of this function. Both tables must have fully named columns. The two tables do not have to have the same exact columns. They can have different overlapping or non-overlapping column names.

Parameters

[in,out]	dest	Pointer by reference to the table receiving the data. if dest is NULL, the src address will simply be copied to dest.
[in,out]	src	Pointer to the table giving up its data.

Returns: M_TRUE if the tables were merged and src is destroyed. Otherwise, M_FALSE. If M_FALSE, src is still valid and no data has been added to dest.

◆ M_table_duplicate()

M_table_t * M_table_duplicate ( const M_table_t * table )

Duplicate a table.

Parameters

[in] table Table.

Returns: Duplicated table.

◆ M_table_load_csv()

M_bool M_table_load_csv	(	M_table_t *	table,
		const char *	data,
		size_t	len,
		char	delim,
		char	quote,
		M_uint32	flags,
		M_bool	have_header
	)

Load CSV formatted data into the table.

Parameters

[in]	table	Table.
[in]	data	CSV data.
[in]	len	Length of data to load.
[in]	delim	CSV delimiter character. Typically comma (",").
[in]	quote	CSV quote character. Typically double quote (""").
[in]	flags	M_CSV_FLAGS flags controlling parse behavior.
[in]	have_header	Whether the CSV data has a header.

Returns: M_TRUE if the data was loaded. Otherwise, M_FALSE.

◆ M_table_write_csv()

char * M_table_write_csv	(	const M_table_t *	table,
		char	delim,
		char	quote,
		M_bool	write_header
	)

Write the table as CSV.

Parameters

[in]	table	Table.
[in]	delim	CSV delimiter character. Typically comma (",").
[in]	quote	CSV quote character. Typically double quote (""").
[in]	write_header	Whether the column names should be written as the CSV header. All columns should be named if writing a header. However, it is not an error if there are unnamed columns.

Returns: CSV data.

◆ M_table_load_json()

M_bool M_table_load_json	(	M_table_t *	table,
		const char *	data,
		size_t	len
	)

Load JSON formatted data into the table.

Should be in the form list of a objects who's keys are headers and value are cell value for the row at the given list index.

E.g.:

[
  { header1: "value", header2: "value" },
  { header1: "value", header2: "value" }
]

Parameters

[in]	table	Table.
[in]	data	JSON string data.
[in]	len	Length of data to load.

Returns: M_TRUE if the data was loaded. Otherwise, M_FALSE.

◆ M_table_create_json()

M_json_node_t * M_table_create_json ( const M_table_t * table )

Write the table as a JSON node object.

A NULL table poiner will return NULL. A table with 0 rows will output a json node as an empty array.

All columns must be named!

Parameters

[in] table Table.

Returns: JSON node object.

◆ M_table_write_json()

char * M_table_write_json	(	const M_table_t *	table,
		M_uint32	flags
	)

Write the table as a JSON buffer.

A NULL table poiner will return NULL. A table with 0 rows will output an empty JSON array ([]).

All columns must be named!

Parameters

[in]	table	Table.
[in]	flags	M_json_writer_flags_t flags controlling writing.

Returns: JSON data.

◆ M_table_load_markdown()

M_bool M_table_load_markdown	(	M_table_t *	table,
		const char *	data,
		size_t	len
	)

Load Markdown formatted data into the table.

Column justification information will be lost.

Parameters

[in]	table	Table.
[in]	data	CSV data.
[in]	len	Length of data to load.

Returns: M_TRUE if the data was loaded. Otherwise, M_FALSE.

◆ M_table_write_markdown()

char * M_table_write_markdown	(	const M_table_t *	table,
		M_uint32	flags
	)

Write the table as Markdown.

Parameters

[in]	table	Table.
[in]	flags	M_table_markdown_flags_t flags controlling write behavior.

Returns: CSV data.

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ M_table_t

Enumeration Type Documentation

◆ M_table_insert_flags_t

◆ M_table_flags_t

◆ M_table_markdown_flags_t

Function Documentation

◆ M_table_create()

◆ M_table_destroy()

◆ M_table_column_insert()

◆ M_table_column_insert_at()

◆ M_table_column_name()

◆ M_table_column_set_name()

◆ M_table_column_idx()

◆ M_table_column_sort_data()

◆ M_table_column_sort_data_at()

◆ M_table_column_order()

◆ M_table_column_remove()

◆ M_table_column_remove_at()

◆ M_table_column_remove_empty_columns()

◆ M_table_column_count()

◆ M_table_row_insert()

◆ M_table_row_insert_at()

◆ M_table_row_insert_dict()

◆ M_table_row_insert_dict_at()

◆ M_table_row_remove()

◆ M_table_row_remove_empty_rows()

◆ M_table_row_count()

◆ M_table_cell_set()

◆ M_table_cell_set_at()

◆ M_table_cell_set_dict()

◆ M_table_cell_clear()

◆ M_table_cell_clear_at()

◆ M_table_cell()

◆ M_table_cell_at()

◆ M_table_merge()

◆ M_table_duplicate()

◆ M_table_load_csv()

◆ M_table_write_csv()

◆ M_table_load_json()

◆ M_table_create_json()

◆ M_table_write_json()

◆ M_table_load_markdown()

◆ M_table_write_markdown()