StarMirror/xlnt
1
0
Fork 0
mirror of https://github.com/tfussell/xlnt.git synced 2024-03-22 13:11:17 +08:00
Code Issues Projects Releases Wiki Activity

work on documentation

Browse Source
This commit is contained in:
Thomas Fussell 2015-11-03 18:26:33 -05:00
parent 7ec6e2d4df
commit 73f1a8b9ee
36 changed files with 955 additions and 222 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
cmake/xlnt.cmake
View File

@ -10,7 +10,7 @@ FILE(GLOB CELL_HEADERS ../include/xlnt/cell/*.hpp)
FILE(GLOB CHARTS_HEADERS ../include/xlnt/charts/*.hpp)
FILE(GLOB CHARTSHEET_HEADERS ../include/xlnt/chartsheet/*.hpp)
FILE(GLOB DRAWING_HEADERS ../include/xlnt/drawing/*.hpp)
FILE(GLOB FORUMULA_HEADERS ../include/xlnt/formula/*.hpp)
FILE(GLOB FORMULA_HEADERS ../include/xlnt/formula/*.hpp)
FILE(GLOB PACKAGING_HEADERS ../include/xlnt/packaging/*.hpp)
FILE(GLOB SERIALIZATION_HEADERS ../include/xlnt/serialization/*.hpp)
FILE(GLOB STYLES_HEADERS ../include/xlnt/styles/*.hpp)
@ -25,7 +25,7 @@ FILE(GLOB CELL_SOURCES ../source/cell/*.cpp)
FILE(GLOB CHARTS_SOURCES ../source/charts/*.cpp)
FILE(GLOB CHARTSHEET_SOURCES ../source/chartsheet/*.cpp)
FILE(GLOB DRAWING_SOURCES ../source/drawing/*.cpp)
FILE(GLOB FORUMULA_SOURCES ../source/formula/*.cpp)
FILE(GLOB FORMULA_SOURCES ../source/formula/*.cpp)
FILE(GLOB PACKAGING_SOURCES ../source/packaging/*.cpp)
FILE(GLOB SERIALIZATION_SOURCES ../source/serialization/*.cpp)
FILE(GLOB STYLES_SOURCES ../source/styles/*.cpp)
@ -48,7 +48,7 @@ source_group(cell FILES ${CELL_HEADERS} ${CELL_SOURCES})
source_group(charts FILES ${CHARTS_HEADERS} ${CHARTS_SOURCES})
source_group(chartsheet FILES ${CHARTSHEET_HEADERS} ${CHARTSHEET_SOURCES})
source_group(drawing FILES ${DRAWING_HEADERS} ${DRAWING_SOURCES})
source_group(formula FILES ${FORUMULA_HEADERS} ${FORUMULA_SOURCES})
source_group(formula FILES ${FORMULA_HEADERS} ${FORMULA_SOURCES})
source_group(packaging FILES ${PACKAGING_HEADERS} ${PACKAGING_SOURCES})
source_group(serialization FILES ${SERIALIZATION_HEADERS} ${SERIALIZATION_SOURCES})
source_group(styles FILES ${STYLES_HEADERS} ${STYLES_SOURCES})

23
docs/api/xlnt.cell.rst Normal file
View File

@ -0,0 +1,23 @@
Cell Module
===========
.. doxygenstruct:: xlnt::cell_reference_hash
:members:
.. doxygenclass:: xlnt::cell_reference
:members:
.. doxygenclass:: xlnt::cell
:members:
.. doxygenclass:: xlnt::comment
:members:
.. doxygentypedef:: xlnt::row_t
.. doxygenclass:: xlnt::column_t
:members:
.. doxygenstruct:: xlnt::column_hash
:members:

2
docs/api/xlnt.charts.rst Normal file
View File

@ -0,0 +1,2 @@
Charts Module
=============

2
docs/api/xlnt.chartsheet.rst Normal file
View File

@ -0,0 +1,2 @@
Charsheet Module
================

5
docs/api/xlnt.drawing.rst Normal file
View File

@ -0,0 +1,5 @@
Drawing Module
==============
.. doxygenclass:: xlnt::drawing
:members:

8
docs/api/xlnt.formula.rst Normal file
View File

@ -0,0 +1,8 @@
Formula Module
==============
.. doxygenclass:: xlnt::tokenizer
:members:
.. doxygenclass:: xlnt::translator
:members:

24
docs/api/xlnt.packaging.rst Normal file
View File

@ -0,0 +1,24 @@
Packaging Module
================
.. doxygenclass:: xlnt::document_properties
:members:
.. doxygenclass:: xlnt::default_type
:members:
.. doxygenclass:: xlnt::override_type
:members:
.. doxygenclass:: xlnt::manifest
:members:
.. doxygenclass:: xlnt::relationship
:members:
.. doxygenstruct:: xlnt::zip_info
:members:
.. doxygenclass:: xlnt::zip_file
:members:

191
docs/api/xlnt.rst
View File

@ -1,183 +1,22 @@
xlnt library
xlnt Library
============
.. doxygenstruct:: xlnt::cell_reference_hash
:members:
.. doxygenenum:: xlnt::limit_style
.. doxygenvariable:: xlnt::LimitStyle
.. doxygenclass:: xlnt::cell_reference
:members:
.. doxygenclass:: xlnt::cell
:members:
.. doxygenclass:: xlnt::comment
:members:
.. doxygenstruct:: xlnt::date
:members:
.. doxygenstruct:: xlnt::time
:members:
.. doxygenstruct:: xlnt::datetime
:members:
.. doxygenstruct:: xlnt::timedelta
:members:
.. doxygenclass:: xlnt::relationship
:members:
.. doxygenstruct:: xlnt::zip_info
:members:
.. doxygenclass:: xlnt::zip_file
:members:
.. doxygenclass:: xlnt::drawing
:members:
.. doxygenclass:: xlnt::tokenizer
:members:
.. doxygenclass:: xlnt::translator
:members:
.. doxygenclass:: xlnt::alignment
:members:
.. doxygenclass:: xlnt::border
:members:
.. doxygenclass:: xlnt::color
:members:
.. doxygenclass:: xlnt::fill
:members:
.. doxygenclass:: xlnt::font
:members:
.. doxygenclass:: xlnt::named_style
:members:
.. doxygenclass:: xlnt::number_format
:members:
.. doxygenclass:: xlnt::protection
:members:
.. doxygenclass:: xlnt::side
:members:
.. doxygenclass:: xlnt::style
:members:
.. doxygenclass:: xlnt::document_properties
:members:
.. doxygenclass:: xlnt::document_security
:members:
.. doxygenclass:: xlnt::manifest
:members:
.. doxygenclass:: xlnt::named_range
:members:
.. doxygenclass:: xlnt::theme
:members:
.. doxygenclass:: xlnt::workbook
:members:
.. doxygenclass:: xlnt::cell_vector
:members:
.. doxygenclass:: xlnt::column_properties
:members:
.. doxygenstruct:: xlnt::major_order
:members:
.. doxygenclass:: xlnt::page_margins
:members:
.. doxygenstruct:: xlnt::page_setup
:members:
.. doxygenclass:: xlnt::pane
:members:
.. doxygenclass:: xlnt::range_reference
:members:
.. doxygenclass:: xlnt::range
:members:
.. doxygenclass:: xlnt::row_properties
:members:
.. doxygenclass:: xlnt::sheet_protection
:members:
.. doxygenclass:: xlnt::sheet_view
:members:
.. doxygenclass:: xlnt::header
:members:
.. doxygenclass:: xlnt::footer
:members:
.. doxygenclass:: xlnt::header_footer
:members:
.. doxygenstruct:: xlnt::margins
:members:
.. doxygenclass:: xlnt::worksheet
:members:
.. doxygenclass:: xlnt::comment_serializer
:members:
.. doxygenclass:: xlnt::excel_serializer
:members:
.. doxygenclass:: xlnt::manifest_serializer
:members:
.. doxygenclass:: xlnt::relationship_serializer
:members:
.. doxygenclass:: xlnt::shared_strings_serializer
:members:
.. doxygenclass:: xlnt::style_serializer
:members:
.. doxygenclass:: xlnt::theme_serializer
:members:
.. doxygenclass:: xlnt::workbook_serializer
:members:
.. doxygenclass:: xlnt::worksheet_serializer
:members:
.. doxygenclass:: xlnt::xml_document
:members:
.. doxygenclass:: xlnt::xml_node
:members:
.. doxygenclass:: xlnt::xml_serializer
:members:
library modules
Library Modules
===============
.. toctree::
xlnt.s11n
xlnt.cell
xlnt.chart
xlnt.chartsheet
xlnt.drawing
xlnt.formula
xlnt.packaging
xlnt.serialization
xlnt.styles
xlnt.utils
xlnt.workbook
xlnt.worksheet

5
docs/api/xlnt.s11n.rst → docs/api/xlnt.serialization.rst
View File

@ -1,9 +1,12 @@
serialization module
Serialization Module
====================
.. doxygenclass:: xlnt::comment_serializer
:members:
.. doxygenenum:: xlnt::encoding
:members:
.. doxygenclass:: xlnt::excel_serializer
:members:

38
docs/api/xlnt.styles.rst Normal file
View File

@ -0,0 +1,38 @@
Styles Module
=============
.. doxygenclass:: xlnt::alignment
:members:
.. doxygenenum:: xlnt::border
:members:
.. doxygenclass:: xlnt::border
:members:
.. doxygenclass:: xlnt::color
:members:
.. doxygenclass:: xlnt::fill
:members:
.. doxygenclass:: xlnt::font
:members:
.. doxygenclass:: xlnt::named_style
:members:
.. doxygenclass:: xlnt::number_format
:members:
.. doxygenclass:: xlnt::protection
:members:
.. doxygenenum:: xlnt::border_style
:members:
.. doxygenclass:: xlnt::side
:members:
.. doxygenclass:: xlnt::style
:members:

47
docs/api/xlnt.utils.rst Normal file
View File

@ -0,0 +1,47 @@
Utilities Module
================
.. doxygenstruct:: xlnt::date
:members:
.. doxygenstruct:: xlnt::time
:members:
.. doxygenstruct:: xlnt::datetime
:members:
.. doxygenstruct:: xlnt::timedelta
:members:
.. doxygenclass:: xlnt::cell_coordinates_exception
:members:
.. doxygenclass:: xlnt::illegal_character_error
:members:
.. doxygenclass:: xlnt::column_string_index_exception
:members:
.. doxygenclass:: xlnt::data_type_exception
:members:
.. doxygenclass:: xlnt::named_range_exception
:members:
.. doxygenclass:: xlnt::sheet_title_exception
:members:
.. doxygenclass:: xlnt::invalid_file_exception
:members:
.. doxygenclass:: xlnt::read_only_workbook_exception
:members:
.. doxygenclass:: xlnt::missing_number_format
:members:
.. doxygenclass:: xlnt::attribute_error
:members:
.. doxygenclass:: xlnt::value_error
:members:

17
docs/api/xlnt.workbook.rst Normal file
View File

@ -0,0 +1,17 @@
Workbook Module
===============
.. doxygenclass:: xlnt::document_security
:members:
.. doxygenclass:: xlnt::external_book
:members:
.. doxygenclass:: xlnt::named_range
:members:
.. doxygenclass:: xlnt::theme
:members:
.. doxygenclass:: xlnt::workbook
:members:

56
docs/api/xlnt.worksheet.rst Normal file
View File

@ -0,0 +1,56 @@
Worksheet Module
================
.. doxygenclass:: xlnt::cell_vector
:members:
.. doxygenclass:: xlnt::column_properties
:members:
.. doxygenenum:: xlnt::major_order
:members:
.. doxygenclass:: xlnt::page_margins
:members:
.. doxygenstruct:: xlnt::page_setup
:members:
.. doxygenclass:: xlnt::pane
:members:
.. doxygenclass:: xlnt::range_reference
:members:
.. doxygenclass:: xlnt::range
:members:
.. doxygenclass:: xlnt::row_properties
:members:
.. doxygenclass:: xlnt::selection
:members:
.. doxygenclass:: xlnt::sheet_protection
:members:
.. doxygenclass:: xlnt::sheet_view
:members:
.. doxygenclass:: xlnt::worksheet_properties
:members:
.. doxygenclass:: xlnt::header
:members:
.. doxygenclass:: xlnt::footer
:members:
.. doxygenclass:: xlnt::header_footer
:members:
.. doxygenstruct:: xlnt::margins
:members:
.. doxygenclass:: xlnt::worksheet
:members:

4
docs/changes.rst Normal file
View File

@ -0,0 +1,4 @@
0.9.0 (unreleased)
==================
Beta release

4
docs/charts/introduction.rst Normal file
View File

@ -0,0 +1,4 @@
Charts
======
Charts aren't supported yet.

36
docs/comments.rst Normal file
View File

@ -0,0 +1,36 @@
Comments
========
Adding a comment to a cell
--------------------------
Comments have a text attribute and an author attribute, which must both be set.
.. code-block:: cpp
xlnt::workbook workbook;
auto worksheet = workbook.get_active_sheet();
auto comment = worksheet.get_cell("A1").get_comment();
comment = xlnt::comment("This is the comment text", "Comment Author");
std::cout << comment.get_text() << std::endl;
std::cout << comment.get_author() << std::endl;
You cannot assign the same Comment object to two different cells. Doing so
raises an xlnt::attribute_error.
.. code-block:: cpp
xlnt::workbook workbook;
auto worksheet = workbook.get_active_sheet();
xlnt::comment comment("Text", "Author");
worksheet.get_cell("A1").set_comment(comment);
worksheet.get_cell("B1").set_comment(comment);
// prints: terminate called after throwing an instance of 'xlnt::attribute_error'
Loading and saving comments
----------------------------
Comments present in a workbook when loaded are stored in the comment
attribute of their respective cells automatically. Comments remaining in a workbook when it is saved are automatically saved to
the workbook file.

204
docs/cookbook.rst Normal file
View File

@ -0,0 +1,204 @@
Simple usage
============
Write a workbook
----------------
.. code-block:: cpp
#include <xlnt/xlnt.hpp>
int main()
{
xlnt::workbook wb;
std::string dest_filename = "empty_book.xlsx";
auto ws1 = wb.get_active_sheet();
ws1.set_title("range names");
for(xlnt::row_t row = 1; row < 40; row++)
{
std::vector<int> to_append(600, 0);
std::iota(std::begin(to_append), std::end(to_append), 0);
ws1.append(to_append);
}
auto ws2 = wb.create_sheet("Pi");
ws2.get_cell("F5").set_value(3.14);
for(xlnt::row_t row = 10; row < 20; row++)
{
for(xlnt::column_t column = 27; column < 54; column++)
{
ws3.get_cell(column, row).set_value(column.column_string());
}
}
std::cout << ws3.get_cell("AA10") << std::endl;
wb.save(dest_filename);
return 0;
}
Read an existing workbook
-------------------------
.. code-block:: cpp
#include <xlnt/xlnt.hpp>
int main()
{
xlnt::workbook wb;
wb.load("empty_book.xlsx");
auto sheet_ranges = wb.get_range("range names");
std::cout << sheet_ranges["D18"] << std::endl;
// prints: 3
return 0;
}
.. note ::
There are several optional parameters that can be used in xlnt::workbook::load (in order):
- `guess_types` will enable or disable (default) type inference when
reading cells.
- `data_only` controls whether cells with formulae have either the
formula (default) or the value stored the last time Excel read the sheet.
- `keep_vba` controls whether any Visual Basic elements are preserved or
not (default). If they are preserved they are still not editable.
.. warning ::
xlnt does currently not read all possible items in an Excel file so
images and charts will be lost from existing files if they are opened and
saved with the same name.
Using number formats
--------------------
.. code-block:: cpp
#include <xlnt/xlnt.hpp>
int main()
{
xlnt::workbook wb;
wb.guess_types(true);
auto ws = wb.get_active_sheet();
ws.get_cell("A1").set_value(xlnt::datetime(2010, 7, 21));
std::cout << ws.get_cell("A1").get_number_format().get_format_string() << std::endl
// prints: yyyy-mm-dd h:mm:ss
// set percentage using a string followed by the percent sign
ws.get_cell("B1").set_value("3.14%");
std::cout << cell.get_value<long double>() << std::endl;
// prints: 0.031400000000000004
std::cout << cell << std::endl;
// prints: 3.14%
std::cout << cell.get_number_format().get_format_string() << std::endl;
// prints: 0%
return 0;
}
Using formulae
--------------
.. code-block:: cpp
#include <xlnt/xlnt.hpp>
int main()
{
xlnt::workbook wb;
auto ws = wb.get_active_sheet();
ws.get_cell("A1").set_formula("=SUM(1, 1)");
wb.save("formula.xlsx");
}
.. warning::
NB you must use the English name for a function and function arguments *must* be separated by commas and not other punctuation such as semi-colons.
xlsx never evaluates formula but it is possible to check the name of a formula:
.. code-block:: cpp
#include <xlnt/xlnt.hpp>
int main()
{
bool found = xlnt::formulae::exists("HEX2DEC");
std::cout << (found ? "True" : "False") << std::endl;
// prints: True
return 0;
}
If you're trying to use a formula that isn't known this could be because you're using a formula that was not included in the initial specification. Such formulae must be prefixed with `xlfn.` to work.
Merge / Unmerge cells
---------------------
.. code-block:: cpp
#include <xlnt/xlnt.hpp>
int main()
{
xlnt::workbook wb;
auto ws = wb.get_active_sheet();
ws.merge_cells("A1:B1");
ws.unmerge_cells("A1:B1");
// or
ws.merge_cells(1, 2, 4, 2)
ws.unmerge_cells(1, 2, 4, 2);
return 0;
}
Inserting an image
-------------------
.. code-block:: cpp
#include <xlnt/xlnt.hpp>
int main()
{
xlnt::workbook wb;
auto ws = wb.get_active_sheet();
ws.get_cell("A1").set_value("You should see three logos below");
// create an image
auto img = xlnt::image("logo.png");
// add to worksheet and anchor next to cells
ws.add_image(img, "A1");
wb.save("logo.xlsx");
return 0;
}
Fold columns (outline)
----------------------
.. code-block:: cpp
int main()
{
xlnt::workbook wb;
auto ws = wb.create_sheet();
bool hidden = true;
ws.group_columns("A", "D", hidden);
wb.save("group.xlsx");
return 0;
}

50
docs/development.rst Normal file
View File

@ -0,0 +1,50 @@
Development
===========
What is suppoprted
------------------
Supporting different platforms
------------------------------
Coding style
------------
Testing
-------
Coverage
++++++++
Organisation
++++++++++++
Checking XML
++++++++++++
Schema validation
+++++++++++++++++
Microsoft Tools
+++++++++++++++
Contributing
------------
Contributions in the form of pull requests are always welcome. Don't forget
to add yourself to the list of authors!
Branch naming convention
------------------------
Pull Requests
-------------
Documentation
+++++++++++++
Benchmarking
------------
Memory Use
++++++++++

4
docs/formatting.rst Normal file
View File

@ -0,0 +1,4 @@
Conditional Formatting
======================
Not supported yet.

106
docs/formula.rst Normal file
View File

@ -0,0 +1,106 @@
Parsing Formulas
================
`xlnt` supports limited parsing of formulas embedded in cells. The
`xlnt/formula` module contains a `tokenizer` class to break
formulas into their consitutuent tokens. Usage is as follows:
.. code-block:: cpp
#include <xlnt/xlnt.hpp>
int main()
{
std::string formula = R"(=IF($A$1,"then True",MAX(DEFAULT_VAL,'Sheet 2'!B1)))";
xlnt::tokenizer tok(formula);
tok.parse();
for(auto &t : tok.get_items())
{
std::cout << t.get_value() << "\t" << t.get_type() << "\t" << t.get_subtype() << std::endl;
}
// prints:
//
// IF( FUNC OPEN
// $A$1 OPERAND RANGE
// , SEP ARG
// "then True" OPERAND TEXT
// , SEP ARG
// MAX( FUNC OPEN
// DEFAULT_VAL OPERAND RANGE
// , SEP ARG
// 'Sheet 2'!B1 OPERAND RANGE
// ) FUNC CLOSE
// ) FUNC CLOSE
return 0;
}
As shown above, tokens have three attributes of interest:
* ``.value``: The substring of the formula that produced this token
* ``.type``: The type of token this represents. Can be one of
- ``token::literal``: If the cell does not contain a formula, its
value is represented by a single ``LITERAL`` token.
- ``token::operand``: A generic term for any value in the Excel
formula. (See ``.subtype`` below for more details).
- ``token::func``: Function calls are broken up into tokens for the
opener (e.g., ``SUM(``), followed by the arguments, followed by
the closer (i.e., ``)``). The function name and opening
parenthesis together form one ``FUNC`` token, and the matching
parenthesis forms another ``FUNC`` token.
- ``token::array``: Array literals (enclosed between curly braces)
get two ``ARRAY`` tokens each, one for the opening ``{`` and one
for the closing ``}``.
- ``token::paren``: When used for grouping subexpressions (and not to
denote function calls), parentheses are tokenized as ``paren``
tokens (one per character).
- ``token::sep``: These tokens are created from either commas (``,``)
or semicolons (``;``). Commas create ``sep`` tokens when they are
used to separate function arguments (e.g., ``SUM(a,b)``) or when
they are used to separate array elements (e.g., ``{a,b}``). (They
have another use as an infix operator for joining
ranges). Semicolons are always used to separate rows in an array
literal, so always create ``sep`` tokens.
- ``token::op_pre``: Designates a prefix unary operator. Its value is
always ``+`` or ``-``
- ``token::op_in``: Designates an infix binary operator. Possible
values are ``>=``, ``<=``, ``<>``, ``=``, ``>``, ``<``, ``*``,
``/``, ``+``, ``-``, ``^``, or ``&``.
- ``token::op_post``: Designates a postfix unary operator. Its value
is always ``%``.
- ``token::wspace``: Created for any whitespace encountered. Its
value is always a single space, regardless of how much whitespace
is found.
* ``.subtype``: Some of the token types above use the subtype to
provide additional information about the token. Possible subtypes
are:
+ ``token::text``, ``token::number``, ``token::logical``,
``token::error``, ``token::range``: these subtypes describe the
various forms of ``operand`` found in formulae. ``logical`` is
either ``true`` or ``false``, ``range`` is either a named range or
a direct reference to another range. ``text``, ``number``, and
``error`` all refer to literal values in the formula
+ ``token::open`` and ``token::close``: these two subtypes are used by
``paren``, ``func``, and ``array``, to describe whether the token
is opening a new subexpression or closing it.
+ ``token::arg`` and ``token::row``: are used by the ``sep`` tokens,
to distinguish between the comma and semicolon. Commas produce
tokens of subtype ``arg`` whereas semicolons produce tokens of
subtype ``row``

17
docs/styles.rst Normal file
View File

@ -0,0 +1,17 @@
Working with styles
===================
Introduction
------------
Styles are used to change the look of your data while displayed on screen.
They are also used to determine the number format being used for a given cell
or range of cells.
Styles can be applied to the following aspects:
* font to set font size, color, underlining, etc.
* fill to set a pattern or color gradient
* border to set borders on a cell
* cell alignment
* protection

5
docs/tutorial.rst Normal file
View File

@ -0,0 +1,5 @@
Manipulating a workbook in memory
=================================
Create a workbook
-----------------

2
docs/validation.rst Normal file
View File

@ -0,0 +1,2 @@
Validating cells
================

2
docs/windows-development.rst Normal file
View File

@ -0,0 +1,2 @@
Testing on Windows
==================

187
include/xlnt/cell/cell.hpp
View File

@ -49,11 +49,7 @@ struct datetime;
struct time;
struct timedelta;
namespace detail {
struct cell_impl;
} // namespace detail
namespace detail { struct cell_impl; }
/// <summary>
/// Describes cell associated properties.
@ -72,16 +68,22 @@ class cell
/// </summary>
enum class type
{
/// no value. note: this is different from an empty string value or 0 numeric value
null,
/// number
numeric,
/// string
string,
/// value is a formula
formula,
/// value is a known error code such as \#VALUE!
error,
/// value is TRUE or FALSE
boolean
};
/// <summary>
/// Return a map of error strings such as #DIV/0! and their associated indices.
/// Return a map of error strings such as \#DIV/0! and their associated indices.
/// </summary>
static const std::unordered_map<std::string, int> &error_codes();
@ -114,15 +116,35 @@ class cell
/// </summary>
bool has_value() const;
/// <summary>
/// Return the value of this cell as an instance of type T.
/// Overloads exist for most C++ fundamental types like bool, int, etc. as well
/// as for std::string and xlnt datetime types: date, time, datetime, and timedelta.
/// </summary>
template <typename T>
T get_value() const;
/// <summary>
/// Make this cell have a value of type null.
/// All other cell attributes are retained.
/// </summary>
void clear_value();
/// <summary>
/// Set the value of this cell to the given value.
/// Overloads exist for most C++ fundamental types like bool, int, etc. as well
/// as for std::string and xlnt datetime types: date, time, datetime, and timedelta.
template <typename T>
void set_value(T value);
/// <summary>
/// Return the type of this cell.
/// </summary>
type get_data_type() const;
/// <summary>
/// Set the type of this cell.
/// </summary>
void set_data_type(type t);
// properties
@ -139,39 +161,130 @@ class cell
bool is_date() const;
// position
/// <summary>
/// Return a cell_reference that points to the location of this cell.
/// </summary>
cell_reference get_reference() const;
/// <summary>
/// Return the column of this cell.
/// </summary>
column_t get_column() const;
/// <summary>
/// Return the row of this cell.
/// </summary>
row_t get_row() const;
/// <summary>
/// Return the location of this cell as an ordered pair.
/// </summary>
std::pair<int, int> get_anchor() const;
// hyperlink
/// <summary>
/// Return a relationship representing this cell's hyperlink.
/// </summary>
relationship get_hyperlink() const;
/// <summary>
/// Add a hyperlink to this cell pointing to the URI of the given value.
/// </summary>
void set_hyperlink(const std::string &value);
/// <summary>
/// Return true if this cell has a hyperlink set.
/// </summary>
bool has_hyperlink() const;
// style
/// <summary>
/// Return true if this cell has had a style applied to it.
/// </summary>
bool has_style() const;
/// <summary>
/// Return the index of this cell's style in its parent workbook.
/// This is also the index of the style in the stylesheet XML, xl/styles.xml.
/// </summary>
std::size_t get_style_id() const;
/// <summary>
/// Set the style index of this cell. This should be an existing style in
/// the parent workbook.
/// </summary>
void set_style_id(std::size_t style_id);
/// <summary>
/// Return the number format of this cell.
/// </summary>
const number_format &get_number_format() const;
void set_number_format(const number_format &format);
/// <summary>
/// Return the font applied to the text in this cell.
/// </summary>
const font &get_font() const;
void set_font(const font &font_);
/// <summary>
/// Return the fill applied to this cell.
/// </summary>
const fill &get_fill() const;
void set_fill(const fill &fill_);
/// <summary>
/// Return the border of this cell.
/// </summary>
const border &get_border() const;
void set_border(const border &border_);
/// <summary>
/// Return the alignment of the text in this cell.
/// </summary>
const alignment &get_alignment() const;
void set_alignment(const alignment &alignment_);
/// <summary>
/// Return the protection of this cell.
/// </summary>
const protection &get_protection() const;
void set_protection(const protection &protection_);
void set_pivot_button(bool b);
/// <summary>
/// Return true iff pivot button?
/// </summary>
bool pivot_button() const;
void set_quote_prefix(bool b);
/// <summary>
/// Return true iff quote prefix?
/// </summary>
bool quote_prefix() const;
// comment
/// <summary>
/// Return the comment of this cell.
/// </summary>
comment get_comment();
/// <summary>
/// Return the comment of this cell.
/// </summary>
const comment get_comment() const;
void set_comment(const comment &comment);
void clear_comment();
bool has_comment() const;
@ -196,35 +309,97 @@ class cell
std::string to_string() const;
// merging
/// <summary>
/// Return true iff this cell has been merged with one or more
/// surrounding cells.
/// </summary>
bool is_merged() const;
/// <summary>
/// Make this a merged cell iff merged is true.
/// Generally, this shouldn't be called directly. Instead,
/// use worksheet::merge_cells on its parent worksheet.
/// </summary>
void set_merged(bool merged);
/// <summary>
/// Return the error string that is stored in this cell.
/// </summary>
std::string get_error() const;
/// <summary>
/// Directly assign the value of this cell to be the given error.
/// </summary>
void set_error(const std::string &error);
/// <summary>
/// Return a cell from this cell's parent workbook at
/// a relative offset given by the parameters.
/// </summary>
cell offset(int column, int row);
/// <summary>
/// Return the worksheet that owns this cell.
/// </summary>
worksheet get_parent();
/// <summary>
/// Return the worksheet that owns this cell.
/// </summary>
const worksheet get_parent() const;
/// <summary>
/// Shortcut to return the base date of the parent workbook.
/// Equivalent to get_parent().get_parent().get_properties().excel_base_date
/// </summary>
calendar get_base_date() const;
// operators
/// <summary>
/// Make this cell point to rhs.
/// The cell originally pointed to by this cell will be unchanged.
/// </summary>
cell &operator=(const cell &rhs);
/// <summary>
/// Return true if this cell the same cell as comparand (compare by reference).
/// </summary>
bool operator==(const cell &comparand) const;
/// <summary>
/// Return true if this cell is uninitialized.
/// </summary>
bool operator==(std::nullptr_t) const;
// friend operators, so we can put cell on either side of comparisons with other types
/// <summary>
/// Return true if this cell is uninitialized.
/// </summary>
friend bool operator==(std::nullptr_t, const cell &cell);
/// <summary>
/// Return the result of left.get_reference() < right.get_reference().
/// What's the point of this?
/// </summary>
friend bool operator<(cell left, cell right);
private:
// make these friends so they can use the private constructor
friend class worksheet;
friend struct detail::cell_impl;
friend class style;
/// <summary>
/// Private constructor to create a cell from its implementation.
/// </summary>
cell(detail::cell_impl *d);
/// <summary>
/// A pointer to this cell's implementation.
/// </summary>
detail::cell_impl *d_;
};

4
include/xlnt/cell/types.hpp
View File

@ -312,8 +312,8 @@ public:
};
/// <summary>
/// Functor for hashing a cell reference.
/// Allows for use of std::unordered_set<cell_reference, cel_reference_hash> and similar.
/// Functor for hashing a column.
/// Allows for use of std::unordered_set<column, column_hash> and similar.
/// </summary>
struct column_hash
{

15
include/xlnt/config.hpp
View File

@ -34,9 +34,18 @@ namespace xlnt {
/// </summary>
enum class limit_style
{
openpyxl, /// limit style using in openpyxl
excel, /// limits according to Excel
maximum /// limits based on system
/// <summary>
/// limits used in openpyxl
/// </summary>
openpyxl,
/// <summary>
/// limits as determined by Excel
/// </summary>
excel,
/// <summary>
/// limits as high as possible based on system (i.e. 32-bit or 64-bit)
/// </summary>
maximum
};
/// <summary>

13
include/xlnt/packaging/zip_file.hpp
View File

@ -13,8 +13,14 @@ struct mz_zip_archive_tag;
namespace xlnt {
/// <summary>
/// Information about a specific file in zip_file.
/// </summary>
struct zip_info
{
/// <summary>
/// A struct representing a particular date and time.
/// </summary>
struct date_time_t
{
int year;
@ -25,6 +31,9 @@ struct zip_info
int seconds;
};
/// <summary>
/// Default constructor for zip_info.
/// </summary>
zip_info();
date_time_t date_time;
@ -44,6 +53,10 @@ struct zip_info
std::size_t file_size;
};
/// <summary>
/// A compressed archive file that exists in memory which can read
/// or write to and from the filesystem, std::iostreams, and byte vectors.
/// </summary>
class zip_file
{
public:

26
include/xlnt/serialization/relationship_serializer.hpp
View File

@ -8,12 +8,32 @@ namespace xlnt {
class relationship;
class zip_file;
/// <summary>
/// Reads and writes collections of relationshps for a particular file.
/// </summary>
class relationship_serializer
{
public:
static std::vector<relationship> read_relationships(zip_file &archive, const std::string &target);
static bool write_relationships(const std::vector<relationship> &relationships, const std::string &target,
zip_file &archive);
/// <summary>
/// Construct a serializer which operates on archive.
/// </summary>
relationship_serializer(zip_file &archive);
/// <summary>
/// Return a vector of relationships corresponding to target.
/// </summary>
std::vector<relationship> read_relationships(const std::string &target);
/// <summary>
/// Write relationships to archive for the given target.
/// </summary>
bool write_relationships(const std::vector<relationship> &relationships, const std::string &target);
private:
/// <summary>
/// Internal archive which is used for reading and writing.
/// </summary>
zip_file &archive_;
};
} // namespace xlnt

15
include/xlnt/worksheet/worksheet.hpp
View File

@ -51,6 +51,9 @@ namespace detail {
struct worksheet_impl;
} // namespace detail
/// <summary>
/// Worksheet header
/// </summary>
class header
{
public:
@ -88,6 +91,9 @@ class header
std::string font_color_;
};
/// <summary>
/// Worksheet footer
/// </summary>
class footer
{
public:
@ -125,6 +131,9 @@ class footer
std::string font_color_;
};
/// <summary>
/// Worksheet header and footer
/// </summary>
class header_footer
{
public:
@ -173,6 +182,9 @@ class header_footer
footer left_footer_, right_footer_, center_footer_;
};
/// <summary>
/// Worksheet margins
/// </summary>
struct margins
{
public:
@ -249,6 +261,9 @@ struct margins
double footer_;
};
/// <summary>
/// A worksheet is a 2D array of cells.
/// </summary>
class worksheet
{
public:

8
include/xlnt/xlnt.hpp
View File

@ -25,14 +25,6 @@
#include <string>
const std::string xlnt_version = "0.1.0";
const std::string author = "Thomas Fussell";
const std::string license = "MIT";
const std::string author_email = "thomas.fussell@gmail.com";
const std::string url = "https://github.com/tfussell/xlnt";
const std::string download_url = "https://github.com/tfussell/xlnt/archive/master.zip";
#include <xlnt/config.hpp>
#include <xlnt/cell/cell.hpp>

9
source/serialization/excel_serializer.cpp
View File

@ -69,8 +69,8 @@ bool load_workbook(xlnt::zip_file &archive, bool guess_types, bool data_only, xl
workbook_serializer_.read_properties_core(core_properties_xml);
}
auto workbook_relationships =
xlnt::relationship_serializer::read_relationships(archive, xlnt::constants::ArcWorkbook());
xlnt::relationship_serializer relationship_serializer_(archive);
auto workbook_relationships = relationship_serializer_.read_relationships(xlnt::constants::ArcWorkbook());
for (const auto &relationship : workbook_relationships)
{
@ -193,8 +193,9 @@ excel_serializer::excel_serializer(workbook &wb) : workbook_(wb)
void excel_serializer::write_data(bool /*as_template*/)
{
relationship_serializer::write_relationships(workbook_.get_root_relationships(), "", archive_);
relationship_serializer::write_relationships(workbook_.get_relationships(), constants::ArcWorkbook(), archive_);
relationship_serializer relationship_serializer_(archive_);
relationship_serializer_.write_relationships(workbook_.get_root_relationships(), "");
relationship_serializer_.write_relationships(workbook_.get_relationships(), constants::ArcWorkbook());
xml_document properties_app_xml;
workbook_serializer workbook_serializer_(workbook_);

12
source/serialization/relationship_serializer.cpp
View File

@ -28,10 +28,14 @@ std::string make_rels_name(const std::string &target)
namespace xlnt {
std::vector<relationship> relationship_serializer::read_relationships(zip_file &archive, const std::string &target)
relationship_serializer::relationship_serializer(zip_file &archive) : archive_(archive)
{
}
std::vector<relationship> relationship_serializer::read_relationships(const std::string &target)
{
xml_document xml;
xml.from_string(archive.read(make_rels_name(target)));
xml.from_string(archive_.read(make_rels_name(target)));
auto root_node = xml.get_child("Relationships");
@ -55,7 +59,7 @@ std::vector<relationship> relationship_serializer::read_relationships(zip_file &
}
bool relationship_serializer::write_relationships(const std::vector<relationship> &relationships,
const std::string &target, zip_file &archive)
const std::string &target)
{
xml_document xml;
@ -77,7 +81,7 @@ bool relationship_serializer::write_relationships(const std::vector<relationship
}
}
archive.writestr(make_rels_name(target), xml.to_string());
archive_.writestr(make_rels_name(target), xml.to_string());
return true;
}

6
source/serialization/tests/test_read.hpp
View File

@ -337,8 +337,9 @@ public:
auto path = PathHelper::GetDataDirectory("/reader/bug137.xlsx");
xlnt::zip_file archive(path);
xlnt::relationship_serializer serializer(archive);
TS_ASSERT_EQUALS(xlnt::relationship_serializer::read_relationships(archive, "xl/workbook.xml"), expected);
TS_ASSERT_EQUALS(serializer.read_relationships("xl/workbook.xml"), expected);
}
{
@ -356,8 +357,9 @@ public:
auto path = PathHelper::GetDataDirectory("/reader/bug304.xlsx");
xlnt::zip_file archive(path);
xlnt::relationship_serializer serializer(archive);
TS_ASSERT_EQUALS(xlnt::relationship_serializer::read_relationships(archive, "xl/workbook.xml"), expected);
TS_ASSERT_EQUALS(serializer.read_relationships("xl/workbook.xml"), expected);
}
}

