Skip to content

Latest commit

 

History

History
65 lines (46 loc) · 4.2 KB

README.md

File metadata and controls

65 lines (46 loc) · 4.2 KB
Raw

MicroXLSWriter

A simple and small XLS file creation library written in C suitable for use on microcontrollers.

Introduction

MicroXLSWriter creates .xls files using a small subset of the BIFF2 file format, which is the format used by Excel 2.0 circa 1987. The BIFF2 format is simpler than modern versions of .xls files that use BIFF8 contained inside a Microsoft Compound File Binary Format file. Modern versions of Excel and LibreOffice are still able to open older BIFF2 files.

Although MicroXLSWriter does not adhere to every requirement of the BIFF2 format, it generates .xls files that Excel and LibreOffice/OpenOffice will open without errors. These files are most likely not compatible with other .xls reader programs and libraries though, because many libraries only expect to work with BIFF8 files.

This library has been designed for use on microcontrollers with limited RAM. It has very low RAM and code space requirements compared to other .xls generation libraries, and doesn't use malloc().

How to use

See the included test.c program for an example usage of the library. To compile it, type make. Here is a general set of steps to follow in order to add this library to your project:

  1. Add microxlswriter.c and microxlswriter.h to your existing project.
  2. Create and open an empty output file using your project's file I/O library.
  3. Create a function that MicroXLSWriter can call when it needs to write to a file. This function is the "glue code" that allows MicroXLSWriter to use your project's file I/O library. See WriteToFile in test.c for an example that uses stdio on a desktop computer.
  4. Set up a MicroXLSWriter struct that points to this function (the writeFunc member). You will pass this struct to all of the MicroXLS_* functions.
  5. Call MicroXLS_Begin() to start the spreadsheet.
  6. Optionally set up any custom column widths with MicroXLS_SetColumnWidth(). To more closely match the BIFF2 requirements, do this prior to adding any cells.
  7. Add cells with MicroXLS_Add* functions.
  8. Finish the spreadsheet by calling MicroXLS_Finish(). Don't forget this step! Excel won't open the file properly without it.
  9. Close the output file. You're done!

Limitations

  • The BIFF2 format only supports a single sheet per file.
  • The BIFF2 format limits the length of text cells to a maximum of 255 characters.
  • No formatting (colors, lines, number formatting, etc.) is supported yet.
  • As mentioned earlier, this library only loosely implements the BIFF2 format. It ignores several of the format requirements, but Excel and LibreOffice don't seem to care.
  • iOS's built-in support for reading .xls files is not compatible with files generated by this library (and sadly, neither is Excel for iOS).
  • Many other .xls manipulation libraries are probably incompatible as well.
    • If file compatibility with other .xls libraries is important, you may need to look for a more complicated library that can generate a modern .xls file using BIFF8 and CFB.

Compatibility

I tested a couple of files generated with this library by opening them in multiple versions of Excel. Here are the results:

  • Excel 2.0: Compatible
  • Excel 3.0: Compatible
  • Excel 4.0a: Compatible
  • Excel 5.0c: Compatible
  • Excel 95: Compatible
  • Excel 97: Compatible
  • Excel 2000: Compatible
  • Excel 2002: Compatible
  • Excel 2003: Compatible
  • Excel 2007: Compatible
  • Excel 2010: Compatible, opens in Protected View with no editing allowed
  • Excel 2013: Compatible, opens in Protected View with no editing allowed
  • Excel 2016: Compatible, opens in Protected View with no editing allowed

License

MicroXLSWriter is licensed under a 2-clause BSD license. See the LICENSE file or the header at the top of each source file for details.

I'd definitely love to hear from you if you use this library in your project. This is not required by the license, but I think it will be interesting to hear about what types of projects this code ends up being used in. If you feel like it, contact me (see below).

Contact

If you have any questions or comments, feel free to contact me. I very much appreciate pull requests and bug reports. My contact details are on my GitHub profile page or on my website:

https://www.downtowndougbrown.com/