XLSX I/O
XLSX I/O

Cross-platform C library for reading values from and writing values to .xlsx files.

Description

XLSX I/O aims to provide a C library for reading and writing .xlsx files. The .xlsx file format is the native format used by Microsoft(R) Excel(TM) since version 2007.

Goal

The library was written with the following goals in mind:

  • written in standard C, but allows being used by C++
  • simple interface
  • small footprint
  • portable across different platforms (Windows, *nix)
  • minimal dependancies: only depends on expat (only for reading) and minizip or libzip (which in turn depend on zlib)
  • separate library for reading and writing .xlsx files
  • does not require Microsoft(R) Excel(TM) to be installed

Reading .xlsx files:

  • intended to process .xlsx files as a data table, which assumes the following:
    • assumes the first row contains header names
    • assumes the next rows contain values in the same columns as where the header names are supplied
    • only values are processed, anything else is ignored (formulas, layout, graphics, charts, ...)
  • the entire shared string table is loaded in memory (warning: could be large for big spreadsheets with a lot of different values)
  • supports .xlsx files without shared string table
  • worksheet data itself is read on the fly without the need to buffer data in memory
  • 2 methods are provided
    • a simple method that allows the application to iterate trough rows and cells
    • an advanced method (with less overhead) which calls callback functions for each cell and after each row

Writing .xlsx files:

  • intended for writing data tables as .xlsx files, which assumes the following:
    • only support for writing data (no support for formulas, layout, graphics, charts, ...)
    • no support for multiple worksheets (only one worksheet per file)
  • on the fly file generation without the need to buffer data in memory
  • no support for shared strings (all values are written as inline strings)

Libraries

The following libraries are provided:

  • -lxlsxio_read - library for reading .xlsx files, requires #include <xlsxio_read.h>
  • -lxlsxio_write - library for writing .xlsx files, requires #include <xlsxio_write.h>
  • -lxlsxio_readw - experimental library for reading .xlsx files, linked with -lexpatw, requires #define XML_UNICODE before #include <xlsxio_read.h>

Command line utilities

Some command line utilities are included:

  • xlsxio_xlsx2csv - converts all sheets in all specified .xlsx files to individual CSV (Comma Separated Values) files.
  • xlsxio_csv2xlsx - converts all specified CSV (Comma Separated Values) files to .xlsx files.

Dependancies

This project has the following depencancies:

Note that minizip is preferred, as there have been reports that .xlsx files generated with XLSX I/O built against libzip can't be opened with LibreOffice.

There is no dependancy on Microsoft(R) Excel(TM).

XLSX I/O was written with cross-platform portability in mind and works on multiple operating systems, including Windows, macOS and Linux.

Building from source

Requirements:

  • a C compiler like gcc or clang, on Windows MinGW and MinGW-w64 are supported
  • the dependancy libraries (see Dependancies)
  • a shell environment, on Windows MSYS is supported
  • the make command
  • CMake version 2.6 or higher (optional, but preferred)

There are 2 methods to build XLSX I/O:

  • using the basic Makefile included
  • using CMake (preferred)

