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

Added docs for array funcitons.

Browse Source
This commit is contained in:
John McNamara 2015-04-16 00:13:40 +01:00
parent 58bfa45752
commit a701fee122
6 changed files with 137 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
Changes.txt
View File

@ -4,15 +4,18 @@
## 0.1.3 March 15 2015
- Added `worksheet_write_array_formula()` function to allow writing of
array formulas in worksheets.
## 0.1.2 March 14 2015
- Added `worksheet_set_h_pagebreaks()` and `worksheet_set_v_pagebreaks()`
functions to define worksheet page breaks.
- Added LXW_FOREACH_WORKSHEET() macro to allow iteration over all the
worksheets in a workbook.
## 0.1.2 March 14 2015
- Added `worksheet_set_print_scale()` function to set the scale factor for
the printed page.
@ -24,8 +27,8 @@
- Added `worksheet_print_area()` function to control the print area of a
worksheet.
- Added `worksheet_fit_to_pages()` function to fit the printed area to a
- Added `worksheet_fit_to_pages()` function to fit the printed area to a
specific number of pages both vertically and horizontally.

1
dev/release/fix_example_docs.pl
View File

@ -22,6 +22,7 @@ my @examples = (
[ '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' ],
[ 'array_formula.c', 'A example of using array formulas' ],
[ 'utf8.c', 'A example of some UTF-8 text' ],
[ 'constant_memory.c', 'Write a large file with constant memory usage' ],
[ 'merge_range.c', 'Create a merged range of cells' ],

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

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 72 KiB

9
docs/src/examples.dox
View File

@ -83,10 +83,17 @@ Next example: @ref dates_and_times03.c
@example dates_and_times03.c
Example of writing dates and times in Excel using different date formats.
Next example: @ref utf8.c
Next example: @ref array_formula.c
@image html date_example03.png
@example array_formula.c
Example of writing array formulas to a worksheet.
Next example: @ref utf8.c
@image html array_formula.png
@example utf8.c
A simple Unicode UTF-8 example. Note, the source file is UTF-8 encoded.

42
examples/array_formula.c Normal file
View File

@ -0,0 +1,42 @@
/*
* Example of how to use the libxlsxwriter library to write simple
* array formulas.
*
* Copyright 2014-2015, John McNamara, jmcnamara@cpan.org
*
*/
#include "xlsxwriter.h"
int main() {
/* Create a new workbook and add a worksheet. */
lxw_workbook *workbook = new_workbook("array_formula.xlsx");
lxw_worksheet *worksheet = workbook_add_worksheet(workbook, NULL);
/* Write some data for the formulas. */
worksheet_write_number(worksheet, 0, 1, 500, NULL);
worksheet_write_number(worksheet, 1, 1, 10, NULL);
worksheet_write_number(worksheet, 4, 1, 1, NULL);
worksheet_write_number(worksheet, 5, 1, 2, NULL);
worksheet_write_number(worksheet, 6, 1, 3, NULL);
worksheet_write_number(worksheet, 0, 2, 300, NULL);
worksheet_write_number(worksheet, 1, 2, 15, NULL);
worksheet_write_number(worksheet, 4, 2, 20234, NULL);
worksheet_write_number(worksheet, 5, 2, 21003, NULL);
worksheet_write_number(worksheet, 6, 2, 10000, NULL);
/* Write an array formula that returns a single value. */
worksheet_write_array_formula(worksheet, 0, 0, 0, 0, "{=SUM(B1:C1*B2:C2)}", NULL);
/* Similar to above but using the RANGE macro. */
worksheet_write_array_formula(worksheet, RANGE("A2:A2"), "{=SUM(B1:C1*B2:C2)}", NULL);
/* Write an array formula that returns a range of values. */
worksheet_write_array_formula(worksheet, 4, 0, 6, 0, "{=TREND(C5:C7,B5:B7)}", NULL);
workbook_close(workbook);
return 0;
}

114
include/xlsxwriter/worksheet.h
View File

@ -479,53 +479,47 @@ int8_t worksheet_write_formula(lxw_worksheet *worksheet,
lxw_col_t col, const char *formula,
lxw_format *format);
/**
* @brief Write a formula to a worksheet cell with a user defined result.
* @brief Write an array formula to a worksheet cell.
*
* @param worksheet Pointer to the lxw_worksheet instance to be updated.
* @param row The zero indexed row number.
* @param col The zero indexed column number.
* @param formula Formula string to write to cell.
* @param format A pointer to a Format instance or NULL.
* @param result A user defined result for a formula.
* @param worksheet
* @param first_row The first row of the range. (All zero indexed.)
* @param first_col The first column of the range.
* @param last_row The last row of the range.
* @param last_col The last col of the range.
* @param formula Array formula to write to cell.
* @param format A pointer to a Format instance or NULL.
*
* @return A #lxw_write_error code.
*
* The `%worksheet_write_formula_num()` function writes a formula or Excel
* function to the cell specified by `row` and `column` with a user defined
* result:
* The `%worksheet_write_array_formula()` function writes an array formula to
* a cell range. In Excel an array formula is a formula that performs a
* calculation on a set of values.
*
* In Excel an array formula is indicated by a pair of braces around the
* formula: `{=SUM(A1:B1*A2:B2)}`.
*
* Array formulas can return a single value or a range or values. For array
* formulas that return a range of values you must specify the range that the
* return values will be written to. This is why this function has `first_`
* and `last_` row/column parameters. The RANGE() macro can also be used to
* specify the range:
*
* @code
* // Required as a workaround only.
* worksheet_write_formula_num(worksheet, 0, 0, "=1 + 2", NULL, 3);
* worksheet_write_array_formula(worksheet, 4, 0, 6, 0, "{=TREND(C5:C7,B5:B7)}", NULL);
*
* // Same as above using the RANGE() macro.
* worksheet_write_array_formula(worksheet, RANGE("A5:A7"), "{=TREND(C5:C7,B5:B7)}", NULL);
* @endcode
*
* Libxlsxwriter doesn't calculate the value of a formula and instead stores
* the value `0` as the formula result. It then sets a global flag in the XLSX
* file to say that all formulas and functions should be recalculated when the
* file is opened.
* If the array formula returns a single value then the `first_` and `last_`
* parameters should be the same:
*
* This is the method recommended in the Excel documentation and in general it
* works fine with spreadsheet applications.
*
* However, applications that don't have a facility to calculate formulas,
* such as Excel Viewer, or some mobile applications will only display the `0`
* results.
*
* If required, the `%worksheet_write_formula_num()` function can be used to
* specify a formula and its result.
*
* This function is rarely required and is only provided for compatibility
* with some third party applications. For most applications the
* worksheet_write_formula() function is the recommended way of writing
* formulas.
* @code
* worksheet_write_array_formula(worksheet, 1, 0, 1, 0, "{=SUM(B1:C1*B2:C2)}", NULL);
* worksheet_write_array_formula(worksheet, RANGE("A2:A2"), "{=SUM(B1:C1*B2:C2)}", NULL);
* @endcode
*
*/
int8_t worksheet_write_formula_num(lxw_worksheet *worksheet,
lxw_row_t row,
lxw_col_t col,
const char *formula,
lxw_format *format, double result);
int8_t worksheet_write_array_formula(lxw_worksheet *worksheet,
lxw_row_t first_row,
lxw_col_t first_col,
@ -604,6 +598,54 @@ int8_t worksheet_write_blank(lxw_worksheet *worksheet,
lxw_row_t row, lxw_col_t col,
lxw_format *format);
/**
* @brief Write a formula to a worksheet cell with a user defined result.
*
* @param worksheet Pointer to the lxw_worksheet instance to be updated.
* @param row The zero indexed row number.
* @param col The zero indexed column number.
* @param formula Formula string to write to cell.
* @param format A pointer to a Format instance or NULL.
* @param result A user defined result for a formula.
*
* @return A #lxw_write_error code.
*
* The `%worksheet_write_formula_num()` function writes a formula or Excel
* function to the cell specified by `row` and `column` with a user defined
* result:
*
* @code
* // Required as a workaround only.
* worksheet_write_formula_num(worksheet, 0, 0, "=1 + 2", NULL, 3);
* @endcode
*
* Libxlsxwriter doesn't calculate the value of a formula and instead stores
* the value `0` as the formula result. It then sets a global flag in the XLSX
* file to say that all formulas and functions should be recalculated when the
* file is opened.
*
* This is the method recommended in the Excel documentation and in general it
* works fine with spreadsheet applications.
*
* However, applications that don't have a facility to calculate formulas,
* such as Excel Viewer, or some mobile applications will only display the `0`
* results.
*
* If required, the `%worksheet_write_formula_num()` function can be used to
* specify a formula and its result.
*
* This function is rarely required and is only provided for compatibility
* with some third party applications. For most applications the
* worksheet_write_formula() function is the recommended way of writing
* formulas.
*
*/
int8_t worksheet_write_formula_num(lxw_worksheet *worksheet,
lxw_row_t row,
lxw_col_t col,
const char *formula,
lxw_format *format, double result);
/**
* @brief Set the properties for a row of cells.
*