1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
|
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd">
<document>
<header>
<title>Formula Support</title>
<authors>
<person email="avik@apache.org" name="Avik Sengupta" id="AS"/>
</authors>
</header>
<body>
<section><title>Introduction</title>
<p>
This document describes the current state of formula support in POI.
The information in this document currently applies to the 3.13 version of POI.
Since this area is a work in progress, this document will be updated with new
features as and when they are added.
</p>
</section>
<section><title>The basics</title>
<p>
In org.apache.poi.ss.usermodel.Cell
<strong> setCellFormula("formulaString") </strong> is used to add a
formula to a sheet, and <strong> getCellFormula() </strong> is used to retrieve
the string representation of a formula.
</p>
<p>
We aim to support the complete excel grammar for formulas. Thus, the string that
you pass in to the <em> setCellFormula </em> call should be what you expect to
type into excel. Also, note that you should NOT add a "=" to the front of the string.
</p>
<p>
Please note that localized versions of Excel allow to enter localized
function-names. However internally Excel stores the English names and thus POI
only supports these and not the localized ones. Also note that only commas may be
used to separate arguments, as per the Excel English style, alternate delimeters
used in other localizations are not supported.
</p>
</section>
<section><title>Supported Features</title>
<ul>
<li>References: single cell & area, 2D & 3D, relative & absolute</li>
<li>Literals: number, text, boolean, error and array</li>
<li>Operators: arithmetic and logical, some region operators</li>
<li>Built-in functions: over 350 recognised, 280 evaluatable</li>
<li>Add-in functions: 24 from Analysis Toolpack</li>
<li>Array Formulas: via Sheet.setArrayFormula() and Sheet.removeArrayFormula()</li>
<li>Region operators: union, intersection</li>
</ul>
</section>
<section><title>Not yet supported</title>
<ul>
<li>Manipulating table formulas (In Excel, formulas that look like "{=...}" as opposed to "=...")</li>
<li>Parsing of previously uncalled add-in functions</li>
<li>Preservation of whitespace in formulas (when POI manipulates them)</li>
</ul>
</section>
<section><title>Supported Functions</title>
<p>To get the list of formula functions that POI supports, you need to
call some code!</p>
<p>The methods you need are available on
<a href="../../apidocs/dev/org/apache/poi/ss/formula/eval/FunctionEval.html">org.apache.poi.ss.formula.eval.FunctionEval</a>.
To find which functions your copy of Apache POI supports, use
<a href="../../apidocs/dev/org/apache/poi/ss/formula/eval/FunctionEval.html#getSupportedFunctionNames()">getSupportedFunctionNames()</a>
to get a list of the implemented function names. For the list of functions that
POI knows the name of, but doesn't currently implement, use
<a href="../../apidocs/dev/org/apache/poi/ss/formula/eval/FunctionEval.html#getNotSupportedFunctionNames()">getNotSupportedFunctionNames()</a>
</p>
</section>
<section><title>Internals</title>
<p>
Formulas in Excel are stored as sequences of tokens in Reverse Polish Notation order. The
<a href="https://sc.openoffice.org/excelfileformat.pdf">open office XLS spec</a> is the best
documentation you will find for the format.
</p>
<p>
The tokens used by excel are modeled as individual *Ptg classes in the <strong>
org.apache.poi.hssf.record.formula</strong> package.
</p>
<p>
The task of parsing a formula string into an array of RPN ordered tokens is done by the <strong>
org.apache.poi.ss.formula.FormulaParser</strong> class. This class implements a hand
written recursive descent parser.
</p>
<p>
Formula tokens in Excel are stored in one of three possible <em> operand classes </em>:
Reference, Value and Array. Based on the location of a token, its class can change
in complicated and undocumented ways. While we have support for most cases, we
are not sure if we have covered all bases (since there is no documentation for this area.)
We would therefore like you to report any
occurrence of #VALUE! in a cell upon opening a POI generated workbook in excel. (Check that
typing the formula into Excel directly gives a valid result.)
</p>
<p>Check out the <a href="site:javadocs">javadocs </a> for details.
</p>
</section>
</body>
</document>
|
