utility.h File Reference

Functions
const char *	lxw_version (void)
	Retrieve the library version. More...
uint16_t	lxw_version_id (void)
	Retrieve the library version ID. More...
char *	lxw_strerror (lxw_error error_num)
	Converts a libxlsxwriter error number to a string. More...
double	lxw_datetime_to_excel_datetime (lxw_datetime *datetime)
	Converts a lxw_datetime to an Excel datetime number. More...
double	lxw_datetime_to_excel_date_with_epoch (lxw_datetime *datetime, uint8_t use_1904_epoch)
	Converts a lxw_datetime to an Excel datetime number with 1900/1904 epoch. More...
lxw_error	lxw_datetime_validate (lxw_datetime *datetime)
	Validate a lxw_datetime struct. More...
double	lxw_unixtime_to_excel_date (int64_t unixtime)
	Converts a unix datetime to an Excel datetime number. More...
double	lxw_unixtime_to_excel_date_with_epoch (int64_t unixtime, uint8_t use_1904_epoch)
	Converts a unix datetime to an Excel datetime number with 1900/1904 epoch. More...

Function Documentation

const char* lxw_version

(

void

)

Returns

The "X.Y.Z" version string.

Get the library version as a "X.Y.Z" version string

printf("Libxlsxwriter version = %s\n", lxw_version());

uint16_t lxw_version_id

(

void

)

Returns

The version ID.

Get the library version such as "X.Y.Z" as a XYZ integer.

printf("Libxlsxwriter version id = %d\n", lxw_version_id());

char* lxw_strerror

(

lxw_error

error_num

)

The lxw_strerror function converts a libxlsxwriter error number defined by lxw_error to a pointer to a string description of the error. Similar to the standard library strerror(3) function.

For example:

lxw_error error = workbook_close(workbook);

if (error)
    printf("Error in workbook_close().\n"
           "Error %d = %s\n", error, lxw_strerror(error));

This would produce output like the following if the target file wasn't writable:

Error in workbook_close().
Error 2 = Error creating output xlsx file. Usually a permissions error.

Parameters

error_num

The error number returned by a libxlsxwriter function.

Returns

A pointer to a statically allocated string. Do not free.

Examples:

anatomy.c.

double lxw_datetime_to_excel_datetime

(

lxw_datetime *

datetime

)

Parameters

datetime

A pointer to a lxw_datetime struct.

Returns

A double representing an Excel datetime.

The lxw_datetime_to_excel_datetime() function converts a datetime in lxw_datetime to an Excel datetime number:

lxw_datetime datetime = {2013, 2, 28, 12, 0, 0.0};

double excel_datetime = lxw_datetime_to_excel_date(&datetime);

See Working with Dates and Times for more details on the Excel datetime format.

double lxw_datetime_to_excel_date_with_epoch	(	lxw_datetime *	datetime,
		uint8_t	use_1904_epoch
	)

This function is similar to lxw_datetime_to_excel_datetime() but it allows you to specify whether to use the 1900 or 1904 epoch. See also the workbook_use_1904_epoch() function.

Parameters

datetime	A pointer to a lxw_datetime struct.
use_1904_epoch	A flag to indicate whether to use the 1904 epoch (true) or the 1900 epoch (false).

lxw_error lxw_datetime_validate

(

lxw_datetime *

datetime

)

Validates a lxw_datetime struct to ensure its fields are within acceptable ranges for Excel dates and times.

The members of the lxw_datetime struct and the range of their values are:

Member	Value
year	1900 - 9999
month	1 - 12
day	1 - 31
hour	0 - 23
min	0 - 59
sec	0 - 59.999

Parameters

datetime

A pointer to a lxw_datetime struct.

Returns

A lxw_error code. Either LXW_NO_ERROR or LXW_ERROR_DATETIME_VALIDATION if a field is out of range.

double lxw_unixtime_to_excel_date

(

int64_t

unixtime

)

Parameters

unixtime

Unix time (seconds since 1970-01-01)

Returns

A double representing an Excel datetime.

The lxw_unixtime_to_excel_date() function converts a unix datetime to an Excel datetime number:

double excel_datetime = lxw_unixtime_to_excel_date(946684800);

See Working with Dates and Times for more details.

double lxw_unixtime_to_excel_date_with_epoch	(	int64_t	unixtime,
		uint8_t	use_1904_epoch
	)

This function is similar to lxw_unixtime_to_excel_date() but it allows you to specify whether to use the 1900 or 1904 epoch. See also the workbook_use_1904_epoch() function.

Parameters

unixtime	Unix time (seconds since 1970-01-01)
use_1904_epoch	A flag to indicate whether to use the 1904 epoch (true) or the 1900 epoch (false).

Macro Definition Documentation

#define CELL

(

cell

)

lxw_name_to_row(cell), lxw_name_to_col(cell)

Convert an Excel A1 cell string into a (row, col) pair.

This is a little syntactic shortcut to help with worksheet layout:

worksheet_write_string(worksheet, CELL("A1"), "Foo", NULL);

//Same as:
worksheet_write_string(worksheet, 0, 0,       "Foo", NULL);

Note

This macro shouldn't be used in performance critical situations since it expands to two function calls.

Examples:

chart.c, chart_area.c, chart_bar.c, chart_clustered.c, chart_column.c, chart_data_labels.c, chart_data_table.c, chart_data_tools.c, chart_doughnut.c, chart_fonts.c, chart_line.c, chart_pattern.c, chart_pie.c, chart_radar.c, chart_scatter.c, chartsheet.c, comments2.c, conditional_format1.c, conditional_format2.c, data_validate.c, diagonal_border.c, dynamic_arrays.c, embed_image_buffer.c, embed_images.c, ignore_errors.c, image_buffer.c, images.c, lambda.c, outline.c, outline_collapsed.c, rich_strings.c, and tables.c.

#define COLS

(

cols

)

lxw_name_to_col(cols), lxw_name_to_col_2(cols)

Convert an Excel A:B column range into a (col1, col2) pair.

This is a little syntactic shortcut to help with worksheet layout:

worksheet_set_column(worksheet, COLS("B:D"), 20, NULL, NULL);

// Same as:
worksheet_set_column(worksheet, 1, 3,        20, NULL, NULL);

Examples:

dynamic_arrays.c, embed_images.c, hide_row_col.c, images.c, macro.c, outline.c, outline_collapsed.c, and tables.c.

#define RANGE

(

range

)

Value:

lxw_name_to_row(range), lxw_name_to_col(range), \
    lxw_name_to_row_2(range), lxw_name_to_col_2(range)

Convert an Excel A1:B2 range into a (first_row, first_col, last_row, last_col) sequence.

This is a little syntactic shortcut to help with worksheet layout.

worksheet_print_area(worksheet, 0, 0, 41, 10); // A1:K42.

// Same as:
worksheet_print_area(worksheet, RANGE("A1:K42"));

Examples:

array_formula.c, conditional_format1.c, conditional_format2.c, dynamic_arrays.c, and tables.c.

Macros
#define	CELL(cell)   lxw_name_to_row(cell), lxw_name_to_col(cell)
	Convert an Excel A1 cell string into a (row, col) pair. More...
#define	COLS(cols)   lxw_name_to_col(cols), lxw_name_to_col_2(cols)
	Convert an Excel A:B column range into a (col1, col2) pair. More...
#define	RANGE(range)
	Convert an Excel A1:B2 range into a (first_row, first_col, last_row, last_col) sequence. More...