Building with make

  • build and install by running make install optionally followed by:
    • PREFIX=<path> - Base path were files will be installed (defaults to /usr/local)
    • WITH_LIBZIP=1 - Use libzip instead of minizip
    • WIDE=1 - Also build UTF-16 library (xlsxio_readw)
    • STATICDLL=1 - Build a static DLL (= doesn't depend on any other DLLs) - only supported on Windows

Building with CMake (preferred method)

  • configure by running cmake -G"Unix Makefiles" (or cmake -G"MSYS Makefiles" on Windows) optionally followed by:
    • -DCMAKE_INSTALL_PREFIX:PATH=<path> Base path were files will be installed
    • -DBUILD_STATIC:BOOL=OFF - Don't build static libraries
    • -DBUILD_SHARED:BOOL=OFF - Don't build shared libraries
    • -DBUILD_TOOLS:BOOL=OFF - Don't build tools (only libraries)
    • -DBUILD_EXAMPLES:BOOL=OFF - Don't build examples
    • -DBUILD_EXAMPLES:BOOL=OFF - Don't build examples
    • -DWITH_LIBZIP:BOOL=ON - Use libzip instead of Minizip
    • -DLIBZIP_DIR:PATH=<path> - Location of libzip library
    • -DMINIZIP_DIR:PATH=<path> - Location of Minizip library
    • -DWITH_WIDE:BOOL=ON - Also build UTF-16 library (libxlsxio_readw)
  • build and install by running make install (or make install/strip to strip symbols)

Prebuilt binaries

Prebuilt binaries are also available for download for the following platforms:

  • Windows 32-bit
  • Windows 64-bit

Both Windows versions were built using the MinGW-w64 under an MSYS2 shell. To link with the .dll libraries from Microsoft Visual C++ you need a .lib file for each .dll. This file can be generated using the lib tool that comes with Microsoft Visual C++.

For 32-bit Windows:

cd lib
lib /def:libxlsxio_write.def /out:libxlsxio_write.lib /machine:x86
lib /def:libxlsxio_read.def /out:libxlsxio_read.lib /machine:x86
lib /def:libxlsxio_readw.def /out:libxlsxio_readw.lib /machine:x86

For 64-bit Windows:

cd lib
lib /def:libxlsxio_write.def /out:libxlsxio_write.lib /machine:x64
lib /def:libxlsxio_read.def /out:libxlsxio_read.lib /machine:x64
lib /def:libxlsxio_readw.def /out:libxlsxio_readw.lib /machine:x64

Example C programs

Reading from an .xlsx file

#include <xlsxio_read.h>
//open .xlsx file for reading
xlsxioreader xlsxioread;
if ((xlsxioread = xlsxioread_open(filename)) == NULL) {
fprintf(stderr, "Error opening .xlsx file\n");
return 1;
}
//read values from first sheet
char* value;
const char* sheetname = NULL;
printf("Contents of first sheet:\n");
if ((sheet = xlsxioread_sheet_open(xlsxioread, sheetname, XLSXIOREAD_SKIP_EMPTY_ROWS)) != NULL) {
//read all rows
while (xlsxioread_sheet_next_row(sheet)) {
//read all columns
while ((value = xlsxioread_sheet_next_cell(sheet)) != NULL) {
printf("%s\t", value);
free(value);
}
printf("\n");
}
}
//clean up
xlsxioread_close(xlsxioread);

Listing all worksheets in an .xlsx file

#include <xlsxio_read.h>
//open .xlsx file for reading
xlsxioreader xlsxioread;
if ((xlsxioread = xlsxioread_open(filename)) == NULL) {
fprintf(stderr, "Error opening .xlsx file\n");
return 1;
}
//list available sheets
const char* sheetname;
printf("Available sheets:\n");
if ((sheetlist = xlsxioread_sheetlist_open(xlsxioread)) != NULL) {
while ((sheetname = xlsxioread_sheetlist_next(sheetlist)) != NULL) {
printf(" - %s\n", sheetname);
}
}
//clean up
xlsxioread_close(xlsxioread);

Writing to an .xlsx file

#include <xlsxio_write.h>
//open .xlsx file for writing (will overwrite if it already exists)
xlsxiowriter handle;
if ((handle = xlsxiowrite_open(filename, "MySheet")) == NULL) {
fprintf(stderr, "Error creating .xlsx file\n");
return 1;
}
//write column names
xlsxiowrite_add_column(handle, "Col1", 16);
xlsxiowrite_add_column(handle, "Col2", 0);
//write data
int i;
for (i = 0; i < 1000; i++) {
xlsxiowrite_add_cell_string(handle, "Test");
}
//close .xlsx file

License

XLSX I/O is released under the terms of the MIT License (MIT), see LICENSE.txt.

This means you are free to use XLSX I/O in any of your projects, from open source to commercial.

This library does not require Microsoft(R) Excel(TM) to be installed.

xlsxiowriter
struct xlsxio_write_struct * xlsxiowriter
write handle for .xlsx object
Definition: xlsxio_write.h:80
xlsxioread_sheetlist_open
DLL_EXPORT_XLSXIO xlsxioreadersheetlist xlsxioread_sheetlist_open(xlsxioreader handle)
open list of worksheet names
xlsxioread_sheet_next_cell
DLL_EXPORT_XLSXIO XLSXIOCHAR * xlsxioread_sheet_next_cell(xlsxioreadersheet sheethandle)
get next cell from worksheet
xlsxioread_sheet_next_row
DLL_EXPORT_XLSXIO int xlsxioread_sheet_next_row(xlsxioreadersheet sheethandle)
get next row from worksheet (to be called before each row)
xlsxioread_close
DLL_EXPORT_XLSXIO void xlsxioread_close(xlsxioreader handle)
close .xlsx file
xlsxioread_sheet_open
DLL_EXPORT_XLSXIO xlsxioreadersheet xlsxioread_sheet_open(xlsxioreader handle, const XLSXIOCHAR *sheetname, unsigned int flags)
open worksheet
XLSXIOREAD_SKIP_EMPTY_ROWS
#define XLSXIOREAD_SKIP_EMPTY_ROWS
skip empty rows (note: cells may appear empty while they actually contain data)
Definition: xlsxio_read.h:154
xlsxioreadersheetlist
struct xlsxio_read_sheetlist_struct * xlsxioreadersheetlist
read handle for list of worksheet names
Definition: xlsxio_read.h:200
xlsxiowrite_add_column
DLL_EXPORT_XLSXIO void xlsxiowrite_add_column(xlsxiowriter handle, const char *name, int width)
add a column cell
xlsxioread_sheetlist_close
DLL_EXPORT_XLSXIO void xlsxioread_sheetlist_close(xlsxioreadersheetlist sheetlisthandle)
close worksheet
xlsxioreadersheet
struct xlsxio_read_sheet_struct * xlsxioreadersheet
read handle for worksheet object
Definition: xlsxio_read.h:225
xlsxiowrite_close
DLL_EXPORT_XLSXIO int xlsxiowrite_close(xlsxiowriter handle)
close .xlsx file
xlsxioread_sheet_close
DLL_EXPORT_XLSXIO void xlsxioread_sheet_close(xlsxioreadersheet sheethandle)
close worksheet
xlsxioread_open
DLL_EXPORT_XLSXIO xlsxioreader xlsxioread_open(const char *filename)
open .xlsx file
xlsxioreader
struct xlsxio_read_struct * xlsxioreader
read handle for .xlsx object
Definition: xlsxio_read.h:95
xlsxiowrite_add_cell_string
DLL_EXPORT_XLSXIO void xlsxiowrite_add_cell_string(xlsxiowriter handle, const char *value)
add a cell with string data
xlsxiowrite_open
DLL_EXPORT_XLSXIO xlsxiowriter xlsxiowrite_open(const char *filename, const char *sheetname)
create and open .xlsx file
xlsxiowrite_add_cell_int
DLL_EXPORT_XLSXIO void xlsxiowrite_add_cell_int(xlsxiowriter handle, int64_t value)
add a cell with integer data
xlsxio_read.h
XLSX I/O header file for reading .xlsx files.
xlsxiowrite_next_row
DLL_EXPORT_XLSXIO void xlsxiowrite_next_row(xlsxiowriter handle)
mark the end of a row (next cell will start on a new row)
xlsxioread_sheetlist_next
DLL_EXPORT_XLSXIO const XLSXIOCHAR * xlsxioread_sheetlist_next(xlsxioreadersheetlist sheetlisthandle)
get next worksheet name
xlsxio_write.h
XLSX I/O header file for writing .xlsx files.