#201 - [GH-ISSUE #252] Libxlsxwriter API refactoring in progress - Porters take note. - github-starred/libxlsxwriter

gitea-mirror commented

2026-05-05 11:54:15 -06:00

Owner

Originally created by @jmcnamara on GitHub (Nov 11, 2019).
Original GitHub issue: https://github.com/jmcnamara/libxlsxwriter/issues/252

Libxlsxwriter uses two kinds of structs as API parameters:

Complex object like structs such as lxw_worksheet which are instantiated through the library and which are memory managed and freed by the library.
Simple user instantiated structs such as lxw_image_options which are used for passing multiple options to a function.

The second type are always copied by the library and freed afterwards, i.e., the library never touches the public user data. However, some of these struct types are also used internally and some of the fields/members for metadata are shared with the external structs. This can cause issues where these fields aren't initialised by the user or just cause general confusion when inspected by the user.

This also make the API/ABI quite fragile since additional fields are often added to internal structs.

For the next version (0.8.8) of the library I'm going to rework the APIs so that external facing structs only contain documented fields and so that different structs are used internally if they require any additional metadata.

If you are porting or wrapping libxlsxwriter then this change will probably cause you some rework as well (although if you are just following the external documented APIs you will probably be okay).

Hopefully this will be a one-off overhead.

You can try out the changes from this rework on the api_refactor branch.

Originally created by @jmcnamara on GitHub (Nov 11, 2019). Original GitHub issue: https://github.com/jmcnamara/libxlsxwriter/issues/252 Libxlsxwriter uses two kinds of structs as API parameters: 1. Complex object like structs such as [lxw_worksheet ](http://libxlsxwriter.github.io/worksheet_8h.html) which are instantiated through the library and which are memory managed and freed by the library. 2. Simple user instantiated structs such as [lxw_image_options](http://libxlsxwriter.github.io/structlxw__image__options.html) which are used for passing multiple options to a function. The second type are always copied by the library and freed afterwards, i.e., the library never touches the public user data. However, some of these struct types are also used internally and some of the fields/members for metadata are shared with the external structs. This can cause issues where these fields aren't initialised by the user or just cause general confusion when inspected by the user. This also make the API/ABI quite fragile since additional fields are often added to internal structs. For the next version (0.8.8) of the library I'm going to rework the APIs so that external facing structs only contain documented fields and so that different structs are used internally if they require any additional metadata. If you are porting or wrapping libxlsxwriter then this change will probably cause you some rework as well (although if you are just following the external documented APIs you will probably be okay). Hopefully this will be a one-off overhead. You can try out the changes from this rework on the [api_refactor](https://github.com/jmcnamara/libxlsxwriter/tree/api_refactor) branch.

gitea-mirror closed this issue

2026-05-05 11:54:17 -06:00

gitea-mirror commented

2026-05-05 11:54:21 -06:00

Author

Owner

@jmcnamara commented on GitHub (Nov 12, 2019):

@Alexhuszagh @RaFaeL-NN @sjmulder @Paxa@ @FTrautwein @gekola @HalfWayMan @Rolltrax @ropensci @yoeljacobsen @viest @fterrag

Please note this refactoring to libxlsxwriter which may affect your ports/wrappers.

@jmcnamara commented on GitHub (Nov 12, 2019): @Alexhuszagh @RaFaeL-NN @sjmulder @Paxa@ @FTrautwein @gekola @HalfWayMan @Rolltrax @ropensci @yoeljacobsen @viest @fterrag Please note this refactoring to libxlsxwriter which may affect your ports/wrappers.

gitea-mirror commented

2026-05-05 11:54:23 -06:00

Author

Owner

@jmcnamara commented on GitHub (Nov 17, 2019):

I've made a series of changes to fix the internal/external struct issues and document any unused (for now) fields. Hopefully this will make the ABI/API more stable in the future and less brittle for people instantiating structs to pass to the API.

I merge this up to master later and will release it in approximately the next day.

If anyone sees any issues let me know.