6
source/serialization/tests/test_write.hpp
View File

@ -47,7 +47,8 @@ public:
{
xlnt::workbook wb;
xlnt::zip_file archive;
xlnt::relationship_serializer::write_relationships(wb.get_relationships(), "xl/workbook.xml", archive);
xlnt::relationship_serializer serializer(archive);
serializer.write_relationships(wb.get_relationships(), "xl/workbook.xml");
auto content = xlnt::xml_serializer::deserialize(archive.read("xl/_rels/workbook.xml.rels"));
TS_ASSERT(Helper::compare_xml(PathHelper::GetDataDirectory() + "/writer/expected/workbook.xml.rels", content));
@ -162,7 +163,8 @@ public:
TS_ASSERT_EQUALS(2, ws.get_relationships().size());
xlnt::zip_file archive;
xlnt::relationship_serializer::write_relationships(ws.get_relationships(), "xl/worksheets/sheet1.xml", archive);
xlnt::relationship_serializer serializer(archive);
serializer.write_relationships(ws.get_relationships(), "xl/worksheets/sheet1.xml");
auto content = xlnt::xml_serializer::deserialize(archive.read("xl/worksheets/_rels/sheet1.xml.rels"));
TS_ASSERT(Helper::compare_xml(PathHelper::GetDataDirectory() + "/writer/expected/sheet1_hyperlink.xml.rels", content));

6
source/serialization/tests/test_write_workbook.hpp
View File

@ -96,7 +96,8 @@ public:
{
xlnt::workbook wb;
xlnt::zip_file archive;
xlnt::relationship_serializer::write_relationships(wb.get_relationships(), "xl/workbook.xml", archive);
xlnt::relationship_serializer serializer(archive);
serializer.write_relationships(wb.get_relationships(), "xl/workbook.xml");
xlnt::xml_document observed;
observed.from_string(archive.read("xl/_rels/workbook.xml.rels"));
auto filename = "workbook.xml.rels";
@ -165,7 +166,8 @@ public:
{
xlnt::workbook wb;
xlnt::zip_file archive;
xlnt::relationship_serializer::write_relationships(wb.get_root_relationships(), "", archive);
xlnt::relationship_serializer serializer(archive);
serializer.write_relationships(wb.get_root_relationships(), "");
xlnt::xml_document observed;
observed.from_string(archive.read("_rels/.rels"));