c/libxlsxwriter
1
0
Fork 0
mirror of https://github.com/jmcnamara/libxlsxwriter synced 2025-03-28 21:13:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add support for Unix datetimes.

Browse Source
This commit is contained in:
John McNamara 2021-07-01 21:00:59 +01:00
parent 36edb6898d
commit 9b89841750
16 changed files with 314 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
dev/release/fix_example_docs.pl
View File

@ -2,7 +2,7 @@
#
# Simple program to arrange the example programs in a user defined order
# instead or sorted order. Also add a caption.
# instead of a sorted order. Also add a caption.
#
# Copyright 2014-2021, John McNamara, jmcnamara@cpan.org
#
@ -21,7 +21,8 @@ my @examples = (
[ 'format_num_format.c', 'Example of writing data with number formatting' ],
[ 'dates_and_times01.c', 'Writing dates and times with numbers' ],
[ 'dates_and_times02.c', 'Writing dates and times with datetime' ],
[ 'dates_and_times03.c', 'Dates and times with different formats' ],
[ 'dates_and_times03.c', 'Writing dates and times with Unix datetimes' ],
[ 'dates_and_times04.c', 'Dates and times with different formats' ],
[ 'hyperlinks.c', 'A example of writing urls/hyperlinks' ],
[ 'rich_strings.c', 'A example of writing "rich" multi-format strings' ],
[ 'array_formula.c', 'A example of using array formulas' ],

BIN
docs/images/date_example03.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 94 KiB

After

Width:  |  Height:  |  Size: 88 KiB

BIN
docs/images/date_example04.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 103 KiB

21
docs/src/examples.dox
View File

@ -174,13 +174,30 @@ date formatting.
<table width="600">
<tr>
<td>@ref dates_and_times02.c "&lt;&lt; dates_and_times02.c"</td>
<td align="right">@ref dates_and_times04.c "dates_and_times04.c &gt;&gt;"</td>
</tr>
</table>
Example of writing dates and times in Excel using Unix datetimes and
formatting.
@image html date_example03.png
@example dates_and_times04.c
<table width="600">
<tr>
<td>@ref dates_and_times03.c "&lt;&lt; dates_and_times03.c"</td>
<td align="right">@ref hyperlinks.c "hyperlinks.c &gt;&gt;"</td>
</tr>
</table>
Example of writing dates and times in Excel using different date formats.
@image html date_example03.png
@image html date_example04.png
@ -189,7 +206,7 @@ Example of writing dates and times in Excel using different date formats.
<table width="600">
<tr>
<td>@ref dates_and_times03.c "&lt;&lt; dates_and_times03.c"</td>
<td>@ref dates_and_times04.c "&lt;&lt; dates_and_times04.c"</td>
<td align="right">@ref rich_strings.c "rich_strings.c &gt;&gt;"</td>
</tr>
</table>

10
docs/src/examples.txt
View File

@ -79,10 +79,18 @@ date formatting.
##############################################################
@example dates_and_times03.c
Example of writing dates and times in Excel using different date formats.
Example of writing dates and times in Excel using Unix datetimes and
formatting.
@image html date_example03.png
##############################################################
@example dates_and_times04.c
Example of writing dates and times in Excel using different date formats.
@image html date_example04.png
##############################################################
@example hyperlinks.c

45
docs/src/working_with_dates.dox
View File

@ -1,14 +1,15 @@
/**
@page working_with_dates Working with Dates and Times
@tableofcontents
Dates and times in Excel are represented by real numbers. For example a date
that is displayed in Excel as "Jan 1 2013 12:00 PM" is stored as the number
41275.5.
The integer part of the number stores the number of days since the epoch,
which is generally 1900, and the fractional part stores the percentage of the
day.
The integer part of the number stores the number of days since the
epoch, which is generally 1900, and the fractional part stores the percentage
of the day.
A date or time in Excel is just like any other number. To display the number
as a date you must apply an Excel number format to it. Here is an example:
@ -20,8 +21,14 @@ as a date you must apply an Excel number format to it. Here is an example:
@image html date_example01.png
Some options for creating or converting dates to the correct format are shown
below.
@section ww_date_struct Writing datetimes with the lxw_datetime struct
To make working with dates and times a little easier the `libxlsxwriter`
library provides the lxw_datetime struct and the worksheet_write_datetime()
library provides the lxw_datetime struct and the `worksheet_write_datetime()`
function.
The members of the lxw_datetime struct and the range of their values are:
@ -64,17 +71,41 @@ The output from this program is the same as the previous example.
@image html date_example02.png
Dates can be formatted using any of the date formats supported by Excel. Here
is a longer example that shows the same date in a several different formats:
@section ww_date_unix Writing Unix datetimes
Another alternative when handling dates is [Unix
Time](https://en.wikipedia.org/wiki/Unix_time) which is a common integer time
format. It is defined as the number of seconds since the Unix epoch
(1970-01-01 00:00 UTC).
The `worksheet_write_unixtime()` function can be used to write dates and times
in this format. Negative values can also be used for dates prior to 1970:
@dontinclude dates_and_times03.c
@skip include
@until return
@until }
The output from this program is:
@image html date_example03.png
@section ww_date_formats Date formatting
Dates can be formatted using any of the date formats supported by Excel. Here
is a longer example that shows the same date in a several different formats:
@dontinclude dates_and_times04.c
@skip include
@until return
@until }
@image html date_example04.png
To get date formats that show up in Excel as a "Date" or "Time" number
category see @ref ww_formats_categories.
Next: @ref working_with_charts
*/

4
examples/dates_and_times01.c
View File

@ -32,8 +32,8 @@ int main() {
worksheet_write_number(worksheet, 0, 0, number, NULL ); // 41333.5
/* Write the number with formatting. Note: the worksheet_write_datetime()
* function is preferable for writing dates and times. This is for
* demonstration purposes only.
* or worksheet_write_unixtime() functions are preferable for writing
* dates and times. This is for demonstration purposes only.
*/
worksheet_write_number(worksheet, 1, 0, number, format); // Feb 28 2013 12:00 PM

62
examples/dates_and_times03.c
View File

@ -1,7 +1,8 @@
/*
* Example of writing dates and times in Excel using different date formats.
* Example of writing dates and times in Excel using a Unix datetime and date
* formatting.
*
* Copyright 2014-2018, John McNamara, jmcnamara@cpan.org
* Copyright 2014-2021, John McNamara, jmcnamara@cpan.org
*
*/
@ -9,62 +10,27 @@
int main() {
/* A datetime to display. */
lxw_datetime datetime = {2013, 1, 23, 12, 30, 5.123};
uint32_t row = 0;
uint16_t col = 0;
int i;
/* Examples date and time formats. In the output file compare how changing
* the format strings changes the appearance of the date.
*/
char *date_formats[] = {
"dd/mm/yy",
"mm/dd/yy",
"dd m yy",
"d mm yy",
"d mmm yy",
"d mmmm yy",
"d mmmm yyy",
"d mmmm yyyy",
"dd/mm/yy hh:mm",
"dd/mm/yy hh:mm:ss",
"dd/mm/yy hh:mm:ss.000",
"hh:mm",
"hh:mm:ss",
"hh:mm:ss.000",
};
/* Create a new workbook and add a worksheet. */
lxw_workbook *workbook = workbook_new("date_and_times03.xlsx");
lxw_worksheet *worksheet = workbook_add_worksheet(workbook, NULL);
/* Add a bold format. */
lxw_format *bold = workbook_add_format(workbook);
format_set_bold(bold);
/* Write the column headers. */
worksheet_write_string(worksheet, row, col, "Formatted date", bold);
worksheet_write_string(worksheet, row, col + 1, "Format", bold);
/* Add a format with date formatting. */
lxw_format *format = workbook_add_format(workbook);
format_set_num_format(format, "mmm d yyyy hh:mm AM/PM");
/* Widen the first column to make the text clearer. */
worksheet_set_column(worksheet, 0, 1, 20, NULL);
worksheet_set_column(worksheet, 0, 0, 20, NULL);
/* Write the same date and time using each of the above formats. */
for (i = 0; i < 14; i++) {
row++;
/* Write some Unix datetimes with formatting. */
/* Create a format for the date or time.*/
lxw_format *format = workbook_add_format(workbook);
format_set_num_format(format, date_formats[i]);
format_set_align(format, LXW_ALIGN_LEFT);
/* 1970-01-01. The Unix epoch. */
worksheet_write_unixtime(worksheet, 0, 0, 0, format);
/* Write the datetime with each format. */
worksheet_write_datetime(worksheet, row, col, &datetime, format);
/* 2000-01-01. */
worksheet_write_unixtime(worksheet, 1, 0, 1577836800, format);
/* Also write the format string for comparison. */
worksheet_write_string(worksheet, row, col + 1, date_formats[i], NULL);
}
/* 1900-01-01. */
worksheet_write_unixtime(worksheet, 2, 0, -2208988800, format);
return workbook_close(workbook);
}

70
examples/dates_and_times04.c Normal file
View File

@ -0,0 +1,70 @@
/*
* Example of writing dates and times in Excel using different date formats.
*
* Copyright 2014-2018, John McNamara, jmcnamara@cpan.org
*
*/
#include "xlsxwriter.h"
int main() {
/* A datetime to display. */
lxw_datetime datetime = {2013, 1, 23, 12, 30, 5.123};
uint32_t row = 0;
uint16_t col = 0;
int i;
/* Examples date and time formats. In the output file compare how changing
* the format strings changes the appearance of the date.
*/
char *date_formats[] = {
"dd/mm/yy",
"mm/dd/yy",
"dd m yy",
"d mm yy",
"d mmm yy",
"d mmmm yy",
"d mmmm yyy",
"d mmmm yyyy",
"dd/mm/yy hh:mm",
"dd/mm/yy hh:mm:ss",
"dd/mm/yy hh:mm:ss.000",
"hh:mm",
"hh:mm:ss",
"hh:mm:ss.000",
};
/* Create a new workbook and add a worksheet. */
lxw_workbook *workbook = workbook_new("date_and_times04.xlsx");
lxw_worksheet *worksheet = workbook_add_worksheet(workbook, NULL);
/* Add a bold format. */
lxw_format *bold = workbook_add_format(workbook);
format_set_bold(bold);
/* Write the column headers. */
worksheet_write_string(worksheet, row, col, "Formatted date", bold);
worksheet_write_string(worksheet, row, col + 1, "Format", bold);
/* Widen the first column to make the text clearer. */
worksheet_set_column(worksheet, 0, 1, 20, NULL);
/* Write the same date and time using each of the above formats. */
for (i = 0; i < 14; i++) {
row++;
/* Create a format for the date or time.*/
lxw_format *format = workbook_add_format(workbook);
format_set_num_format(format, date_formats[i]);
format_set_align(format, LXW_ALIGN_LEFT);
/* Write the datetime with each format. */
worksheet_write_datetime(worksheet, row, col, &datetime, format);
/* Also write the format string for comparison. */
worksheet_write_string(worksheet, row, col + 1, date_formats[i], NULL);
}
return workbook_close(workbook);
}

22
include/xlsxwriter/utility.h
View File

@ -183,7 +183,7 @@ uint16_t lxw_name_to_col_2(const char *col_str);
* @return A double representing an Excel datetime.
*
* The `%lxw_datetime_to_excel_datetime()` function converts a datetime in
* #lxw_datetime to and Excel datetime number:
* #lxw_datetime to an Excel datetime number:
*
* @code
* lxw_datetime datetime = {2013, 2, 28, 12, 0, 0.0};
@ -198,6 +198,26 @@ double lxw_datetime_to_excel_datetime(lxw_datetime *datetime);
double lxw_datetime_to_excel_date_epoch(lxw_datetime *datetime,
uint8_t date_1904);
/**
* @brief Converts a unix datetime to an Excel datetime number.
*
* @param unixtime Unix time (seconds since 1970-01-01)
*
* @return A double representing an Excel datetime.
*
* The `%lxw_unixtime_to_excel_date()` function converts a unix datetime to
* an Excel datetime number:
*
* @code
* double excel_datetime = lxw_unixtime_to_excel_date(946684800);
* @endcode
*
* See @ref working_with_dates for more details.
*/
double lxw_unixtime_to_excel_date(time_t unixtime);
double lxw_unixtime_to_excel_date_epoch(time_t unixtime, uint8_t date_1904);
char *lxw_strdup(const char *str);
char *lxw_strdup_formula(const char *formula);

40
include/xlsxwriter/worksheet.h
View File

@ -2103,7 +2103,7 @@ lxw_error worksheet_write_dynamic_array_formula_num(lxw_worksheet *worksheet,
*
* @return A #lxw_error code.
*
* The `worksheet_write_datetime()` function can be used to write a date or
* The `%worksheet_write_datetime()` function can be used to write a date or
* time to the cell specified by `row` and `column`:
*
* @dontinclude dates_and_times02.c
@ -2124,6 +2124,44 @@ lxw_error worksheet_write_datetime(lxw_worksheet *worksheet,
lxw_col_t col, lxw_datetime *datetime,
lxw_format *format);
/**
* @brief Write a Unix datetime to a worksheet cell.
*
* @param worksheet Pointer to a lxw_worksheet instance to be updated.
* @param row The zero indexed row number.
* @param col The zero indexed column number.
* @param unixtime The Unix datetime to write to the cell.
* @param format A pointer to a Format instance or NULL.
*
* @return A #lxw_error code.
*
* The `%worksheet_write_unixtime()` function can be used to write dates and
* times in Unix date format to the cell specified by `row` and
* `column`. [Unix Time](https://en.wikipedia.org/wiki/Unix_time) which is a
* common integer time format. It is defined as the number of seconds since
* the Unix epoch (1970-01-01 00:00 UTC). Negative values can also be used for
* dates prior to 1970:
*
* @dontinclude dates_and_times03.c
* @skip 1970
* @until 2208988800
*
* The `format` parameter should be used to apply formatting to the cell using
* a @ref format.h "Format" object as shown above. Without a date format the
* datetime will appear as a number only.
*
* The output from this code sample is:
*
* @image html date_example03.png
*
* See @ref working_with_dates for more information about handling dates and
* times in libxlsxwriter.
*/
lxw_error worksheet_write_unixtime(lxw_worksheet *worksheet,
lxw_row_t row,
lxw_col_t col, time_t unixtime,
lxw_format *format);
/**
*
* @param worksheet Pointer to a lxw_worksheet instance to be updated.

1
src/styles.c
View File

@ -1416,7 +1416,6 @@ lxw_styles_assemble_xml_file(lxw_styles *self)
/* Write the tableStyles element. */
_write_table_styles(self);
/* Close the style sheet tag. */
lxw_xml_end_tag(self->file, "styleSheet");
}

28
src/utility.c
View File

@ -419,6 +419,34 @@ lxw_datetime_to_excel_datetime(lxw_datetime *datetime)
return lxw_datetime_to_excel_date_epoch(datetime, LXW_FALSE);
}
/*
* Convert a unix datetime (1970/01/01 epoch) to an Excel serial date, with a
* 1900 epoch.
*/
double
lxw_unixtime_to_excel_date(time_t unixtime)
{
return lxw_unixtime_to_excel_date_epoch(unixtime, LXW_FALSE);
}
/*
* Convert a unix datetime (1970/01/01 epoch) to an Excel serial date, with a
* 1900 or 1904 epoch.
*/
double
lxw_unixtime_to_excel_date_epoch(time_t unixtime, uint8_t date_1904)
{
double excel_datetime = 0.0;
int epoch = date_1904 ? 24107.0 : 25568.0;
excel_datetime = epoch + (unixtime / (24 * 60 * 60.0));
if (!date_1904 && excel_datetime >= 60.0)
excel_datetime = excel_datetime + 1.0;
return excel_datetime;
}
/* Simple strdup() implementation since it isn't ANSI C. */
char *
lxw_strdup(const char *str)

26
src/worksheet.c
View File

@ -7170,6 +7170,32 @@ worksheet_write_datetime(lxw_worksheet *self,
return LXW_NO_ERROR;
}
/*
* Write a date and or time to a cell in Excel.
*/
lxw_error
worksheet_write_unixtime(lxw_worksheet *self,
lxw_row_t row_num,
lxw_col_t col_num,
time_t unixtime, lxw_format *format)
{
lxw_cell *cell;
double excel_date;
lxw_error err;
err = _check_dimensions(self, row_num, col_num, LXW_FALSE, LXW_FALSE);
if (err)
return err;
excel_date = lxw_unixtime_to_excel_date_epoch(unixtime, LXW_EPOCH_1900);
cell = _new_number_cell(row_num, col_num, excel_date, format);
_insert_cell(self, row_num, col_num, cell);
return LXW_NO_ERROR;
}
/*
* Write a hyperlink/url to an Excel file.
*/

9
test/unit/helper.h
View File

@ -126,3 +126,12 @@
\
ASSERT_DOUBLE(exp, got); \
free(datetime);
#define TEST_UNIXTIME(_unixtime, exp) \
got = lxw_unixtime_to_excel_date(_unixtime); \
ASSERT_DOUBLE(exp, got);
#define TEST_UNIXTIME_1904(_unixtime, exp) \
got = lxw_unixtime_to_excel_date_epoch(_unixtime, 1); \
ASSERT_DOUBLE(exp, got);

40
test/unit/utility/test_datetime_to_excel.c
View File

@ -12,7 +12,7 @@
// Test _datetime_to_excel_date().
CTEST(utility, _datetime_date_and_time) {
CTEST(utility, test_datetime_date_and_time) {
double got;
lxw_datetime *datetime;
@ -117,7 +117,7 @@ CTEST(utility, _datetime_date_and_time) {
TEST_DATETIME(9999, 12, 31, 23, 59, 59.000, 2958465.999988426);
}
CTEST(utility, _datetime_date_only) {
CTEST(utility, test_datetime_date_only) {
double got;
lxw_datetime *datetime;
@ -324,7 +324,7 @@ CTEST(utility, _datetime_date_only) {
}
CTEST(utility, _datetime_date_only_1904) {
CTEST(utility, test_datetime_date_only_1904) {
double got;
lxw_datetime *datetime;
@ -532,7 +532,7 @@ CTEST(utility, _datetime_date_only_1904) {
TEST_DATETIME_DATE_1904(9999, 12, 31, 2957003);
}
CTEST(utility, _datetime_time_only) {
CTEST(utility, test_datetime_time_only) {
double got;
lxw_datetime *datetime;
@ -636,3 +636,35 @@ CTEST(utility, _datetime_time_only) {
TEST_DATETIME_TIME(23, 17, 12.632, 0.97028509259259266);
TEST_DATETIME_TIME(23, 59, 59.999, 0.99999998842592586);
}
CTEST(utility, test_unixtime) {
double got;
TEST_UNIXTIME(-2209075200, 0); // 1899-12-31 00:00
TEST_UNIXTIME(-2209032000, 0.5); // 1899-12-31 12:00
TEST_UNIXTIME(-2208988800, 1); // 1900-01-01 00:00
TEST_UNIXTIME(-2208945600, 1.5); // 1900-01-01 12:00
TEST_UNIXTIME(-2203977600, 59); // 1900-02-28 00:00
TEST_UNIXTIME(-2203934400, 59.5); // 1900-02-28 12:00
TEST_UNIXTIME(-2203891200, 61); // 1900-03-01 00:00
TEST_UNIXTIME(-2203848000, 61.5); // 1900-03-01 12:00
TEST_UNIXTIME(0, 25569); // 1970-01-01 00:00
TEST_UNIXTIME(43200, 25569.5); // 1970-01-01 12:00
TEST_UNIXTIME(946684800, 36526); // 2000-01-01 00:00
TEST_UNIXTIME(946728000, 36526.5); // 2000-01-01 12:00
}
CTEST(utility, test_unixtime_1904) {
double got;
TEST_UNIXTIME_1904(-2082844800, 0); // 1904-01-01 00:00
TEST_UNIXTIME_1904(-2082801600, 0.5); // 1904-01-01 12:00
TEST_UNIXTIME_1904(0, 24107); // 1970-01-01 00:00
TEST_UNIXTIME_1904(43200, 24107.5); // 1970-01-01 12:00
TEST_UNIXTIME_1904(946684800, 35064); // 2000-01-01 00:00
TEST_UNIXTIME_1904(946728000, 35064.5); // 2000-01-01 12:00
}