@jmcnamara commented on GitHub (Nov 17, 2019): I've made a series of changes to fix the internal/external struct issues and document any unused (for now) fields. Hopefully this will make the ABI/API more stable in the future and less brittle for people instantiating structs to pass to the API. I merge this up to master later and will release it in approximately the next day. If anyone sees any issues let me know.

gitea-mirror commented

2026-05-05 11:54:26 -06:00

Author

Owner

@RaFaeL-NN commented on GitHub (Nov 17, 2019):

I get "error: wrong number of arguments specified for `deprecated' attribute" under MinGW

@RaFaeL-NN commented on GitHub (Nov 17, 2019): I get "error: wrong number of arguments specified for `deprecated' attribute" under MinGW

gitea-mirror commented

2026-05-05 11:54:29 -06:00

Author

Owner

@RaFaeL-NN commented on GitHub (Nov 17, 2019):

Also, code for copying of user_props->created to doc_props does not exists in workbook_set_properties. If it's documented now, I think it must be or not?

@RaFaeL-NN commented on GitHub (Nov 17, 2019): Also, code for copying of user_props->created to doc_props does not exists in workbook_set_properties. If it's documented now, I think it must be or not?

gitea-mirror commented

2026-05-05 11:54:33 -06:00

Author

Owner

@jmcnamara commented on GitHub (Nov 17, 2019):

@RaFaeL-NN

I get "error: wrong number of arguments specified for `deprecated' attribute" under MinGW

I don't see that in my MinGW environment. How are you compiling it?

Also, code for copying of user_props->created to doc_props does not exists in workbook_set_properties. If it's documented now, I think it must be or not?

It is documented in the lxw_doc_properties struct. I'll add it to workbook_set_properties() as well. http://libxlsxwriter.github.io/structlxw__doc__properties.html

@jmcnamara commented on GitHub (Nov 17, 2019): @RaFaeL-NN > I get "error: wrong number of arguments specified for `deprecated' attribute" under MinGW I don't see that in my MinGW environment. How are you compiling it? > Also, code for copying of user_props->created to doc_props does not exists in workbook_set_properties. If it's documented now, I think it must be or not? It is documented in the `lxw_doc_properties` struct. I'll add it to `workbook_set_properties()` as well. http://libxlsxwriter.github.io/structlxw__doc__properties.html

gitea-mirror commented

2026-05-05 11:54:36 -06:00

Author

Owner

@RaFaeL-NN commented on GitHub (Nov 17, 2019):

How are you compiling it?

I don't know how to answer on this. I type "make" in MSYS under Windows

@RaFaeL-NN commented on GitHub (Nov 17, 2019): > How are you compiling it? I don't know how to answer on this. I type "make" in MSYS under Windows

gitea-mirror commented

2026-05-05 11:54:38 -06:00

Author

Owner

@jmcnamara commented on GitHub (Nov 17, 2019):

@RaFaeL-NN

I don't know how to answer on this. I type "make" in MSYS under Windows

I followed the steps shown in the libxlsxwriter user guide for installing on Windows using Mingw-w64 and MSYS2 and when I type make I don't see that, or any other issue:

I'll add it to workbook_set_properties() as well.

I've added an explanation of the created parameter to the workbook_set_properties() docs:

http://libxlsxwriter.github.io/workbook_8h.html#aa814fd7f8d2c3ce86a7aa5d5ed127000

@jmcnamara commented on GitHub (Nov 17, 2019): @RaFaeL-NN > I don't know how to answer on this. I type "make" in MSYS under Windows I followed the steps shown in the [libxlsxwriter user guide for installing on Windows using Mingw-w64 and MSYS2](http://libxlsxwriter.github.io/getting_started.html#gsg_ming) and when I type `make` I don't see that, or any other issue: > I'll add it to `workbook_set_properties()` as well. I've added an explanation of the `created` parameter to the `workbook_set_properties()` docs: http://libxlsxwriter.github.io/workbook_8h.html#aa814fd7f8d2c3ce86a7aa5d5ed127000

gitea-mirror commented

2026-05-05 11:54:41 -06:00

Author

Owner

@RaFaeL-NN commented on GitHub (Nov 17, 2019):

I've added an explanation of the created parameter to the workbook_set_properties() docs:

I still can't see any code for this in workbook_set_properties in workbook.c at master. How it works? Is there an example?

@RaFaeL-NN commented on GitHub (Nov 17, 2019): > I've added an explanation of the created parameter to the workbook_set_properties() docs: I still can't see any code for this in workbook_set_properties in workbook.c at master. How it works? Is there an example?

gitea-mirror commented

2026-05-05 11:54:43 -06:00

Author

Owner

@jmcnamara commented on GitHub (Nov 17, 2019):

I still can't see any code for this in workbook_set_properties in workbook.c at master.

Sorry. I understand now. I had omitted copying the user value. I've fixed it on master.

Here is a working example:

#include "xlsxwriter.h"

int main() {

    lxw_workbook  *workbook   = workbook_new("doc_properties.xlsx");
    lxw_worksheet *worksheet  = workbook_add_worksheet(workbook, NULL);

    struct tm tmp_tm;
    tmp_tm.tm_year  = 119;
    tmp_tm.tm_mon   = 3;
    tmp_tm.tm_mday  = 17;
    tmp_tm.tm_hour  = 19;
    tmp_tm.tm_min   = 45;
    tmp_tm.tm_sec   = 15;
    tmp_tm.tm_isdst = -1;

    /* Create a properties structure and set some of the fields. */
    lxw_doc_properties properties = {
        .title    = "This is an example spreadsheet",
        .subject  = "With document properties",
        .author   = "John McNamara",
        .manager  = "Dr. Heinz Doofenshmirtz",
        .company  = "of Wolves",
        .category = "Example spreadsheets",
        .keywords = "Sample, Example, Properties",
        .comments = "Created with libxlsxwriter",
        .status   = "Quo",
        .created  = timegm(&tmp_tm),
    };

    /* Set the properties in the workbook. */
    workbook_set_properties(workbook, &properties);

    /* Add some text to the file. */
    worksheet_set_column(worksheet, 0, 0, 50, NULL);
    worksheet_write_string(worksheet, 0, 0,
                           "Select 'Workbook Properties' to see properties." , NULL);

    workbook_close(workbook);

    return 0;
}

@jmcnamara commented on GitHub (Nov 17, 2019): > I still can't see any code for this in workbook_set_properties in workbook.c at master. Sorry. I understand now. I had omitted copying the user value. I've fixed it on master. Here is a working example: ```C #include "xlsxwriter.h" int main() { lxw_workbook *workbook = workbook_new("doc_properties.xlsx"); lxw_worksheet *worksheet = workbook_add_worksheet(workbook, NULL); struct tm tmp_tm; tmp_tm.tm_year = 119; tmp_tm.tm_mon = 3; tmp_tm.tm_mday = 17; tmp_tm.tm_hour = 19; tmp_tm.tm_min = 45; tmp_tm.tm_sec = 15; tmp_tm.tm_isdst = -1; /* Create a properties structure and set some of the fields. */ lxw_doc_properties properties = { .title = "This is an example spreadsheet", .subject = "With document properties", .author = "John McNamara", .manager = "Dr. Heinz Doofenshmirtz", .company = "of Wolves", .category = "Example spreadsheets", .keywords = "Sample, Example, Properties", .comments = "Created with libxlsxwriter", .status = "Quo", .created = timegm(&tmp_tm), }; /* Set the properties in the workbook. */ workbook_set_properties(workbook, &properties); /* Add some text to the file. */ worksheet_set_column(worksheet, 0, 0, 50, NULL); worksheet_write_string(worksheet, 0, 0, "Select 'Workbook Properties' to see properties." , NULL); workbook_close(workbook); return 0; } ```

gitea-mirror commented

2026-05-05 11:54:46 -06:00

Author

Owner

@jmcnamara commented on GitHub (Nov 20, 2019):

Merged upstream in version 0.8.8.

@jmcnamara commented on GitHub (Nov 20, 2019): Merged upstream in version 0.8.8.

Rows
Columns

[GH-ISSUE #252] Libxlsxwriter API refactoring in progress - Porters take note. #201