OpenDocument v1.2 Cd05 Part2 Editor Revision

Open Document Format for Office
Applications (OpenDocument) Version

1.2
Part 2: Recalculated Formula (OpenFormula)
Format Annotated Version
Committee Draft 05
19 June 2010
Specification URIs:
This Version:
http://docs.oasis-open.org/office/v1.2/cd05/OpenDocument-v1.2-cd05-part2.odt
(Authoritative)
http://docs.oasis-open.org/office/v1.2/cd05/OpenDocument-v1.2-cd05-part2.pdf
http://docs.oasis-open.org/office/v1.2/cd05/OpenDocument-v1.2-cd05-part2.html
Previous Version:
http://docs.oasis-open.org/office/v1.1/OS/OpenDocument-v1.1.odt
http://docs.oasis-open.org/office/v1.1/OS/OpenDocument-v1.1.pdf
http://docs.oasis-open.org/office/v1.1/OS/OpenDocument-v1.1-html/OpenDocument-
v1.1.html
Latest Version:
http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2-part2.odt
http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2-part2.pdf
http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2-part2.html
Technical Committee:
OASIS Open Document Format for Office Applications (OpenDocument) TC
Chairs:
Robert Weir, IBM
Michael Brauer, Oracle Corporation
Editors:
David A. Wheeler <dwheeler@dwheeler.com>,
100414201 29 May 2010
Copyright OASIS Open 2002 - 2010. All Rights Reserved. Page 1 of 442
Patrick Durusau <patrick@durusau.net>
Eike Rathke, Oracle Corporation <erack@sun.com>
Robert Weir, IBM <robert_weir@us.ibm.com>
Related Work:
This document is part of the OASIS Open Document Format for Office Applications
(OpenDocument) Version 1.2 specification.
The OpenDocument v1.2 specification has these parts:
OpenDocument v1.2 part 1; OpenDocument Schema
OpenDocument v1.2 part 2 (this part): Recalculated Formula (OpenFormula) Format
OpenDocument v1.2 part 3: Packages
Declared XML Namespaces:
None.
Abstract:
This document is part of the Open Document Format for Office Applications
(OpenDocument) Version 1.2 specification.
It defines a formula language to be used in OpenDocument documents.
Status:
This document was last revised or approved by the OASIS Open Document Format for
Office Applications (OpenDocument) Technical Committee on the above date. The level of
approval is also listed above. Check the current location noted above for possible later
revisions of this document. This document is updated periodically on no particular schedule.
Technical Committee members should send comments on this specification to the Technical
Committee's email list. Others should send comments to the Technical Committee by using
the "Send A Comment" button on the Technical Committee's web page at
www.oasis-open.org/committees/office.
For information on whether any patents have been disclosed that may be essential to
implementing this specification, and any offers of patent licensing terms, please refer to the
Intellectual Property Rights section of the Technical Committee web page
(www.oasis-open.org/committees/office/ipr.php.
The non-normative errata page for this specification is located at www.oasis-
open.org/committees/office.
Note: This is the annotated version of this specification, which includes non-normative information
(notes, rationales, and TODO/TBD). These annotations are not included in the final official
specification, and thus are not normative, but they are available to implementors as guidance.
To show only the normative specification: Modify the text at the end of the first line of this
document (after OASIS), which has a text setting for the value Notes. If Notes is set to 0 (off),
the annotations (including the one your are viewing now) will not be displayed.
100414201 29 May 2010
Notices
Copyright OASIS 20022010. All Rights Reserved.
All capitalized terms in the following text have the meanings assigned to them in the OASIS
Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the
OASIS website.
This document and translations of it may be copied and furnished to others, and derivative works
that comment on or otherwise explain it or assist in its implementation may be prepared, copied,
published, and distributed, in whole or in part, without restriction of any kind, provided that the
above copyright notice and this section are included on all such copies and derivative works.
However, this document itself may not be modified in any way, including by removing the copyright
notice or references to OASIS, except as needed for the purpose of developing any document or
deliverable produced by an OASIS Technical Committee (in which case the rules applicable to
copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into
languages other than English.
The limited permissions granted above are perpetual and will not be revoked by OASIS or its
successors or assigns.
This document and the information contained herein is provided on an "AS IS" basis and OASIS
DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY
OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE.
OASIS requests that any OASIS Party or any other party that believes it has patent claims that
would necessarily be infringed by implementations of this OASIS Committee Specification or OASIS
Standard, to notify OASIS TC Administrator and provide an indication of its willingness to grant
patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS
Technical Committee that produced this specification.
OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership
of any patent claims that would necessarily be infringed by implementations of this specification by
a patent holder that is not willing to provide a license to such patent claims in a manner consistent
with the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS may
include such claims on its website, but disclaims any obligation to do so.
OASIS takes no position regarding the validity or scope of any intellectual property or other rights
that might be claimed to pertain to the implementation or use of the technology described in this
document or the extent to which any license under such rights might or might not be available;
neither does it represent that it has made any effort to identify any such rights. Information on
OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS
Technical Committee can be found on the OASIS website. Copies of claims of rights made available
for publication and any assurances of licenses to be made available, or the result of an attempt
made to obtain a general license or permission for the use of such proprietary rights by
implementers or users of this OASIS Committee Specification or OASIS Standard, can be obtained
from the OASIS TC Administrator. OASIS makes no representation that any information or list of
intellectual property rights will at any time be complete, or that any claims in such list are, in fact,
Essential Claims.
The names "OASIS", OpenDocument, Open Document Format and ODF are trademarks of
OASIS, the owner and developer of this specification, and should be used only to refer to the
organization and its official outputs. OASIS welcomes reference to, and implementation and use of,
specifications, while reserving the right to enforce its marks against misleading uses. Please see
http://www.oasis-open.org/who/trademark.php for above guidance.
100414201 29 May 2010
Table of Contents
1 Introduction.................................................................................................................................19
1.1 Introduction..........................................................................................................................19
1.2 Terminology.........................................................................................................................20
1.3 Purpose...............................................................................................................................20
1.4 Normative References.........................................................................................................21
1.5 Non-Normative References..................................................................................................21
2 Expressions and Evaluators........................................................................................................23
2.1 OpenDocument Formula Expression....................................................................................23
2.2 Evaluators...........................................................................................................................23
2.2.1 OpenDocument Formula Evaluator...............................................................................23
2.2.2 OpenDocument Formula Small Group Evaluator...........................................................25
2.2.3 OpenDocument Formula Medium Group Evaluator.......................................................27
2.2.4 OpenDocument Formula Large Group Evaluator...........................................................27
2.3 Variances (Implementation-defined, Unspecified, and Behavioral Changes).........................33
3 Formula Processing Model..........................................................................................................35
3.1 General................................................................................................................................35
3.2 Expression Calculation.........................................................................................................35
3.3 Non-Scalar Evaluation (aka 'Array expressions')..................................................................36
3.4 Host-Defined Behaviors.......................................................................................................38
3.5 When recalculation occurs...................................................................................................39
3.6 Numerical Models................................................................................................................39
3.7 Basic Limits.........................................................................................................................40
4 Types..........................................................................................................................................43
4.1 General................................................................................................................................43
4.2 Text (String).........................................................................................................................43
4.3 Number................................................................................................................................43
4.3.1 General........................................................................................................................43
4.3.2 Time.............................................................................................................................44
4.3.3 Date.............................................................................................................................44
4.3.4 DateTime......................................................................................................................45
4.3.5 Percentage...................................................................................................................45
4.3.6 Currency.......................................................................................................................45
4.3.7 Logical (Number)..........................................................................................................45
4.4 Complex Number.................................................................................................................46
100414201 29 May 2010
4.5 Logical (Boolean).................................................................................................................47
4.6 Error....................................................................................................................................47
4.7 Empty Cell...........................................................................................................................48
4.8 Reference............................................................................................................................48
4.9 ReferenceList......................................................................................................................49
4.10 Array..................................................................................................................................49
4.11 Pseudotypes......................................................................................................................49
4.11.1 General.......................................................................................................................49
4.11.2 Scalar.........................................................................................................................49
4.11.3 DateParam..................................................................................................................49
4.11.4 TimeParam.................................................................................................................49
4.11.5 Integer........................................................................................................................50
4.11.6 Basis...........................................................................................................................50
4.11.7 Criterion......................................................................................................................51
4.11.8 Database....................................................................................................................52
4.11.9 Field...........................................................................................................................52
4.11.10 Criteria......................................................................................................................52
4.11.11 Sequences (NumberSequence, NumberSequenceList, DateSequence,
LogicalSequence, and ComplexSequence)............................................................................53
5 Expression Syntax......................................................................................................................54
5.1 General................................................................................................................................54
5.2 Basic Expressions...............................................................................................................54
5.3 Constant Numbers...............................................................................................................55
5.4 Constant Strings..................................................................................................................56
5.5 Operators............................................................................................................................57
5.6 Functions and Function Parameters.....................................................................................58
5.7 Nonstandard Function Names.............................................................................................60
5.8 References..........................................................................................................................61
5.9 Reference List.....................................................................................................................63
5.10 Quoted Label.....................................................................................................................64
5.10.1 General......................................................................................................................64
5.10.2 Lookup of Defined Labels...........................................................................................64
5.10.3 Automatic Lookup of Labels........................................................................................64
5.10.4 Implicit Intersection.....................................................................................................65
5.10.5 Automatic Range........................................................................................................65
5.10.6 Automatic Intersection.................................................................................................66
5.11 Named Expressions...........................................................................................................67
5.12 Constant Errors..................................................................................................................69
100414201 29 May 2010
5.13 Inline Arrays.......................................................................................................................70
5.14 Whitespace........................................................................................................................71
6 Standard Operators and Functions..............................................................................................75
6.1 General................................................................................................................................75
6.2 Common Template for Functions and Operators..................................................................75
6.3 Implicit Conversion Operators..............................................................................................76
6.3.1 General........................................................................................................................76
6.3.2 Conversion to Scalar....................................................................................................76
6.3.3 Implied intersection.......................................................................................................76
6.3.4 Force to array context (ForceArray)..............................................................................77
6.3.5 Conversion to Number..................................................................................................77
6.3.6 Conversion to Integer...................................................................................................78
6.3.7 Conversion to NumberSequence..................................................................................79
6.3.8 Conversion to NumberSequenceList.............................................................................80
6.3.9 Conversion to DateSequence.......................................................................................80
6.3.10 Conversion to Complex Number.................................................................................80
6.3.11 Conversion to ComplexSequence...............................................................................80
6.3.12 Conversion to Logical.................................................................................................81
6.3.13 Conversion to LogicalSequence..................................................................................82
6.3.14 Conversion to Text......................................................................................................82
6.3.15 Conversion to DateParam...........................................................................................83
6.3.16 Conversion to TimeParam...........................................................................................83
6.4 Standard Operators.............................................................................................................83
6.4.1 General........................................................................................................................83
6.4.2 Infix Operator "+"..........................................................................................................83
6.4.3 Infix Operator "-"...........................................................................................................84
6.4.4 Infix Operator "*"...........................................................................................................84
6.4.5 Infix Operator "/"...........................................................................................................85
6.4.6 Infix Operator "^"...........................................................................................................85
6.4.7 Infix Operator "="..........................................................................................................87
6.4.8 Infix Operator "<>"........................................................................................................88
6.4.9 Infix Operator Ordered Comparison ("<", "<=", ">", ">=")...............................................88
6.4.10 Infix Operator "&"........................................................................................................89
6.4.11 Infix Operator Reference Range (":")...........................................................................90
6.4.12 Infix Operator Reference Intersection ("!")...................................................................90
6.4.13 Infix Operator Reference Concatenation ("~") (aka Union)...........................................91
6.4.14 Postfix Operator "%"...................................................................................................92
100414201 29 May 2010
6.4.15 Prefix Operator "+"......................................................................................................93
6.4.16 Prefix Operator "-".......................................................................................................93
6.5 Matrix Functions..................................................................................................................94
6.5.1 General........................................................................................................................94
6.5.2 MDETERM...................................................................................................................94
6.5.3 MINVERSE...................................................................................................................95
6.5.4 MMULT.........................................................................................................................96
6.5.5 MUNIT..........................................................................................................................96
6.5.6 TRANSPOSE...............................................................................................................97
6.6 Bit operation functions.........................................................................................................98
6.6.1 General........................................................................................................................98
6.6.2 BITAND........................................................................................................................98
6.6.3 BITLSHIFT...................................................................................................................99
6.6.4 BITOR........................................................................................................................100
6.6.5 BITRSHIFT.................................................................................................................101
6.6.6 BITXOR......................................................................................................................102
6.7 Byte-position text functions................................................................................................103
6.7.1 General......................................................................................................................103
6.7.2 FINDB........................................................................................................................103
6.7.3 LEFTB........................................................................................................................103
6.7.4 LENB..........................................................................................................................104
6.7.5 MIDB..........................................................................................................................104
6.7.6 REPLACEB................................................................................................................105
6.7.7 RIGHTB......................................................................................................................105
6.7.8 SEARCHB..................................................................................................................105
6.8 Complex Number Functions...............................................................................................106
6.8.1 General......................................................................................................................106
6.8.2 COMPLEX..................................................................................................................106
6.8.3 IMABS........................................................................................................................106
6.8.4 IMAGINARY...............................................................................................................107
6.8.5 IMARGUMENT...........................................................................................................107
6.8.6 IMCONJUGATE..........................................................................................................108
6.8.7 IMCOS.......................................................................................................................108
6.8.8 IMCOT........................................................................................................................109
6.8.9 IMCSC........................................................................................................................109
6.8.10 IMCSCH...................................................................................................................110
6.8.11 IMDIV........................................................................................................................110
100414201 29 May 2010
6.8.12 IMEXP.......................................................................................................................111
6.8.13 IMLN.........................................................................................................................111
6.8.14 IMLOG10..................................................................................................................112
6.8.15 IMLOG2....................................................................................................................112
6.8.16 IMPOWER................................................................................................................112
6.8.17 IMPRODUCT............................................................................................................113
6.8.18 IMREAL....................................................................................................................113
6.8.19 IMSIN.......................................................................................................................114
6.8.20 IMSEC......................................................................................................................114
6.8.21 IMSECH....................................................................................................................115
6.8.22 IMSQRT....................................................................................................................115
6.8.23 IMSUB......................................................................................................................116
6.8.24 IMSUM.....................................................................................................................116
6.8.25 IMTAN......................................................................................................................117
6.9 Database Functions...........................................................................................................117
6.9.1 General.......................................................................................................................117
6.9.2 DAVERAGE................................................................................................................118
6.9.3 DCOUNT....................................................................................................................118
6.9.4 DCOUNTA..................................................................................................................118
6.9.5 DGET.........................................................................................................................119
6.9.6 DMAX.........................................................................................................................119
6.9.7 DMIN..........................................................................................................................120
6.9.8 DPRODUCT...............................................................................................................120
6.9.9 DSTDEV.....................................................................................................................121
6.9.10 DSTDEVP.................................................................................................................121
6.9.11 DSUM.......................................................................................................................121
6.9.12 DVAR........................................................................................................................122
6.9.13 DVARP.....................................................................................................................122
6.10 Date and Time Functions.................................................................................................123
6.10.1 General.....................................................................................................................123
6.10.2 DATE........................................................................................................................123
6.10.3 DATEDIF..................................................................................................................124
6.10.4 DATEVALUE.............................................................................................................125
6.10.5 DAY..........................................................................................................................126
6.10.6 DAYS........................................................................................................................126
6.10.7 DAYS360..................................................................................................................127
6.10.8 EDATE......................................................................................................................128
100414201 29 May 2010
6.10.9 EOMONTH...............................................................................................................129
6.10.10 HOUR.....................................................................................................................130
6.10.11 ISOWEEKNUM.......................................................................................................130
6.10.12 MINUTE..................................................................................................................131
6.10.13 MONTH..................................................................................................................132
6.10.14 NETWORKDAYS....................................................................................................132
6.10.15 NOW......................................................................................................................133
6.10.16 SECOND................................................................................................................134
6.10.17 TIME.......................................................................................................................134
6.10.18 TIMEVALUE............................................................................................................135
6.10.19 TODAY...................................................................................................................136
6.10.20 WEEKDAY..............................................................................................................137
6.10.21 WEEKNUM.............................................................................................................137
6.10.22 WORKDAY.............................................................................................................138
6.10.23 YEAR......................................................................................................................139
6.10.24 YEARFRAC............................................................................................................140
6.11 External Access Functions................................................................................................143
6.11.1 General.....................................................................................................................143
6.11.2 DDE..........................................................................................................................143
6.11.3 HYPERLINK.............................................................................................................144
6.12 Financial Functions..........................................................................................................146
6.12.1 General.....................................................................................................................146
6.12.2 ACCRINT..................................................................................................................147
6.12.3 ACCRINTM...............................................................................................................148
6.12.4 AMORDEGRC..........................................................................................................149
6.12.5 AMORLINC...............................................................................................................151
6.12.6 COUPDAYBS...........................................................................................................152
6.12.7 COUPDAYS..............................................................................................................153
6.12.8 COUPDAYSNC.........................................................................................................155
6.12.9 COUPNCD...............................................................................................................156
6.12.10 COUPNUM.............................................................................................................157
6.12.11 COUPPCD..............................................................................................................158
6.12.12 CUMIPMT...............................................................................................................159
6.12.13 CUMPRINC............................................................................................................160
6.12.14 DB..........................................................................................................................161
6.12.15 DDB........................................................................................................................162
6.12.16 DISC.......................................................................................................................164
100414201 29 May 2010
6.12.17 DOLLARDE............................................................................................................165
6.12.18 DOLLARFR............................................................................................................165
6.12.19 DURATION.............................................................................................................166
6.12.20 EFFECT.................................................................................................................167
6.12.21 FV..........................................................................................................................167
6.12.22 FVSCHEDULE........................................................................................................168
6.12.23 INTRATE................................................................................................................169
6.12.24 IPMT.......................................................................................................................170
6.12.25 IRR.........................................................................................................................171
6.12.26 ISPMT....................................................................................................................171
6.12.27 MDURATION..........................................................................................................172
6.12.28 MIRR......................................................................................................................173
6.12.29 NOMINAL...............................................................................................................173
6.12.30 NPER.....................................................................................................................174
6.12.31 NPV........................................................................................................................175
6.12.32 ODDFPRICE...........................................................................................................176
6.12.33 ODDFYIELD...........................................................................................................178
6.12.34 ODDLPRICE...........................................................................................................179
6.12.35 ODDLYIELD............................................................................................................181
6.12.36 PDURATION...........................................................................................................183
6.12.37 PMT........................................................................................................................184
6.12.38 PPMT.....................................................................................................................185
6.12.39 PRICE....................................................................................................................186
6.12.40 PRICEDISC............................................................................................................187
6.12.41 PRICEMAT.............................................................................................................188
6.12.42 PV..........................................................................................................................189
6.12.43 RATE......................................................................................................................190
6.12.44 RECEIVED.............................................................................................................191
6.12.45 RRI.........................................................................................................................192
6.12.46 SLN........................................................................................................................193
6.12.47 SYD........................................................................................................................194
6.12.48 TBILLEQ.................................................................................................................194
6.12.49 TBILLPRICE...........................................................................................................195
6.12.50 TBILLYIELD............................................................................................................196
6.12.51 VDB........................................................................................................................197
6.12.52 XIRR.......................................................................................................................198
6.12.53 XNPV.....................................................................................................................199
100414201 29 May 2010
6.12.54 YIELD.....................................................................................................................200
6.12.55 YIELDDISC.............................................................................................................202
6.12.56 YIELDMAT..............................................................................................................203
6.13 Information Functions.......................................................................................................204
6.13.1 General.....................................................................................................................204
6.13.2 AREAS.....................................................................................................................204
6.13.3 CELL........................................................................................................................205
6.13.4 COLUMN..................................................................................................................207
6.13.5 COLUMNS...............................................................................................................207
6.13.6 COUNT.....................................................................................................................208
6.13.7 COUNTA..................................................................................................................209
6.13.8 COUNTBLANK.........................................................................................................209
6.13.9 COUNTIF.................................................................................................................210
6.13.10 COUNTIFS.............................................................................................................210
6.13.11 ERROR.TYPE.........................................................................................................211
6.13.12 FORMULA..............................................................................................................212
6.13.13 INFO.......................................................................................................................212
6.13.14 ISBLANK................................................................................................................214
6.13.15 ISERR....................................................................................................................215
6.13.16 ISERROR...............................................................................................................215
6.13.17 ISEVEN..................................................................................................................216
6.13.18 ISFORMULA...........................................................................................................217
6.13.19 ISLOGICAL.............................................................................................................218
6.13.20 ISNA.......................................................................................................................218
6.13.21 ISNONTEXT...........................................................................................................219
6.13.22 ISNUMBER.............................................................................................................219
6.13.23 ISODD....................................................................................................................220
6.13.24 ISREF.....................................................................................................................221
6.13.25 ISTEXT...................................................................................................................221
6.13.26 N............................................................................................................................222
6.13.27 NA..........................................................................................................................222
6.13.28 NUMBERVALUE.....................................................................................................223
6.13.29 ROW......................................................................................................................224
6.13.30 ROWS....................................................................................................................224
6.13.31 SHEET...................................................................................................................225
6.13.32 SHEETS.................................................................................................................226
6.13.33 TYPE......................................................................................................................226
100414201 29 May 2010
6.13.34 VALUE....................................................................................................................227
6.14 Lookup Functions.............................................................................................................230
6.14.1 General.....................................................................................................................230
6.14.2 ADDRESS................................................................................................................230
6.14.3 CHOOSE..................................................................................................................231
6.14.4 GETPIVOTDATA.......................................................................................................232
6.14.5 HLOOKUP................................................................................................................233
6.14.6 INDEX......................................................................................................................234
6.14.7 INDIRECT................................................................................................................235
6.14.8 LOOKUP..................................................................................................................235
6.14.9 MATCH.....................................................................................................................237
6.14.10 MULTIPLE.OPERATIONS.......................................................................................238
6.14.11 OFFSET.................................................................................................................240
6.14.12 VLOOKUP..............................................................................................................241
6.15 Logical Functions.............................................................................................................242
6.15.1 General.....................................................................................................................242
6.15.2 AND..........................................................................................................................242
6.15.3 FALSE......................................................................................................................243
6.15.4 IF..............................................................................................................................244
6.15.5 IFERROR.................................................................................................................245
6.15.6 IFNA.........................................................................................................................245
6.15.7 NOT.........................................................................................................................245
6.15.8 OR............................................................................................................................246
6.15.9 TRUE.......................................................................................................................247
6.15.10 XOR.......................................................................................................................247
6.16 Mathematical Functions...................................................................................................248
6.16.1 General.....................................................................................................................248
6.16.2 ABS..........................................................................................................................248
6.16.3 ACOS.......................................................................................................................249
6.16.4 ACOSH.....................................................................................................................249
6.16.5 ACOT.......................................................................................................................250
6.16.6 ACOTH.....................................................................................................................250
6.16.7 ASIN.........................................................................................................................251
6.16.8 ASINH......................................................................................................................251
6.16.9 ATAN........................................................................................................................252
6.16.10 ATAN2....................................................................................................................252
6.16.11 ATANH....................................................................................................................253
100414201 29 May 2010
6.16.12 BESSELI.................................................................................................................253
6.16.13 BESSELJ................................................................................................................254
6.16.14 BESSELK...............................................................................................................254
6.16.15 BESSELY...............................................................................................................255
6.16.16 COMBIN.................................................................................................................255
6.16.17 COMBINA...............................................................................................................256
6.16.18 CONVERT..............................................................................................................256
6.16.19 COS.......................................................................................................................282
6.16.20 COSH.....................................................................................................................283
6.16.21 COT........................................................................................................................284
6.16.22 COTH.....................................................................................................................284
6.16.23 CSC........................................................................................................................285
6.16.24 CSCH.....................................................................................................................285
6.16.25 DEGREES..............................................................................................................286
6.16.26 DELTA....................................................................................................................286
6.16.27 ERF........................................................................................................................287
6.16.28 ERFC......................................................................................................................287
6.16.29 EUROCONVERT....................................................................................................288
6.16.30 EVEN......................................................................................................................290
6.16.31 EXP........................................................................................................................290
6.16.32 FACT......................................................................................................................291
6.16.33 FACTDOUBLE........................................................................................................292
6.16.34 GAMMA..................................................................................................................292
6.16.35 GAMMALN.............................................................................................................293
6.16.36 GCD.......................................................................................................................293
6.16.37 GESTEP.................................................................................................................294
6.16.38 LCM........................................................................................................................295
6.16.39 LN..........................................................................................................................295
6.16.40 LOG........................................................................................................................296
6.16.41 LOG10....................................................................................................................297
6.16.42 MOD.......................................................................................................................297
6.16.43 MULTINOMIAL.......................................................................................................298
6.16.44 ODD.......................................................................................................................298
6.16.45 PI............................................................................................................................299
6.16.46 POWER..................................................................................................................300
6.16.47 PRODUCT..............................................................................................................300
6.16.48 QUOTIENT.............................................................................................................301
100414201 29 May 2010
6.16.49 RADIANS...............................................................................................................302
6.16.50 RAND.....................................................................................................................302
6.16.51 RANDBETWEEN....................................................................................................302
6.16.52 SEC........................................................................................................................303
6.16.53 SERIESSUM...........................................................................................................303
6.16.54 SIGN......................................................................................................................304
6.16.55 SIN.........................................................................................................................305
6.16.56 SINH.......................................................................................................................305
6.16.57 SECH.....................................................................................................................306
6.16.58 SQRT.....................................................................................................................306
6.16.59 SQRTPI..................................................................................................................307
6.16.60 SUBTOTAL.............................................................................................................307
6.16.61 SUM.......................................................................................................................308
6.16.62 SUMIF....................................................................................................................309
6.16.63 SUMIFS..................................................................................................................309
6.16.64 SUMPRODUCT......................................................................................................310
6.16.65 SUMSQ..................................................................................................................310
6.16.66 SUMX2MY2............................................................................................................311
6.16.67 SUMX2PY2.............................................................................................................311
6.16.68 SUMXMY2..............................................................................................................312
6.16.69 TAN........................................................................................................................313
6.16.70 TANH......................................................................................................................313
6.17 Rounding Functions.........................................................................................................314
6.17.1 General.....................................................................................................................314
6.17.2 CEILING...................................................................................................................314
6.17.3 INT...........................................................................................................................315
6.17.4 FLOOR.....................................................................................................................316
6.17.5 MROUND.................................................................................................................317
6.17.6 ROUND....................................................................................................................317
6.17.7 ROUNDDOWN.........................................................................................................318
6.17.8 ROUNDUP...............................................................................................................319
6.17.9 TRUNC.....................................................................................................................320
6.18 Statistical Functions.........................................................................................................320
6.18.1 General.....................................................................................................................320
6.18.2 AVEDEV...................................................................................................................320
6.18.3 AVERAGE.................................................................................................................321
6.18.4 AVERAGEA..............................................................................................................321
100414201 29 May 2010
6.18.5 AVERAGEIF..............................................................................................................322
6.18.6 AVERAGEIFS...........................................................................................................322
6.18.7 BETADIST................................................................................................................323
6.18.8 BETAINV..................................................................................................................324
6.18.9 BINOM.DIST.RANGE................................................................................................325
6.18.10 BINOMDIST............................................................................................................326
6.18.11 LEGACY.CHIDIST...................................................................................................326
6.18.12 CHISQDIST............................................................................................................327
6.18.13 LEGACY.CHIINV.....................................................................................................328
6.18.14 CHISQINV..............................................................................................................328
6.18.15 LEGACY.CHITEST..................................................................................................329
6.18.16 CONFIDENCE........................................................................................................330
6.18.17 CORREL.................................................................................................................331
6.18.18 COVAR...................................................................................................................331
6.18.19 CRITBINOM...........................................................................................................332
6.18.20 DEVSQ...................................................................................................................332
6.18.21 EXPONDIST...........................................................................................................333
6.18.22 FDIST.....................................................................................................................334
6.18.23 LEGACY.FDIST......................................................................................................335
6.18.24 FINV.......................................................................................................................336
6.18.25 LEGACY.FINV........................................................................................................336
6.18.26 FISHER..................................................................................................................337
6.18.27 FISHERINV............................................................................................................337
6.18.28 FORECAST............................................................................................................338
6.18.29 FREQUENCY.........................................................................................................338
6.18.30 FTEST....................................................................................................................339
6.18.31 GAMMADIST..........................................................................................................340
6.18.32 GAMMAINV............................................................................................................341
6.18.33 GAUSS...................................................................................................................341
6.18.34 GEOMEAN.............................................................................................................342
6.18.35 GROWTH...............................................................................................................342
6.18.36 HARMEAN..............................................................................................................343
6.18.37 HYPGEOMDIST.....................................................................................................344
6.18.38 INTERCEPT...........................................................................................................345
6.18.39 KURT......................................................................................................................346
6.18.40 LARGE...................................................................................................................346
6.18.41 LINEST...................................................................................................................347
100414201 29 May 2010
6.18.42 LOGEST.................................................................................................................353
6.18.43 LOGINV..................................................................................................................355
6.18.44 LOGNORMDIST.....................................................................................................356
6.18.45 MAX.......................................................................................................................357
6.18.46 MAXA.....................................................................................................................357
6.18.47 MEDIAN.................................................................................................................358
6.18.48 MIN........................................................................................................................359
6.18.49 MINA......................................................................................................................360
6.18.50 MODE.....................................................................................................................360
6.18.51 NEGBINOMDIST....................................................................................................361
6.18.52 NORMDIST............................................................................................................362
6.18.53 NORMINV..............................................................................................................363
6.18.54 LEGACY.NORMSDIST............................................................................................363
6.18.55 LEGACY.NORMSINV..............................................................................................364
6.18.56 PEARSON..............................................................................................................365
6.18.57 PERCENTILE.........................................................................................................365
6.18.58 PERCENTRANK.....................................................................................................367
6.18.59 PERMUT................................................................................................................368
6.18.60 PERMUTATIONA....................................................................................................368
6.18.61 PHI.........................................................................................................................369
6.18.62 POISSON...............................................................................................................369
6.18.63 PROB.....................................................................................................................370
6.18.64 QUARTILE..............................................................................................................371
6.18.65 RANK.....................................................................................................................372
6.18.66 RSQ.......................................................................................................................372
6.18.67 SKEW.....................................................................................................................374
6.18.68 SKEWP..................................................................................................................374
6.18.69 SLOPE...................................................................................................................375
6.18.70 SMALL...................................................................................................................375
6.18.71 STANDARDIZE.......................................................................................................376
6.18.72 STDEV...................................................................................................................376
6.18.73 STDEVA.................................................................................................................377
6.18.74 STDEVP.................................................................................................................378
6.18.75 STDEVPA...............................................................................................................379
6.18.76 STEYX....................................................................................................................380
6.18.77 LEGACY.TDIST......................................................................................................380
6.18.78 TINV.......................................................................................................................381
100414201 29 May 2010
6.18.79 TREND...................................................................................................................382
6.18.80 TRIMMEAN............................................................................................................382
6.18.81 TTEST....................................................................................................................383
6.18.82 VAR........................................................................................................................385
6.18.83 VARA......................................................................................................................386
6.18.84 VARP......................................................................................................................387
6.18.85 VARPA....................................................................................................................388
6.18.86 WEIBULL................................................................................................................388
6.18.87 ZTEST....................................................................................................................389
6.19 Number Representation Conversion Functions.................................................................390
6.19.1 General.....................................................................................................................390
6.19.2 ARABIC....................................................................................................................390
6.19.3 BASE........................................................................................................................391
6.19.4 BIN2DEC..................................................................................................................392
6.19.5 BIN2HEX..................................................................................................................394
6.19.6 BIN2OCT..................................................................................................................395
6.19.7 DEC2BIN..................................................................................................................396
6.19.8 DEC2HEX.................................................................................................................398
6.19.9 DEC2OCT................................................................................................................399
6.19.10 DECIMAL................................................................................................................400
6.19.11 HEX2BIN................................................................................................................401
6.19.12 HEX2DEC...............................................................................................................402
6.19.13 HEX2OCT...............................................................................................................403
6.19.14 OCT2BIN................................................................................................................404
6.19.15 OCT2DEC..............................................................................................................405
6.19.16 OCT2HEX...............................................................................................................406
6.19.17 ROMAN..................................................................................................................407
6.20 Text Functions..................................................................................................................409
6.20.1 General.....................................................................................................................409
6.20.2 ASC..........................................................................................................................409
6.20.3 CHAR.......................................................................................................................411
6.20.4 CLEAN.....................................................................................................................412
6.20.5 CODE.......................................................................................................................412
6.20.6 CONCATENATE.......................................................................................................413
6.20.7 DOLLAR...................................................................................................................413
6.20.8 EXACT.....................................................................................................................414
6.20.9 FIND.........................................................................................................................415
100414201 29 May 2010
6.20.10 FIXED.....................................................................................................................416
6.20.11 JIS..........................................................................................................................416
6.20.12 LEFT......................................................................................................................419
6.20.13 LEN........................................................................................................................420
6.20.14 LOWER..................................................................................................................420
6.20.15 MID.........................................................................................................................421
6.20.16 PROPER................................................................................................................422
6.20.17 REPLACE...............................................................................................................422
6.20.18 REPT......................................................................................................................423
6.20.19 RIGHT....................................................................................................................424
6.20.20 SEARCH.................................................................................................................424
6.20.21 SUBSTITUTE.........................................................................................................425
6.20.22 T.............................................................................................................................426
6.20.23 TEXT......................................................................................................................426
6.20.24 TRIM......................................................................................................................427
6.20.25 UNICHAR...............................................................................................................427
6.20.26 UNICODE...............................................................................................................428
6.20.27 UPPER...................................................................................................................428
7 Other Capabilities.....................................................................................................................430
7.1 General..............................................................................................................................430
7.2 Inline constant arrays.........................................................................................................430
7.3 Inline non-constant arrays..................................................................................................431
7.4 Year 1583..........................................................................................................................431
8 Non-portable Features..............................................................................................................433
8.1 General..............................................................................................................................433
8.2 Distinct Logical...................................................................................................................433
8.3 Auto Text to Number..........................................................................................................434
9 Test Cases (non-normative)......................................................................................................435
9.1 Test Case Data Set............................................................................................................436
Appendix A. Index.......................................................................................................................440
100414201 29 May 2010
1 Introduction
1.1 Introduction
This document is part of the Open Document Format for Office Applications (OpenDocument)
Version 1.2 specification. It defines a formula language for OpenDocument documents, which is
also called OpenFormula.
OpenFormula is a specification of an open format for exchanging recalculated formulas between
office applications, in particular, formulas in spreadsheet documents. OpenFormula defines data
types, syntax, and semantics for recalculated formulas, including predefined functions and
operations.
Using OpenFormula allows document creators to change the office application they use, exchange
formulas with others (who may use a different application), and access formulas far in the future,
with confidence that the recalculated formulas in their documents will produce equivalent results if
given equivalent inputs.
OpenFormula is intended to be a supporting document to the Open Document Format for Office
Applications (OpenDocument) format, particularly for defining its attributes table:formula and
text:formula. It can also be used in other circumstances where a simple, easy-to-read infix text
notation is desired for exchanging recalculated formulas.
Note: This specification is derived from actual practice in industry. It was especially influenced by
the OpenOffice.org exchange syntax and by the semantics of Microsoft Excel, but many other
spreadsheet implementations were considered including (alphabetically) Corel's WordPerfect suite,
Document To Go's Sheet to Go, GNOME Gnumeric, IBM/Lotus 1-2-3, KOffice's Kspread, and
WikiCalc. This was done to simplify transition of spreadsheet documents to this format. Also,
Winer's Law of the Internet (by Dave Winer) claims that "Productive open work will only result in
standards as long as the parties involved strive to follow prior art in every way possible. Gratuitous
innovation is when the standardization process ends, and usually that happens quickly."
Implementations use OpenFormula as a method to exchange recalculated formulas. Once an
implementation reads a formula in this format, it may choose to represent the formula internally in
an arbitrary way (such as a bytecode sequence, compiled machine code, or a tree of nodes).
Formulas are executed whenever they are needed to compute a specific result.
OpenFormula is not a full-fledged programming language. It is specifically designed to describe how
to calculate a single result, which it returns as its answer. OpenFormula is, in general, side-effect-
free; it does not have built-in operations to "assign" a value, and unless otherwise noted its
functions do not have side-effects. Built-in functions, when passed the same values, generally
produce the same result (with the notable exception of random number functions like RAND()). It is
designed so that it is not possible to describe a calculation in a single function that can "loop
forever." By design, all formula calculations that only reference built-in functions must eventually end
(though this may take a long time for a few computationally-intense functions, or end in failure if
they involve references to external values that cannot be acquired). In a spreadsheet, endless loops
can be created indirectly through multiple formulas, because two or more formulas may (through
references) create a circular dependency. Implementations typically handle such cycles specially,
either (1) forbidding them or (2) requiring a special setting before allowing them which also prevents
them from becoming endless. For example, implementations of OpenDocument normally forbid
circular references unless the <table:iteration> element is set, and if set, iterations are
allowed up to a specified maximum number of iterations.
100414201 29 May 2010
OpenFormula's format is designed to be useful as an attribute value within an XML document. It is
not, itself, in XML, but instead uses the traditional mathematical infix notation. Formulas used for
recalculation have not traditionally been written using XML. Instead, computer-recalculated formulas
are traditionally written using a modified mathematical infix notation such as "=value*5+2". This non-
XML format is much easier for humans to understand (because it is the form people have used for
decades), is shorter than XML formats, and there are many tools specifically designed to handle
these formats. This is different from specifications such as MathML, which are designed to support
display and not necessarily recalculation. Formulas not used for (re)calculation are not the primary
subject of this specification.
Note: Spreadsheets can contain errors. If spreadsheets are used for extremely critical decisions, it
is wise to use tools that try to detect such errors (some are built into some spreadsheet
implementations; other tools are external). More information about errors in spreadsheets can be
found in locations such as the article "The Risky Business of Spreadsheet Errors" by Ivars Peterson,
the European Spreadsheet Risks Interest Group, and Ray Panko's Spreadsheet Research (SSR)
page. This specification does not directly implement a defect detection tool, but it is key to enabling
and improving such tools. By publicly defining a common format for spreadsheet formulas, and by
publicly defining their semantics, this specification makes it much easier to build defect detection
tools for spreadsheets. The specification even points out potential issues (e.g., precedence of ^ vs.
unary -), making it easier to build tools. Thus, this specification can be viewed as a key step in
countering defects in spreadsheets.
1.2 Terminology
All text is normative unless otherwise labeled.
Within the normative text of this specification, the terms "shall", "shall not", "should", "should not",
"may" and need not are to be interpreted as described in Annex H of [ISO/IEC Directives].
1.3 Purpose
OpenFormula defines:
1. data types
2. syntax
3. semantics
for recalculated formulas.
OpenFormula also defines functions.
OpenFormula does not define:
1. a user interface
2. a general notation for mathematical expressions
Note: Information within a Rationale:, Note:, or TODO/TBD: section is not normative:
Rationale explains why a part of the specification is defined that way.
Notes provide other information, such as tips for implementation or information on what various
existing implementations do.
100414201 29 May 2010
TODO/TBD identifies something left to do, possibly including the pros and cons for a decision
yet to be made.
It is expected that there will be an unannotated version of this document, without this information,
which will be the version proposed for standardization, as well an annotated version with this
information (but not formally standardized). It is expected that the official printed form will not
include this information, but that the annotations will be included as hidden text.
This information is embedded throughout the document to prevent questions from being asked
repeatedly during specification development, and to aid implementors in avoiding common
mistakes. Much discussion about existing implementations is included; where practical, existing
implementations should help guide any standard, and these additional notes should help ensure
that this is true.
Rationale: Both the New York Times "Everyday Dictionary" (1982) and Merriam-Webster's
"Webster's Ninth New Collegiate Dictionary" (1983) declare that both "formulas" and "formulae" are
acceptable. A Google search on 2005-12-30 found 24,800,000 pages with the term "formulas" as
opposed to 6,810,000 for "formulae", so we chose to use the more common spelling. Please change
all uses of the term "formulas" to "formulae" when translating this specification into Latin.
1.4 Normative References
[ISO/IEC Directives] ISO/IEC Directives, Part 2 (Fifth Edition) Rules for the structure and
drafting of International Standards, International Organization for Standardization and International
Electrotechnical Commission, 2004.
[JISX0201] The Unicode Consortium., JIS X 0201 (1976) to Unicode 1.1 Table, 1994,
http://www.unicode.org/Public/MAPPINGS/OBSOLETE/EASTASIA/JIS/JIS0201.TXT.
[JISX0208] The Unicode Consortium., JIS X 0208 (1990) to Unicode, 1994,
[ODF11] OASIS Standard, Open Document Format for Office Applications (OpenDocument)
v1.1, February 2007, http://docs.oasis-open.org/office/v1.1/OS/OpenDocument-v1.1.pdf.
[RFC3986] T. Berners-Lee, R. Fielding, L. Masinter, Uniform Resource Identifier (URI): Generic
Syntax, http://www.ietf.org/rfc/rfc3986.txt, IETF, 2005.
[RFC3987] M. Duerst, M. Suignard, Internationalized Resource Identifiers (IRIs),
http://www.ietf.org/rfc/rfc3987.txt, IETF, 2005.
[UAX11] Asmus Freytag, East Asian Width, Unicode Standard Annex #11,
http://www.unicode.org/reports/tr11/tr11-19.html, 2009.
[UNICODE] The Unicode Consortium. The Unicode Standard, Version 5.2.0, defined by: The
Unicode Standard, Version 5.2 (Mountain View, CA, The Unicode Consortium, 2009. ISBN 978-1-
936213-00-9). (http://www.unicode.org/versions/Unicode5.2.0/).
[XML1.0] Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, Eve Maler, Franois Yergeau ,
Extensible Markup Language (XML) 1.0 (Fourth Edition), http://www.w3.org/TR/2006/REC-xml-
20060816/, W3C, 2006.
1.5 Non-Normative References
[ISO/IEC Directives] ISO/IEC Directives, Part 2 (Fifth Edition) Rules for the structure and
drafting of International Standards, International Organization for Standardization and International
Electrotechnical Commission, 2004.
100414201 29 May 2010
[JISX0201] The Unicode Consortium., JIS X 0201 (1976) to Unicode 1.1 Table, 1994,
[JISX0208] The Unicode Consortium., JIS X 0208 (1990) to Unicode, 1994,
[ODF11] OASIS Standard, Open Document Format for Office Applications (OpenDocument)
v1.1, February 2007, http://docs.oasis-open.org/office/v1.1/OS/OpenDocument-v1.1.pdf.
[RFC3986] T. Berners-Lee, R. Fielding, L. Masinter, Uniform Resource Identifier (URI): Generic
Syntax, http://www.ietf.org/rfc/rfc3986.txt, IETF, 2005.
[RFC3987] M. Duerst, M. Suignard, Internationalized Resource Identifiers (IRIs),
http://www.ietf.org/rfc/rfc3987.txt, IETF, 2005.
[UAX11] Asmus Freytag, East Asian Width, Unicode Standard Annex #11,
http://www.unicode.org/reports/tr11/tr11-19.html, 2009.
[UNICODE] The Unicode Consortium. The Unicode Standard, Version 5.2.0, defined by: The
Unicode Standard, Version 5.2 (Mountain View, CA, The Unicode Consortium, 2009. ISBN 978-1-
936213-00-9).
[XML1.0] Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, Eve Maler, Franois Yergeau ,
Extensible Markup Language (XML) 1.0 (Fourth Edition), http://www.w3.org/TR/2006/REC-xml-
20060816/, W3C, 2006.
Additional references:
Blattner, Patrick, Laurie, Ulrich, Ken Cook, and Timothy Dyck (1999). Special Edition Using
Microsoft Excel. Que. Indianapolis, Indiana. ISBN 0-7897-1729-8.
Simon, Jinjer (2000). Excel 2000 in a Nutshell. O'Reilly.
Walden, Jeff (1986). File Formats for Popular PC Software: A Programmer's Reference.
Wiley Press Book, John Wiley & Sons, Inc. NY, NY.
Walkenbach, John (1999). Excel 2000 Formulas. M&T Books, an imprint of IDG Books
Worldwide, Inc. ISBN 0-7645-4609-0.
Walkenbach, John (2004). Excel 2003 Formulas. Wiley Publishing, Inc. Indianapolis,
Indiana. ISBN 0-7645-4073-4.
Zwillinger, Daniel (editor-in-chief). CRC Standard Mathematical Tables and Formulae.
Chapman & Hall/CRC, CRC Press Company. 31
st
edition. 2003.
100414201 29 May 2010
2 Expressions and Evaluators
2.1 OpenDocument Formula Expression
An OpenDocument formula expression shall adhere to the expression syntax defined in chapter 4. It
may use subsets or supersets of OpenFormula.
Ed. Note (Michael): That an expression may contain only a subset an expression syntax seems
to be self-evident. That it may use a supeset seems to be problematic to me.
2.2 Evaluators
2.2.1 OpenDocument Formula Evaluator
An OpenDocument Formula Evaluator is a program that can parse and recalculate OpenDocument
formula expressions, and that meets the following additional requirements:
A) It may implement subsets or supersets of this specification.
Ed. Note (Michael): Again, I think we should drop this clause. An evaluator in any case may
implement a superset. And the subset cases should be covered by the function groups.
B) It shall conform to one of: (C16) OpenDocument Formula Small Group Evaluator, (C17)
OpenDocument Formula Medium Group Evaluator or (C18) OpenDocument Formula Large Group
Evaluator
C) It may implement additional functions beyond those defined in this specification. It may further
implement additional formula syntax, additional operations, additional optional parameters for
functions, or may consider function parameters to be optional when they are required by this
specification.
D) Applications should clearly document their extensions in their user documentation, both online
and paper, in a manner so users would be likely to be aware when they are using a non-standard
extension.
Note: An expression may reference a nonstandard function by name, or depend on implementation-
defined behavior, or on semantics not guaranteed by this specification. Reference to or
dependence upon functions or behavior not defined by this standard may impair the interoperability
of the resulting expression(s).
Note: This specification defines formulas in terms of a canonical text representation used for
exchange. If formulas are contained in XML attributes some characters shall be escaped as
required by the XML specification (e.g., the character & shall be escaped in XML attributes using
notations such as &). All string and character literals references by this specification are in the
value space defined by [UNICODE] thus, A is U+0041, Z is U+005A, and the range of characters
A-Z is the range U+0041 through U+005A inclusive.
Note: Future versions of this specification may add a huge group (over 400 functions) and/or a
tiny group (e.g., one without database functions and so on).
Rationale: Here are some of the drivers for the various groups:
Small is driven by PDAs, cell phones, etc. It represents the capabilities and functions
implemented by such diverse applications as Sheet To Go (which runs on PalmOS PDAs),
100414201 29 May 2010
OpenOffice.org 2 Calc, and Microsoft Excel 2003. In general, if any implementation did not
implement a particular function or semantic, that requirement was moved outside of Small (with
a few exceptions, such as requiring both ISERR and ISERROR).
Medium is a "majority intersection" of the capabilities in common desktop spreadsheet
programs (e.g., most spreadsheet implementations for the desktop provide those capabilities),
considering implementations such as Microsoft Excel 2003, Corel Word Perfect Office 12,
IBM/Lotus 1-2-3 version 9.8, OpenOffice.org Calc, and Gnumeric.
Large is driven by what is needed to be compatible with market-leading spreadsheet
applications, such as Microsoft Excel 2003 and OpenOffice.org.
Huge is almost the union of capabilities of common desktop spreadsheet programs; it is not
currently defined in this specification, but a future version might add it.
Having groups for compliance lets applications quickly achieve some level of compliance that is
sufficient for many user needs, yet be able to distinguish themselves if they provide an especially
rich set of functionality. In particular, it is expected that many applications will meet the small group
almost out of the box (once they support the file exchange and syntax). The Medium group gives
implementations a relatively easy goal (if they don't already implement it). The Huge group is a
steep goal, but even if spreadsheet implementations that do not implement everything in Huge can
implement a subset with the same semantics -- and thus be able to exchange that information with
other programs that implement the same subset. Additional groups Tiny and Colossal could be
added on both ends of the grouping, if appropriate.
Here are some of the known weaknesses of current spreadsheet implementations as compared to
Large:
KSpread's MOD function handles negative numbers differently than other spreadsheets, and
KSpread 1.4.2 incorrectly computes VALUE (e.g., VALUE("6") is 0 instead of 6). This is old
information and both issues have probably already been fixed.
OpenOffice.org 2.0's LOG function requires the second parameter; here it is optional. This is
already fixed as of OpenOffice.org 2.4.
For more about the differences between Excel and Lotus 1-2-3, see Calculation differences
between Microsoft Excel and Lotus 1-2-3 formulas. That document has many errors in it, however:
Excel does not ALWAYS treat text as an error in a Number context, in fact, if given A4+A5, and A4 is
the text "100", Excel 2002 will silently convert the text to a number. The note does report that "Excel
2000 and later versions contain functions for compatibility with Lotus 1-2-3 Release 4.0 and later.
The "A" functions AVERAGEA, MAXA, MINA, STDEVA, STDEVPA, VARA, and VARPA
calculate results by using all of the cells in a range (including blank cells), cells that contain text, and
cells that contain the Logical values TRUE or FALSE."
Complex numbers are placed in the large group, because not all applications support them, and
even those that do sometimes are require additional steps. Excel 2003 can handle them, but only
when the Analysis Toolpak is installed (by going to Tools/Add-ins). Gnumeric can handle them.
There is an extra package for OpenOffice.org 2 for handling complex numbers. Unfortunately, the
approach to Complex numbers used by Excel and others, using text values, is incredibly
convoluted. Instead of creating a new type (Complex) and allowing functions to handle the new
type, such applications require that you use a whole new set of functions, even for operators that
are normally expressed with infix notation. Many spreadsheets cannot use infix operators like "*" to
multiple complex numbers. Thus, to compute e^PI*i, instead of saying EXP(PI*i), you have to say
IMEXP(IMPRODUCT(PI(),COMPLEX(0,1))). Not all functions have an IMxyz() equivalent, making
complex number use even more complicated. However, that really is what applications require. This
specification is written so that portable approaches work, but is carefully written to permit future
applications to add a complex number (as a distinct type, type of number, or subtype of number),
and permit operators like + to work on them directly.
100414201 29 May 2010
2.2.2 OpenDocument Formula Small Group Evaluator
An OpenDocument Formula Small Group Evaluator is an OpenDocument Formula Evaluator that
meets the following additional requirements:
A) It shall implement at least the limits defined in the Basic Limits section.
B) It shall implement the syntax defined in these sections on syntax: Criteria; Basic Expressions;
Constant Numbers; Constant Strings; Operators; Functions and Function Parameters; Nonstandard
Function Names; References; Simple Named Expressions; Errors; Whitespace.
C) It shall implement all implicit conversions for the types it implements, at least Text, Conversion to
Number, Reference, Conversion to Logical, and Error.
D) It shall implement the following operators (which are all the operators except reference union (~)):
Infix Operator Ordered Comparison ("<", "<=", ">", ">="); Infix Operator "&; Infix Operator "+; Infix
Operator "-; Infix Operator "*; Infix Operator "/; Infix Operator "^; Infix Operator "=; Infix Operator
"<>; Postfix Operator %; Prefix Operator +; Prefix Operator -; Infix Operator Reference
Intersection ("!"); Infix Operator Range (":").
E) It shall implement at least the following functions as defined in this specification: ABS ; ACOS ;
AND ; ASIN ; ATAN ; ATAN2 ; AVERAGE ; AVERAGEIF ; CHOOSE ; COLUMNS ; COS ; COUNT ;
COUNTA ; COUNTBLANK ; COUNTIF ; DATE ; DAVERAGE ; DAY ; DCOUNT ; DCOUNTA ; DDB ;
DEGREES ; DGET ; DMAX ; DMIN ; DPRODUCT ; DSTDEV ; DSTDEVP ; DSUM ; DVAR ; DVARP
; EVEN ; EXACT ; EXP ; FACT ; FALSE ; FIND ; FV ; HLOOKUP ; HOUR ; IF ; INDEX ; INT ; IRR ;
ISBLANK ; ISERR ; ISERROR ; ISLOGICAL ; ISNA ; ISNONTEXT ; ISNUMBER ; ISTEXT ; LEFT ;
LEN ; LN ; LOG ; LOG10 ; LOWER ; MATCH ; MAX ; MID ; MIN ; MINUTE ; MOD ; MONTH ; N ; NA
; NOT ; NOW ; NPER ; NPV ; ODD ; OR ; PI ; PMT ; POWER ; PRODUCT ; PROPER ; PV ;
RADIANS ; RATE ; REPLACE ; REPT ; RIGHT ; ROUND ; ROWS ; SECOND ; SIN ; SLN ; SQRT ;
STDEV ; STDEVP ; SUBSTITUTE ; SUM ; SUMIF ; SYD ; T ; TAN ; TIME ; TODAY ; TRIM ; TRUE ;
TRUNC ; UPPER ; VALUE ; VAR ; VARP ; VLOOKUP ; WEEKDAY ; YEAR
F) It need not evaluate references that contain more than one area.
G) It need not implement inline arrays, complex numbers, and the reference union operator.
H) For expressions embedded in an OpenDocument document, it shall consider the values of the
following host-defined properties: HOST-CASE-SENSITIVE, HOST-PRECISION-AS-SHOWN,
HOST-SEARCH-CRITERIA-MUST-APPLY-TO-WHOLE-CELL, HOST-AUTOMATIC-FIND-
LABELS, HOST-USE-REGULAR-EXPRESSIONS, HOST-USE-WILDCARDS, HOST-NULL-YEAR,
HOST-NULL-DATE.
I) It shall support international characters for named expression identifiers.
Rationale: The list of functions in the small group is based on Richard Kernick's email of 2005-10-
20 on the OpenFormula mailing list, identifying the list of functions supported by Documents to Go
for the Palm, version 6. He proposed that this list would be an excellent subset, since it
demonstrated (through an actual implementation) what functions would best support a significant
number of spreadsheet users in small environments. In general, we want to emphasize what
industry is doing, instead of pretending, so unless suggested otherwise we used actual
implementations as our guide.
Changes were then made based on examination of various implementations. ERROR.TYPE is not
universally portable (e.g., it's named ERRORTYPE in OOo2 with completely different results), so it
was moved out of this group. Instead of CONCATENATE people normally use &, so it was removed
from this group as well.
Rationale: A few of these functions are not in Quattro Pro or Lotus 1-2-3.In particular, there is an
ISERR/ISERROR issue. Both Quattro Pro and Lotus 1-2-3v9 have a function named ISERR; neither
has a function named ISERROR. Even more confusingly, in Lotus 1-2-3v9, ISERR has the
100414201 29 May 2010
functionality of ISERROR instead of ISERR. This is because in Lotus 1-2-3v9, @ISERR(@NA) is 1
(True). In Quattro Pro, Excel, OpenOffice.org, SheetToGo, etc., ISERR(NA()) is 0 (False); this is
written as @ISERR(@NA) in Quattro Pro.The function ISERROR could be moved to a higher level,
leaving only ISERR at level 1; but this would not handle Lotus 1-2-3v9.8, since it would map its
ISERR to this specification's ISERROR. Removing ISERROR would require rewriting of many level
1 tests as well as the testsuite generator. In some sense this means that "NA" isn't considered an
"error" by systems that only have ISERR, since the only True/False detection system skips NA. But
by defining ISERR with the semantics as has been done, the model defined in this specification is
still correct. Conversely, ISERR could be moved to a higher level, which would mean that Quattro
Pro does not meet level 1. There is no perfect solution; it is impractical to have a group lacking both
ISERR and ISERROR. Since both functions are quite valuable, and both are trivial to implement,
both are required for even the small group.
It is unfortunate that the functions ISERR and ISERROR have such similar names, but this really is
standard practice, so we've simply documented it that way.
Note: Other functions not in Quattro Pro are: COLUMNS, COUNTA, DCOUNTA, DSTDEV, LOG10,
PRODUCT. In some cases the "nonmatches" are simply different names. E.G., Quattro Pro's
ISSTRING maps to ISTEXT, LENGTH to LEN, REPEAT to REPT, and so on.
Lotus 1-2-3v9.8.1 represents AND, OR, and NOT as operators but has them. It has no
distinguishable POWER function, and must use the infix operator. Functions not in Lotus 1-2-
3v9.8.1 are: COLUMNS, COUNTA, DCOUNTA, DEGREES, DPRODUCT, ISLOGICAL, RADIANS,
SUBSTITUTE. Many functions are just renamed, e.g., ISEMPTY becomes ISBLANK.
Note: John Cowan reported on 2005-10-19 that he had examined the following implementations for
their time/date functions:
Microsoft Excel 2003 internal help
Gnumeric list on web site
KSpread posted to this list
Quantrix Modeler 2.0 manual on web site
OpenOffice.org 2.0 manual draft on web site
Cowan reported that "Quantrix Modeler is a spreadsheet-like application that descends conceptually
from Lotus Improv, so it is an offshoot of the main line of tradition and therefore valuable as a cross-
check."
All 5 of them implemented the following, and therefore were recommended for level 1:
DATE, DATEVALUE, DAY, DAYS360, HOUR, MINUTE, MONTH, NOW,
SECOND, TIME, TIMEVALUE, TODAY, WEEKDAY, YEAR.
He proposed the following functions for level 2. They are not present in Quantrix, and are available
in OpenOffice.org only when the Analysis AddIn is present:
EDATE, EOMONTH, NETWORKDAYS, WORKDAY, YEARFRAC.
Note: This specification does not mandate a user interface for international characters, so a
resource-constrained application may choose to not show the traditional glyph (e.g., it may show the
[UNICODE] numeric code instead).
Note: The table:use-wildcards attribute was proposed to the ODF-TC on 2007-03-08 by Eike
Rathke, and was eventually accepted. It was confirmed to be documented in OpenDocument 1.2
draft dated 28 April 2008.
100414201 29 May 2010
2.2.3 OpenDocument Formula Medium Group Evaluator
An OpenDocument Formula Medium Group Evaluator is an OpenDocument Small Group Formula
Evaluator that meets the following additional requirements:
A) It shall implement the following functions as defined in this specification: ACCRINT ; ACCRINTM
; ACOSH ; ACOT ; ACOTH ; ADDRESS ; ASINH ; ATANH ; AVEDEV ; BESSELI ; BESSELJ ;
BESSELK ; BESSELY ; BETADIST ; BETAINV ; BINOMDIST ; CEILING ; CHAR ; CLEAN ; CODE ;
COLUMN ; COMBIN ; CONCATENATE ; CONFIDENCE ; CONVERT ; CORREL ; COSH ; COT ;
COTH ; COUPDAYBS ; COUPDAYS ; COUPDAYSNC ; COUPNCD ; COUPNUM ; COUPPCD ;
COVAR ; CRITBINOM ; CUMIPMT ; CUMPRINC ; DATEVALUE ; DAYS360 ; DB ; DEVSQ ; DISC ;
DOLLARDE ; DOLLARFR ; DURATION ; EFFECT ; EOMONTH ; ERF ; ERFC ; EXPONDIST ;
FISHER ; FISHERINV ; FIXED ; FLOOR ; FORECAST ; FTEST ; GAMMADIST ; GAMMAINV ;
GAMMALN ; GCD ; GEOMEAN ; HARMEAN ; HYPGEOMDIST ; INTERCEPT ; INTRATE ; ISEVEN
; ISODD ; ISOWEEKNUM ; KURT ; LARGE ; LCM ; LEGACY.CHIDIST ; LEGACY.CHIINV ;
LEGACY.CHITEST ; LEGACY.FDIST ; LEGACY.FINV ; LEGACY.NORMSDIST ;
LEGACY.NORMSINV ; LEGACY.TDIST ; LINEST ; LOGEST ; LOGINV ; LOGNORMDIST ;
LOOKUP ; MDURATION ; MEDIAN ; MINVERSE ; MIRR ; MMULT ; MODE ; MROUND ;
MULTINOMIAL ; NEGBINOMDIST ; NETWORKDAYS ; NOMINAL ; ODDFPRICE ; ODDFYIELD ;
ODDLPRICE ; ODDLYIELD ; OFFSET ; PEARSON ; PERCENTILE ; PERCENTRANK ; PERMUT ;
POISSON ; PRICE ; PRICEMAT ; PROB ; QUARTILE ; QUOTIENT ; RAND ; RANDBETWEEN ;
RANK ; RECEIVED ; ROMAN ; ROUNDDOWN ; ROUNDUP ; ROW ; RSQ ; SERIESSUM ; SIGN ;
SINH ; SKEW ; SKEWP ; SLOPE ; SMALL ; SQRTPI ; STANDARDIZE ; STDEVA ; STDEVPA ;
STEYX ; SUBTOTAL ; SUMPRODUCT ; SUMSQ ; SUMX2MY2 ; SUMX2PY2 ; SUMXMY2 ; TANH ;
TBILLEQ ; TBILLPRICE ; TBILLYIELD ; TIMEVALUE ; TINV ; TRANSPOSE ; TREND ; TRIMMEAN
; TTEST ; TYPE ; VARA ; VDB ; WEEKNUM ; WEIBULL ; WORKDAY ; XIRR ; XNPV ; YEARFRAC ;
YIELD ; YIELDDISC ; YIELDMAT ; ZTEST
B) It shall implement the Infix Operator Reference Union ("~")
C) It shall evaluate references with more than one area.
Rationale: This is the set of functions that are "widely implemented" by desktop spreadsheet
applications. This was originally computed by starting with the small group, and adding functions
that were implemented by at least 4 of the following applications: Excel 2003, Gnumeric, Lotus 1-2-
3 v9, OpenOffice.org 2, and QuattroPro 12. Some effort was made to identify translations (e.g.,
where the same function has a different name). Per December 2006 discussion the following were
moved from Large to Medium: ACOT, ACOTH, COT, COTH (since other trig functions were in
medium, it was inconsistent to keep these in Large).
2.2.4 OpenDocument Formula Large Group Evaluator
An OpenDocument Formula Large Group Evaluator is an OpenDocument Medium Group Formula
Evaluator that meets the following additional requirements:
A) It shall implement the syntax defined in these sections on syntax: Inline Arrays; Automatic
Intersection; External Named Expressions.
B) It shall implement the complex number type as discussed in the section on Complex Number,
array formulas, and Sheet-local Named Expressions.
It shall implement the following functions as defined in this specification: AMORDEGRC ;
AMORLINC ; ARABIC ; AREAS ; ASC ; AVERAGEA ; AVERAGEIFS ; BASE ; BIN2DEC ; BIN2HEX
; BIN2OCT ; BINOM.DIST.RANGE ; BITAND ; BITLSHIFT ; BITOR ; BITRSHIFT ; BITXOR ;
CHISQDIST ; CHISQINV ; COMBINA ; COMPLEX ; COUNTIFS ; CSC ; CSCH ; DATEDIF ; DAYS ;
DDE ; DEC2BIN ; DEC2HEX ; DEC2OCT ; DECIMAL ; DELTA ; EDATE ; ERROR.TYPE;
EUROCONVERT ; FACTDOUBLE ; FDIST ; FINDB ; FINV ; FORMULA ; FREQUENCY ;
FVSCHEDULE ; GAMMA ; GAUSS ; GESTEP ; GETPIVOTDATA ; GROWTH ; HEX2BIN ;
100414201 29 May 2010
HEX2DEC ; HEX2OCT ; HYPERLINK ; IFERROR ; IFNA ; IMABS ; IMAGINARY ; IMARGUMENT ;
IMCONJUGATE ; IMCOS ; IMCOT ; IMCSC ; IMCSCH ; IMDIV ; IMEXP ; IMLN ; IMLOG10 ;
IMLOG2 ; IMPOWER ; IMPRODUCT ; IMREAL ; IMSEC ; IMSECH ; IMSIN ; IMSQRT ; IMSUB ;
IMSUM ; IMTAN; INDIRECT ; INFO ; IPMT ; ISFORMULA ; ISPMT ; ISREF ; JIS ; LEFTB ; LENB ;
MAXA ; MDETERM ; MULTIPLE.OPERATIONS ; MUNIT ; MIDB ; MINA ; NORMDIST ; NORMINV ;
NUMBERVALUE ; OCT2BIN ; OCT2DEC ; OCT2HEX ; PDURATION ; PERMUTATIONA ; PHI ;
PPMT ; PRICEDISC ; REPLACEB ; RIGHTB ; RRI ; SEARCH ; SEARCHB ; SEC ; SECH ; SHEET ;
SHEETS ; SUMIFS ; TEXT ; UNICHAR ; UNICODE ; VARPA ; XOR
Rationale: This is essentially a union of the functions supported by Microsoft Excel and
OpenOffice.org 2.0, plus a few. Many people want to make sure that their spreadsheets from Excel
or OpenOffice.org can be stored in this format, and the way to ensure that is to ensure that the
same functions are supported.
GAMMA was added because FACT cannot portably provide that functionality, it's painful to
implement using the existing functions, and it's implemented on several other spreadsheets. It
already existed in Gnumeric, so including it eases the transition for Gnumeric users.
Bit operations (BITAND BITLSHIFT BITOR BITRSHIFT BITXOR) were added. They are hard to do
without when they are needed, they are very useful (and thus provided in many programming
languages), they're easy to implement, and adding them supports Gnumeric interoperability.
Gnumeric spelling was used, since these names clearly differentiate them from the logical AND, OR,
and XOR.
Logical XOR added. It can be simulated with the built-in functions, but only in awkward and non-
obvious manners, e.g. {=ISODD(SUM(IF(x1<>0;1;0))+SUM(IF(x2<>0;1;0))+...)}. This aids Gnumeric
interoperability.
Note: DATEDIF is included to support interoperability with older systems and documents. It is only
included in LARGE (even though it's widely implemented) because it's not widely used nor needed.
The following functions are in OpenOffice.org, but not in Excel 2003: ACOT, ACOTH, ARABIC, B,
BASE, COMBINA, COT, COTH, CURRENT, DAYS, DDE, DECIMAL, EFFECTIVE, ERRORTYPE,
FORMULA, GAUSS, ISFORMULA, MUNIT, PERMUTATIONA, PHI, PRICEDISC, RRI, SHEET,
SHEETS, STYLE.
Some of these functions have similar names, in particular, some differ only because they end in S:
DAYS/DAY, SHEETS/SHEET. This is potentially confusing. However, this is standard practice, and it
is too embedded now to change it.
The following functions are in OpenOffice.org, but not in Excel 2003: CUMIPMT_ADD,
CUMPRINC_ADD, DURATION_ADD, GCD_ADD, ISEVEN_ADD, ISODD_ADD, LCM_ADD,
WEEKNUM_ADD. The _ADD functions have Excel 2003 semantics. A difference is the
WEEKNUM_ADD function that uses Excel's nonstandard week numbering system, while
WEEKNUM uses ISO standard week numbering.
OpenOffice.org implementors have agreed to change their semantics for GCD and LCM, so as a
result there is no need for OpenOffice.org's GCD_ADD and LCM_ADD. Originally OpenOffice.org's
LCM and GCD accepted non-integer values and did special operations with them. The following
functions will be removed from OpenOffice.org and replaced by the Excel compatible "_ADD"
function renamed to their equivalent:
GCD => GCD_ADD => GCD
LCM => LCM_ADD => LCM
The following functions will be removed from OpenOffice.org and replaced by the compatible
function, renamed to their equivalent where applicable:
EFFECT_ADD => EFFECTIVE => EFFECT
NOMINAL_ADD=> NOMINAL => NOMINAL
CUMIPMT_ADD => CUMIPMT => CUMIPMT
CUMPRINC_ADD => CUMPRINC => CUMPRINC
100414201 29 May 2010
ISEVEN_ADD => ISEVEN => ISEVEN
ISODD_ADD => ISODD => ISODD
DURATION_ADD => DURATION
DURATION => PDURATION
Note: In OpenOffice.org the EFFECTIVE and NOMINAL functions have a different default result
formatting (percentage), as opposed to EFFECT_ADD and NOMINAL_ADD (not percentage), which
are the same as EFFECT and NOMINAL in this specification. But this makes no difference, so we
don't need separate functions for interoperability. Similar for CUMIPMT and CUMPRINC, which in
OpenOffice.org have the result formatted as the default locale's currency, whereas CUMIPMT_ADD
and CUMPRINC_ADD do not have a format assigned, as CUMIPMT and CUMPRINC in this
specification. In fact, for portability across locales, an automatic format attribution is not desired.
Note: A number of external-query functions were not added, due to concerns about portability,
security, and how widely they are really used. These include the ODBC add-in functions:
SQL.OPEN SQL.EXEC.QUERY SQL.BIND SQL.RETRIEVE SQL.RETRIEVE.TO.FILE SQL.CLOSE
SQL.GET.SCHEMA SQL.ERROR SQL.REQUEST. These also include the QUERY functions
QUERYGETDATA, QUERYGETDATADIALOG, and QUERYREFRESH.
Note: NUMBERSTRING is a hidden function of Excel noted in
http://sc.openoffice.org/excelfileformat.sxw, but typical documentation on Excel doesn't reveal this.
This is a very obscure function, and there's no indication that it's needed for interoperability, so it
has not been included.
Note: According to (http://www.mvps.org/visio/Excel_2007.htm) retrieved July 17, 2006, Excel 2007
will accept16k (2^14) columns (A..XFD) and 1M (2^20) rows, and new functions. Most of the new
functions are not really new, they were just in separate packages that are now merged in:
Double-byte functions (not really new, already in the list) FINDB, LEFTB, LENB, MIDB,
REPLACEB, RIGHTB and SEARCHB
Cube functions:
CUBEKPIMEMBER - Returns a key performance indicator (KPI) name, property, and
measure, and displays the name and property in the cell. A KPI is a quantifiable
measurement, such as monthly gross profit or quarterly employee turnover, used to monitor
an organization's performance.
CUBEMEMBER -Returns a member or tuple in a cube hierarchy. Use to validate that the
member or tuple exists in the cube.
CUBEMEMBERPROPERTY - Returns the value of a member property in the cube. Use to
validate that a member name exists within the cube and to return the specified property for
this member.
CUBERANKEDMEMBER - Returns the nth, or ranked, member in a set. Use to return one
or more elements in a set, such as the top sales performer or top 10 students.
CUBESET - Defines a calculated set of members or tuples by sending a set expression to
the cube on the server, which creates the set, and then returns that set
CUBESETCOUNT - Returns the number of items in a set.
CUBEVALUE - Returns an aggregated value from a cube.
Well-known Bessel functions, which aren't actually new: BESSELI, BESSELJ, BESSELK,
BESSELY
Number conversions (not new): BIN2DEC, BIN2HEX, BIN2OCT, DEC2BIN, DEC2HEX,
DEC2OCT, HEX2BIN, HEX2DEC, HEX2OCT, OCT2BIN, OCT2DEC, OCT2HEX
100414201 29 May 2010
Other Engineering: CONVERT, DELTA (Tests whether two values are equal), ERF (Returns
the error function), ERFC (Returns the complementary error function), GESTEP (Tests whether
a number is greater than a threshold value)
Complex number support (not new): COMPLEX, IMABS, IMAGINARY, IMARGUMENT,
IMCONJUGATE, IMCOS, IMDIV , IMEXP, IMLN, IMLOG10, IMLOG2, IMPOWER,
IMPRODUCT, IMREAL, IMSIN, IMSQRT, IMSUB, IMSUM
Other external: EUROCONVERT (Converts a number to euros, converts a number from euros
to a euro member currency, or converts a number from one euro member currency to another
by using the euro as an intermediary (triangulation)), SQL.REQUEST (Connects with an
external data source and runs a query from a worksheet, then returns the result as an array).
GETPIVOTDATA.
Other: SUMIFS (Adds the cells in a range that meet multiple criteria), AVERAGEIF (Returns the
average (arithmetic mean) of all the cells in a range that meet a given criteria), AVERAGEIFS
(Returns the average (arithmetic mean) of all cells that meet multiple criteria.)
Some Lotus 1-2-3 functions are given different names in this specification. In general, OpenFormula
uses Excel/OpenOffice.org-like names instead. Note that no "@" symbol precedes function names,
and the Lotus 1-2-3 "@@" becomes INDIRECT. Logical operators are functions (AND, OR, and
NOT). In addition, the following Lotus 1-2-3 names have the following OpenFormula names (which
generally follows the "Excel branch" naming conventions):
Lotus 1-2-3 OpenFormula
@ INDIRECT
AVG AVERAGEA
CELLPOINTER CELL
COUNT COUNTA
CTERM NPER, but different parameters
DAVG DAVERAGE
D360 DAYS360
DCOUNT DCOUNTA
DSTD DSTDP
DSTDS DSTDEV
DVAR DVARP
DVARS DVAR
INT TRUNC
ISNUMBER ISNONTEXT
ISRANGE ISREF
ISSTRING ISTEXT
LENGTH LEN
MAX MAXA
100414201 29 May 2010
MIN MINA
PMT PMT - different parameter order
PUREAVG AVERAGE
PURECOUNT COUNT
PUREMAX MAX
PUREMIN MIN
PURESTD STDEVP
PURESTDS STDEV
PUREVAR VARP
PUREVARS VAR
PV PV - different parameter order
RAND RAND - different each recalculation
RATE RATE - different parameter order
REPEAT REPT
S T
STD STDEVPA
STDDS STDEVA
STRING FIXED
TERM NPER - different parameter order
VAR VARPA
VARS VARA
Other sources of information about spreadsheet functions are:
http://www.planatechsolutions.com/xllplus-online/tech_builtin_fn_numbers_bynumber.htm
http://www.spreadsheetgear.com/products/spreadsheetgear.net.aspx
A future version of this specification might add a huge group. Examine the candidate functions.
Here's the list of additional possibilities, generated by merging the names of functions of many
spreadsheet programs and removing function names included in this specification:
ABDAYS; ACCRINTXL; ACCRUED; ACCRUED2; ACDAYS; ACSC; ACSCH; ADDB; ADDBO; ADDH;
ADDHO; AMAINT; AMINT; AMNTHS; AMPMT; AMPMTI; AMPRN; AMRES; AMRPRN; AMTERM;
ANDB; ANDH; ARRAY; ASCII; ASCIITOCHAR; ASCTOHEX; ASEC; ASECH; ATL_LAST; BDAYS;
BERNOULLI; BETA; BETAI; BETALN; BINO; BINOMIAL; BINTOHEX; BINTOHEX64; BINTONUM;
BINTONUM64; BINTOOCT; BINTOOCT64; BITAND; BITLSHIFT; BITRB; BITRH; BITSB; BITSH;
BITTB; BITTH; BLOCKNAME; BLOCKNAME2; BLOCKNAMES; BLOCKNAMES2; BOOL2INT;
BOOL2STRING; BUSDAY; CALL; CARX; CARY; CATB; CATH; CATNB; CATNH; CAUCHY; CDAYS;
CEIL; CELLINDEX; CELLPOINTER; CHARTOASCII; CHR; CNT; COLS; COLUMNNUMBER;
COMB; COMBINA; COMMAND; COMPARE; COMPOUND; CONTINUOUS; COORD; COV;
CRONBACH; CSC; CSCH; CUMIPMT_ADD; CUMPRINC_ADD; CUM_BIV_NORM_DIST; CUR;
CURRENT; CURRENTDATE; CURRENTDATETIME; CURRENTTIME; CURVALUE; DATALINK;
100414201 29 May 2010
DATE2UNIX; DATECONVERT; DATEINFO; DAYNAME; DAYOFYEAR; DAYSINMONTH;
DAYSINYEAR; DCNT; DDELINK; DEC2FRAC; DECILE; DECSEX; DEGTORAD; DEVSQA; DFRAC;
DIMCIRC; DIV; DOLLARTEXT; DPURECOUNT; DSTD; DSTDS; DURAT; DURATION_ADD;
DVARS; EASTERSUNDAY; EDIGIT; EMNTH; EPS; ERFD; ERR; ERROR; ERRORTYPE; EURO;
EXP2; EXPM1; EXPPOWDIST; EXPRESSION; FACTLN; FBDAY; FEETBL; FIB; FIELD;
FILEEXISTS; FILENAME; FIRSTBLANKPAGE; FIRSTINGROUP; FRAC2DEC; FRACD;
FRACTION; FREQDIST; FULLP; FUTV; FV2; FVAL; FVAMOUNT; FV_ANNUITY; GAMMA;
GAMMAI; GAMMAP; GAMMAQ; GEOMDIST; GEOSUM; GETENV; GETGROUP;
GETREGISTRYKEY; GRANDTOTAL; GRANDTOTAL123; G_DURATION; G_PRODUCT; HALFP;
HEX; HEXTOASC; HEXTOBIN; HEXTOBIN64; HEXTONUM; HEXTONUM64; HEXTOOCT;
HEXTOOCT64; HOLS; HOURS; HYPOT; IMARCCOS; IMARCCOSH; IMARCCOT; IMARCCOTH;
IMARCCSC; IMARCCSCH; IMARCSEC; IMARCSECH; IMARCSIN; IMARCSINH; IMARCTAN;
IMARCTANH; IMCOSH; IMCOT; IMCOTH; IMCSC; IMCSCH; IMINV; IMNEG; IMPRODUCT;
IMSEC; IMSECH; IMSINH; IMSUM; IMTAN; IMTANH; INDEXTOLETTER; INT2BOOL; INTXL; INV;
INVB; INVBINO; INVH; INVSUMINV; IPAYMT; IRATE; ISAAF; ISAPP; ISBDAY; ISBETWEEN;
ISBLOCK; ISDATE; ISEMPTY; ISEVEN_ADD; ISFILE; ISFORMULA; ISLEAPYEAR;
ISLEGALPAGENAME; ISMACRO; ISNOTTEXT; ISNUM; ISODD_ADD; ISOYEAR; ISPRIME;
ISTIME; ITHPRIME; KANSUUJI; KPRODUCT; KURTOSIS; KURTP; LANDAU; LAPLACE;
LARGEST; LASTBLANKPAGE; LASTCELLVALUE; LASTINGROUP; LBDAY; LENGTHB;
LETTERTOINDEX; LEVEL_COUPON; LINTERP; LLDEC; LN1P; LOG2; LOGBASE; LOGCONV;
LOGFIT; LOGISTIC; LOGN; LOGREG; LWKDAY; MAXLOOKUP; MDAYS; MDET; MEMAVAIL;
MEMEMSAVAIL; MINLOOKUP; MINUTES; MNTHS; MODULO; MONTHNAME; MONTHS;
MTGACC; MULT; MULTIPLY; NAND; NBDAY; NENGO; NETPV; NEXTMONTH; NOR; NORMAL;
NSUM; NT_D; NT_MU; NT_PHI; NT_PI; NT_SIGMA; NUM2STRING; NUMTOBIN; NUMTOBIN64;
NUMTOHEX; NUMTOHEX64; NUMTOOCT; NUMTOOCT64; NWKDAY; OCTTOBIN; OCTTOHEX;
OCTTONUM; OFFCAP; OFFTRAF; OPT_2_ASSET_CORRELATION; OPT_AMER_EXCHANGE;
OPT_BAW_AMER; OPT_BINOMIAL; OPT_BJER_STENS; OPT_BS; OPT_BS_CARRYCOST;
OPT_BS_DELTA; OPT_BS_GAMMA; OPT_BS_RHO; OPT_BS_THETA; OPT_BS_VEGA;
OPT_COMPLEX_CHOOSER; OPT_EURO_EXCHANGE; OPT_EXEC;
OPT_EXTENDIBLE_WRITER; OPT_FIXED_STRK_LKBK; OPT_FLOAT_STRK_LKBK;
OPT_FORWARD_START; OPT_FRENCH; OPT_GARMAN_KOHLHAGEN; OPT_JUMP_DIFF;
OPT_MILTERSEN_SCHWARTZ; OPT_ON_OPTIONS; OPT_RGW; OPT_SIMPLE_CHOOSER;
OPT_SPREAD_APPROX; OPT_TIME_SWITCH; ORB; ORH; PAGEINDEX; PAGEINDEX2;
PAGENAME; PAGENAME2; PAGENAMES; PAGENAMES2; PARETO; PAYMT; PBDAY; PFACTOR;
FPIRATE; PMT2; PMTC; PMTI; POLA; POLR; POW; PPAYMT; PRANK; PRICE2; PROBBLOCK;
PROPERTY; PUREAVG; PURECOUNT; PUREMAX; PUREMEDIAN; PUREMIN; PURESTD;
PURESTDS; PUREVAR; PUREVARS; PV2; PVAL; PVAMOUNT; PV_ANNUITY; R.DBETA;
R.DBINOM; R.DCAUCHY; R.DCHISQ; R.DEXP; R.DF; R.DGAMMA; R.DGEOM; R.DHYPER;
R.DLNORM; R.DNBINOM; R.DNORM; R.DPOIS; R.DT; R.DWEIBULL; R.PBETA; R.PBINOM;
R.PCAUCHY; R.PCHISQ; R.PEXP; R.PF; R.PGAMMA; R.PGEOM; R.PHYPER; R.PLNORM;
R.PNBINOM; R.PNORM; R.PPOIS; R.PT; R.PWEIBULL; R.QBETA; R.QBINOM; R.QCAUCHY;
R.QCHISQ; R.QEXP; R.QF; R.QGAMMA; R.QGEOM; R.QHYPER; R.QLNORM; R.QNBINOM;
R.QNORM; R.QPOIS; R.QT; R.QWEIBULL; RADIANS; RADIX; RADTODEG; RANDBERNOULLI;
RANDBETA; RANDBINOM; RANDCAUCHY; RANDCHISQ; RANDDISCRETE; RANDEXP;
RANDEXPPOW; RANDFDIST; RANDGAMMA; RANDGEOM; RANDGUMBEL; RANDHYPERG;
RANDLANDAU; RANDLAPLACE; RANDLEVY; RANDLOG; RANDLOGISTIC; RANDLOGNORM;
RANDNEGBINOM; RANDNORM; RANDNORMTAIL; RANDPARETO; RANDPOISSON;
RANDRAYLEIGH; RANDRAYLEIGHTAIL; RANDTDIST; RANDUNIFORM; RANDWEIBULL;
RANGENAME; RAYLEIGH; RAYLEIGHTAIL; REFCONVERT; REGEXP; REGEXPRE;
REGRESSION; REPEAT; ROOTN; ROT; ROUNDDOWNXL; ROUNDM; ROUNDUPXL;
SCENARIOINFO; SCENARIOLAST; SCMARG; SEC; SECH; SECONDS; SEMEAN; SETSTRING;
SEXDEC; SHLB; SHLBO; SHLH; SHLHO; SHRB; SHRBO; SHRH; SHRHO; SIMTABLE;
SKEWNESS; SLEEK; SMALLEST; SOY; SPI; SPLINE; SSMEDIAN; STD; STDS; STEC; STKOPT;
STRCMPNORM; STREQ; STRING; STYLE; SUBB; SUBBO; SUBH; SUBHO; SUBTOTAL123;
SUBTOTAL2; SUBTOTALX; SUM2XMY; SUMA; SUMNEGATIVE; SUMPOSITIVE; SUMXPY2;
SUMXY; SUMXY2; SUUJI; TABLELINK; TDATESTRING; TDIGIT; TDOW; TERM; TERM2; TFIND;
TLDATESTRING; TLEFT; TLENGTH; TMID; TNUMBERSTRING; TOGGLE; TOTAL; TREPLACE;
100414201 29 May 2010
TRIGHT; UNIX2DATE; USESPLINE; V; VARIANCE; VARS; VERSION; VERSIONCURRENT;
VERSIONDATA; VERSIONINFO; VHLOOKUP; WEEKNUM_ADD; WEEKS; WEEKSINYEAR;
WEIGHTAVG; WKDAY; XCOUNT; XINDEX; XORB; XORH; YDAYS; YDIV; YEARS; YIELD2;
YIELDPER; YLD2YLD; ZERO_COUPON
The list above is only a place to start, so that we do not forget any. Also, need to examine the new
CUBE functions of MS Excel.
Note: The following functions are documented by this specification, but not included even in the
Large group:CELL ; DOLLAR
Rationale: DOLLAR and its alias USDOLLAR are widely implemented, but inherently unportable;
their function changes when exchanging spreadsheets between users using different locales. CELL
provides system/platform/implementation-dependent functionality.
The set of functions here could be determined through analysis, but we think users will find it helpful
to have a specific list of functions that are not included when they ask for Large group
implementation. We also found it useful for double-checking to make sure that every function that
was supposed to be assigned to a group was, in fact, assigned to a group.
2.3 Variances (Implementation-defined, Unspecified, and
Behavioral Changes)
Applications should document all implementation-defined and variances from this standard in a
manner that the application users can obtain the information (e.g., in the application help for the
relevant function).
In a few cases a specific approach is required (e.g., string indexes begin at one), which may be
different than the user interface of some implementations.
Note: Historically, spreadsheets have been influenced by three market leaders: VisiCorp's VisiCalc,
Lotus 1-2-3, and Microsoft Excel. Excel's default semantics have some minor "semantic" differences
with Lotus 1-2-3, and different implementations tend to follow one or the other approaches.
In practice, for nearly all documents the differences are irrelevant. The primary variances and
differences from OpenFormula and some existing applications are:
Some conversions between types are not required to be automatic. In particular, applications
may, but need not,, perform automatic conversion of text in a cell when it is to be used as a
number (see Auto Text to Number).
Note: Interoperability is improved by the use of the DATE and TIME functions or the textual ISO
8601 date representation because dates in that format do not rely upon epoch or locale-specific
settings.
There need not be a distinguishable Logical type. Applications may have a Logical type distinct
from Number (see Distinct Logical), but Logical values may also be represented by the Number
type using the values 1 (True) and 0 (False). This means that functions that take number
sequences (such as SUM) may or may not include true and false values in the sequence.
Applications vary on the set of Errors they support. In this specification. The only distinguished
Error is #N/A; all other errors are simply errors, allowing applications to choose the Error set that
best meets their needs.
In this specification, string index positions start from 1. Users of applications with string index
positions starting from 0 shall add and subtract 1 on import/export of this format, as appropriate.
Database criteria match patterns (such as the pattern matching language for text) have
historically varied: Some support glob syntax (e.g., a*b is a, followed by 0 or more characters,
100414201 29 May 2010
followed by b), while others support traditional regular expression syntax (e.g., a*b is zero or
more as, followed by b). This specification supports both pattern languages.
In an OpenDocument file, calculation settings impact formula recalculation, which can be the same
or different from a particular application's defaults. These include whether or not text comparisons
are case-sensitive, or if search criteria shall apply to the whole cell.
Note: Microsoft Excel and GNOME Gnumeric consider Logical values to be a distinct Logical type,
e.g., ISNUMBER(TRUE()) is false, and so on. Many other applications, including OpenOffice.org,
Lotus 1-2-3v9.8, and Quattro Pro consider Logical to simply be a number (1 for TRUE(), 0 for
FALSE(). This means that SUM over a range can produce different answers for different
applications if true/false values are included. ROMAN() on Excel works oddly if given
TRUE()/FALSE() values for its second parameter (it does not interpret TRUE() as 1, and FALSE() as
0); see that function's specification.
Automatic converting Text to Number shows quite a variance. First, assume that B3 has the Text
value 7, and B4 has the Number 2:
Excel: Convert to Number auto-converts an inline string or reference to text into Number;
NumberSequence skips non-Number. So 7+2 is 9, B3+B4 is 9, SUM(B3:B4) is 2.
OpenOffice.org 2.0.2: Convert to Number auto-converts inline strings to Number, but
references to non-Numbers are considered 0. So 7+2 is 9, B3+B4 is 2, SUM(B3:B4) is 2.
Lotus 1-2-3 and others: Convert to Number always considers inline strings and references to
non-Number as 0. So 7+2 is 2, B3+B4 is 2, SUM(B3:B4) is 2.
OpenOffice.org 2.0.2 supports array functions, but does not support inline constant arrays or range
concatenation. OpenOffice.org 2.4 does support inline constant arrays.
Excel 2003 supports inline arrays, but only for constants (you can't have calculations in them).
100414201 29 May 2010
3 Formula Processing Model
3.1 General
This section describes the basic formula processing model: how expressions are calculated, when
recalculation occurs, and limits on formulas.
3.2 Expression Calculation
Conceptually, formulas are recalculated from the outside in. Any formula is an expression that
produces a result. An expression is calculated as follows:
1. If an expression is a constant number or string, that constant is returned
2. If it is a reference, the reference is returned. If a reference is to be displayed, the value of
the reference is displayed, not the reference itself.
3. Otherwise, it is one or more operations or functions; in the case of operations, the highest-
precedence operation not processed is processed first.
a) The values of all argument expressions are computed, that is, formulas are normally
eagerly evaluated. Exceptions to eager evaluation are noted in the function or
operation's specification; in particular, the IF() function does not calculate the else
parameter if the the condition is true, and does not calculate the then parameter if the
condition is false. The CHOOSE() function does not calculate parameters other than
the chosen. Function parameters shall act as if they had been computed in left-to-right
order. Operators should act as if they had been computed in the order of precedence
and associativity (so they are computed left-to-right for +, *, and so on, but right-to-left
for the exponentiation operator ^).
b) If any of the arguments of the function/operation are not of the correct type, the
appropriate implicit conversion function is called to convert it to the correct type for the
operator or function.
c) The operation or function is then called with the resulting values of its arguments.
The above model only describes how recalculation appears to the end-user. Applications may, and
typically do, optimize this process as long as the final results produce the same answer. For
example, applications may parse a formula and translate it into some intermediate form (such as a
byte code), which immediately descends to the innermost computation that needs to be calculated
and then works out to the final result.
When a formula is computed, it is notionally provided a "context" as input. The context may include
formula variables (including named ranges, document variables, fields, and so on), and/or additional
function definitions that the formula can call. A formula may also be provided as input an ordered list
of zero or more parameters (though the syntax for parameters is not given in this version of the
specification). In an OpenDocument formula, this context also includes calculation settings (such as
whether or not text comparisons are case-sensitive).
A formula may include calls to functions, which are normally provided the same context but with
their own set of ordered parameters.
Any formula computes a single result, though that single result may actually be a set of values.
100414201 29 May 2010
3.3 Non-Scalar Evaluation (aka 'Array expressions')
Non-scalar values passed as arguments to functions are evaluated by intersection or iteration.
1) Evaluation as an implicit intersection of the argument with the expression's evaluation
position.
1.1) Inline Arrays
Element (0;0) of the array is used in place of the array.
Note:
=ABS({-3;-4}) => ABS(-3) // row vector
=ABS({-3|-4}) => ABS(-3) // column vector
=ABS({-3;-4|-6;-8}) => ABS(-3) // matrix
={1;2;3|4;5;6} => 1 // simple display
1.2) References
1.2.1) If the target reference is a row-vector (Nx1) use the value at the intersection of
the evaluation position's column and the reference's row.
Note:
in cell B2 : =ABS(A1:C1) => ABS(B1)
If there is no intersection the result is #VALUE!
Note: in cell D4 : =ABS(A1:C1) => #VALUE!
1.2.2) If the target reference is a column-vector (1xM) the value at the intersection of
the evaluation position's row and the reference's column.
Note:
in cell B2 : =ABS(A1:A3) => ABS(A2)
in cell D4 : =ABS(A1:A3) => #VALUE!
Note: Matrices always return #VALUE!
Note: a valid extension would be to support 2d intersection for 3d references. e.g. the intersection of
Sheet2.A1:B2, from Sheet1.A1 is Sheet2.A1, but currently only OOoCalc implements it.
2) Matrix evaluation.
If an expression is being evaluated in a cell flagged as a being part of a 'Matrix'
(OpenDocument 8.1.3 table:number-matrix-columns-spanned):
2.1) The portion of a non-scalar result to be displayed may not be co-extensive with a
specified display area. The portion of the non-scalar result to be displayed is
determined by:
2.1.1) If the position to be displayed exists in the result, display that position.
2.1.2) If the non-scalar result is 1 column wide, subsequent columns in the display area
display the value in the first column. This applies to
- scalars '3'
- singletons '{3}'
- column vectors '{1|2|3}'
2.1.3) If the non-scalar result is 1 row high, subsequent rows in the display area use
the value of the first row.This applies to
- scalars '3'
- singletons '{3}'
- row vectors '{1;2;3}'
100414201 29 May 2010
2.1.4) If none of the other rules apply #N/A
Note:
in matrix A1:B3 with ={1;2|3;4|5;6} : cell B2 contains 4. [Rule 2.1.1]
in matrix A1:B3 with ={1|3|5} : cell B2 contains 3. [Rule 2.1.1 for
row, and Rule 2.1.2 column]
in matrix A1:B3 with ={2;4} : cell B2 contains 4. [Rule 2.1.3 for
row, and Rule 2.1.1 column]
in matrix A1:C4 with ={1;2|3;4|5;6} : cell C1,A4 contain #N/A. [Rule 2.1.4]
NOTE : if a value is not requested it is not displayed
in matrix A1:B2 with ={1;2|3;4|5;6} : the value '6' is not displayed because B3
is not part of the display matrix.
2.2) Calculations with non-scalar inputs are a generalization of (2.1).
When evaluating a formula in 'matrix' mode, and a non-scalar value is passed to a
function argument that expects a scalar, the function is evaluated multiple times,
iterating over the non-scalar input(s) and putting the function result into a matrix at the
position corresponding to the input. Unary/Binary operators, other than range and
union, follow the rules for scalar functions when passed non-scalar values.
Inline arrays and references are interchangeable.
2.2.1) Functions returning arrays are not eligible for implicit iteration. When evaluated in
'matrix' mode the {0;0}th element is used.
Note:
e.g. =SUM(INDIRECT({"A1";"A2")) would produce the value in A1 when evaluated
in array mode.
Note: This is a preliminary observation of how Excel does it, but must not always be necessarily
true. If in Excel that formula is entered as a 2 rows array formula the content of A1 in the first row
and the content of A2 in the second row is displayed. How does that fit with "the {0;0}th element is
used"? It seems more an iteration over the single elements, returning them. Which is different to
what Calc does, it sums the elements for each output cell, resulting in A1+A2 for a similar example
not using inline arrays, {=SUM(INDIRECT(A5:A6))} with A1 in A5 and A2 in A6.
2.2.2) The result matrix is rectangular, sized with the maximum number of rows and
columns from all non-scalar arguments.
Note:
={1;2}+{3;4;5} => {4;6;#N/A}
={1}+{1;2} => {2;3}
2.2.3) The result matrix is populated by extracting the corresponding value from each of
the non-scalar arguments based on the following rules, and evaluating the function
with that set of arguments.
2.2.3.1) If the argument data is a singleton array or a scalar the value is repeated
for each evaluation.
Note:
= 1 + {1;2;3|4;5;6} => {2;3;4|5;6;7}
= {1} + {1;2;3|4;5;6} => {2;3;4|5;6;7}
2.2.3.2) If the argument data is 1 column wide the value in the corresponding row
is used to evaluate all columns in the result matrix.
100414201 29 May 2010
Note:
= {1|2} + {10;20|30;40} => {11;21|32;42}
2.2.3.3) If the argument data is 1 row height the value in the corresponding column
is used to evaluate all rows in the result matrix.
Note:
= {1;2} + {10;20|30;40} => {11;22|31;42}
2.2.3.4) If one argument data is 1 column wide and another argument data is 1 row
height the value of the corresponding row respectively column is used to
evaluate all elements in the result matrix.
Note:
={1;2} + {10|20} => {11;12|21;22}
2.2.3.5) If an argument is a 2d matrix the argument value in the position
corresponding to the current output position is used if it is within range of the
supplied argument, otherwise #N/A is used in the calculation.
Note:
=MID("abcd";{1;2};{1;2;3}) => {"a";"bc";#VALUE!}
3.4 Host-Defined Behaviors
A Formula Evaluator operates in an execution environment (a "host"). The behavior of the Formula
Evaluator is parametrized by host-defined properties and functions.
The following properties are host-defined:
1) HOST-CASE-SENSITIVE: if true, text comparisons are case-sensitive. This influences the
operators =, <>, <, <=, >, and >=, as well as database query functions that use them. Note that
the EXACT function is always case-sensitive, regardless of this calculation setting.
2) HOST-PRECISION-AS-SHOWN: If true, calculations are performed using rounded values of
those displayed; otherwise, calculations are performed using the precision of the underlying
numeric representation. Note: This does not impose a particular numeric model. Since
implementations may use binary representations, this rounding may be inexact for decimal
value.
3) HOST-SEARCH-CRITERIA-MUST-APPLY-TO-WHOLE-CELL If true, the specified search criteria
shall apply to the entire cell contents if it is a text match using = or <>; if not, only the initial text
needs to match.
4) HOST-AUTOMATIC-FIND-LABELS: if true, row and column labels are automatically found.
5) HOST-USE-REGULAR-EXPRESSIONS: If true, regular expressions are used for character string
comparisons and when searching.
6) HOST-USE-WILDCARDS: If true, wildcards question mark '?' and asterisk '*' are used for
character string comparisons and when searching. Wildcards may be escaped with a tilde '~'
character.
7) HOST-NULL-YEAR: This defines how to convert a two-digit year into a four-digit year. All two-
digit year values are interpreted as a year that equals or follows this year.
8) HOST-NULL-DATE: Defines the beginning of the epoch; a numeric date of 0 equals this date.
9) HOST-LOCALE: The locale to be used for locale-dependent operations, such as conversion of
text to dates, or text to numbers.
100414201 29 May 2010
The function HOST-REFERENCE-RESOLVER(Reference) is implementation defined. This function
takes as input a Unicode string containing a Reference according to section 4.8 and returns a
resolved value.
Note: Excel 2003 semantics are case-sensitive=false and search-criteria-must-apply-to-whole-
cell=false.
3.5 When recalculation occurs
Implementations of OpenFormula typically recalculate formulas when its information is needed.
Typical implementations will note what values a formula depends on, and when those dependent
values are changed and the formula's results are displayed, it will re-execute the formulas that
depend on them to produce the new results (choosing the formulas in the right order based on their
dependencies). Implementations may recalculate when a value changes (this is termed automatic
recalculation) or on user command (this is termed manual recalculation).
Some functions' dependencies are difficult to determine and/or should be recalculated more
frequently. These include functions that return today's date or time, random number generator
functions (such as RAND), or ones that indirectly determine the cells to act on. Many
implementations always recalculate formulas including such functions whenever a recalculation
occurs. Functions that are always recalculated whenever a recalculation occurs are termed volatile
functions. Functions that are often volatile functions include CELL, HYPERLINK, INDIRECT, INFO,
NOW, OFFSET, RAND and TODAY. Functions that depend on the cell position of the formula they
are contained in or the position of a cell they reference need to be recalculated whenever that cell is
moved, such functions are COLUMN, ROW and SHEET. In addition, formulas may indicate that
they should always be recalculated during a recalculation process by including a forced
recalculation marker, as described in the syntax below.
Note: For more on volatile functions, see Walkenbach's "Microsoft Excel 2003 Formulas" page 109,
or the equivalent section in "Microsoft Excel 2000 Formulas", page 108.
3.6 Numerical Models
This specification does not, by itself, specify a numerical implementation model, though it does
imply some minimal levels of accuracy for most functions. For example, an application cannot say
that it implements the infix operator / as specified in this document if it implements integer-only
arithmetic.
In practice, applications tend to use at least one IEEE 754-1985 binary floating-point representation,
using at least the 64-bit representation and possibly larger widths for intermediate results. When
IEEE 754 representations are used, results such as Inf (infinity) and Nan (not a number) are
considered an Error value. Applications may use IEEE 854-1987 (which covers decimal arithmetic).
In general, applications are encouraged to use appropriate standards for their numerical models.
This means that applications will often not produce exact results, but only approximate results for
a large number of places.
Note: There is a vast amount of information on numerical models and standards for them. However,
not all CPUs/FPUs fully implement all the standards (the formats in particular are widespread, but
do not always precisely implement their numerical processing model). IEEE 754-1985 specifies
these floating-point formats: single-precision (32-bit), double-precision (64-bit), the normally not
used single-extended precision (>= 43-bit), and double-extended precision ( 79-bit, usually
implemented with 80 bits). Only 32-bit values are required by the standard; the rest are optional. C
compilers usually map float to single-precision and double to double-precision. Single-precision
(32-bit) has a sign bit, 8 bits of exponent, and 23 bits of mantissa; double-precision (64-bit) has a
sign bit, 11 bits of exponent,and 52 bits of mantissa. More information about IEEE 754 and the
current revision effort is at http://www.cs.berkeley.edu/~ejr/Projects/ieee754/ and
http://en.wikipedia.org/wiki/IEEE_754; the paper How Futile are Mindless Assessments of Roundoff
in Floating-Point Computation? (http://www.cs.berkeley.edu/~wkahan/Mindless.pdf) discusses some
100414201 29 May 2010
of the challenges facing spreadsheet applications, which generally use the underlying (binary)
number system such as IEEE-754 yet try to make it appear to users that a decimal implementation
is being used.
3.7 Basic Limits
Evaluators which claim to support basic limits shall support at least the following limits:
1. formulas up to at least 1024 characters long, as measured when in OpenDocument
interchange format not counting the square brackets around cell addresses, or the . in a
cell address when the sheet name is omitted.
2. at least 30 parameters per function when the function prototype permits a list of parameters.
3. permit strings of ASCII characters of up to 32,767 (2^15-1) characters.
4. support at least 7 nesting levels of functions.
Rationale: Excel 2003 supports 1,024 characters per formula, per Walkenbach "Excel 2003
Formulas" page 33, using its own UI representation. The measurement given above is carefully
devised to mean the same thing in this case, since the representation is similar but not identical.
The result is a reasonable measure of formulas that can be widely ported due to length. Most
implementations are not this limited in size, anyway. Excel 2003 supports up to 30 parameters,
according to OpenOffice.org's documentation on the .xls file format. Note that while string
processing is not required to support international characters for basic, even basic must support
international characters in variable names. The reason is simple: Many spreadsheet documents do
not process strings at all, so having poor support for string-handling is actually sufficient for a large
number of real-world use cases. They would need to support international characters in labels, but
labels are outside the scope of this specification. However, named expressions (variables) are
widely used in spreadsheets, and it would be unacceptable if the names were limited to only ASCII
characters.
Test Cases:
Expression Result Comment
=SUM([.B4];[.B5];[.B4];[.B5];[.B4];[.B5]; [.B4];[.B5];[.B4];[.B5];[.B4];
[.B5]; [.B4];[.B5];[.B4];[.B5];[.B4];[.B5]; [.B4];[.B5];[.B4];[.B5];[.B4];
[.B5]; [.B4];[.B5];[.B4];[.B5];[.B4];[.B5])
75
Functions shall be
able to take 30
parameters.
=[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+
[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+
[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+
[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+
[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+
[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+
[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+
[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+
[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+
[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+
[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+
[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+
[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+
[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+
[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+
[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+
[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+
[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+
1961 Formulas can be
up to 1024
characters long,
not counting the
[..] around cell
addresses, and
not counting the .
in a cell address
where the sheet
name is not given.
100414201 29 May 2010
[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+
[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+
[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+
[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+
[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+
[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+
[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+
[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+
[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+
[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+
[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+
[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+
[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+[.B5]+[.B4]+
[.B5]+1111
=LEN(REPT("x";2^15-1)) 32767
Strings of ASCII
characters can be
up to 32767
characters
(applications
should support
even larger text
lengths)
=SIN(SIN(SIN(SIN(SIN(SIN(SIN(0))))))) 0
Support at least 7
levels of nesting
functions.
Useful information about spreadsheets that was used to develop this specification included the
following:
OpenOffice.org's Documentation of the Microsoft Excel File Format. http://sc.openoffice.org.
(This location has much other useful information).
Excel 2000 in a Nutshell: A Power User's Quick Reference. Jinjer Simon. August 2000. O'Reilly.
Ximian has a nice LXR setup that lets you easily surf the OpenOffice.org spreadsheet source
code at http://ooo.ximian.com/lxr/source/sc/. Of particular interest is the Calc compiler.cxx file,
see: http://ooo.ximian.com/lxr/source/sc/sc/source/core/tool/compiler.cxx.
http://www.ccil.org/~cowan/OF provides the OpenOffice.org help documents for its functions in
various formats. It is LGPL-licensed, because embedded in the OpenOffice.org implementation
and the OpenOffice.org license states that "OpenOffice.org uses a single open-source license
for the source code and a separate documentation license for most documents published on the
website without the intention of being included in the product."
http://www.gnome.org/projects/gnumeric/functions.shtml describes the Gnumeric functions. This
text is believed to be licensed under the GPL.
Many special tests of various spreadsheet implementations are at:
http://www.dwheeler.com/openformula.
http://www.mcs.vuw.ac.nz/~db/FishBrainWiki?Excel provides information on Microsoft Excel's
display syntax
http://rubyforge.org/projects/lxl LXL (Like Excel) is a mini-language that mimics Microsoft Excel
formulas; written in Ruby
Dan Bricklin (creator of VisiCalc, the original spreadsheet) is developing WikiCalc. This is an
open source software web application that's a Wiki with spreadsheet capabilities added; it can
100414201 29 May 2010
locally or over a network. More info at: http://blogs.zdnet.com/BTL/?
p=2141&part=rss&tag=feed&subj=zdblog
Note: Excel 2003 is limited to 32,767 (2^15-1) ASCII characters per string. OpenOffice.org is limited
to 65,535 (2^16-1) ASCII characters per string. For non-ASCII characters it is more complex to state
limits; typical implementations use UTF-8, UTF-16, or UTF-32, so their limits would vary, and an
implementation could even store text in a particular encoding along with an encoding marker. As a
result, it's difficult to specify a limit for non-ASCII text lengths that makes sense. But with a large
limit on ASCII text lengths, long lengths for non-ASCII text will tend to follow.
100414201 29 May 2010
4 Types
4.1 General
All values defined by OpenFormula have a type. OpenFormula defines Text, Number, Complex
Number, Logical, Error, Reference, ReferenceList and Array types.
4.2 Text (String)
A Text value (also called a string value) is a sequence of zero or more characters.
Evaluators should accept [UNICODE] strings, but shall accept strings of ASCII (Unicode U+0020
through U+007F, inclusive) characters.
A text value of length zero is termed the empty string.
Index positions in a text value begin at 1.
Note: Excel, Gnumeric, SheetToGo, OpenOffice.org, and KSpread all use 1-based positioning.
Lotus1-2-3v9.8 and Quattro Pro 12 use 0-based positioning. It is impractical to stay silent on
whether 0 or 1 is the first position -- too many functions (such as FIND) depend on this. So, the
more common usage is chosen here. Lotus1-2-3 and Quattro Pro both have translation
mechanisms that account for this difference already; it is considered a user interface issue.
Note: We discuss type Text first, because complex numbers can be Text, Number, or their own
different type at level 3.
4.3 Number
4.3.1 General
A number is a numeric value.
Numbers shall be able to represent fractional values (they shall not be limited to only integers).
Evaluators may implement Number with an arbitrary fixed or with a variable bit length. A cell with a
constant numeric value has the Number type.
Note: Many evaluators implement numbers as 64-bit IEEE floating point values and use the CPU's
floating-point instructions where available (so intermediate values may be represented using more
than 64 bits).
Rationale: Originally some efforts were expended to try to make formulas produce the "expected
answer" for unsophisticated users. In particular, the equal-to operator for numbers matches
imprecisely in many applications, because many users do not understand that (1/3)*3 on most
implementations will produce a value close to one but not precisely equal to one. Originally there
was a test to ensure that (1/3)*3 was equal to 1. The Gnumeric developers objected, on the grounds
that requiring that equality be "sloppy" made it very difficult for sophisticated users to use
spreadsheets to their full capabilities. In contrast, the function INT still requires that INT((1/3)*3) is 1,
because if INT does not do so, many user's spreadsheets will not work as they expect. The
expected answers of INT may not make numerical analysts happy, but users will get what appears
(to them) to be wrong answers otherwise.
100414201 29 May 2010
Implementations typically support many subtypes of Number, including Date, Time, DateTime,
Percentage, fixed-point arithmetic, and arithmetic supporting arbitrarily long integers, and determine
the display format from this. All such Number subtypes shall yield True for the ISNUMBER function.
This specification does not require that specific subtypes be distinguishable from each other, or that
the subtype be tracked, but in practice most implementations do such tracking because requiring
users to manually format every cell appropriately becomes tedious very quickly. Automatically
determining the most likely subtype is especially important for a good user interface when
generating OpenDocument format, since some subtypes (such as date, time, and currency) are
stored in a different manner depending on their subtype. Thus, this specification identifies some
common subtypes and identifies those subtypes where relevant in some function definitions, as an
aid to implementing good user interfaces. Many applications vary in the subtype produced when
combining subtypes (e.g., what is the result when percentages are multiplied together), so unless
otherwise noted these are unspecified. Typical implementations try to heuristically determine the
"right" format for a cell when a formula is first created, based on the operations in the formula. Users
can then override this format, so as a result the heuristics are not important for data exchange (and
thus outside the scope of this specification).
All Number subtypes shall yield True for the ISNUMBER function.
Note: This specification does not require that specific subtypes be distinguishable from each other,
or that the subtype be tracked, but in practice most evaluators do such tracking. Automatically
determining the most likely subtype is important for a good user interface and when generating
OpenDocument format, since some subtypes (such as date, time, and currency) are stored in a
different manner depending on their subtype. Typical implementations try to heuristically determine
the "right" format for a cell when a formula is first created, based on the operations in the formula.
Expression authors can then override this display format, so as a result the heuristics are not
important for data exchange (and thus outside the scope of this specification).
4.3.2 Time
Time is a subtype of Number.
Time is represented as a fraction of a day.
4.3.3 Date
Date is a subtype of Number.
Date is represented by an integer value.
A serial date is the expression of a date as the number of days elapsed from a start date called the
epoch.
Evaluators shall support all dates from 1904-01-01 through 9999-12-31 (inclusive) in calculations,
should support dates from 1899-12-30 through 9999-12-31 (inclusive) and may support a wider date
range.
Note: Using expressions that assume serial numbers are based on a particular epoch may cause
interoperability issues.
Evaluators shall support positive serial numbers. Evaluators may support negative serial numbers to
represent dates before an epoch.
Note: It is implementation-defined if the year 1900 is treated as a leap year.
Note: Evaluators that treat 1900 as a non-leap year can use the epoch date 1899-12-30 to
compensate for serial numbers that originate from evaluators that treat 1900 as a leap year and use
1899-12-31 as an epoch date.
100414201 29 May 2010
4.3.4 DateTime
DateTime is a subtype of Number. It is a Date plus Time.
Note: Excel for Windows usually uses 1/1/1900 as serial number 1, while Excel for Macintosh uses
1/1/1904 as serial number 1. "Excel 2000 in a Nutshell" page 330 discusses time storage in Excel,
including this, and noting December 31, 9999 as a date both support.
Excel 2003 copies a bug from an old version of Lotus 1-2-3; both act as though 1900 was a leap
year. Thus 1900-02-29 has the serial number 60, and all date calculations on or before that date are
wrong by one day. This specification does not require copying this bug. See "Excel 2003 Formulas"
page 143.
Excel 2003 is unable to deal with dates before January 1, 1900; again, there's no requirement that
other implementations have this limitation. Implementations that wish to support a broader range of
dates, yet also the same numbers for most dates, could do so by using negative numbers as dates
before the epoch (be careful, because a time inside the day adds to the beginning of the date).
In OpenDocument Format a Date, DateTime, or Time value in a cell is stored in a special locale-
independent format based on ISO 8601; see the OpenDocument specification for more information.
Implementations may choose to store dates in a special type that is distinguishable from other
numbers. However, from the point of view of a formula, a Date, DateTime, or Time value is simply a
subtype of Number, and must follow the rules of this specification. Most countries use the Gregorian
calendar and ISO 8601, but not all. Note that applications must be able to convert Text, in a variety
of formats, into Date and DateTime values.
Note: In earlier times dates were dependent on the location of the event, which is not necessarily
the current locale. In particular, different countries switched from Julian to Gregorian on different
dates. This creates a challenge if it is desired to represent dates in formulas significantly before
1900. One solution is to use the "proleptic Gregorian" calendar, which is simply the current
Gregorian calendar indefinitely extended in both directions of time. Python 2.4's date types use
proleptic Gregorian, and points to Dershowitz and Reingold's book "Calendrical Calculations" for
various means to convert that to other calendar systems. The advantage of proleptic Gregorian is
that it is locale-independent, works well with ISO 8601, and there are defined ways to convert
between it and other calendars. If the goal is just to store dates, and not compute differences, then it
can easily represent arbitrary dates without complexity in the basic spreadsheet implementation. If
conversions are needed, they can be embedded in spreadsheet formulas -- which is the right place
to put them, because the current locale is often not the locale of the event, and only the person
entering the data will know the correct locale.
4.3.5 Percentage
A percentage is a subtype of Number that may be displayed by multiplying the number by 100 and
adding the sign % or with other formatting depending upon the number format assigned to the cell
where it appears.
4.3.6 Currency
A currency is a subtype of Number that may appear with or without a currency symbol or with other
formatting depending upon the number format assigned to the cell where it appears.
4.3.7 Logical (Number)
A Logical value is a subtype of Number where TRUE() returns 1 and FALSE() returns 0.
The implicit conversion operator Convert to Logical 6.3.12, when a Number is passed as a
condition, 0 is considered False and all other numeric values are considered True.
100414201 29 May 2010
Note: Logical values can be a distinct type from Number. 4.5
4.4 Complex Number
A complex number (sometimes also called an imaginary number) is a pair of real numbers including
a real part and an imaginary part. In mathematics, complex numbers are often written as x + iy,
where x (the real part) and y (the imaginary part) are real numbers and i is
. 1
. A complex
number can also be written as re
i
= rcos() + irsin(), where r is the modulus of the complex
number (a real number) and is the argument or phase (a real number representing an angle in
radians).
A complex number may, but need not be, represented as a Number or Text. The results of the
functions ISNUMBER() and ISTEXT() are implementation-defined when applied to a complex
number.
Functions and operators that accept complex numbers shall accept Text values as complex
numbers (6.3.10 Conversion to Complex Number, as well as Numbers that are not complex
numbers.
Note: IMSUM("3i";4) will produce the same result as COMPLEX(4;3).
Note: Expression authors should be aware that use of functions that are not defined by
OpenFormula as accepting complex numbers as input may impair interoperability.
Equality can be tested using IMSUB to compute the difference, use IMABS to find the absolute
difference, and then ensure the absolute difference is smaller than or equal to some nonnegative
value (for exact equality, compare for equality with 0).
Note: Values are stored this way for maximum portability. Not all applications/readers can handle
complex numbers, but all can handle strings so they will still be displayed correctly if only reading
(and no recalculation) occurs. Naturally, when read back in by an application that implements
complex numbers, they are recalculated as complex numbers.
Test Cases:
=IMREAL(IMSUM(COMPLEX(2;3);
COMPLEX(4;5)))
6 Must use IMSUM to add at level 3.
=IMAGINARY(IMSUM(COMPLEX(2;3);
COMPLEX(4;5)))
8 Must use IMSUM to add at level 3.
=IMREAL(IMSUM(4;"3i";"2+i")) 6
Can use Text and ordinary Numbers with
IM functions.
=IMAGINARY(IMSUM(4;"3i";"2+i")) 4
Can use Text and ordinary Numbers with
IM functions.
=IMAGINARY(IMSUM(4;"3i";"2-i")) 2 2-i is legitimate
=IMAGINARY(IMSUM(4;"3i";"2-5i")) -2 2-5i is legitimate
Note: Handling complex numbers is itself complex. Excel can handle them, but only when the
Analysis Toolpak is installed (by going to Tools/Add-ins). Gnumeric can always handle them. OOo2
can but only when an optional package is installed.. One serious problem with complex numbers is
that the typical implementation approach for Complex numbers, (used by Excel, Gnumeric, Ooo2,
and others) is incredibly convoluted. Instead of creating a new type (Complex) as a subtype of
Number, and allowing functions to handle the new type, many implementations treat Complex
100414201 29 May 2010
Numbers as a Text value (ISTEXT is true, ISNUMBER is false). Many view this as a major design
flaw. Because of this, users who attempt to use complex numbers have to use a whole new set of
functions, even for operators that are normally expressed with infix notation. Thus, to compute
e^(PI*i), instead of saying EXP(PI()*i), you have to say IMEXP(IMPRODUCT(PI();COMPLEX(0;1))).
Even addition and subtraction cannot use the infix notation, you must instead use IMSUM() and
IMSUB(). Not all functions have an IMxyz() equivalent in all implementations (e.g., there's no IMTAN
in Excel), making complex number use even more complicated. In some cases having a different
function makes sense anyway because their legal domains are different (e.g., SQRT should report
an Error on a negative number, and IMSQRT should not), but in most cases functions should
seamlessly handle complex numbers.
The solution adopted here is to specify a set of capabilities that does work on existing spreadsheets
that support complex numbers (such as Excel, Gnumeric, and OpenOffice.org), but not to require
that complex numbers be stored as Text, and not to require that operators like "+" and '*" fail to work
on them. Later in this document we define an option, in which implementing applications allow the
normal operators work correctly with complex numbers. This means that careful users can create
spreadsheets that port everywhere on today's spreadsheets, but that applications can gradually
improve their support so that traditional infix operators (like "+") work correctly. And from a
specification point of view, we avoid accidentally blocking us in and preventing future progress.
4.5 Logical (Boolean)
A Logical value (also called a Boolean value) is a value with one of two values: TRUE() and
FALSE().
Note: Logical values can be represented as a subtype of Number. 4.3.7
Rationale: This type is called "Logical" in this specification, not the usual Computer Science term
Boolean, because that's the usual term in spreadsheet implementations and it's consistent with the
function name ISLOGICAL(). Excel, Gnumeric, SheetToGo, and many other spreadsheet
implementations have distinct Number and Logical types. This means for example, that
ISNUMBER(TRUE()) is FALSE, and because Logical values are distinguished, a SUM() over a
range covering Boolean values skips the boolean values. However, Lotus 1-2-3 (Walkenbach 2004,
pg. 712) and OpenOffice.org 2, as well as the original VisiCalc, do not have a distinguished boolean
type, so SUMs over a range with boolean values will produce a different result. It is claimed in
Python PEP 285 , "Most languages eventually grow a Boolean type". E.G., C added one as part of
C99, Python added one in version 2.3. But the semantics of the type vary; some, like C, consider
them synonyms of 1 and 0.
Note: If a computed value computes 5, but is given a boolean format, this means that when it is
saved to OpenDocument, its office:boolean-value will be normalized to either true or false.
That's because when saving values, OpenDocument applications use the display type to determine
the value to store in them. When sending to recalculating applications this is irrelevant, since the
recalculated value will be recalculated into 5. When sending to applications that do not recalculate,
formulas are essentially read-only... in which case, the having the stored value as true or false is
correct because that really is what the document creator had displayed.
4.6 Error
An Error is one of a set of possible error values. Implementations may have many different error
values, but one error value in particular is distinct: #N/A, the result of the NA() function. Users may
choose to enter some data values as #N/A, so that this error value propagates to any other formula
that uses it, and may test for this using the function ISNA().
100414201 29 May 2010
Functions and operators that receive one or more error values as an input shall produce one of
those input error values as their result, except when the formula or operator is specifically defined to
do otherwise.
In an OpenDocument document, if an error value is the result of a cell computation it shall be stored
as if it was a string. That is, the office:value-type of an error value is string; if the computed
value is stored, it is stored in the attribute office:string-value.
Note: This does not change an Error into a string type (since the Error will be restored on
recalculation); this enables applications which cannot recalculate values to display the error
information.
Note: This treats errors as strings, instead of as their own special type, when stored. Storing as
strings is sufficient, since this is solely for the purpose of displaying results by applications that don't
implement spreadsheets. A recalculation will restore the error to a full and more detailed Error type.
Note: We keep maximum flexibility by simply asserting that there are Error values without saying
what they are other than NA. In practice, users generally don't care which errors are which (other
than an NA) in most cases, and implementations do different things in different cases.
Note: Excel 2003 has the following Error values (with ERROR.TYPE values), according to
Walkenbach 2003, page 49 and Simon's "Excel 2000 in a Nutshell" page 527:
#DIV/0! (2) - Attempt to divide by zero, including division by an empty cell.
#NAME? (5) - Unrecognized/deleted name.
#N/A (7) - NA. Lookup functions which failed and NA() return this value.
#NULL! (1) - Intersection of ranges produced zero cells.
#NUM! (6) - Failed to meet domain constraints (e.g., input was too large or too small)
#REF! (4) - Reference to invalid cell.
#VALUE! (3) - Parameter is wrong type.
4.7 Empty Cell
An empty cell is neither zero nor the empty string, and an empty cell can be distinguished from cells
containing values (including zero and the empty string). An empty cell is not the same as an Error,
in particular, it is distinguishable from the Error #N/A (not available).
4.8 Reference
A cell strip consists of cell positions in the same row and in one or more contiguous columns.
A cell rectangle consists of cell positions in the same cell strips of one or more contiguous rows.
A cell cuboid consists of cell positions in the same cell rectangles of one or more contiguous sheets.
A reference is the smallest cuboid that (1) contains specifically-identified cell positions and/or
specifically-identified complete columns/rows such that (2) removal of any cell positions either
violates condition (1) or does not leave a cuboid.
Cell positions in a cell cuboid/rectangle/strip can resolve to empty cells (section 3.7).
The definitions of specific operations and functions that allow references as operands and
parameters stipulate any particular limitations there are on forms of references and how empty cells,
when permitted, are interpreted.
100414201 29 May 2010
Note: References can point to one or more empty cells. Empty cells are not the same as a zero-
length Text value, because COUNTA makes a distinction. In a Number scalar context, empty cells
are converted to 0; in a Text scalar context, they are converted to an empty text (string) value.
4.9 ReferenceList
A reference list contains 1 or more references, in order. A reference list can be passed as an
argument to functions where passing one reference results in an identical computation as an
arbitrary sequence of single references occupying the identical cell range.
Note: For example, SUM([.A1:.B2]) is identical to SUM([.A1]~[.B2]~[.A2]~[.B1]), but
COLUMNS([.A1:.B2]), resulting in 2 columns, is not identical to COLUMNS([.A1]~[.B2]~[.A2]~[.B1]),
where iterating over the reference list would result in 4 columns.
A reference list cannot be converted to an array.
Note: For example, in array context {ABS([.A1]~[.B2]~[.A2]~[.B1])} is an invalid expression, whereas
{ABS([.A1:.B2])} is not.
Passing a reference list where a function does not expect one shall generate an Error. Passing a
reference list in array iteration context to a function expecting a scalar value shall generate an Error.
4.10 Array
An array is a set of rows each with the same number of columns that contain one or more values.
There is a maximum of one value per intersection of row and column. The intersection of a row and
column may contain no value.
4.11 Pseudotypes
4.11.1 General
Many functions require a type or a set of types with special properties, and/or process them
specially. For example, a "Database" requires headers that are the field names. These specialized
types are called pseudotypes.
4.11.2 Scalar
A Scalar value is a value that has a single value. A reference to more than one cell is not a scalar
(by itself), and shall be converted to one as described below. An array with more than one element
is not a scalar. The types Number (including a complex number), Logical, and Text are scalars.
4.11.3 DateParam
A DateParam is a value that is either a Number (interpreted as a serial number; 4.3.3) or Text; text is
automatically converted to a date value. 6.3.15
4.11.4 TimeParam
A TimeParam is a value that is either a Number (interpreted as a serial number; 4.3.2) or Text; text
is automatically converted to a time value (fraction of a day). 6.3.16
100414201 29 May 2010
4.11.5 Integer
An integer is a subtype of Number that has no fractional value. An integer X is equal to INT(X).
Division of one integer by another integer may produce a non-integer.
Note: Most implementations represent all numbers, including integers, using a floating-point
representation.
4.11.6 Basis
A basis is a subtype of Integer (and thus of Number) that indicates the calendar system conventions
to be used. If basis is omitted from a financial function, the default is basis 0.
Basis values are defined as follows (where x/y indicates x days per month and y days per year):
Basis 0 or omitted (30/360): Truncates date values and swaps them if date1 is after date2.
If the dates are equal, the difference of days is 0. Assumes that each month has 30 days
and the total number of days in the year is 360 by making the following adjustments:
If both day-of-months are 31, they are changed to 30
Otherwise, if date1s day-of-month is 31, it is changed to 30
Otherwise, if date1s day-of-month is 30 and date2s day-of-month is 31, date2s day-
of-month is changed to 30 (note that date2s day-of-month will stay 31 if date1s day <
30)
Otherwise, if both dates are the last day of February in their respective years, both day-
of-month is changed to 30
Otherwise, if date1 is the last day of February, its day-of-month is changed to 30
Then computes the difference as
(date2.year*360 + date2.month*30 + date2.day) - (date1.year*360 + date1.month*30 +
date1.day).
Basis 1 (Actual/actual): Truncates date values and swaps them if date1 is after date2. If
the dates are equal, the difference in days is 0. If date1 and date2 not less than or equal
to a year apart (as defined below), then the days in the years between the dates is the
average number of days in the years between date1 and date2, inclusive. Otherwise, the
days in the years between the dates is 365, except for these cases (where it is 366): the
dates are in the same year and it is a leap-year, a February 29 occurs between the two
dates, or date2 is February 29.
To determine if date1 and date2 are less than or equal to a year apart for purposes of this
algorithm, one of these conditions much be true:
The two dates have the same year
Date2s year is exactly one more than date1s year, and ((date1.month > date2.month)
or ((date1.month == date2.month) and (date1.day >= date2.day)))
Basis 2 (Actual/360): Truncates date values and swaps them if date1 is after date2. If the
dates are equal, the difference of days is 0. Computes the actual difference in days, and
presumes there are always 360 days per year.
Basis 3 (Actual/365): Truncates date values and swaps them if date1 is after date2. If the
dates are equal, the difference of days is 0. Computes the actual difference in days, and
presumes there are always 365 days per year.
100414201 29 May 2010
Basis 4 (30/360): Truncates date values and swaps them if date1 is after date2. If the
dates are equal, the difference of days is 0. Assumes that each month has 30 days and the
total number of days in the year is 360; any day-of-month (in date1, date2, or both) with a
value of 31 is changed to 30. February dates are never changed, because there is no
February 31.
Then computes the difference as
(date2.year*360 + date2.month*30 + date2.day) - (date1.year*360 + date1.month*30 +
date1.day).
Rationale: This defines how basis values are actually implemented in implementations such as
Except, based on extensive analysis. We have used how implementations actually define these
terms for the sake of interoperability; other definitions would have made it impossible to recalculate
many existing spreadsheets and get the same answer. We had originally intended for
OpenFormula to have the same interpretation of basis values as OOXML, but OOXMLs definitions
are incompatible with actual implementations. Since no one currently implements what OOXML
specifies, using OOXML would have eliminated interoperability with most existing spreadsheets that
use basis values. By defining the OOXML values with an increment of 32, should anyone actually
implement those basis values in the future, it will be easy to convert them to and from this format
(by adding/subtracting 32 during reading and writing). Basis 0 is sometimes called US or NASD,
and basis 4 is sometimes called European, but these names are misleading; there are a large
number of calendar conventions in both the US and Europe, and they are certainly not all covered
here. For more information, see http://www.dwheeler.com/yearfrac.
4.11.7 Criterion
A criterion is a single cell Reference, Number or Text. It is used in comparisons with cell contents.
A reference to an empty cell is interpreted as the numeric value 0.
A matching expression can be:
A Number or Logical value. A matching cell content equals the Number or Logical value.
A value beginning with a comparator (<, <=, =, >, >=, <>). 6.4.9
For =, if the value is empty it matches empty cells. 4.7
For <>, if the value is empty it matches non-empty cells.
For <>, if the value is not empty it matches any cell content except the value, including empty
cells.
Note: "=0" does not match empty cells.
For = and <>, if the value is not empty and can not be interpreted as a Number type or one of
its subtypes and the calculation setting search-criteria-must-apply-to-whole-cell is true,
comparison is against the entire cell contents, if false, comparison is against any subpart of the
field that matches the criteria. For = and <>, if the value is not empty and can not be interpreted
as a Number type or one of its subtypes 3.4 applies.
Other Text value. If calculation setting search-criteria-must-apply-to-whole-cell is true, the
comparison is against the entire cell contents, if false, comparison is against any subpart of the
field that matches the criteria.
100414201 29 May 2010
4.11.8 Database
A database is a rectangular organized set of data. Any database has a set of one or more fields
that determine the structure of the database. A database has a set of zero or more records with
data, and each record contains data for every field (though that field may be empty).
Evaluators shall support the use of ranges as databases if they support any database functions.
The first row of a range is interpreted as a set of field names.
Note: Field names of type Text and unique without regard to case enhance the interoperability of
data. It is also a common expectation that rows following the first row of data are data records that
correspond to field names in the first row.
A single cell containing text can be used as a database; if it is, it is a database with a single field
and no data records.
Evaluators supporting databases and named ranges shall support the use of named ranges as a
range, and the use of a Text value as a database (which, if it matches the name of a named range,
will be considered the named range).
Note: It is considered good practice to define a named range for a database because it eases
maintenance (the range can be changed for all functions by changing just one definition). However,
the use of named ranges for a database is not required by this specification.
4.11.9 Field
A field is a value that selects a field in a database; it is also called a field selector. If the field
selector is Text, it selects the field in the database with the same name.
Evaluators should match the database field name case insensitive.
If a field selector is a Number, it is a positive integer and used to select the fields. Fields are
numbered from left to right beginning with the number 1.
All functions that accept a field parameter shall, when evaluated, return an Error if the selected field
does not exist.
4.11.10 Criteria
A criteria is a rectangular set of values, with at least one column and two rows, that selects matching
records from a database. The first row lists fields against which expressions will be matched. 4.11.9
Rows after the first row contain fields with expressions for matching against database records.
For a record to be selected from a database, all of the expressions in a row of criteria shall match.
A reference to an empty cell is interpreted as the numeric value 0.
Expressions are matched as per 4.11.7 Criterion.
Test Cases:
=DSUM(TESTDB;
"TestID"; [.B36:.B37])
96
Trivial criteria, checking for equal to a number. We use SUM
on the TestID to make sure that EXACTLY the right records
were selected.
=DSUM(TESTDB;
"TestID"; [.G36:.G37])
4757 Check for less than a number.
100414201 29 May 2010
=DSUM(TESTDB;
"TestID"; [.B36:.C37])
64
Two criteria side-by-side are an AND (meet ALL criteria of a
row of criteria )
=DSUM(TESTDB;
"TestID"; [.B36:.B38])
737
Two criteria on top of each other are an OR (meet ANY of the
rows of criteria )
=DSUM(TESTDB;
"TestID"; [.B36:.C38])
193 Can have multiple criteria sets.
=DSUM(TESTDB;
"TestID"; [.B36:.D38])
0 Can have multiple criteria sets.
=DSUM(TESTDB;
"TestID"; [.D36:.D37])
2048 Simple text match.
=DSUM(TESTDB;
"TestID"; [.H36:.H37])
3679 Date comparison
=DSUM(TESTDB;
"TestID"; [.E36:.E37])
1580 Comparison less than zero.
=DSUM(TESTDB;
"TestID"; [.F36:.F37])
8128 Less than or equal to.
=DSUM(TESTDB;
"TestID"; [.G36:.G38])
6037 Pair of comparisons, and check on greater than or equal to.
=DSUM(TESTDB;
"TestID"; [.H38:.H39])
2048
Matches of field names and text should ignore case if case-
sensitive is false.
=DSUM(TESTDB;
"TestID"; [.D38:.D39])
6144
If initial text matches, should return it (do not require exact
match at higher levels)
Rationale: There are many other criteria supported by different applications. Various
implementations have different pattern languages, and that's a problem. For the moment, well just
define the subset of criteria that are supported by most applications, which is sufficient for most
uses. Future versions might extend this definition, if we can get widespread agreement on them.
4.11.11 Sequences (NumberSequence, NumberSequenceList,
DateSequence, LogicalSequence, and ComplexSequence)
Some functions accept a sequence, i.e., a value that is to be treated as a sequential series of
values. The following are sequences: NumberSequence, NumberSequenceList, DateSequence,
LogicalSequence, and ComplexSequence.
When evaluating a function that accepts a sequence, the evaluator shall follow the rules for that
sequence as defined in section 5.3. When processing a ReferenceList, the references are
processed in order (first, second if any, and so on). In a cuboid, the first sheet is first processed,
followed by later sheets (if any) in order. Inside a sheet, it is implementation-defined as to whether
the values are processed row-at-a-time or column-at-a-time, but it must be one of these two
processing orders. If processing row-at-a-time, the sequence must be produced by processing each
row in turn, from smallest to largest column value (e.g., A1, B1, C1). If processing column-at-a-time,
the sequence must be produced by processing each column at a time, from the smallest to the
largest row value (e.g., A1, A2, A3).
100414201 29 May 2010
5 Expression Syntax
5.1 General
The OpenFormula syntax is defined using the BNF notation of the XML specification, chapter 6
[XML1.0]. Each syntax rule is defined using "::=".
Note: Formulas are typically embedded inside an XML document. When this occurs, characters
(such as "<", ">", '"', and "&") shall be escaped, as described in section 2.4 of the XML specification
[XML1.0]. In particular, the less-than symbol "<" is typically represented as <, the double-quote
symbol as ", and the ampersand symbol as & (alternatively, a numeric character
reference can be used).
5.2 Basic Expressions
Formulas may start with a '=' (EQUALS SIGN, U+003D), which if present may be followed by a
forced recalculate marker '=' (EQUALS SIGN, U+003D), followed by an expression. If the second
'=' (EQUALS SIGN, U+003D) is present, this formula is a "forced recalculation" formula. If a formula
is marked as a "forced recalculation" formula, then it should be recalculated whenever one of its
predecessors it depends on changes.
Expressed in BNF grammar, a formula is specified:
Formula : : = Intro? Expression
Intro : : = ' =' ForceRecalc?
ForceRecalc : : = ' ='
Rationale: User-defined functions can have side-effects, though they are not recommended.
Having a ForceRecalc marker allows users to force recalculation in cases the dependency analysis
of an application would miss. Also, some functions can refer to values without it being clear to a
dependency analysis which ones it depends on. This is a specialized capability, and most
documents will not need to use forced recalculation.
Note: Spreadsheet implementations decide what to recalculate, and may decide to consider other
formulas as if they were "forced recalculate" formulas based on the functions used in them.
The primary component of a formula is an Expression . Formulas are composed of
Expression s, which may in turn be composed from other Expression s.
Expression : : =
Whitespace* (
Number |
String |
Array |
PrefixOp Expression |
Expression PostfixOp |
Expression InfixOp Expression |
' ( ' Expression ' ) ' |
FunctionName Whitespace* ' ( ' ParameterList ' ) ' |
Reference |
100414201 29 May 2010
QuotedLabel |
AutomaticIntersection |
NamedExpression |
Error
) Whitespace*
SingleQuoted : : = "' " ( [^' ] | "' ' ") + "' "
Note: The test cases are in the specific sections for each alternatives, rather than here.
Note: Several different syntactic units in an expression can have the representation '...', with
possible embedded pairs of single quotes. This defined here as SingleQuoted; SingleQuoted is not
actually referenced here, but in several different syntactic units below. These units are
disambiguated by the non-whitespace character following it. Thus, in, 'Sheet1'.Name1, Sheet1 is a
sheet, while in 'http://example.com/'#'Sheet1'.xyz, the first part is an IRI. A typical lexer can treat all
uses of '...' as the same syntactic unit, and then let a higher-level parser handle the different cases,
so that single syntactic unit (SingleQuoted) is documented here.
5.3 Constant Numbers
Constant numbers are written using '.' (FULL STOP, U+002E) dot as the decimal separator. Optional
"E" or "e" denotes scientific notation. Syntactically, negative numbers are positive numbers with a
prefix "-" (HYPHEN-MINUS, U+002D) operator. A constant number is of type Number.
Number : : = StandardNumber |
' . ' [0- 9] + ( [eE] [- +] ? [0- 9] +) ?
StandardNumber : : = [0- 9] + ( ' . ' [0- 9] +) ? ( [eE] [- +] ? [0- 9] +) ?
Evaluators should be able to read the Number format, which accepts a decimal fraction that starts
with decimal point '.' (FULL STOP, U+002E), without a leading zero. Evaluators shall write numbers
only using the StandardNumber format, which requires a leading digit, and shall not write
numbers with a leading '.' (FULL STOP, U+002E).
Note: Application implementors need to remember that when reading/writing numbers, use the C
locale, e.g., POSIX setlocale(LC_NUMERIC, "C") or equivalent. The user's locale may use a
different syntax, such as using , as the decimal separator. Note that leading - and + signs are
allowed as unary prefix operators, and % as a postfix operator; syntactically they are operators,
though applications should optimize them away.
Rationale: Writers are required to write a leading digit, because future versions of this specification
might not include a requirement to accept numbers with a leading ..
Negative numbers are treated as a number with a prefix - operator. This makes the BNF very
clean, and this way precedence is easy to specify correctly. Other language definitions, such as the
one for Ada95, do this as well. There is a risk of incorrectly conflicting with the precedence rules if
you try to handle "-" in the number lexical processing; it's just too easy to get things wrong. Microsoft
Excel, OpenOffice.org, and most other spreadsheet applications treat prefix - with a uniform
precedence (whether or not it precedes a constant number of an expression). However, there is at
least one application (Microsoft Works) where unary "-" has different precedence, depending on
whether or not it's in front of a constant number, according to http://www.burns-
stat.com/pages/Tutor/spreadsheet_addiction.html. Since it's obvious that implementations can make
this mistake, writing the BNF in this clear way (without making negative numbers a special case)
prevents this misunderstanding entirely.
Test Cases:
100414201 29 May 2010
=56.5 56.5
Numbers use . as the decimal separator;
trivial fractions supported.
=.5 0.5
Readers accept initial . for constant
numbers, but should not write them.
=550E-1 55 Exponents can be negative
=550E+1 5500 Exponents can be positive
=56e2 5600
Exponents can have no sign (+ assumed)
and lowercase e is okay
5.4 Constant Strings
Constant strings are surrounded by double-quote characters (QUOTATION MARK, U+0022); a
literal double-quote character '"' (QUOTATION MARK, U+0022) as string content is escaped by
duplicating it. When a formula is stored in an XML attribute, XML escaping rules apply: thus inside
an XML attribute double-quote characters shall be escaped (e.g., as ") and carriage return
characters in a String (e.g., as ) . A constant string is of type Text.
String : : = ' "' ( [^"#x00] | ' ""' ) * ' "'
Test Cases:
=LEN("Hi") 2 Simple string.
=LEN("Hi""t") 4 Repeat double-quote to embed a double-quote character.
=LEN("\n") 2
C-format strings have no effect inside character strings. This is two
characters, \ and n.
Rationale: XML escaping conventions (such as ") are used as usual in an XML attribute, but
they are not enough, which is why the character doubling is also used. To see why, consider the
case where the formulas is:
="I am a string"
That is represented in the XML this way:
table:formula="="I am a string""
Now we want to insert a double-quote in the string. We can't do this:
table:formula="="I am a string with a " character ""
because we'll prematurely end the XML attribute, and we can't do this:
table:formula="="I am a string with a " character ""
because we'll prematurely end the string - it's going to look at the word "character" and expect an
operator there. Here's what this syntax does instead - the formula is:
100414201 29 May 2010
="I am a string with a "" character"
which is then represented in XML as:
table:formula="="I am a string with a "" character
""
This is very regular, easy to parse, and consistent with current practice.
5.5 Operators
Operators are functions with one or more parameters.
PrefixOp : : = ' +' | ' - '
PostfixOp : : = ' %'
InfixOp : : = ArithmeticOp | ComparisonOp | StringOp | ReferenceOp
ArithmeticOp : : = ' +' | ' - ' | ' *' | ' /' | ' ^'
ComparisonOp : : = ' =' | ' <>' | ' <' | ' >' | ' <=' | ' >='
StringOp : : = ' &'
There are three predefined reference operators: reference intersection , reference concatenation ,
and range. The result of these operators may be a 3 dimensional range, with front-upper-left and
back-lower-right corners, or even a list of such ranges in the case of cell concatenation.
ReferenceOp : : = IntersectionOp | ReferenceConcatenationOp | RangeOp
IntersectionOp : : = ' ! '
ReferenceConcatenationOp : : = ' ~'
RangeOp : : = ' : '
Table 1 - Operators defines the associativity and precedence of operators, from hightest to lowest
precedence.
Table 1 - Operators
Associativity Operator(s) Comments
left : Range.
left !
Reference intersection ([.A1:.C4]![.B1:.B5] is [.B1:.B4]). Displayed
as the space character in some implementations.
left ~
Reference union. Displayed as the function parameter separator in
some implementations.
right +,-
Prefix unary operators, e.g., -5 or -[.A1]. Note that these have a
different precedence than add and subtract.
left %
Postfix unary operator % (divide by 100). Note that this is legal
with expressions (e.g., [.B1]%), it can be duplicated (1%%), and it
does not change the meaning of other operations such as "+".
left ^ Power (2 ^ 3 is 8).
left *,/ Multiply, divide.
left +,-
Binary operations add, subtract. Note that unary (prefix) + and -
have a different precedence.
100414201 29 May 2010
left &
Binary operation string concatenation. Note that unary (prefix) +
and - has a different precedence. Note that "&" shall be escaped
when included in an XML document
left
=, <>, <, <=,
>, >=
Comparison operators equal to, not equal to, less than, less than
or equal to, greater than, greater than or equal to
Note: Prefix - has a higher precedence than ^, that ^ is left-associative, and that reference
intersection has a higher precedence than reference union.
Note: Prefix + and are defined to be right-associative. However, note that typical applications
which implement at most the operators defined in this specification (as specified) may implement
them as left-associative, because the calculated results will be identical.
Note: Precedence can be overridden by using parentheses, so "=2+3*4" computes to 14 but
"=(2+3)*4" computes 20. Implementations should retain "unnecessary" parentheses and white
space, since these are added by people to improve readability.
Note: There are no test cases in this section, because the test cases are provided in the text about
the individual operators. This was done to eliminate duplication in this specification, and also
because some applications may choose to only implement a subset (e.g., not implementing cell
concatenation).
Implementations' user interfaces may display these operators differently or with a different
precedence, but when writing or reading formulas they must use the precedence rules here.
Rationale: The above is the conventional set of operators for most spreadsheet applications, along
with their conventional precedence and associativity. This format is intentionally similar to traditional
presentations of spreadsheet formulas, which reduces the likelihood of error or misunderstanding.
For example, Microsoft Excel documentation at http://support.microsoft.com/kb/25189/EN-US/ )
claims that the precedence is (from highest to lowest) Range, Intersection, Union in that order.
Walkenbach gives Microsoft Excel 2003's precedence levels as (lowest to highest, note that the
book gives the reverse order) comparison (such as "="), "&", "+" and "-", "*" and "/", "^", "%", and
unary "-" (negation). (Walkenbach, 2004, pg 38). Prefix "-" and "+" are right-associative, not non-
associative, because "--[.B3]" is legal (and it converts B3 to a number, so it can have an effect). Cell
address intersection has an even higher precedence than - so that a unary minus in front of an
intersection will work correctly.
Parentheses are not normally documented as an operator in spreadsheet applications, so they are
not considered operators here as well. Instead they are simply part of expression syntax. If
parentheses were considered to be operators with a precedence, they would have a precedence
higher than any of the operators here.
See the infix operator ^ text for the rationale for its left-to-right associativity, and why prefix - has
a higher precedence than infix ^. Not all applications have historically done this, but many have,
and the group agreed that it needed to be specified, and not left as being implementation-
dependent.
Although the user interface is not specified here, the representation is intentionally chosen so that
formulas can "round trip" to this format and back without loss using typical formula representations.
For example, it would be possible to replace some or all uses of "%" with "/100", and to replace "^"
with POWER(), but this would cause the display format to change once it was saved and reloaded.
5.6 Functions and Function Parameters
Functions are called by name, followed by parentheses surrounding a list of parameters.
Parameters are separated using the semicolon ';' (SEMICOLON, U+003B) character:
FunctionName : : = Identifier
100414201 29 May 2010
Identifier : : = LetterXML ( LetterXML | DigitXML |
' _' | ' . ' | CombiningCharXML) *
Where LetterXML, DigitXML, and CombiningCharXML are Letter, Digit, and CombiningChar as they
are defined in [XML1.0].
Function names are case-insensitive.
Note: User interfaces may, of course, display a different parameter separator. The comma (,) is a
common alternative separator, though note that using comma as a parameter separator interferes
with its use as a decimal or thousands separator.
User-defined function names may use an arbitrary Identifier, but the names of the functions
predefined by this specification use the stricter format [A-Za-z] [A-Za-z0-9_.]*.
Rationale: Function names are often displayed in all upper case by implementations, showed this
way in documentation, and saved in uppercase, owing to the influence of the first spreadsheet
program (VisiCalc).
Some applications, such as Excel and Gnumeric, use the "," as the function parameter separator in
their user interface. Others, such as OpenOffice.org and Lotus 1-2-3, use ";" instead. Many locales
use "," as the decimal separator; using the semicolon as the parameter separator eliminates
confusion and the risk of incorrect implementation. What the user interface uses is not relevant to
this specification.
Note: Microsoft Excel accepts empty parameters in any position. OpenOffice.org 1.1.3 did not.
Typical implementations will have many built-in functions, and most implementations also support
one or more ways to create user-defined functions.
Function calls shall be given a parameter list, though it may be empty. An empty list of parameters is
considered a call with 0 parameters, not a call with one parameter that happens to be empty.
TRUE() is syntactically a function call with 0 parameters. It is syntactically legitimate to provide
empty parameters, though functions may not accept empty parameters unless otherwise noted:
ParameterList : : = /* empty */ |
Parameter ( Separator EmptyOrParameter ) * |
Separator EmptyOrParameter /* First param empty */
( Separator EmptyOrParameter ) *
EmptyOrParameter : : = /* empty */ Whitespace* | Parameter
Parameter : : = Expression
Separator : : = ' ; '
Test Cases:
=TRUE() True
Syntactically this is a zero-parameter function call, not a one-
parameter function call whose parameter happens to be
empty. Implementations will typically treat TRUE() as a
constant.
=ABS(4) 4 One parameter
=MAX(2;3) 3 Two parameters note that ; is the separator, not ,
=IF(FALSE();7;8) 8 Simple if, three parameters
=IF(FALSE();7;) 0 Empty parameter for else parameter is considered 0 by IF
100414201 29 May 2010
Note: If there is a need for passing exactly one parameter that is empty, a function like
EMPTYPARAM() could be defined for representing an empty parameter. However, the committee
has not yet identified any need for such a thing, and saw no reason to invent the unnecessary. If it's
needed in the future, it could be added.
5.7 Nonstandard Function Names
When writing a document using function(s) not defined in this specification, an evaluator should
include a prefix in such function names to identify the original definer of the function's semantics.
The prefix should begin with a domain name owned by the definer, in reverse order, and should be
in uppercase letters (where lower/uppercase letters apply). This prefix should be the shortest prefix
sufficient to identify the application company/project, followed by a period, optionally followed by
version information or more specific product identification and a period, followed by the original
function name itself. The version information should be included if an application substantially
changes the semantics of a function (as viewed by users of that function) and one of those later
versions of the function is intended. Evaluators may implement functions originally defined by
another evaluator, and thus may read and/or write function names that use another evaluator's
prefix.
Note: Examples of such names include COM.MICROSOFT.CUBEMEMBER,
ORG.OPENOFFICE.STYLE, ORG.GNUMERIC.RANDRAYLEIGH, and COM.LOTUS.V98.FOO.
Note: Sample prefixes for various spreadsheet applications include (in alphabetical order):
COM.COREL (Corel Word Perfect Office / Quattro Pro)
COM.DATAVIZ (DataViz' DocumentsToGo SheetToGo)
COM.GOOGLE (Google spreadsheet)
COM.LOTUS (Lotus 1-2-3)
COM.MICROSOFT (Microsoft Excel; with an additional sub-prefix could also be used for Works
and Pocket Excel)
COM.SOFTWAREGARDEN (wikiCalc)
COM.SUN (Sun StarOffice Calc, where it differers from OpenOffice.org)
ORG.GNUMERIC (GNOME Gnumeric)
ORG.KOFFICE (KOffice Kspread)
ORG.OASIS (the putative prefix for standard functions)
ORG.OPENOFFICE (OpenOffice.org).
Evaluators should avoid defining evaluator-unique functions beginning with a top-level domain
name followed by a period. Evaluators should avoid defining application functions beginning with
NET., COM., ORG., or a country code followed by a period.
Evaluators that do not support a function should compute its result as some Error value other than
NA().
Note: No test case here, intentionally. It makes little sense to have a standard test for
implementation-unique names.
This naming scheme enables different applications to innovate without interfering with each other or
with standard functions. It enables other applications to implement the function, using the prefixed
name of the original function's creator. It also enables a standard for the function to emerge later,
100414201 29 May 2010
which may have modified semantics based on the experience of the other applications. This
capability is necessary for making this specification open to innovation.
This format can handle application-unique names that begin with NET., COM. and so on, using
the application-unique prefix. However, if the function is later standardized, it would then typically
require renaming. To avoid this unnecessary renaming ,this specification states that applications
should avoid doing this in the first place.
5.8 References
References refer to a specific cell or set of cells. The syntax for a constant reference:
Reference : : = ' [' Source? RangeAddress ' ] '
RangeAddress : : =
SheetLocatorOrEmpty ' . ' Column Row ( ' : ' ' . ' Column Row ) ? |
SheetLocatorOrEmpty ' . ' Column ' : ' ' . ' Column |
SheetLocatorOrEmpty ' . ' Row ' : ' ' . ' Row |
SheetLocator ' . ' Column Row ' : ' SheetLocator ' . ' Column Row |
SheetLocator ' . ' Column ' : ' SheetLocator ' . ' Column |
SheetLocator ' . ' Row ' : ' SheetLocator ' . ' Row
SheetLocatorOrEmpty : : = SheetLocator | /* empty */
SheetLocator : : = SheetName ( ' . ' SubtableCell) *
SheetName : : = QuotedSheetName | ' $' ? [^\] \. #$' ] +
QuotedSheetName : : = ' $' ? SingleQuoted | Error
SubtableCell : : = ( Column Row ) | QuotedSheetName
Column : : = ' $' ? [A- Z] +
Row : : = ' $' ? [1- 9] [0- 9] *
Source : : = "' " IRI "' " "#"
CellAddress : : = SheetLocatorOrEmpty ' . ' Column Row /* Not used
directly */
References always begin with '[' (LEFT SQUARE BRACKET, U+005B); this disambiguates cell
addresses from function names and named expressions. SheetNames include single-quote'
(APOSTROPHE, U+0027) characters by doubling them and having the entire name surrounded by
single-quotes. Column labels shall be in uppercase. The syntax supports whole-row and whole-
column references. A reference is of type Reference.
Columns are named by a sequence of one or more uppercase letters A-Z (U+0041 through
U+005A). Columns are named A, B, C, ... X, Y, Z, AA, AB, AC, ... AY, AZ, BA, BB, BC, ... ZX, ZY, ZZ,
AAA, AAB, AAC, AAZ, ABA, ABB, and so on.
If a RangeAddress does not contain a Column element or does not contain a Row element, it
specifies a cell rectangle (4.8 Reference). If it contains Row elements, the cell rectangle starts on
the first column and ends on the last column the evaluator supports. If it contains Column elements,
the cell rectangle starts on the first row and ends on the last row the evaluator supports.
If in a RangeAddress the first part (left of ':' colon) contains a SheetLocator and the second
part (right of ':' colon) does not contain a SheetLocator, the second part inherits the
SheetLocator from the first part.
If a RangeAddress contains two different SheetLocators, it specifies a cell cuboid (4.8
Reference).
A reference with an explicit row or column value beyond the capabilities of an evaluator shall be
computed as an Error, and not as a reference.
100414201 29 May 2010
Note that references can include a single embedded : separator. Evaluators should use
references with embedded : separators inside the [..] markers, instead of the general-purpose :
operator, when saving files, and where there is a choice of cells to join, and evaluators should
choose the leftmost pair.
Source location's IRI is described in [RFC3987], Internationalized Resource Identifiers (IRIs), based
on [RFC3986], Uniform Resource Identifier (URI): General Syntax. Evaluators should support
absolute IRIs (URLs are IRIs too). Evaluators should support relative IRIs, which can be
distinguished because they do not begin with [A- Za- z] + ": ". Relative IRIs are formed according
to section 6.5 of RFC3987, respectively section 4.2 of RFC3986. Evaluators should always use a ./
prefix when writing a relative IRI, since this is unambiguous. Evaluators should support the file
scheme (file:// prefix).
Evaluators may support a variety of IRI/URI/URL schemes (such as http:).
Test Cases:
=[.B4] 2 Simple reference
=[.$B$4] 2 Absolute reference
=[.$B4] 2 Partly absolute reference
=[.B$4] 2 Partly absolute reference
=SUM([.B4:.B5]) 5 Simple range
=[Sheet1.B4] 2 Explicit sheet name
=['Sheet1'.B4] 2 Explicit sheet name, quoted
=SUM([Sheet1.B4:Sh
eet1.B5])
5 Simple range with explicit Sheet name
=SUM([Sheet1.B4:Sh
eet2.C5])
28 Simple 3D range, naturally with explicit sheet names
=['./openformula-
testsuite.ods'#'Sheet
1'.B4]
2
External reference to local IRI. This is a should, not a shall,
so an application can pass this section without passing this
test case.
Note: The text here is consistent with OpenDocument's definitions of cellRangeAddress and
cellAddress. The $ marking make a cell address absolute, otherwise it is relative (this has an
effect when formulas are copied). OpenDocument also defines a cellRangeAddressList (space-
separated ranges) which is used by several OpenDocument constructs. OpenFormula does not use
the cellRangeAddressList grammar; cell concatenation can do the same thing when this is
necessary.
Referencing a sheet that was deleted is typically turned into an Error, such as #REF!.
A SheetName may be quoted, so a reference that begins with ['...' may be describing a Source or a
SheetName. However, the next non-whitespace character eliminates the ambiguity if it is #, it is
the Source.
Typical implementations will consider Source as SingleQuoted; the text is shown this way to
emphasize that it is an IRI that is expected between the single quote marks.
100414201 29 May 2010
Typical spreadsheet displays will often not display or require input of the square brackets.
Note that user interfaces may omit the surrounding [...] of a reference.
Rationale: Cell addresses in OpenFormula begin with "[" and end with a "]"; this makes parsing
simpler, faster, and more reliable. Cell addresses are specified in A1 notation, not an R1C1 notation,
as required by OpenDocument 1.0 section 8.1.3 subsection "Formula". Not using R1C1 notation can
in some cases cause an increase in compressed file size (because copied formulas are shown
differently and thus do not compress as well). However, A1 notation is much easier for humans to
understand, so using A1 format is likely to increase reliability and debuggability (because it is more
likely to be correctly generated and interpreted). Where this is a serious problem, array formulas
should be used instead, which can achieve the same results. Both R1C1 and A1 could be allowed,
but then different spreadsheets are likely to generate different characters for the same cell, and thus
create "differences" that do not exist even in simple spreadsheets. Only uppercase characters are
allowed, for the same reason. Column labels shall be in uppercase; this makes it easier to
distinguish between column labels and many named expressions, and increases the likelihood that
functions can be read and written unchanged by different applications.
The above notation supports selectors for whole-rows and whole-columns. Applications which
cannot directly support them can try to fake them by translating them into a large range, but should
not do so, because they mean different things. Spreadsheet applications of the future are likely to
support larger and larger limits; whole-row and whole-column notations do not change their meaning
in such cases, while limited-range expressions do. We directly support these selectors so that large
spreadsheets of the future would not silently fail.
In the syntax rules above, it was easier to show the rules for RangeAddress by repeating
SheetLocator each time as well as the built-in range operation. Yet people often discuss individual
Cell Addresses in conversation, meaning something that does not include a range of any kind.
Therefore, an explicit rule for the syntax of CellAddress is given, even though it is not directly used
by the syntax rules for formulas (it is subsumed by RangeAddress).
Note that the above can be easily expanded to support subtable addressing, e.g., [.B2.C3], though it
does not require applications to support it. OpenDocument 1.0 section 8.3.1 discusses subtables,
and requires the syntax A1.B2 when addressing subtables in those contexts (which are not
formulas).
Note that the above syntax requires duplication of the prefix if you are asking for a range, e.g.,
[Sheet1.B2:Sheet2.C3], or [.B2.C3:.B2.D4]. This duplication is slightly inconvenient when you simply
want the same sheet location, but has the advantage of being extremely flexible, and is very explicit
in terms of what is desired, so this is considered to be the better approach. Note the careful
definition of the syntax for subtables; the syntax has to differentiate between sheet names in the
earlier parts and row/column addresses, and the names of named expressions and function calls
can also include ..
5.9 Reference List
A reference list is the result of the Infix Operator Reference Concatenation '~', the syntax is:
ReferenceList : : = Reference ( Whitespace* ReferenceConcatenationOp
Whitespace* Reference) *
A reference list can be passed as an argument to functions expecting a reference parameter where
passing one reference results in an identical computation as an arbitrary sequence of single
references occupying the identical cell range. A reference list cannot be converted to an array.
100414201 29 May 2010
5.10 Quoted Label
5.10.1 General
A quoted label is Text contained in a table as cell content, either literally or as a formula result.
QuotedLabel : : = SingleQuoted
A quoted label identifies a column or a row, depending on the label range in which its text appears.
5.10.2 Lookup of Defined Labels
For a QuotedLabel, first the cells defined in column label ranges (cell ranges of the
table:label-cell-range-address attribute in the elements <table:label-range> with
attribute table:orientation set to column) are searched for the string content of
QuotedLabel (without the quotes). If found, the corresponding column's range of the data cell
range of the table:data-cell-range-address attribute is taken as a reference. If not found,
the cells defined in row label ranges (attribute table:orientation set to row) are searched and
if found the corresponding row's range of the data cell range is taken. Label ranges of the current
formula's sheet take precedence over label ranges of other sheets if a name occurs in both.
5.10.3 Automatic Lookup of Labels
For a QuotedLabel where no defined label is found, an automatic lookup is performed on the
sheet where the formula cell resides, if that document setting is enabled (HOST-AUTOMATIC-FIND-
LABELS value true ).
Matches to the upper left of the formula cell are preferred over other matches, followed by matches
with a smaller distance. The following algorithm is used:
Cells on the same sheet as the formula cell are examined column-wise from left to right whether
they contain the text of QuotedLabel (without the quotes). If more than one cell match, the
distance and direction from the formula cell's position is taken into account. The distance is
calculated by Distance= ColumnDifference*ColumnDifference+ RowDifference*Row
Difference using an idealized layout of quadratic cells. For the direction, during the run two
independent match positions are remembered each time Distance is smaller than a previous
Distance: Match2 for positions right of and/or below the formula position (FormulaColumn <
MatchColumn || FormulaRow < MatchRow), Match1 for all others (not right of and not below).
Match1 also holds the very first match, in case there is only one match or all matches are
somewhere below or right of the formula cell. After having found the smallest distances the
conditions are:
1. If Match1 has the smallest distance, that match is taken.
2. Else, Match2 (right and/or below) has the smallest or an equal distance:
2.1 A match to the upper left (FormulaColumn >= Match1Column && FormulaRow >=
Match1Row) takes precedence over matches to other directions.
2.2 Else, if there is no match to the upper left:
2.2.1 If Match1 is somewhere right of the formula cell (FormulaColumn <
Match1Column) it was the first match found in column-wise lookup.
2.2.1.1 If Match2 is above the formula cell (FormulaRow >= Match2Row) it is to
the upper right of the formula cell and either nearer than Match1 or Match1 is
below. Match2 is taken.
100414201 29 May 2010
2.2.1.2 Else Match2 is below the formula cell and Match1 is taken.
2.2.2 Else (Match1 not right of the formula cell => two matches below or below and
right) the match with the smallest distance is taken.
If the resulting cell is below or above another cell containing Text a row lable is assumed, else a
column label is assumed.
Note: The automatic label lookup can lead to situations where after loading a file the "geometry" is
different from what it was when the user entered the formula and changed cell contents before
saving the document, thus resulting in different lookup results. This may happen also during one
edit cycle if the user added column labels and formulas are changed and recompiled afterwards.
Applications should deprecate the use of the automatic lookup and encourage the user to use
defined label ranges instead.
5.10.4 Implicit Intersection
For the reference resulting from a single QuotedLabel an implicit intersection is generated if the
operator or function where it is used with expects a scalar value. The intersection is generated with
the current formula's cell position, thus for a column label an intersection is generated with the
formula cell's row, for a row label with the formula cell's column.
5.10.5 Automatic Range
When passed as a non-scalar argument (e.g. Array or NumberSequence) to a function, a column or
row label is converted to an automatic range reference that is adjusted each time the formula is
interpreted. The range is generated from the corresponding column respectively row intersecting an
area directly below respectively right of the label cell that is constructed by encompassing
contiguous cells. A blank cell interrupts contiguousness, one blank cell directly below respectively
right of the label cell is ignored.
Example:
Table 2 - Automatic Range
Row Data Expression Result Comment
1 Label
2
3 1
4 2
5
6 8
7
8 32
=SUM('Label') 3 Blank cell in row 2 is
skipped (two blank cells in
row 2 and 3 would not and
stop), blank cell in row 5
stops the automatic range.
100414201 29 May 2010
If any cell content is entered in row 5 the range is regenerated as follows:
Table 3 - Automatic Range
Row Data Expression Result Comment
1 Label
2
3 1
4 2
5 4
6 8
7
8 32
=SUM('Label') 15 Blank cell in row 2 is
skipped, blank cell in row 7
stops the automatic range.
5.10.6 Automatic Intersection
An automatic intersection may be used to identify the intersection of two quoted labels. Note that
this is different from the IntersectionOp, which takes two references instead of two labels:
AutomaticIntersection : : = QuotedLabel Whitespace* ' ! ! ' Whitespace*
QuotedLabel
In an automatic intersection, one of the labels identifies a row, the other a column; they may be in
either order. Each QuotedLabel is looked up as defined above under "Lookup of Defined Lables"
and "Automatic Lookup of Labels". If two data cell ranges are found, the intersection of the column's
data cell range and the row's data cell range is generated. If the intersection result is not exactly one
cell, an Error is generated.
Note: An alternative is to use @ as a somewhat natural operator instead of !!, so that
the expression becomes Sales@Hamburg. Note that @ has been traditionally the
prefix for functions; will there be a need to use @ again in the future that way? Note that
using @ in this way would interfere with applications which use @ in the interface
(Lotus 1-2-3, etc.) - they would have to do something different.
Note: An AutomaticIntersection may be represented differently in the user interface than a
use of the IntersectionOp, for example by using a space. This resembles natural language, for
example the user interface may appear as =Sales Hamburg with Sales being a ColumnLabel and
Hamburg being a RowLabel, which results in displaying the result of the cell at the intersection.
TODO: Need test cases
Note: Excel has a weird feature called stacked labels , where a label may be the result of a
concatenation of cell contents of stacked adjacent cells in one column, which confusingly enough in
the UI are separated with a space as well. It's hard to predict what an expression like =SUM(one
two three four) actually refers to.. even more if you have B2:'one two', B2:'three', C1:'one', C2:'two
three' and A3:'four'. There was double that we even should include or specify this , so the
Hippocratic oath (First, do no (knowing) harm) was employed.
100414201 29 May 2010
5.11 Named Expressions
A NamedExpression references another expression, possibly in a completely different spreadsheet
or any other document type that can be imported into a spreadsheet.
NamedExpression : : = SimpleNamedExpression |
SheetLocalNamedExpression | ExternalNamedExpression
SimpleNamedExpression : : = Identifier |
' $$' ( Identifier | SingleQuoted)
SheetLocalNamedExpression : : =
QuotedSheetName ' . ' SimpleNamedExpression
ExternalNamedExpression : : =
Source ' #' ( SimpleNamedExpression | SheetLocalNamedExpression)
Evaluators supporting named expressions shall support Simple Named Expressions that are global
to all the sheets in a (spreadsheet) document in the current document. This is a named expression
without a Source, QuotedSheetName, or SubtableCell. The type of a named expression is
the type of the value that the named expression returns.
Named expressions are case-consistent, meaning that matching is done case-insensitive and
identifiers can not differ ONLY in their case. Evaluators should write identifiers with identical case in
all locations.
Evaluators may support Sheet-local Named Expressions that are local (attached) to individual
sheets. In that case, a non-empty QuotedSheetName can be used to reference a sheet-specific
named expression. The most specific named expression for a given expression is used. If the
QuotedSheetName is empty, the search for the named expression begins with the current sheet,
then up through the container(s) of the sheet (the same is true if the QuotedSheetName rule
fragment is not included at all). If there is a non-empty QuotedSheetName, search begins with that
named sheet, then up through its container(s) for the given name.
Note: There is no syntax for referencing a named expression without first looking at the current
sheet's named expressions; where this is a problem, a user can define a blank sheet and reference
that sheet as the starting location for finding the named expression.
If a sheetname is not empty, it shall be quoted using ' (APOSTROPHE, U+0027). While both
Source and QuotedSheetName can begin with the single-quote character ' (APOSTROPHE,
U+0027), they are distinguished: after the closing single-quote character, a non-empty source shall
have the '#' (NUMBER SIGN, U+0023) character as the next non-whitespace; a non-empty
sheetname shall be followed by the '.' (FULL STOP, U+002E) character as the next non-whitespace.
Expressions should limit the names of their identifiers to only ([UNICODE]) letters, underscores, and
digits, not including patterns that look like cell references or the words True or False.
Note: Some evaluators do not support the use of Unicode for identifiers.
Identifier : : = ( LetterXML
( LetterXML | DigitXML | ' _' | CombiningCharXML) * )
- ( [A- Za- z] +[0- 9] + )
- ( [Tt] [Rr] [Uu] [Ee] ) - ( [Ff] [Aa] [Ll] [Ss] [Ee] )
Rationale: In many implementations, including Excel and Gnumeric, NamedExpressions can be
sheet-specific or global. The above syntax supports referencing names in other sheets, which was a
requirement. We need to modify OpenDocument's specs to allow for sheet-local named
expressions; it currently only explains how to define global named expressions.
Note: This version of the specification doesn't define how to create new functions. However, it
would not be hard to extend this specification to add this capability. Many new functions could easily
100414201 29 May 2010
be defined in terms of the predefined set, as long as there were a way to access parameters
through new functions like PARAMETER(n) and NUMPARAMETERS().
Note: If NamedExpressions are later extended to permit calling them like functions, then the
NamedExpression must be preceded by the $$ marker in such cases otherwise, it would be
considered a traditional function call.
Note: Excel 2000 in a Nutshell, page 120, gives the following rules for its names. A name must:
begin with a letter or underscore
be followed with zero or more letters, digits, underscore (_), period (.), question mark (?), or
backslash. Note that it permits periods, which complicates entry (since "." is used as the
separator between sheetnames and cell addresses in OpenFormula). Note that spaces are not
permitted.
cannot exceed 255 (and really can't exceed 253, since then selecting the name box is a
problem).
cannot match cell's address. A cell address is the one or two letter column label A through IV
(uppercase, lowercase, or combination) followed by a number between 1 and 65535. It also
cannot match the obsolete RrCc row-column name format (where r is a number from 1 to 255
and c is a number from 1 to 65535).
Note that later versions of Excel expand the number of columns, complicating names further.
Test Cases Simple Named Expressions:
=FOUR 4 Simple named expression
=$$FOUR 4 Named expression, marker saying so
=$$'FOUR' 4 Named expression, marker saying so
= 4
International characters are permitted in names, not just
ASCII or Latin-1
Test Cases External Named Expressions:
='./openformula-
testsuite.ods'#$$'FOUR'
4 External reference to local IRI.
Test Cases Sheet-local Named Expressions:
='Sheet1'.$$'FOUR' 4 Sheet-specific reference
='./openformula-
testsuite.ods'#'Sheet1'. $
$FOUR
4 External reference to sheet-specific IRI.
100414201 29 May 2010
5.12 Constant Errors
Evaluators shall support the Error value #N/A. Evaluators may support other Error values.
Evaluators may allow entry of errors directly, parse them and recognize them as Errors. Functions
shall propagate Errors unless stated otherwise.
Inline Error constants shall have the following syntax:
Error : : = ' #' [A- Z0- 9] + ( [! ?] | ( ' /' ( [A- Z] | ( [0- 9] [! ?] ) ) ) )
Specific Error values are indicated by an identifier.
Table 4 is a list of constant error names that are used by several existing implementations.
Evaluators may implement other constant Error values.
Table 4 - Possible Other Constant Error Values
Name Comments
#DIV/0! Attempt to divide by zero, including division by an empty cell. ERROR.TYPE of 2
#NAME? Unrecognized/deleted name. ERROR.TYPE of 5.
#N/A
Not available. ISNA() applied to this value will return True. Lookup functions which
failed, and NA(), return this value. ERROR.TYPE of 7.
#NULL! Intersection of ranges produced zero cells. ERROR.TYPE of 1.
#NUM!
Failed to meet domain constraints (e.g., input was too large or too small).
ERROR.TYPE of 6.
#REF! Reference to invalid cell (e.g., beyond the applications abilities). ERROR.TYPE of 4.
#VALUE! Parameter is wrong type. ERROR.TYPE of 3.
An unknown constant Error value shall be mapped into an Error value supported by the evaluator
when read (e.g., the application's equivalent of #NAME?), though an evaluator may warn the user if
this has or will take place. It is desirable to preserve the original specific Error name when writing an
Error constant back out, where possible, but evaluators may write a different Error value for a
formula than they did when reading it for Errors other than #N/A. Whitespace shall not be included
in an Error name.
Evaluators should use a human-comprehensible name, not a numeric id, for constant Error values
they write.
Test Cases:
=#N/A NA Another way to write NA
=ISERROR(#N/A) True
This tests to ensure that the parser can find
the end of the error
=#DIV/0! Error This tests for handling /0! correctly
=ISERROR(#DIV/0!) True
=#NAME? Error We'll test all the well-known codes
=ISERROR(#NAME?) True
100414201 29 May 2010
=#NULL! Error
=ISERROR(#NULL!) True
=#NUM! Error
=ISERROR(#NUM!) True
=#REF! Error
=ISERROR(#REF!) True
=#VALUE! Error
=ISERROR(#VALUE!) True
=#UNKNOWNERRORCODE! Error
Applications shall be able to read an
unknown error value generated by another
application, and map it into one of their own
error codes. If it has such a code,
#NAME? or equivalent would be
appropriate
=ISERROR(#UNKNOWNERRORCOD
E!)
True
Unknown error codes still need to be
processed as errors
Rationale: There was significant discussion on whether '/', '!', and '?' should be allowed in a name,
since it would simplify parsing in some circumstances if they were forbidden. This has been kept, for
the simple reason that spreadsheet applications which do share error names tend to use these
names, with these spellings. And it does not seem hard to parse them this way, so there doesn't
seem to be a strong reason to simplify these. Originally we had Error ::= '#' [^\. #']+, but this was
an extremely loose syntax likely to cause trouble it'd be too easy to miss the end of the error
term. And while there were some original concerns about making the lexing of this simple, that's
been resolved too. We want applications to be free to have a different and more refined error
system, though, so we want a regular expression that will enable them to write out specific forms
(so other applications will know where the error name ends).
Rationale: Since spreadsheet implementations may have additional or more specific types of
errors, the notion of error has been generalized. Many implementations share these error values,
however, so these representations are recommended so sharing is possible where appropriate.
The recommended names are used by many implementations.
Note: A trivial lexer cannot simply parse anything beginning with # as an error, because # can
also occur as part of a Source identifier. One solution is to lex simply # as a character; if a parser
receives # where it could be an Error value, it could switch the lexer to a different mode solely for
reading the text of the error constant (or just call a different lexer), then switch back. Modern lex
tools, such as flex, can do this easily.
5.13 Inline Arrays
Inline arrays are enclosed with curly braces. Inside, they contain one or more rows, with each row
separated by a row separator:
Array : : = ' {' MatrixRow ( RowSeparator MatrixRow ) * ' }'
MatrixRow : : = Expression ( ' ; ' Expression ) *
100414201 29 May 2010
RowSeparator : : = ' | '
Evaluators that support inline arrays shall accept a matrix with one or more rows, each with one or
more columns, with the same number of columns in each row, with constant values for each
expression. Evaluators that do not support inline arrays, or cannot support a particular use permitted
by this syntax, should compute an Error value for such arrays. An inline array is of type Array.
Note: Expression authors should be aware that use of Expression other than constant Number
or constant String may impair interoperability.
Note: The syntax here does not permit empty (zero-value) arrays there has to be at least one row,
with at least one value.
Note: Gnumeric is adding the ability to handle matrices where not all values are constants, termed
dynamic matrices. The syntax above, which permits arbitrary Expressions, can handle matrices
whose values are not constant.
Rationale: Earlier drafts of this specification defined a standard method to describe 3D arrays, but
this appeared to be an unnecessary syntactic frill. If needed, a function could be used to define 3D
inline arrays, making a special syntax unnecessary.
Test Cases:
=SUM( {2;3|4;5} ) 14 A 2x2 inline array
=SUM({3|4|5}) 12 3x1 array (3 rows, 1 column)
=MDETERM({1;1;2|0;1;2|1;0;2}) 2
Matrix determinant. For a 3x3 array
MDETERM({A1;B1;C1|A2;B2;C2|
A3;B3;C3}) = A1*(B2*C3-B3*C2) +
A2*(B3*C1-B1*C3) + A3*(B1*C2-B2*C1) =
1*(1*2-0*2) + 0*... + 2*(1*2-1*2) = 2 + 0 + 0
= 2
5.14 Whitespace
Whitespace : : = #x20 | #x09 | #x0a | #x0d
For calculation purposes, whitespace is ignored unless it is inside the contents of string constants or
text surrounded by single quotes. Evaluators shall ignore any whitespace characters before and/or
after any operators, constant numbers, constant strings, constant errors, inline arrays, parentheses
used for controlling precedence, and the closing parenthesis of a function call. Whitespace shall be
ignored following the initial equal sign(s). Whitespace shall be ignored just before a function name,
but whitespace shall not separate a function name from its initial opening parentheses. Whitespace
shall not be used in the interior of a terminating grammar rule (a rule that references no other rule
other than character sets, internally or externally-defined), unless specifically permitted by the
terminating grammar rule, since these rules define the lexical properties of a component. Evaluators
shall not write formulas with whitespace embedded in any unquoted identifier, constant Number, or
constant Error. Evaluators shall treat SPACE (U+0020), CHARACTER TABULATION (U+0009),
LINE FEED (U+000A), and CARRIAGE RETURN (U+000D) as whitespace characters.
An embedded line break shall be represented by a single LINE FEED character (U+000A), not by a
carriage return-linefeed pair. When embedded in an XML attribute the linefeed character is
represented as
.
100414201 29 May 2010
Evaluators should retain whitespace entered by the original formula creator and use it when saving
or presenting the formula, and should not add additional whitespace unless directed to do so during
the process of editing a formula.
Test Cases:
= 3.5 + 3 6.5 Whitespace permitted
= ( 2 + 3 ) * 5 25
Whitespace permitted around ordinary
parentheses used for grouping
= 300 % 3
Percent is not special; it can be surrounded
by whitespace too
Rationale: Whitespace (including newlines) should be retained so it can be used to make complex
formulas easier to understand. Retaining is only a should because this can be burdensome to
implement in some implementations, and because changing whitespace outside of a string constant
and single-quoted value does not change the calculated result of an expression.
In some applications, such as Microsoft Excel, the space is used as an operator (such as the
intersection operator) and also as ignorable whitespace. This is very confusing, making it difficult to
parse and risky to use. The OpenFormula exchange format uses "!" instead of whitespace for the
intersection operation, which eliminates this painful and unnecessary problem.
Although the exchange format can handle it, some Excel-like display formats could have difficulties
with whitespace that separates a function name from its initial opening parentheses. As a small
concession for this common case, that particular combination is not permitted.
Note: For purposes of this specification, the user interface is the textual representation of formulas
as presented to end-users. This may be the same as the exchange syntax, but it need not be and
often won't be. The exchange syntax is optimized for unambiguous exchange between different
applications (which may implement different capabilities) and parsing at high speed (disambiguation
markers aid in this).
In contrast, user interfaces often emphasize brevity, with some attempt to automatically do what the
user meant and/or provide an interface the user happens to be familiar with. Today's applications
tend to have different user interfaces, and at least one application (Corel Quattro Pro) allows the
user interface to be selected and changed dynamically. User interfaces often differ on details such
as what is the formula parameter separator (semicolon or comma), do function calls need an @
prefix or not, the character for reference intersection (such as space or !), reference union (~ or
,), range (: or ..), the equality (= or ==) and inequality (<> or !=) operators, and how to
refer to external documents, other sheets, or named expression identifiers. For document exchange
these differences are irrelevant; users can simply choose the application that provides the user
interface they prefer.
However, some implementors may want to have a reasonable UI intentionally similar to the
exchange format, but where users do not need to type in various markings such as [...] around cell
references. The text below demonstrates a sample user interface that is intentionally similar to the
exchange format. This is provided as an aid to implementors who wish to create a simple user
interface that easily works with the exchange format, since it is an important use case. This analysis
also helped in examining the syntax given above, to eliminate potential problems in it.
More generally, a user interface will accept text and determine what is being input. For our
purposes, we will assume that all functions begin with an initial character of =. Without an initial =
character, it will presume that some sort of constant is being entered into a cell, and compare
against various patterns to determine what that is (e.g., YYYY-MM-DD would be a date, something
100414201 29 May 2010
matching a number format would be a number, etc.). Let us consider from here on the case where
there is an initial =, to be interpreted as a formula.
If a user interface is intended to be similar to the exchange format, it will probably continue to use
the semicolon as function separator, the exchange characters for operators, and so on. Thus, most
of a simple user interface is usually easy to develop, simply by copying the syntax given this
specification.
However, most user interfaces do not require markers to disambiguate most cell references, named
expressions, and function names. Once these markers are removed from the exchange format, it
may appear difficult to develop a user interface to distinguish between these cases, especially if the
application supports extensions such as subtables (either cells and sheets inside cells) and function
calls on named expressions. This is actually not as difficult as it may first appear; this section
documents one way to do this.
First, notice that an Expression can be (among other things) a function call (beginning with a
function name), a reference, or a named expression. Without markings or rules, some of their
patterns would be ambiguous, especially since most user interfaces will treat function and column
names in case-insensitive manner. Two things are needed: (1) rules to disambiguate, and (2)
overriding patterns so that a human can easily force any particular interpretation. Ideally those rules
would also handle phrases such as whole column ranges in a graceful manner.
Thus, the implementation can look for patterns, where higher-precedence matches would override
lower-precedence ones. The following is a example of a list of such patterns, starting with the
highest-precedence one, along with an example (in the UI and exchange format) and the meaning
of the pattern; the {...} surround syntactic names:
Pattern Example
UI Exchange
Meaning
{Identifier} ( .... SUM(... SUM(...
ERROR
.TYPE( .
..
ERROR.TY
PE( ...
Function call to built-in function, such as SUM(...)
or ERROR.TYPE(...). If there is no such function,
search for a named expression of that name
starting from the current sheet, and if found, use
that (and consider it a call through the named
expression). Use prefix $$ to force interpreting this
as a named expression. Notice that function calls
must have opening parentheses, disambiguating
them from other possibilities.
{LetterXML}
{LetterXML |
DigitXML}* \. $? [A-
Za-z]+ $? [0-9]+ ...
A1.B2 [A1.B2] or
['A1'.B2]
Sheet name and cell reference; Sheet A1's cell
B2. Notice we prefer this interpretation to the less
likely cell A1, subtable cell B2. This can't be a
function call, because it didn't match the previous
pattern. For arbitrary sheet names, surround the
sheet name with '...'. Use prefix '...' followed by .
to force this interpretation
$?[A-Za-z]+ $?[0-
9]+
A1 [.A1] Cell reference to current sheet; cell A1 of current
sheet. Use prefix . to force this interpretation
$?[A-Za-z]+ : $?
[A-Za-z]+
B:B [.B:.B] Full column range reference. Whitespace may
surround the :.
{Identifier} Hello Hello or $
$Hello
If it isn't anything else, it must be a named
expression. Use prefix $$ to force interpretation to
be a named expression, which must always be
used to call functions in named expressions (if that
100414201 29 May 2010
is permitted).
And here are forms that are completely unambiguous, allowing the user to force a particular
interpretation:
Pattern Example
UI Exchange
Meaning
\ .[A-Za-z]+[0-9]+ ... .A1 [.A1]
.A1.B2 [.A1.B2]
Unambiguous cell reference to current sheet; cell
A1 of current sheet. The prefix is needed when
referring to a subtable of a cell in the current sheet.
{QuotedSheetName} \
. [A-Za-z]+[0-9]+ ...
'A1'.B2 ['A1'.B2] Sheet name and cell reference, marked
unambiguously, arbitrary sheet name.
' IRI ' # ... './myfile.
ods'#Tot
al
'./myfile.ods'
#Total
Source IRIs are always unambiguous; they are
surrounded by '...' followed by #.
$$ ... $$A1 $$A1 or $
$'A1'
Unambiguously marked named expression id,
named A1.
This means you can have complex expressions like this:
UI Example Meaning
$$A1.B2 Search for named expression name, A1.B2 (a
5-character name), starting from current sheet
A1.$$B1 Go to sheet A1, then look in its named
expression id "B1".
'http://oasis.org'#S1.M1 Get the document from oasis.org, then look in
sheet S1's cell M1
'http://fred'#'A1'.$$B2 External source fred, sheet A1, named
expression id B2.
'http://fred'#B2 External source fred, (global) named expression
B2.
$$Myfunc(1) Call named expression Myfunc. Note that this is
not in the current specification, but is a plausible
extension.
Note again that this particular user interface is not mandated by this specification. It is simply an
illustration to show how to create a user interface. Applications can innovate with new and better
user interfaces, while still exchanging documents with others.
100414201 29 May 2010
6 Standard Operators and Functions
6.1 General
OpenFormula defines commonly used operators and functions.
Function names ignore case. Evaluators should write function names in all uppercase letters when
writing OpenFormula formulas.
Rationale: By writing function names in all upper case, the text is more likely to stay the same
when a file is read and later rewritten, making textual comparison simpler. Also, function names are
traditionally written in all uppercase for spreadsheet formulas. This may be due to the influence of
the first spreadsheet, VisiCalc; VisiCalc first ran on the Apple ][ microcomputer, and early models of
that microcomputer could not display lowercase letters in text mode unless it was modified.
Unless otherwise noted, if any value being provided is an Error, the result is an Error; if more than
one Error is provided, one of them is returned (evaluators should return the leftmost Error result).
6.2 Common Template for Functions and Operators
For every function or operator, the following are defined in this specification:
Name: The function/operator name.,
Summary: One sentence briefly describing the function or operator.
Syntax:
Parameter names are shown in order, with each parameter prefixed by the type or pseudo-
type of that parameter. If the type has multiple names separated by |, then any of those
types are permitted.
A { ... } indicates a list of zero or more parameters, separated by the function parameter
separator character.
A { ... } followed by a superscripted + indicates a list of one or more parameters, separated
by the function parameter separator character.
Components surrounded by [ ... ] are optional. Optional components may be omitted.
An optional parameter followed by the = symbol has the default value given after the equal
sign.
Parameters are separated with a semicolon (";"), as per the OpenFormula syntax.
When a function is given a value of a different type, the parameters are first converted
using the implicit conversion rules before the function operates on its parameters.
Evaluators may extend functions by permitting fewer or additional parameters, which documents
may use. Extended functions may result in a lack of interoperability.
Returns: Return type (e.g., Number, Text, Logical, Reference).
Constraints: A description of constraints, in addition to the constraints imposed by the
parameter types. If there are no additional constraints beyond those imposed by the parameter
types, this is "None". If a constraint is not met, the function/operator shall return an Error unless
otherwise noted.
100414201 29 May 2010
Semantics: This text describes what the function/operator does.
If a parameter is a pseudotype, but the provided value fails to meet the requirements for that
type, the behavior is implementation-defined.
Note: Functions and operators are defined by mathematical formulas or by an OpenFormula
formula. Formulas define the correct result, and not the algorithm for calculation. Since
computing systems have limited precision and range of numbers, some functions cannot or
should not be naively implemented as their formulas suggest. This specification defines the
mathematically correct answer, and allows implementors to choose the best algorithm that will
meet that definition.
Comment: Explanatory comment.
See also A list of related operators and functions.
The implicit conversion operators omit many of these items, e.g., the syntax (since there is none).
6.3 Implicit Conversion Operators
6.3.1 General
Any given function or operand takes 0 or more parameters, and each of those parameters has an
expected type. The expected type can be one of the base types, identified above. It can also be of
some conversion type that controls conversion, e.g., Any means that no conversion is done (it can
be of any type); NumberSequence causes a conversion to an ordered sequence of zero or more
numbers. If the passed-in type does not match the expected type, an attempt is made to
automatically convert the value to the expected type. An Error is returned if the type cannot be
converted (this can never happen if the expected type is Any). Unless otherwise noted, any
conversion operation applied to a value of type Error returns the same value.
6.3.2 Conversion to Scalar
To convert to a scalar, if the value is of type:
Number, Logical, or Text, return the value.
reference to a single cell: obtain the value of the referenced cell, and return that value.
reference to more than one cell: do an implied intersection, 6.3.3, to determine which single cell
to use, then handle as a reference to a single cell.
6.3.3 Implied intersection
In some cases a reference to a single cell is needed, but a reference to multiple cells is provided. In
this case an "implied intersection" is performed. To perform an implied intersection:
Compute the union of cells contained in the current row and current column of the formula being
computed.
Intersect this with the provided reference to multiple cells
If a single cell is referenced; return it; otherwise, return an Error.
Note: Implied intersection is basically ((my_row union my_column) intersection (given reference)).
Tests with Excel 2003 and OpenOffice.org 2 confirm this. See Walkenbach's "Microsoft Excel 2000
Formulas", pg 68.
100414201 29 May 2010
6.3.4 Force to array context (ForceArray)
A ForceArray attribute forces calculation of the argument's expression into non-scalar array mode.
This means that no implied intersection is performed, instead where a reference to a single cell is
expected and multiple cells are provided, iteration over the multiple cells is performed and results
are stored in an array that is passed on.
For example, =SUMPRODUCT(ABS(A1:A3)) iterates with the ABS function over each cell of the
range A1:A3 and passes a 1x3 array as argument to the SUMPRODUCT function.
See also Non-Scalar Evaluation
6.3.5 Conversion to Number
If the expected type is Number, then if value is of type:
Number, return it.
Logical, return 0 if FALSE, 1 if TRUE.
Text: The specific conversion is implementation-defined; an evaluator may return 0, an Error
value, or the results of its attempt to convert the Text value to a Number (and fall back to 0 or
Error if it fails to do so). Evaluators may apply VALUE() or some other function to do this
conversion, should they choose to do so. Conversion depends on the actual locale the
application runs in, especially if group or decimal separators are involved.
Note: Many implementors recommend to generate an Error for an attempted conversion
instead.
Reference: If the reference covers more than one cell, do an implied intersection to determine
which cell to use. Then obtain the value of the single cell and perform the rules as above. If the
calculation setting precision-as-shown is true, then convert the number to the closest possible
representation of the displayed number. If the cell is empty (blank), use 0 (zero) as the value.
Evaluators may choose to convert references to Text in a different manner than they handle
converting embedded Text to a Number.
Note: Semantics vary in current applications:
Excel, Gnumeric, and SheetToGo use "Excel" semantics: If they encounter Text or a reference
to Text, they always convert the Text value to a Number (using VALUE()) and return the Number
or Error. (Walkenbach, 2004) Under these semantics, COS("hi") first computes VALUE("hi"),
producing an Error, and COS() applied to an Error value produces an Error value.
Lotus 1-2-3v9, Quattro Pro, KSpread use "Lotus" semantics: If they encounter Text or a
reference to Text, they always return the number 0. Under these semantics, COS("hi")
computes COS(0), producing 1.
OpenOffice.org 2 splits the difference: Inline Text is converted to a Number (like Excel), but
references to Text are always considered 0 (even if they could be converted to a different
number, and would be converted to a different number if in-line). Thus, in OOo 2, if B3 has the
string value "7", B3+1 is 1, but "7"+1 and (B3&"")+1 are both 8.
=(1=1)+2 3 Inline Logical True is converted to 1.
=[.B5]+[.B6] 4 Adding forces conversion of TRUE to 1, even if by reference
=IF(ISERROR(7+0);TR
UE();OR( ("7"+0)=7;
True Since + forces a conversion to number, passing "7" to +
should force a conversion to 0, 7, or an error.
100414201 29 May 2010
("7"+0)=0))
=IF(ISERROR([.B3]+0);T
RUE();OR( ([.B3]+0)=7;
([.B3]+0)=0))
True
B3 is "7"; it should convert to 0, 7, or an error. Note that
[.B3]+0 may produce a different result than inline "7"+0.
=ISERR(IF(COS("hi")=1;
1/0;0))
True
Functions expecting a number but get non-numeric text
convert the number to 0 or an Error.
=5+[.B8] 5
Empty cells in a number context are automatically converted
into 0.
6.3.6 Conversion to Integer
If the expected type is Integer for a function or operator, apply the Conversion to Number
operation. 6.3.5 Then, if the result is a Number but not an integer, apply the specific conversion from
Number to integer specified by that particular function/operator. If the function or operator does not
specify any particular conversion operation, then the conversion from a non-integer Number into an
integer is implementation-defined.
Many different conversions from a non-integer number into an integer are possible. The conversion
direction may be towards negative infinity, towards positive infinity, towards zero, away from zero,
towards the nearest even number, or towards the nearest odd number. A conversion can select the
nearest integer, the nearest even or odd integer, or the next integer in the given direction if it is not
already an integer. If a conversion selects the nearest integer, a direction is still needed (for when a
value is halfway between two integers). In this specification, this conversion is referred to as
rounding or truncation; these terms by themselves do not specify any specific operation.
If a function specifies its rounding operation using a series of capital letters, the function defined in
this specification for that function is used to do the conversion to integer. Common such functions
are:
INT, which if given non-integer rounds down to the next integer towards negative infinity,
regardless of whether or not it is the closest integer.
ROUND, which if given non-integer rounds to the nearest integer. If the input number is halfway
between integers, it rounds away from zero.
TRUNC, which if given non-integer rounds towards zero, regardless of whether or not that
integer is the closest integer.
Rationale: It'd be nice if we could simply say, all functions expecting an integer first use INT on
their input parameters, or some other function. But this is not true in practice, and many users have
built important documents that depend on the differing rounding properties of different functions.
E.G., many functions use INT, but ISEVEN uses TRUNC. It would be extremely risky to users if the
conversion to integer function silently changed on them, because it could cause documents to
silently produce the wrong answers. Users who want an conversion that is different from what the
function does, or using one with implementation-defined behavior, can use the rounding functions
already available.
TODO: Walk through functions, and change all Number in input or result types to Integer where
appropriate. Document which integer conversion function is used (usually INT), and include test
cases to check that.
100414201 29 May 2010
6.3.7 Conversion to NumberSequence
If the expected type is NumberSequence, then if value is of type:
Number, Text, or Logical, handle as Conversion to Number (creating a sequence of length 1).
reference, create a sequence of numbers from the values of the referenced cells that only
includes the values of type Number or Error. Thus, Empty cells and Text that could be converted
into a value is not included in a number sequence. If the Logical type is a distinguished type
from the Number type, it should not be included in the sequence of numbers; if the Logical type
is not a distinguished type, then such values will (of course) be included in the number
sequence.
Test Cases:
=SUM([.B3:.B5]
)
5 Conversion to NumberSequence ignores strings (in B3).
=SUM([.B3:.B1
0])
Error If a sequence includes Error, the result has Error.
Note: Although this conversion is described as "creating" a sequence of numbers, which is accurate
from a user's point of view, applications typically implement this using mechanisms that do not
create intermediate forms where possible. For example, they may embed searching for the numbers
as part of each function (using templates or macros so little new code needs to be written). This
makes handling NumberSequences very fast.
Note: SUM expects a list of zero or more NumberSequences. In Excel, SUM() skips non-numbers
and does NOT convert boolean (Logical) or Text types. This means that A1+A2 is not the same as
SUM(A1:A2): if A1 or A2 are not a number, the "+" operator attempts to convert the value to a
number, while SUM() simply ignores the values.
Note: On November 17, 2005, Richard Kernick posted to the OpenFormula mailing list some results
from Pocket Excel, showing that Pocket Excel had subtly different semantics than Excel 2003. In
particular, in Pocket Excel references to a range are treated differently than a reference to a single
cell: explicit ranges work as usual for a conversion to a NumberSequence, EVEN when the range
contains only one cell, but non-explicit ranges containing only one cell force a conversion as with
the rules for Number. We have not identified any other implementation where this is true. Thus,
Pocket Excel does not quite meet the rules stated above. Here was Kernick's demonstration. First,
he set the following:
A1: =1=1 (boolean, TRUE)
A2: '2 (text, "2")
A3: 3 (numeric)
He then computed:
=A1+A2+A3 =6 (as expected)
=SUM(A1:A3) =3 (as expected)
=SUM(A1,A2,A3) =6 (different, and not meeting the rules above. Excel returns 3)
=SUM(A1:A1,A2:A2,A3:A3) =3 (same as Excel 2003, but different from above)
This demonstrates that references to a range is treated differently to a reference to a single cell in
Pocket Excel; this is a semantic variance with other implementations.
100414201 29 May 2010
Rationale: Converting to a NumberSequence is different than converting to a Number. Obviously, it
produces a list. NumberSequences ignore non-numbers, and an advantage of this rule is speed -
implementations can quickly determine what values to use. This means that users should convert
Text to Numbers if they want them used in a NumberSequence. Since OOo2 has no separate
Logical type, it has no way to implement a "skip Logicals" semantic.
6.3.8 Conversion to NumberSequenceList
Identical to Conversion to NumberSequence , with the addition that instead of a Reference also a
ReferenceList is accepted as argument. Each Reference in the list is converted to a
NumberSequence in the order of occurrence.
6.3.9 Conversion to DateSequence
Identical to Conversion to NumberSequence except that each element in the list represents a serial
date value of subtype Date.
6.3.10 Conversion to Complex Number
An evaluator may accept complex numbers as Text, Number, or a different distinguishable type.
If the value is:
Number that is not complex, use the Number with 0 as the imaginary part.
Text, attempt to convert to complex number using VALUE(). If it is a number that is not complex,
use it. If the text matches one of these patterns, accept it:
( [+- ] ?Number [+- ] ) ?Number[ij ]
[+- ] ?Number[ij ]
Logical, convert to Number and then handle as Number.
reference: Convert to Scalar, then use the rules above. If the reference is to an empty cell,
consider it equal to 0.
=SUM([.B3:.B5]
)
5 Conversion to NumberSequence ignores strings (in B3).
=SUM([.B3:.B1
0])
Error If a sequence includes Error, the result has Error.
6.3.11 Conversion to ComplexSequence
If the expected type is ComplexSequence, then if value is of type:
Number, Text, or Logical, handle as Conversion to Complex Number (creating a sequence of
length 1).
Reference, create a sequence of complex numbers from the values of the referenced cells that
only includes the values of type Number, Text, and Error. Empty cells are not included in a
complex number sequence. If the Logical type is a distinguished type from the Number type, it
100414201 29 May 2010
should not be included in the sequence of numbers; if the Logical type is not a distinguished
type, then such values will (of course) be included in the number sequence.
6.3.12 Conversion to Logical
If the expected type is Logical, then if value is of type:
Number, return TRUE() for nonzero and FALSE() for 0.
Text: The specific conversion is implementation-defined; an evaluator may return False, an
Error value, or the results of its attempt to convert the Text value (ignoring case) to a Logical
value (and fall back to False or Error if it fails to do so). Conversion depends on the actual
locale the evaluator runs in.
Note: A typical algorithm for converting a Text value to a Logical value is to determine if the text
matches the text "TRUE" ignoring case, then return TRUE, if the text matches the text "FALSE"
ignoring case, then return FALSE, otherwise return Error. Typically case is ignored no matter what
the value of HOST-CASE-SENSITIVE is. It is implementation-defined what happens if the text does
not match "TRUE" or "FALSE" in a case-sensitive manner- it may return a Logical value or an Error.
Note: Many Implementers recommend to generate an Error for an attempted conversion instead.
Logical, return it.
Reference, convert to scalar and then perform as above. If the reference is to an empty cell,
consider it FALSE().
=IF(5;TRUE();FALSE()) True Nonzero considered True.
=IF(0;TRUE();FALSE()) False Zero considered False.
Note: Semantics vary in current applications:
In Excel, Gnumeric and SheetToGo, the text "True" and "False" (ignoring case) are
automatically converted to True and False, else an Error.
On others, such as Lotus 1-2-3 Quattro Pro, and OpenOffice.org 2, this is handled like text to
number. So on Lotus 1-2-3 and Quattro Pro, text is always considered 0, so all text is
considered False.
On OpenOffice.org, inline text is converted following Excel-like rules, but referenced text is
always considered 0 and thus always False.
Additionally, conversion may differ for specific functions explicitly expecting values of type Logical,
such as AND and OR, where textual cell content may get ignored completely. The following table
illustrates the current behavior of some applications in an English language locale, assuming a cell
content of:
A1: "false" A2: "true" A3: "blah"
Expression OOo Gnumeric Kspread Excel
=IF(A1;TRUE();FALSE()) FALSE FALSE FALSE
=IF(A2;TRUE();FALSE()) FALSE TRUE TRUE
=IF(A3;TRUE();FALSE()) FALSE Error Error
100414201 29 May 2010
=IF("false";TRUE();FALSE()) FALSE FALSE FALSE
=IF("true";TRUE();FALSE()) TRUE TRUE TRUE
=IF("blah";TRUE();FALSE()) Error Error Error
=AND(A1) Error TRUE Error
=AND("false") Error TRUE FALSE
=AND("true") Error TRUE TRUE
=AND("blah") Error TRUE Error
=AND(A1;TRUE()) TRUE TRUE TRUE
=AND("false";TRUE()) Error TRUE FALSE
=AND("true";TRUE()) Error TRUE TRUE
=AND("blah";TRUE()) Error TRUE Error
TODO: add Kspread 1.6 behavior, which is different from 1.4; said to be similar to OOo with the
exception that inline text and and textual cell content is treated identical. Note that this is merely a
TODO for the annotations, not for the specification.
6.3.13 Conversion to LogicalSequence
If the expected type is LogicalSequence, then if value is of type:
Number or Logical, handle as Conversion to Logical (creating a sequence of length 1).
Reference, create a sequence of logical values from the values of the referenced cells that only
includes the values of type Logical and Error. If the Logical type is not a distinguished type, then
include values of type Number, converting each to a Logical value as described in Conversion
to Logical. Empty cells are not included in a LogicalSequence.
6.3.14 Conversion to Text
If the expected type is Text, then if value is of type:
Number, transform into Text (with no whitespace).
Text, return it.
Logical, return "TRUE" if it is TRUE and "FALSE" if it is false.
100414201 29 May 2010
Reference: perform conversion to scalar. If the referenced cell is empty, treat as an empty string
(a text value with length 0). Then perform as above.
Test Cases:
=a & [.B8] & b ab Blank cells are considered empty
=a & [.B4] & b a2b Numbers are converted into strings
6.3.15 Conversion to DateParam
If the expected type is the pseudotype DateParam, then if value is of type:
Number, return it.
Text, pass to DATEVALUE, and if non-Error, return it. If DATEVALUE would return an Error, an
evaluator may attempt to convert to a Number in other ways (such as by calling VALUE); this is
implementation-defined. If the evaluator cannot convert to Number, it returns an Error.
Logical, the result is implementation-defined, either a Number or Error
Reference: perform conversion to scalar, then perform as above. If the cell is empty, return 0.
6.3.16 Conversion to TimeParam
If the expected type is the pseudotype TimeParam, then if value is of type:
Number, return it.
Text, pass to TIMEVALUE, and if non-Error, return it. If TIMEVALUE would return an Error, an
evaluator may attempt to convert to a Number in other ways (such as by calling VALUE); this is
implementation-defined. If the evaluator cannot convert to Number, it returns an Error.
Logical, the result is implementation-defined, either a Number or Error
Reference: perform conversion to scalar, then perform as above. If the cell is empty, return 0.
6.4 Standard Operators
6.4.1 General
The functions defined under standard operators differ from other functions only on the basis of their
frequency of use. That frequency of use has lead to the colloquial terminology, standard operators.
6.4.2 Infix Operator "+"
Summary: Add two numbers.
Syntax: Number Left + Number Right
Returns: Number
Constraints: None
100414201 29 May 2010
Semantics: Adds numbers together.
anchor:infix-operator-+
Test Cases:
=1+2 3 Simple addition.
=[.B4]+[.B5] 5 2+3 is 5.
See also Infix Operator "-", Prefix Operator "+"
6.4.3 Infix Operator "-"
Summary: Subtract the second number from the first.
Syntax: Number Left - Number Right
Returns: Number
Constraints: None
Semantics: Subtracts one number from another number.
anchor:infix-operator--
Test Cases:
=3-1 2 Simple subtraction.
=[.B5]-[.B4] 1 3-2 is 1.
=5 - - 2 7 Subtraction can be combined with unary minus.
=5--2 7
Subtraction can be combined with unary minus, even without
spaces
=3-2+3 4 Left-to-right associative
=[.C8]-[.C7] 365 Difference of two dates is the number of days between them.
See also Infix Operator "+", Prefix Operator "-"
6.4.4 Infix Operator "*"
Summary: Multiply two numbers.
Syntax: Number Left * Number Right
Returns: Number
Constraints: None
Semantics: Multiplies numbers together.
100414201 29 May 2010
anchor:infix-operator-*
Test Cases:
=3*4 12 Simple multiplication.
=[.B4]*[.B5] 6 2*3 is 6.
=2+3*4 14 Multiplication has a higher precedence than addition.
See also Infix Operator "+", Infix Operator "/"
Note: Excel 2002 cannot use "*" to multiply two complex numbers together; instead, you have to
use IMPRODUCT. This is, of course, very inconvenient, but many other applications do the same
thing.
6.4.5 Infix Operator "/"
Summary: Divide the second number into the first.
Syntax: Number Left / Number Right
Returns: Number
Constraints: None
Semantics: Divides numbers. Dividing by zero returns an Error.
anchor:infix-operator-/
Test Cases:
=6/3 2 Simple division.
=144/3/2 24 Division is left-to-right associative
=6/3*2 4 Division and multiplication are left-to-right
=2+6/2 5 Division has a higher precedence than +.
=5/2 2.5 Simple division; fractional values are possible.
=1/0 Error Dividing by zero is not allowed.
See also Infix Operator "-", Infix Operator "*"
6.4.6 Infix Operator "^"
Summary: Exponentiation (Power).
Syntax: Number Left ^ Number Right
Returns: Number
100414201 29 May 2010
Constraints: NOT(AND(Left=0; Right=0)); Evaluators may evaluate expressions where OR(Left !=
0; Right != 0) evaluates to a non-Error value.
Semantics: Returns POWER(Left, Right).
anchor:infix-operator-^
Note: In Excel, 0^0 is Error (more specifically, #NUM!). Future versions of this specification may be
more specific. OpenOffice.org 2.4, as well as most mathematical texts, treat 0^0 as 1.
Test Cases:
=2^3 8 Simple exponentiation.
=9^0.5 3 Raising to the 0.5 power is the same as a square root.
=(-5)^3 -125 Must be able to accept Left < 0.
=4^-1 0.25 Must be able to accept Right < 0.
=5^0 1 Raising nonzero to the zeroth power results in 1.
=0^5 0 Raising zero to nonzero power results in 0.
=2+3*4^2 50 Precedence: ^ is higher than *, which is higher than +.
=-2^2 4 Unary "-" has a higher precedence than "^".
=(2^3)^2 64 8^2 is the square of 8
=2^(3^2) 512 2 to the ninth power
=2^3^2 64 ^ is left-associative, not right-associative
Rationale: This format has both ^ and POWER(), even though they are semantically the same
thing. Most spreadsheet implementations supply both, allowing users to use whichever
representation they prefer. Since this specification also supports both, it supports roundtripping the
user's preferred representation. Some users intentionally use ^ in some contexts, and POWER() in
others; without both representations it would be difficult to reconstruct a user's preferences.
There has been a lot of discussion about the precedence of binary "^" compared to unary "-". It was
felt that we (the formula subcommittee) could not be silent about precedence. The precedence of
prefix - being higher than infix ^ causes the expression -2^2 to compute as 4, and is shared by
Excel, OpenOffice.org 2, and Gnumeric. This is not universal; prefix "-" has a lower precedence on
Lotus 1-2-3, Quattro Pro, SheetToGo, and Excel's own Visual Basic (Walkenbach, 2004, pg. 579),
so these products will need to insert and remove parentheses when reading/writing expressions in
OpenFormula where this matters. Mandating anything else would greatly increase confusion and
create an unnecessary difference with actual practice in many spreadsheets still in use. The impact
of this is expected to be rare; many documents with formulas do not use ^ at all, and those who are
genuinely concerned about precedence are likely to parenthesize anyway. OpenFormula can also
be used for attribute draw:formula as defined in OpenDocument 1.0 section 9.5.5 and attribute
anim:formula as defined in 13.3.2; neither of these attributes includes an exponentiation operator
"^", so this issue of precedence causes no problem. (Note that they require "," as the function
separator, and have other requirements, as discussed later in this document).
Note that ^ is left-associative, not right-associative, because many spreadsheet applcations do
this: Excel 2000, OpenOffice.org 2.0, Lotus 1-2-3v9.8, SheetToGo, and Corel Quattro Pro 12. This is
not universal; Gnumeric 1.4.3 is right-associative. Kspread and wikiCalc were originally right-
associative, but after discussing associativity in the formula subcommittee, they agreed to switch to
100414201 29 May 2010
left-associativity. Having it be left-associative simplifies implementation; implementations can treat
all infix operators as left-associative.
See also Infix Operator "*", POWER
6.4.7 Infix Operator "="
Summary: Report if two values are equal
Syntax: Scalar Left = Scalar Right
Returns: Logical
Constraints: None
Semantics: Returns TRUE if two values are equal. If the values differ in type, return FALSE. If the
values are both Number, return TRUE if they are considered equal, else return FALSE. If they are
both Text, return TRUE if the two values match, else return FALSE. For Text values, if the
calculation setting HOST-CASE-SENSITIVE is false, text is compared but characters differencing
only in case are considered equal. If they are both Logicals, return TRUE if they are identical, else
return FALSE. Error values cannot be compared to a constant Error value to determine if that is the
same Error value.
Evaluators may approximate and test equality of two numeric values with an accuracy of the
magnitude of the given values scaled by the number of available bits in the mantissa, ignoring some
least significant bits and thus providing compensation for not exactly representable values.
The result of 1=TRUE() is FALSE for evaluators that implement a distinct Logical type and TRUE if
they don't.
anchor:infix-operator-=
Test Cases:
=1=1 True Trivial comparison.
=[.B4]=2 True References are converted into numbers, and then compared.
=1=0 False Trivial comparison.
=3=3.0001 False
Grossly wrong equality results are not acceptable. Spreadsheets
cannot "pass" automated tests by simply making "=" always
return TRUE when it's even slightly close.
="Hi"="Bye" False Trivial text comparison - no match.
=FALSE()=FALSE() True Can compare Logical values.
=TRUE()=FALSE() False Can compare Logical values.
="5"=5 False Different types are not equal.
=ISNA(NA()=NA()) True
If there's an error on either side, the result is an error -- even if
you're comparing the "same" error on both sides.
=Hi=HI True Note, this is only true if HOST-CASE-SENSITIVE is false.
100414201 29 May 2010
See also Infix Operator "<>"
Note: OpenOffice.org's equal operator performs case sensitive or case-insensitive matching,
depending on the setting of Tools.Options.Calc.Calculate "Case sensitive". By default, OOo2 is
case-sensitive, while most others are case-insensitive. In an OpenDocument file the setting is
stored in the HOST-CASE-SENSITIVE attribute.
Note: It'd be nice to devise a more specific definition of = for nearly equal numbers, but after
discussion we were unable to agree on one.
6.4.8 Infix Operator "<>"
Summary: Report if two values are not equal
Syntax: Any Left <> Any Right
Returns: Logical
Constraints: None
Semantics: Returns NOT(Left = Right) if Left and Right are not Error. For Text values, if the
calculation setting HOST-CASE-SENSITIVE is false, text is compared but characters differencing
only in case are considered equal.
If either Left and Right are an Error, the result is an Error; this operator cannot be used to determine
if two Errors are the same kind of Error.
Note: In some user interfaces the infix operator <> is displayed (or accepted) as != or .
anchor:infix-operator-<>
Test Cases:
=1<>1 False 1 really is 1.
=1<>2 True 1 is not 2.
=1<>"1" True Text and Number have different types.
="Hi"<>"HI" False
Text comparison ignores case distinctions. Note,
this is only true if HOST-CASE-SENSITIVE is
false.
=1/0=1/0 Error
This operator cannot compare error values to
determine if they are the same error. If either side
is an error, the result is an error.
See also Infix Operator "="
Note: We don't need many test cases here, because it's defined in terms of another function that is
tested.
6.4.9 Infix Operator Ordered Comparison ("<", "<=", ">", ">=")
Summary: Report if two values have the given order
100414201 29 May 2010
Syntax: Scalar Left op Scalar Right
where op is one of: "<", "<=", ">", or ">="
Returns: Logical
Constraints: None
Semantics: Returns TRUE if the two values are less than, less than or equal, greater than, or
greater than or equal (respectively). If both Left and Right are Numbers, compare them as numbers.
If both Left and Right are Text, compare them as text; if the calculation setting HOST-CASE-
SENSITIVE is false, text is compared but characters are compared ignoring case. If the values
are both Logical, convert both to Number and then compare as Number.
These functions return one of True, False, or an Error if Left and Right have different types, but it is
implementation-defined which of these results will be returned when the types differ.
Test Cases:
=5<6 True Trivial comparison.
=5<=6 True Trivial comparison.
=5>6 False Trivial comparison.
=5>=6 False Trivial comparison.
="A"<"B" True Trivial comparison of text.
="a"<"B" True True when HOST-CASE-SENSITIVE is false.
="AA">"A" True
Longer text is "larger" than shorter text, if they match in case-insensitive
way through to the end of the shorter text.
See also Infix Operator "<>", Infix Operator "="
6.4.10 Infix Operator "&"
Summary: Concatenate two strings.
Syntax: Text Left & Text Right
Returns: Text
Constraints: None
Semantics: Concatenates two text (string) values.
Note: The infix operator & is equivalent to CONCATENATE(Left,Right).
anchor:infix-operator-&
Test Cases:
="Hi " & "there" "Hi there" Simple concatenation.
100414201 29 May 2010
="H" & "" "H" Concatenating an empty string produces no change.
=-5&"b" -5b Unary - has higher precedence than &
=3&2-1 31 Binary - has higher precedence than &
See also Infix Operator "+", CONCATENATE
Rationale: As with exponentiation, both infix operator "&" and the CONCATENATE function are
required so that it is easy to preserve user preferences for representation.
6.4.11 Infix Operator Reference Range (":")
Summary: Computes an inclusive range given two references
Syntax: Reference Left : Reference Right
Returns: Reference
Constraints: None
Semantics: Takes two references and computes the range, that is, a reference to the smallest 3-
dimensional cube of cells that include both Left and Right including the cells on sheets positioned
between Left and Right. Left and Right need not be a single cell. For an expression such as
[.B4:.B5]:[.C5] the resulting range is B4:C5. In case Left and/or Right involve a reference list (result
of operator reference union), the range is computed and extended for each element of the list(s).
Note: For example, (a,b,c,d denoting one reference each)
(a~b):(c~d) computes a:b:c:d
determining the outermost front-top-left and rear-bottom-right corners.
Left and Right may also be defined names or the result of a function returning a reference, such as
INDIRECT.
anchor:infix-operator-reference-range-(:)
Test Cases:
=SUM([.B4:.B5]) 5
This isn't a range operation in ODF; it's just a cell specifier, with a
range embedded. The result is the same, though
=SUM([.B4]:
[.B5])
5 Simple range creation. Note the range OUTSIDE the [..] markers
=SUM(([.B4]:
[.C4]:[.C5]))
14
Range can extend an existing range, this is the same as
SUM([.B4:C5]))
See also Infix Operator Reference Union, Infix Operator Reference Intersection, INDIRECT
6.4.12 Infix Operator Reference Intersection ("!")
Summary: Compute the intersection of two references
Syntax: Reference Left ! Reference Right
100414201 29 May 2010
Returns: Reference
Constraints: None
Semantics: Takes two references and computes the intersection - a reference to the intersection of
cells in both Left and Right. If there are no cells in common, returns an Error.
If Left or Right are not of type Reference or ReferenceList, an Error shall be returned.
If Left and/or Right are reference lists (result of infix operator reference concatenation), the
intersection is computed for each combination of Left and Right, producing a reference list of
intersections.
Note: For example (a,b,c,d denoting one reference each):
(a~b)!(c~d) will compute (a!c)~(a!d)~(b!c)~(b!d)
If for a resulting intersection there are no cells in common, the element is ignored and omitted from
the result list. If for all intersections there are no cells in common and the result list is empty, Error
#NULL! is returned.
Note: Intersection is notated as "!" in OpenFormula format, but as a space character in some user
interfaces.
anchor:infix-operator-reference-intersection-(!)
Test Cases:
=SUM(([.B3:.B5]!
[.B5:.B6]))
3
Simple intersection; reference result is [.B5], and SUM simply
sums that one number (3) and returns it.
=4+(-[.B4]:[.C5]!
[.B4])
2
Range and intersection have a higher precedence than unary
minus.
See also Infix Operator Reference Union
6.4.13 Infix Operator Reference Concatenation ("~") (aka Union)
Summary: Concatenate two references
Syntax: Reference Left ~ Reference Right
Returns: ReferenceList
Constraints: None
Semantics: Takes two references and computes the "cell union", which is a concatenation of the
reference Left followed by the reference Right. This is not the same as a union in set theory;
duplicate references to cells are not removed. The resulting reference will have the number of
areas, as reported by AREAS, as AREAS(Left)+AREAS(Right).
Note: Concatenation is notated as "~" in OpenFormula format, but as a comma or + in some user
interfaces.
If Left or Right are not of type Reference or ReferenceList, an Error shall be returned.
anchor:infix-operator-reference-concatenation-(~)-(aka-Union)
Test Cases:
100414201 29 May 2010
=SUM([.B4:.B5]~[.B4:.
B5])
10
Simple union. Note that duplicate values are not removed, so
we have 2 + 3 + 2 + 3
=SUM((B4!
B4:C5~B4))
4
Range and intersection have a higher precedence than union.
Range has the highest precedence, then intersection, and then
finally union.
=SUM((B4!B4:
(C5~B4)))
2
Range and intersection have a higher precedence than union,
so use parentheses to force union first if necessary.
=SUM((B4:C5~B4!
B4))
16
Range has the highest precedence, then intersection, and then
finally union.
See also Infix Operator Reference Range, Infix Operator Reference Intersection
Rationale: OpenOffice .org 1.1.3 and 2.0.2 do not include this operator. However, other applications,
such as Microsoft Excel and Gnumeric, include this operation. In Excel this is represented using the
comma (",") character, the same symbol used as the parameter separator for function calls. This is a
very poor choice with a number of unfortunate ramifications. One problem is that concatetating cells
in a function parameter requires surrounding the cells with additional parentheses in Excel display
syntax. For example, AREAS(A1:A3,B2:B4) is a function call with two parameters, while
AREAS((A1:A3,B2:B4)) is a function call with one parameter. Another problem is that the comma
interferes with the use of "," as a decimal separator (as it is used in many locales) when using
traditional entry formats (which do not mark cell addresses with " .. "). Gnumeric uses "+" as the cell
concatenation operator in its display, but this has its own problems: it interferes with the use of "+"
as a matrix addition operator. There are many alternatives, e.g., other characters (such as "~", "|",
and "\"), or requiring a function syntax for this purpose. The character "_" would be a poor choice
because formula variables can also include this character in their name (complicating parsing when
"[..]" are not used; is B3_B2 a formula variable, or are B2 and B3 concatenated?). Because of these
issues, this specification uses "~" as the cell concatenation symbol.
6.4.14 Postfix Operator "%"
Summary: Divide the operand by 100
Syntax: Number Left %
Returns: Number
Constraints: None
Semantics: Computes Left / 100.
anchor:postfix-operator-%
Test Cases:
=50% 0.5 Simple percent value.
=20+50% 20.5
Percent does not change the meaning of other operations; this is not
30.
=3^200% 9 Percent has a higher precedence than ^
100414201 29 May 2010
=[.B4]% 0.02 Percent can be used as a general operator
Note: Implementations typically change the display format for values that are percentages. Many
have heuristics that treat percentages as a subtype of Number, and track which subtype results from
a computation, to automatically set the initial format of a number. These heuristics vary by
implementation (and by version of implementation), so they are not specified here.
Rationale: The % operator makes it easy to enter and display percentages. Spreadsheet
implementations use % as general operator (like ! for factorial in traditional mathematics), and do
not limit its use to being after a constant number. This standard defines it in its full generality, to
accurately reflect general consensus by spreadsheet implementors. Although this could be
represented as simply /100, doing so would make it unnecessarily difficult to round-trip formulas
while accurately reflecting user input.
See also Prefix Operator "-", Prefix Operator "+"
6.4.15 Prefix Operator "+"
Summary: No operation; returns its one argument.
Syntax: + Any Right
Returns: Any
Constraints: None
Semantics: Returns the value given to it. Note that this does not convert a value to the Number
type. In fact, it does no conversion at all of a Number, Logical, or Text value - it returns the same
Number, Logical, or Text value (respectively). The "+" applied to a reference may return the
reference, or an Error.
anchor:prefix-operator-+
Test Cases:
=+5 5 Numbers don't change
=+"Hello" "Hello" Does not convert a string to a number.
See also Infix Operator "+"
Note: In OOo2, SUM(+[.B4:.B5]) produces 5, because the "+" operator causes no change and just
returns the range reference. In Excel 2003, it produces a #VALUE! Error; prefix "+" is not permitted
on references.
6.4.16 Prefix Operator "-"
Summary: Negate its one argument.
Syntax: - Number Right
Returns: Number
Constraints: None
Semantics: Computes 0 - Right.
100414201 29 May 2010
anchor:prefix-operator--
Test Cases:
=-[.B4] -2 Negated 2 is -2.
=-2=(0-2) True Negative numbers are fine.
See also Infix Operator "-"
6.5 Matrix Functions
6.5.1 General
Matrix functions operate on matrices.
A matrix with M columns and N rows is defined by
A
MN
=
(
a
11
a
21
. a
M1
a
12
a
22
. a
M2

a
1N
a
2N
. a
MN
)
The dimension subscript may be omitted, if the context allows it, i.e.
A
MN
=A
. Matrices are
represented by upper case letters. The elements of a matrix are denoted by the corresponding
lower case letter and a subscript, which defines the column and the row.
Square matrices have the same amount of columns and rows, i.e.
M=N
.
Note: This matrix notation adopts the order of columns and rows in spreadsheet applications and
differs from the common order in matrix notations. The reversal here is simply because in cell
notations, the column identifier (the letters) come before the row indicator (the numbers). This could
be described differently so that more traditional notation could be used, but it was left this way
because some spreadsheet users will only be familiar with the letter-number system.
6.5.2 MDETERM
Summary: Calculates the determinant of a matrix.
Syntax: MDETERM( ForceArray Array matrix )
Returns: Number
Constraints: Only square matrices are allowed.
Semantics: Returns the determinant of the matrix. The determinant is defined by
det
(
A
NN)
=
P
sgn( P)
i=1
N
a
ip
i
100414201 29 May 2010
where P denotes a permutation of the numbers 1, 2, ..., n and
sgn( P)
is the sign of the
permutation, which is +1 for an even amount of permutations and -1 for an odd amount.
Matrices with a non-zero determinant are invertible.
anchor:MDETERM
Test Cases:
=MDETERM([.B4:.C5]) -2 MDETERM( B4:C5 ) = 2 * 5 4 * 3 = -2
=MDETERM([.A41:C43]) -1
=MDETERM([.B4:.B5]) Error Only square matrices are allowed.
=MDETERM([.A41:.B42]) 0 Singular matrix.
=MDETERM([.B4]) 2 A 1x1 matrix.
See also MINVERSE
Note: This function is called MDET in Excel (2002).
6.5.3 MINVERSE
Summary: Returns the inverse of a matrix.
Syntax: MINVERSE( ForceArray Array matrix )
Returns: Array
Constraints: Only square matrices are allowed.
Semantics: Calculates the inverse
A
1
of matrix A. The matrix A multiplied with its inverse
A
1
results in the unity matrix of the same dimension as A:
A
NN
A
NN
1
=A
NN
1
A
NN
=1
NN
Invertible matrices have a non-zero determinant. If the matrix is not invertible, this function should
return an Error value.
anchor:MINVERSE
Test Cases:
=MINVERSE([.B4:.C5]) =[.M41:.N42] Simple 2x2 matrix.
=MINVERSE([.A41:.C43]) =[.D41:.F43]
Should give an error for Gaussian
algorithms without pivoting.
=MINVERSE([.B4:.B5]) Error Only square matrices are allowed.
=MINVERSE([.A41:.B42]) Error Singular matrix.
=MINVERSE([.B4]) 0.5 1x1 matrix.
100414201 29 May 2010
See also MDETERM
Note: This function is called MINV in Excel (2002).
Note: Many implementations use the Gaussian algorithm. However, the Gaussian algorithm for the
determination of the determinant becomes unstable for some data sets if the implementation fails to
perform pivoting. Thus, we include a test case requiring pivoting, to make sure that this important
step is actually performed.
Note: If the matrix is not invertable, an Error must be returned. It could be argued that a division by
zero Error would fit best as the inverse of the determinant is involved in the calculation and it is zero
for non-invertible matrices. However, Gnumeric returns #NUM! and OOo Calc returns #DIV/0!
6.5.4 MMULT
Summary: Multiplies the matrices A and B.
Syntax: MMULT( ForceArray Array A ; ForceArray Array B )
Returns: Array
Constraints: COLUMNS(A)=ROWS(B)
Semantics: Returns the matrix product of the two matrices. The elements
c
mn
of the resulting
matrix
C
MN
=A
KM
B
NK
, are defined by:
c
mn
=
k=1
K
a
km
b
nk
anchor:MMULT
Test Cases:
=MMULT([.B4:.C5];[.B4:.C5])
{=16;28|
21;37}
TODO: Replace result with a range?
=MMULT([.A41:.C43];[.D41:.F43]) =[.J41:.L43]
Matrix multiplied with its inverse results
in a unity matrix.
=MMULT([.B4:.B5];[.A41:.C43]) Error Dimensions must match.
=MMULT([.B4:.C5];[.A41:.C42]) ={10;20;14|16;26;18}
Multiplication of matrices with different
dimension.
TODO: Replace result with a range?
6.5.5 MUNIT
Summary: Creates a unit matrix of a specified dimension N.
Syntax: MUNIT( Integer N )
100414201 29 May 2010
Returns: Array
Constraints: The dimension has to be greater than zero.
Semantics: Creates the unit matrix (identity matrix) of dimension N.
1
NN
=
(
1 0 . 0
0 1 . 0

0 0 . 1
)
anchor:MUNIT
Test Cases:
=MUNIT(2) =[.J41:.K42] 2x2 unity matrix
=MUNIT(3) =[.J41:.L43] 3x3 unity matrix
=MUNIT(0) Error Dimension has to greater than zero.
Note: Currently, this is function is only implemented in OOo Calc.
6.5.6 TRANSPOSE
Summary: Returns the transpose of a matrix.
Syntax: TRANSPOSE( Array A )
Returns: Array
Constraints: None
Semantics: Returns the transpose A
T
of a matrix A, i.e. rows and columns of the matrix are
exchanged.
A
MN
T
=
(
a
11
a
21
. a
N1
a
12
a
22
. a
N2

a
1M
a
2M
. a
NM
)
NM
anchor:TRANSPOSE
Test Cases:
=TRANSPOSE([.B4:.C5]) {=2;3|4;5} 2x2 matrix
=TRANSPOSE([.A41:.C43]) =[.G41:.I43] 3x3 matrix
=TRANSPOSE([.B4]) =[.B4] 1x1 matrix
=TRANSPOSE([.A41:.B43]) =[.G41:.I42] 2x3 matrix -> 3x2 matrix
100414201 29 May 2010
=TRANSPOSE([.A41:.C42]) =[.G41:.H43] 3x2 matrix -> 2x3 matrix
Note: This function is called MTRANS in Excel (2002).
6.6 Bit operation functions
6.6.1 General
Evaluators shall support unsigned integer values and results of at least 48 bits (values from 0 to
2^48-1 inclusive).
6.6.2 BITAND
Summary: Returns bitwise and of its parameters
Syntax: BITAND( Integer X ; Integer Y )
Returns: Number
Constraints: X 0, Y 0
Semantics: Returns bitwise and of its parameters. In the result, each bit position is 1 if and only if
all parameters' bits at that position are also 1; else it is 0.
anchor:BITAND
Test Cases:
=BITAND(12;10) 8
The bitwise and of 12 (binary 1100) and 10 (binary 1010) is 8
(binary 1000). This tests all 4 combinations of bits.
=BITAND(7;0) 0 0 is a valid value.
=BITAND(214748
3641;
2147483637)
214748363
3
Test for 31 bits. 2147483641 = 2^31-2-4-1 = 1111...11001 and
2147483637 = 2^31-2-8-1 = 1111...10101 (with 31 binary digits)
=BITAND(429496
7289;
4294967285)
429496728
1
Test for 32 bits. 4294967289 = 2^32-2-4-1 = 1111...11001 and
=BITAND(281474
976710649 ;
28147497671064
5)
281474976
710641
Test for 48 bits. 281474976710649 = 2^48-2-4-1 = 1111...11001 and
281474976710645 = 2^48-2-8-1 = 1111...10101 (with 48 binary
digits)
=BITAND(281474
976710655;
28147497671065
5)
281474976
710655
Test for 48 bits 2^48-1 ANDed with itself is 2^48-1
=BITAND(281474
976710655;
28147497671065
5)<>2814749767
True Test for 48 bits 2^48-1 ANDed with itself is not 2^48.
100414201 29 May 2010
10656
See also BITOR, BITXOR, AND
Note: If implementing in C, beware of converting this to a signed type, or to simply a long (on many
architectures a long is only 32 bits). This can be implemented in C if x and y are the input values of
type double, the result must in type double, and unsigned long long is supported and at least 48
bits wide, by using this C expression:
(double) (((unsigned long long) x) & ((unsigned long long) y))
This specification does not require that a list of NumberSequence be accepted, but that is a
plausible extension and may be added in a future edition of this specification. Thus, the text above
is carefully written so that applications which implement that extension have obvious guidance on
what the result should be.
Rationale: The first test case uses 12 (binary 1100) and 10 (binary 1010), because that tests all
four possible bit combinations. The other cases embed these numbers, but insert a binary 1 bit at
the top and bottom (to test that indeed the full range is implemented), as follows:
This function was originally implemented in Gnumeric, and since it is broadly useful it is included in
this specification. However, old versions of Gnumeric were limited in handling numbers up to 2^31-
1, with bit 32 was reserved as a sign bit. This was very restrictive; it limited calculations to 32 bits,
yet there was no reason that all applications should be so restricted. This restriction was not noted
in Gnumeric's documentation, so it is not clear it was intended by the original developers.
This specification requires support for at least up to 48 bits. This is because most implementations
use IEEE 754's 64-bit (double) representations for numbers. These have 53-bit mantissas, but
there seemed to be little need to handle exactly 53 bits, and requiring exactly that support might
cause implementation issues without user need. However, there are many applications where 48
bits of support are useful. Implementations that use 32-bit number representations can implement
this function with a more limited domain, but they will not be compliant with this specification. This
seemed reasonable, since users will want to know what range of numbers they can count on, and
this was the largest range that was both useful and relatively easy to implement.
6.6.3 BITLSHIFT
Summary: Returns left shift of value x by n bits (<<)
Syntax: BITLSHIFT( Integer x ; Integer n )
Returns: Number
Constraints: x 0
Semantics: Returns left shift of value x by n bit positions:
If n<0, return BITRSHIFT(x,-n)
100414201 29 May 2010
if n=0, return x
if n>0, return x*2^n
anchor:BITLSHIFT
Test Cases:
=BITLSHIFT(63;2
)
252 Simple left shift
=BITLSHIFT(63;0
)
63 A shift of 0 returns x unchanged
=BITLSHIFT(63;-
2)
15 A negative left shift is a right shift.
=BITLSHIFT(1;47
)
140737488
355328
1 << 47 is 2^47
=BITLSHIFT(214
7483641; 0)
214748364
1
Test for 31 bits. 2147483641 = 2^31-2-4-1 = 1111...11001 (with 31
binary digits)
=BITLSHIFT(429
4967289; 0)
429496728
9
binary digits)
=BITLSHIFT(281
474976710649 ;
0)
281474976
710649
Test for 48 bits. 281474976710649 = 2^48-2-4-1 = 1111...11001
(with 48 binary digits)
See also BITAND, BITXOR, BITRSHIFT
Note: If implementing in C, beware of converting x to a signed type, or to simply a long (on many
architectures a long is only 32 bits). Note that the results are unsigned.
6.6.4 BITOR
Summary: Returns bitwise or of its parameters
Syntax: BITOR( Integer X ; Integer Y )
Returns: Number
Semantics: Returns bitwise or of its parameters. In the result, each bit position is 1 if any of its
parameters' bits at that position are also 1; else it is 0.
anchor:BITOR
Test Cases:
=BITOR(12;10) 14
The bitwise or of 12 (binary 1100) and 10 (binary 1010) is 14
=BITOR(7;0) 7 0 is a valid value.
100414201 29 May 2010
=BITOR(2147483
641;
2147483637)
214748364
5
Test for 31 bits. 2147483641 = 2^31-2-4-1 = 1111...11001 and
=BITOR(4294967
289;
4294967285)
429496729
3
Test for 32 bits. 4294967289 = 2^32-2-4-1 = 1111...11001 and
=BITOR(2814749
76710649 ;
28147497671064
5)
281474976
710653
Test for 48 bits. 281474976710649 = 2^48-2-4-1 = 1111...11001 and
281474976710645 = 2^48-2-8-1 = 1111...10101 (with 48 binary
digits)
=BITOR(2814749
76710655;
28147497671065
5)
281474976
710655
Test for 48 bits 2^48-1 ORed with itself is 2^48-1
=BITOR(2814749
76710655;
28147497671065
5)<>2814749767
10656
True Test for 48 bits 2^48-1 ORed with itself is not 2^48.
See also BITAND, BITXOR, AND
Note: See BITAND. In C, the equivalent operator is |.
6.6.5 BITRSHIFT
Summary: Returns right shift of value x by n bits (>>)
Syntax: BITRSHIFT( Integer x ; Integer n )
Returns: Number
Constraints: x 0
Semantics: Returns right shift of value x by n bit positions:
If n<0, return BITLSHIFT(x,-n)
if n=0, return x
if n>0, return INT(x/2^n)
anchor:BITRSHIFT
Test Cases:
=BITRSHIFT(63;
2)
15 Simple right shift
=BITRSHIFT(63;
0)
63 A shift of 0 returns x unchanged
=BITRSHIFT(63;-
2)
252 A negative right shift is a left shift.
100414201 29 May 2010
=BITRSHIFT(63;
48)
0 If you shift all the 1 bits away, the result is 0
=BITRSHIFT(214
7483641; 0)
214748364
1
binary digits)
=BITRSHIFT(429
4967289; 0)
429496728
9
binary digits)
=BITRSHIFT(281
474976710649 ;
0)
281474976
710649
Test for 48 bits. 281474976710649 = 2^48-2-4-1 = 1111...11001
See also BITAND, BITXOR, BITLSHIFT
Note: If implementing in C, beware of converting x to a signed type, or to simply a long (on many
architectures a long is only 32 bits).
6.6.6 BITXOR
Summary: Returns bitwise exclusive or of its parameters
Syntax: BITXOR( Integer X ; Integer Y )
Returns: Number
Semantics: Returns bitwise exclusive or (xor) of its parameters. In the result, each bit position is 1
if one or the other parameters' bits at that position are 1; else it is 0.
anchor:BITXOR
Test Cases:
=BITXOR(12;10) 6
The bitwise xor of 12 (binary 1100) and 10 (binary 1010) is 6
=BITXOR(7;0) 7 0 is a valid value.
=BITXOR(21474
83641; 2)
214748364
3
binary digits)
=BITXOR(42949
67289; 2)
429496729
1
binary digits)
=BITXOR(28147
4976710649 ; 2)
281474976
710651
Test for 48 bits. 281474976710649 = 2^48-2-4-1 = 1111...11001
=BITXOR(28147
4976710655; 0)
281474976
710655
Test for 48 bits 2^48-1 XORed with 0 is 2^48-1
=BITXOR(28147
4976710655;
0)<>2814749767
10656
True Test for 48 bits 2^48-1 XORed with 0 is not 2^48.
100414201 29 May 2010
See also BITAND, BITOR, OR
Note: See BITAND. In C, the equivalent operator is ^.
6.7 Byte-position text functions
6.7.1 General
Byte-position text functions are like their equivalent ordinary text functions, but manipulate byte
positions rather than a count of the number of characters. Byte positions are integers that may
depend on the specific text representation used by the implementation. Byte positions are by
definition implementation-dependent and reliance upon them reduces interoperability.
The pseudotypes ByteLength and BytePosition are Integers, but their exact meanings and values
are not further defined by this specification.
Rationale: Implementations that store strings as double-byte characters can easily implement these
functions with numeric values exactly equal to Excel. Others will not, in particular, the byte positions
for UTF-8 formats will be different. Thus, we generalize these functions so that they report the byte
position (whatever that means for that particular implementation, which may or may not even
correspond to a real byte position!), and that it is NOT portable to do anything with byte positions
except pass them to other functions that expect byte positions.
This does not specifically require that byte positions of 0 be the starting position. This permits trivial
implementations that implement these byte-position functions as synonyms of their normal
functions, which in many circumstances is sufficient.
6.7.2 FINDB
Summary: Returns the starting position of a given text, using byte positions.
Syntax: FINDB( Text Search ; Text T [ ; BytePosition Start ] )
Returns: BytePosition
Semantics: The same as FIND, but using byte positions.
anchor:FINDB
Test Cases:
=MIDB(abcabc;
FINDB("b";"abcabc"); 1)
b Simple FINDB().
See also FIND , LEFTB , RIGHTB
6.7.3 LEFTB
Summary: Returns a selected number of text characters from the left, using a byte position.
Syntax: LEFTB( Text T [ ; ByteLength Length ] )
100414201 29 May 2010
Returns: Text
Semantics: As LEFT, but using a byte position.
anchor:LEFTB
Test Cases:
=LEFTB(abcabc;
FINDB("b";"abcabc"))
"bcabc" Simple LEFTB().
See also LEFT, RIGHT, RIGHTB
6.7.4 LENB
Summary: Returns the length of given text in units compatible with byte positions
Syntax: LENB( Text T )
Returns: ByteLength
Constraints: None.
Semantics: As LEN, but compatible with byte position values.
anchor:LENB
Test Cases:
=LEFTB(abcabc;
LENB("abcabc"))
abcabc
LENB produces results that can be used by
other byte position functions
See also LEN, LEFTB, RIGHTB
6.7.5 MIDB
Summary: Returns extracted text, given an original text, starting position using a byte position, and
length.
Syntax: MIDB( Text T ; BytePosition Start ; ByteLength Length )
Returns: Text
Constraints: Length >= 0.
Semantics: As MID, but using byte positions.
anchor:MIDB
Test Cases:
100414201 29 May 2010
=MIDB("123456789";FIN
DB(123456789;5);3)
"567" Simple use of MIDB.
See also MID, LEFTB, RIGHTB, REPLACEB
6.7.6 REPLACEB
Summary: Returns text where an old text is replaced with a new text, using byte positions.
Syntax: REPLACEB( Text T ; BytePosition Start ; ByteLength Len ; Text New )
Returns: Text
Semantics: As REPLACE, but using byte positions.
anchor:REPLACEB
Test Cases:
=REPLACEB("123456789";FIN
D(123456789;5);LENB(567);
"Q")
"1234Q89" Replacement text may have different length.
See also REPLACE, LEFTB, RIGHTB, MIDB, SUBSTITUTE
6.7.7 RIGHTB
Summary: Returns a selected number of text characters from the right, using byte position.
Syntax: RIGHTB( Text T [ ; ByteLength Length ] )
Returns: Text
Semantics: As RIGHT, but using byte positions.
anchor:RIGHTB
Test Cases:
=RIGHTB("Hello";LE
NB(lo))
"lo" Simple RIGHTB().
See also RIGHT, LEFTB
6.7.8 SEARCHB
Summary: Returns the starting position of a given text, using byte positions.
Syntax: SEARCHB( Text Search ; Text T [ ; BytePosition Start ] )
100414201 29 May 2010
Returns: BytePosition
Semantics: As SEARCH, but using byte positions.
anchor:SEARCHB
Test Cases:
=LEFTB(abcabc;
SEARCHB("b";"abcabc"))
bcabc Simple SEARCHB().
See also SEARCH, EXACT, FIND, FINDB
6.8 Complex Number Functions
6.8.1 General
Functions for complex numbers.
6.8.2 COMPLEX
Summary: Creates a complex number from a given real coefficient and imaginary coefficient.
Syntax: COMPLEX( Number Real ; Number Imaginary [ ; Text Suffix ] )
Returns: Complex
Constraints: None
Semantics: Constructs a complex number by the given coefficients. The third parameter Suffix is
optional, and should be either i or j. Upper case I or J are not accepted for the suffix
parameter.
anchor:COMPLEX
Test Cases:
=IMREAL(COMPLEX(1;-3)) 1 Real coefficient
=IMAGINARY(COMPLEX(0;-2;i)) -2
Imaginary coefficient with suffix
parameter
Note: The third parameter is optional. Note that it may get tossed in systems that support Complex
numbers as a full type (instead of just a string).
6.8.3 IMABS
Summary: Returns the absolute value of a complex number
Syntax: IMABS( Complex X )
Returns: Number
100414201 29 May 2010
Constraints: None
Semantics: If X=a+bi or X=a+bj, the absolute value =
.
a
2
+b
2
; if N=r(cos + isin), the absolute
value = r.
anchor:IMABS
Test Cases:
=IMABS(COMPLEX(4;3)) 5
=IMABS(COMPLEX(4;-3)) 5
=IMABS(COMPLEX(-4;3)) 5
=IMABS(COMPLEX(-4;-3)) 5
=IMABS([.B4]) 5 Get complex number from a cell
See also IMARGUMENT
Note: Excel uses Complex(0;0) as the default value for empty cell while OpenOffice.org 2.0 returns
Error in such cases.
6.8.4 IMAGINARY
Summary: Returns the imaginary coefficient of a complex number
Syntax: IMAGINARY( Complex X )
Returns: Number
Constraints: None
Semantics: If X=a+bi or X=a+bj, then the imaginary coefficient is b.
anchor:IMAGINARY
Test Cases:
=IMAGINARY(COMPLEX(4;-3)) -3
=IMAGINARY([.B4]) -3 Get complex number from a cell
See also IMREAL
Error in such case.
6.8.5 IMARGUMENT
Summary: Returns the complex argument of a complex number
Syntax: IMARGUMENT( Complex X )
100414201 29 May 2010
Returns: Number
Constraints: None
Semantics: If X=a+bi=r(cos + isin), a or b is not 0 and - < , then the complex argument is
. is expressed by radians. If X=0, then IMARGUMENT(X) is implementation-defined and either 0
or an error.
anchor:IMARGUMENT
Test Cases:
=IMARGUMENT(COMPLEX(3;4)) 0.927295218002
=IMARGUMENT(COMPLEX(3;-4)) -0.927295218002
=IMARGUMENT(COMPLEX(-3;4)) 2.214297435588
=IMARGUMENT(COMPLEX(-3;-4)) -2.214297435588
See also IMABS
Note: Both Excel and OpenOffice.org 2.0 returns Error when N is referenced by a empty cell.
6.8.6 IMCONJUGATE
Summary: Returns the complex conjugate of a complex number
Syntax: IMCONJUGATE( Complex X )
Returns: Complex
Constraints: None
Semantics: If X=a+bi, then the complex conjugate is a-bi.
anchor:IMCONJUGATE
Test Cases:
=IMABS(IMSUB( IMCONJUGATE(CO
MPLEX(3;4)); COMPLEX(3;-4) ))
0
=IMABS(IMSUB( IMCONJUGATE(CO
MPLEX(-3;-4)); COMPLEX(-3;4) ))
0
Error in such case.
6.8.7 IMCOS
Summary: Returns the cosine of a complex number
Syntax: IMCOS( Complex X )
100414201 29 May 2010
Returns: Complex
Constraints: None
Semantics: If X=a+bi, then cos(X)=cos(a)cosh(b)-sin(a)sinh(b)i.
anchor:IMCOS
Test Cases:
=IMREAL( IMCOS(COMPLEX(1;1)) ) 0.833730025131
=IMAGINARY( IMCOS(COMPLEX(1;1)
) )
-0.988897705763
See also IMSIN
Error in such case.
6.8.8 IMCOT
Summary: Returns the cotangent of a complex number
Syntax: IMCOT(Complex N)
Returns: Complex
Constraints: None
Semantics: Equivalent to the following (except N is computed only once):
IMDIV(IMCOS(N);IMSIN(N))
anchor:IMCOT
Test Cases:
=IMCOT(PI()/2) 0 Function exists
See also IMTAN
6.8.9 IMCSC
Summary: Returns the cosecant of a complex number
Syntax: IMCSC(Complex N)
Returns: Complex
Constraints: None
Semantics: Equivalent to the following:
100414201 29 May 2010
IMDIV(1;IMSIN(N))
anchor:IMCSC
Test Cases:
=IMCSC(PI()/2) 1 Function exists
See also IMSIN
6.8.10 IMCSCH
Summary: Returns the hyperbolic cosecant of a complex number
Syntax: IMCSCH( Complex N )
Returns: Number
Constraints: None
Semantics: Computes the hyperbolic cosecant. This is equivalent to:
IMDIV(1;IMSINH(N))
anchor:IMCSCH
Test Cases:
=IMCSCH(PI()/2) 1 Function exists
See also IMSINH, CSCH
6.8.11 IMDIV
Summary: Divides the second number into the first.
Syntax: IMDIV( Complex X ; Complex Y )
Returns: Complex
Constraints: None
Semantics: Given X=a+bi and Y=c+di, return the quotient
(ac+bd )+(bcad )i
(c
2
+d
2
)
Division by zero returns an Error.
anchor:IMDIV
Test Cases:
100414201 29 May 2010
=IMREAL( IMDIV(COMPLEX(5;3);
COMPLEX(1;-1)) )
1 Simple division
=IMAGINARY( IMDIV(COMPLEX(5;3);
COMPLEX(1;-1)) )
4 Simple division
See also IMDIV
6.8.12 IMEXP
Summary: Returns the exponent of e and a complex number.
Syntax: IMEXP( Complex X )
Returns: Complex
Constraints: None
Semantics: If X=a+bi, the result is
e
a
(cos b+i sin b)
.
anchor:IMEXP
Test Cases:
=IMREAL( IMEXP(COMPLEX(1;2)) ) -1.131204383757 Simple exponent
=IMAGINARY( IMEXP(COMPLEX(1;2))
)
2.471726672005 Simple exponent
See also IMLN
6.8.13 IMLN
Summary: Returns the natural logarithm of a complex number.
Syntax: IMLN( Complex X )
Returns: Complex
Constraints: None
Semantics: If X=r(cos + isin ) , is expressed by radians, then the natural logarithm is returned.
anchor:IMLN
Test Cases:
=IMREAL( IMLN(COMPLEX(1;2)) ) 0.804718956217
=IMAGINARY( IMLN(COMPLEX(1;2)) ) 1.107148717794
100414201 29 May 2010
See also IMEXP , IMLOG10
6.8.14 IMLOG10
Summary: Returns the common logarithm of a complex number.
Syntax: IMLOG10( Complex X )
Returns: Complex
Constraints: None
Semantics: If X=r(cos + isin ) , is expressed by radians, then the common logarithm is
returned.
anchor:IMLOG10
Test Cases:
=IMREAL(IMLOG10(COMPLEX(1;2)) ) 0.349485002168
=IMAGINARY( IMLOG10(COMPLEX(1;2
)) )
0.480828578784
See also IMLN , IMPOWER
6.8.15 IMLOG2
Summary: Returns the binary logarithm of a complex number.
Syntax: IMLOG2( Complex X )
Returns: Complex
Constraints: None
Semantics: If X=r(cos + isin ) , is expressed by radians, then the binary logarithm is returned.
anchor:IMLOG2
Test Cases:
=IMREAL( IMLOG2(COMPLEX(1;2)) ) 1.160964047444
=IMAGINARY(IMLOG2(COMPLEX(1;2)) ) 1.597277964688
See also IMLN , IMPOWER
6.8.16 IMPOWER
Summary: Returns the power of N and a complex number.
100414201 29 May 2010
Syntax: IMPOWER( Complex X ; Number n )
Returns: Complex
Constraints: None
Semantics: If X=a+bi=r(cos + isin ) , the result is
r
n
(cos n+i sin n)
.
anchor:IMPOWER
Test Cases:
=IMREAL( IMPOWER(COMPLEX(-
1;2); 3) )
11
=IMAGINARY( IMPOWER(COMPLEX(-
1;2); 3) )
-2
See also IMEXP
6.8.17 IMPRODUCT
Summary: Returns the product of complex numbers.
Syntax: IMPRODUCT( { ComplexSequence N }+ )
Returns: Complex
Constraints: None
Semantics: Multiply the complex numbers together. Given two complex numbers X=a+bi and
Y=c+di, the product X*Y = (ac-bd) + (ad+bc)i
anchor:IMPRODUCT
Test Cases:
=IMREAL( IMPRODUCT(COMPLEX(1;
2); COMPLEX(-1;-2); COMPLEX(2;-
3) ))
-6
=IMAGINARY( IMPRODUCT(COMPLE
X(1;2); COMPLEX(-1;-2);
COMPLEX(2;-3) ))
-17
See also IMDIV
6.8.18 IMREAL
Summary: Returns the real coefficient of a complex number
Syntax: IMREAL( Complex N )
100414201 29 May 2010
Returns: Number
Constraints: None
Semantics: If N=a+bi or N=a+bj, then the real coefficient is a.
anchor:IMREAL
Test Cases:
=IMREAL(COMPLEX(4;-3)) 4
=IMABS([.B4]) 4 Get complex number from a cell
See also IMAGINARY
Error in such case.
6.8.19 IMSIN
Summary: Returns the sine of a complex number
Syntax: IMSIN( Complex N )
Returns: Complex
Constraints: None
Semantics: If N=a+bi, then sin(N)=sin(a)cosh(b)-cos(a)sinh(b)i.
anchor:IMSIN
Test Cases:
=IMREAL( IMSIN(COMPLEX(1;1)) ) 1.298457581416
=IMAGINARY( IMSIN(COMPLEX(1;1))
)
0.634963914785
See also IMCOS
Error in such case.
6.8.20 IMSEC
Summary: Returns the secant of a complex number
Syntax: IMSEC(Complex N)
Returns: Complex
Constraints: None
100414201 29 May 2010
Semantics: Equivalent to the following:
IMDIV(1;IMCOS(N))
anchor:IMSEC
Test Cases:
=IMCSC(PI()/2) 1 Function exists
See also IMCOS
6.8.21 IMSECH
Summary: Returns the hyperbolic secant of a complex number
Syntax: IMSECH( Complex N )
Returns: Number
Constraints: None
Semantics: Computes the hyperbolic secant. This is equivalent to:
IMDIV(1;IMCOSH(N))
anchor:IMSECH
Test Cases:
=IMSECH(0) 1 Function exists
See also IMCOSH, SECH
6.8.22 IMSQRT
Summary: Returns the square root of a complex number
Syntax: IMSQRT( Complex N )
Returns: Complex
Constraints: None
Semantics: If N=r(cos + isin), is expressed by radians, then the square root of N is returned.
anchor:IMSQRT
Test Cases:
=IMREAL(IMSQRT(COMPLEX(1;-2))) 1.272019649514
100414201 29 May 2010
=IMAGINARY(IMSQRT(COMPLEX(1;-2))) -0,786151377757
See also IMPOWER
6.8.23 IMSUB
Summary: Subtracts the second complex number from the first.
Syntax: IMSUB( Complex X ; Complex Y )
Returns: Complex
Constraints: None
Semantics: Subtract complex number Y from X.
anchor:IMSUB
Test Cases:
=IMREAL( IMSUB(COMPLEX(5;3);
COMPLEX(3;2))
2 Simple complex number subtraction.
=IMAGINARY( IMSUB(COMPLEX(5;3);
COMPLEX(3;2))
1 Simple complex number subtraction.
=IMREAL(IMSUB("5-3i";"2i")) 5
=IMAGINARY(IMSUB("5-3i";"2i")) -5
See also IMSUM
6.8.24 IMSUM
Summary: Sums (add) a set of complex numbers, including all numbers in ranges
Syntax: IMSUM( { ComplexSequence N }+ )
Returns: Complex Number
Constraints: None
Semantics: Adds complex numbers together. Text that cannot be converted to a complex number is
ignored.
It is implementation-defined what happens if this function is given zero parameters; an evaluator
may either produce an Error or the Number 0 if it is given zero parameters.
anchor:IMSUM
Test Cases:
100414201 29 May 2010
=IMREAL(IMSUM(COMPLEX(1;2);
COMPLEX(2;3) ))
2 Simple sum with one parameter
=IMAGINARY(IMSUM(COMPLEX(1;2);
COMPLEX(2;3) ))
5 Sum with two parameters
=IMREAL( IMSUM(COMPLEX(1;2);
[.B4:.B5]))
6
Sum with range parameters. Here
assumes that, [.B4] contains
COMPLEX(2;3), and [.B5] contains
COMPLEX(3;4)
=IMAGINARY( IMSUM(COMPLEX(1;2);
[.B4:.B5]))
9
Sum with range parameters. Here
assumes that, [.B4] contains
COMPLEX(2;3), and [.B5] contains
COMPLEX(3;4)
See also IMSUB
Note: Both Excel and OpenOffice.org 2.0 use COMPLEX(0;0) as the default value for empty cell.
TODO: .B4 and .B5 actually DO NOT contain the numbers claimed, and therefore these tests will
always fail. Need to allocate cells with complex numbers, and then fix the test cases.
6.8.25 IMTAN
Summary: Returns the tangent of a complex number
Syntax: IMTAN(Complex N)
Returns: Complex
Constraints: None
Semantics: Equivalent to the following (except N is computed only once):
IMDIV(IMSIN(N);IMCOS(N))
anchor:IMTAN
Test Cases:
=IMTAN(0) 0 IMTAN exists
See also IMSIN, IMCOS, IMCOT
6.9 Database Functions
6.9.1 General
Database functions use the variables, Database 4.11.8, Field 4.11.9, and Criteria 4.11.10.
The results of database functions may change when the values of the HOST-USE-REGULAR-
EXPRESSIONS or HOST-USE-WILDCARDS properties change. 3.4
100414201 29 May 2010
6.9.2 DAVERAGE
Summary: Finds the average of values in a given field from the records (rows) in a database that
match a search criteria.
Syntax: DAVERAGE( Database D ; Field F ; Criteria C )
Returns: Number
Constraints: Nonef
Semantics: Perform AVERAGE on data records in database D field F that match criteria C.
anchor:DAVERAGE
Test Cases:
=DAVERAGE(TESTDB; "TestID"; [.B36:.B37]) 48 Simple criteria.
See also AVERAGE, COUNT, DSUM, DCOUNT, SUM
6.9.3 DCOUNT
Summary: Counts the number of records (rows) in a database that match a search criteria and
contain numerical values.
Syntax: DCOUNT( Database D ; Field F ; Criteria C )
Returns: Number
Constraints: None
Semantics: Perform COUNT on data records in database D field F that match criteria C.
anchor:DCOUNT
Test Cases:
=DCOUNT(TESTDB; "Bright Stars"; [.B36:.B37]) 2 Simple criteria.
See also COUNT, COUNTA, DCOUNTA, DSUM
6.9.4 DCOUNTA
Summary: Counts the number of records (rows) in a database that match a search criteria and
contain values (as COUNTA).
Syntax: DCOUNTA( Database D ; Field F ; Criteria C )
Returns: Number
Constraints: None
Semantics: Perform COUNTA on data records in database D field F that match criteria C.
100414201 29 May 2010
anchor:DCOUNTA
Test Cases:
=DCOUNTA(TESTDB; "Bright Stars"; [.B36:.B37]) 2 Simple criteria.
See also COUNT, COUNTA, DCOUNT, DSUM
Note: KSpread 1.4.2 DCOUNTA does not work if the Criteria are Logical values. E.G., you can't say
"Correct?" with a boolean value below, and expect it to match boolean values in the records. If you
change them all to Numbers (e.g., 0 or 1), so that the Criteria to match is a number and the
True/False computed values become 1 or 0, KSpread works fine.
Also, if KSpread's DCOUNTA has as a Criteria that it must match "1", for some odd reason it also
matches 1/0 (Infinity). Note that in KSpread, 1/0 is not the same as MOD(3;0); the former is
"Infinity", while the latter is #DIV/0! (other spreadsheets consider them the same Error).
6.9.5 DGET
Summary: Gets the single value in the field from the single record (row) in a database that matches
a search criteria.
Syntax: DGET( Database D ; Field F ; Criteria C )
Returns: Number
Constraints: None
Semantics: Extracts the value in field F of the one data record in database D that matches criteria
C. If no records match, or more than one matches, it returns an Error.
anchor:DGET
Test Cases:
=DGET(TESTDB; "TestID";
[.D36:.D37])
2048 Simple criteria, single row answer.
=DGET(TESTDB; "TestID";
[.B36:.B37])
Error
Simple criteria, but multiple row answers so an error
is returned.
See also DMAX, DMIN, DSUM
6.9.6 DMAX
Summary: Finds the maximum value in a given field from the records (rows) in a database that
Syntax: DMAX( Database D ; Field F ; Criteria C )
Returns: Number
Constraints: None
100414201 29 May 2010
Semantics: Perform MAX on only the data records in database D field F that match criteria C.
anchor:DMAX
Test Cases:
=DMAX(TESTDB; "TestID"; [.B36:.B37]) 64 Simple criteria.
See also MAX, DMIN, MIN
6.9.7 DMIN
Summary: Finds the minimum value in a given field from the records (rows) in a database that
Syntax: DMIN( Database D ; Field F ; Criteria C )
Returns: Number
Constraints: None
Semantics: Perform MIN on only the data records in database D field F that match criteria C.
anchor:DMIN
Test Cases:
=DMIN(TESTDB; "TestID"; [.B36:.B37]) 32 Simple criteria.
See also MIN, DMAX, MAX
6.9.8 DPRODUCT
Summary: Finds the product of values in a given field from the records (rows) in a database that
Syntax: DPRODUCT( Database D ; Field F ; Criteria C )
Returns: Number
Constraints: None
Semantics: Multiply together only the data records in database D field F that match criteria C.
anchor:DPRODUCT
Test Cases:
=DPRODUCT(TESTDB; "TestID"; [.B36:.B37]) 2048 Simple criteria.
100414201 29 May 2010
See also SUM, DSUM
6.9.9 DSTDEV
Summary: Finds the sample standard deviation in a given field from the records (rows) in a
database that match a search criteria.
Syntax: DSTDEV( Database D ; Field F ; Criteria C )
Returns: Number
Constraints: None
Semantics: Perform STDEV on only the data records in database D field F that match criteria C.
anchor:DSTDEV
Test Cases:
=DSTDEV(TESTDB; "TestID"; [.B36:.B37])
22.6274169
979695
Simple criteria.
See also STDEV, DSTDEVP
6.9.10 DSTDEVP
Summary: Finds the population standard deviation in a given field from the records (rows) in a
database that match a search criteria.
Syntax: DSTDEVP( Database D ; Field F ; Criteria C )
Returns: Number
Constraints: None
Semantics: Perform STDEVP on only the data records in database D field F that match criteria C.
anchor:DSTDEVP
Test Cases:
=DSTDEVP(TESTDB; "TestID"; [.B36:.B37]) 16 Simple criteria.
See also STDEVP, DSTDEV
6.9.11 DSUM
Summary: Finds the sum of values in a given field from the records (rows) in a database that
Syntax: DSUM( Database D ; Field F ; Criteria C )
Returns: Number
100414201 29 May 2010
Constraints: None
Semantics: Perform SUM on only the data records in database D field F that match criteria C.
anchor:DSUM
Test Cases:
=DSUM(TESTDB; "TestID"; [.B36:.B37]) 96 Simple criteria.
See also SUM, DMIN, DMAX
6.9.12 DVAR
Summary: Finds the sample variance in a given field from the records (rows) in a database that
Syntax: DVAR( Database D ; Field F ; Criteria C )
Returns: Number
Constraints: None
Semantics: Perform VAR on only the data records in database D field F that match criteria C.
anchor:DVAR
Test Cases:
=DVAR(TESTDB; "TestID"; [.B36:.B37]) 512 Simple criteria.
See also VAR, DVARP
6.9.13 DVARP
Summary: Finds the population variance in a given field from the records (rows) in a database that
Syntax: DVARP( Database D ; Field F ; Criteria C )
Returns: Number
Constraints: None
Semantics: Perform VARP on only the data records in database D field F that match criteria C.
anchor:DVARP
Test Cases:
=DVARP(TESTDB; "TestID"; [.B36:.B37]) 256 Simple criteria.
100414201 29 May 2010
See also VARP, DVAR
6.10 Date and Time Functions
6.10.1 General
6.10.2 DATE
Summary: Constructs a date from year, month, and day of month.
Syntax: DATE( Integer Year ; Integer Month ; Integer Day )
Returns: Date
Constraints: 1904 <= Year <= 9956; 1 <= Month <= 12; 1 <= Day <= 31; Evaluators may evaluate
expressions that do no meet this constraint.
Semantics: This computes the date's serial number given Year, Month, and Day of the Gregorian
calendar. Fractional values are truncated. Month > 12 and Day > days of Month will roll over the
date, computing the result by adding months and days as necessary. The value of the serial number
depends on the current epoch.
anchor:DATE
Test Cases:
Expression Result Comments
=DATE(2005;1;31)=[.C7] True Simple date value.
=DATE(2005;12;31)-
DATE(1904;1;1)
37255 Date differences are computed correctly.
=DATE(2004;2;29)=DATE(2004;2;2
8)+1
True 2004 was a leap year.
=DATE(2000;2;29)=DATE(2000;2;2
8)+1
True 2000 was a leap year.
=DATE(2005;3;1)=DATE(2005;2;28
)+1
True 2005 was not a leap year.
=DATE(2017.5; 1; 2)=DATE(2017;
1; 2)
True Fractional values for year are truncated
=DATE(2006; 2.5; 3)=DATE(2006;
2; 3)
True Fractional values for month are truncated
=DATE(2006; 1; 3.5)=DATE(2006;
1; 3)
True Fractional values for day are truncated
=DATE(2006; 13; 3)=DATE(2007;
1; 3)
True Months > 12 roll over to year
=DATE(2006; 1; 32)=DATE(2006;
2; 1)
True Days greater than month limit roll over to month
100414201 29 May 2010
=DATE(2006; 25;
34)=DATE(2008;2;3)
True Days and months roll over transitively
=DATE(2006;-1;
1)=DATE(2005;11;1)
True Negative months roll year backward
=DATE(2006;4;-
1)=DATE(2006;3;30)
True Negative days roll month backward
=DATE(2006;-4;-
1)=DATE(2005;7;30)
True
Negative days and months roll backward
transitively
=DATE(2003;2;29)=DATE(2003;3;1
)
True Non-leap year rolls forward
See also TIME, DATEVALUE
Rationale: Date values are allowed to wrap around because this provides a convenient way to
compute the next value. This is particularly handy for months, and since it rolls over for months, it
is better for consistency's sake to do the same with days. Excel, OpenOffice.org, and Gnumeric all
perform this wrap-around. Kspread 1.4.2 and Lotus1-2-3v9 limit values to "reasonable" values, and
do not accept and roll over out-of-range values; these programs would require changes to meet this
requirement, but since valid spreadsheet data for these systems would normally not have them
anyway, this should be an upwards-compatible change for them.
Note:
OOo gives an Error for dates less than 15 October 1582, the first day of the Gregorian calendar.
Many implementations do not accept (or process correctly) dates before 1904-01-01 or 1900-03-01.
Some implementations do not allow negative year numbers for the DATE() function, though that is a
plausible extension and is not forbidden by this specification.
6.10.3 DATEDIF
Summary: Returns the difference in years, months, or days of two date numbers.
Syntax: DATEDIF( DateParam StartDate ; DateParam EndDate ; Text Format )
Returns: Number
Constraints: None
Semantics: Compute difference of StartDate and EndDate, in the units given by Format.
The Format is a code from the following table, entered as text, that specifies the format you want
the result of DATEDIF to have.
Table 5 - DATEDIF
format Returns the number of
y Years
m Months. If there is not a complete
month between the dates, 0 will be
returned.
100414201 29 May 2010
d Days
md Days, ignoring months and years
ym Months, ignoring years
yd Days, ignoring years
anchor:DATEDIF
Test Cases:
=DATEDIF(DATE(1990;2;15);
DATE(1993;9;15); "y")
3
DATE(1993;9;15); "m")
43
The number of months between February 15,
1990, and September 15, 1993.
DATE(1993;9;15); "d")
1308
DATE(1993;9;15); "md")
0
The day of the month for both start-date and end-
date is the 15th
DATE(1993;9;15); "ym")
7
The number of months between February and
September.
DATE(1993;9;15); "yd")
212
See also DAYS360, DAYS, Infix Operator -
6.10.4 DATEVALUE
Summary: Returns the date serial number from given text.
Syntax: DATEVALUE( Text D )
Returns: Date
Constraints: None
Semantics: This computes the serial number of the text string D, using the current locale. This
function shall accept ISO date format (YYYY-MM-DD), which is locale-independent. It is
semantically equal VALUE(Date) if Date has a date format, since text matching a date format is
automatically converted to a serial number when used as a Number. If the text of D has a combined
date and time format, e.g. YYYY-MM-DD HH:MM:SS, the integer part of the date serial number is
returned. If the text of Date does not have a date or time format, an evaluator may return an Error.
See VALUE for more information on date formats. The value of the serial number depends on the
current epoch.
anchor:DATEVALUE
Test Cases:
100414201 29 May 2010
=DATEVALUE("2004-12-25")=DATE(2004;12;25) True DATEVALUE
=DATEVALUE("2004-12-25
12:34:56")=DATE(2004;12;25)
True
Only the integer
part is returned
Note: Excel 2000 doesn't allow the input to be a reference, but Excel 2002 does (it allows normal
operations). DATEVALUE is widespread, but is not available in SheetToGo. Other than the test for
"date-formattedness", which you can't count on, this is basically the same as VALUE().
OOo2 returns the full integer+fractional number if passed a combined date and time string.
Gnumeric 1.4 does not allow a combined date and time string.
See also TIME, DATE, TIMEVALUE, VALUE
6.10.5 DAY
Summary: Returns the day from a date.
Syntax: DAY( DateParam Date )
Returns: Number
Constraints: None
Semantics: Returns the day portion of a date.
anchor:DAY
Test Cases:
=DAY(DATE(2006;5;21)) 21 Basic extraction.
=DAY(DATE(2006;12;15)) 15
See also MONTH, YEAR
6.10.6 DAYS
Summary: Returns the number of days between two dates
Syntax: DAYS( DateParam EndDate ; DateParam StartDate )
Returns: Number
Constraints: None
Semantics: Returns the number of days between two dates. If StartDate and EndDate are
Numbers, this is EndDate StartDate. If they are both Text, this is DATEVALUE(StartDate)
DATEVALUE(EndDate).
anchor:DAYS
Test Cases:
100414201 29 May 2010
=DAYS(DATE(1993;4;16);
DATE(1993;9;25))
-162
Simple comparison,
note that negative
results are allowed.
See also DATEDIF, DAYS360, MONTH, YEAR, Infix Operator -
Note: Lotus 1-2-3v9.8 has a function named DAYS but with different semantics. It supports an
optional Basis parameter with many different options. Without the optional parameter, it defaults to
a 30/360 basis, so in Lotus 1-2-3v9.8 DAYS(DATE(1993;4;16); DATE(1993;9;25)) computes -159,
not -162. OpenOffice.org computes -162 for DAYS, as shown above.
6.10.7 DAYS360
Summary: Returns the number of days between two dates using the 360-day year
Syntax: DAYS360( DateParam StartDate ; DateParam EndDate [ ; Integer Method = 0 ] )
Returns: Number
Constraints: 0 <= Method <= 1
Semantics: Returns the number of days between two dates, using the 360-day year system (12 30-
month days). In this system, February always has 30 days and there are no leap years.
If method is 0, it uses the National Association of Securities Dealers (NASD) method, also known as
the U.S. method. If the method is 1, the European method is used.
The US/NASD Method (30US/360):
1. Truncate date values, set sign=1.
2. If StartDate's day-of-month is 31, it is changed to 30.
3. Otherwise, if StartDate's day-of-month is the last day of February, it is changed to 30.
4. If EndDate's day-of-month is 31 and StartDate's day-of-month is 30 (after having applied a
change for #2 or #3, if necessary), EndDate's day-of-month is changed to 30.
Note: This calculation is slightly different from Basis 0 (4.11.6 Basis). Dates are never
swapped.
The European Method (30E/360):
1. Truncate date values, set sign=1.
2. If StartDate is after EndDate then swap dates and set sign=-1.
3. If StartDate's day-of-month is 31, it is changed to 30.
4. If EndDate's day-of-month is 31, it is changed to 30.
Note: Days in February are never changed.
Note: This calculation is identical to Basis 4 (4.11.6 Basis)
For both methods the value then returned is
sign * ((EndDate.year*360 + EndDate.month*30 + EndDate.day) - (StartDate.year*360 +
StartDate.month*30 + StartDate.day))
anchor:DAYS360
100414201 29 May 2010
Test Cases:
=DAYS360(DATE(1993;4;
16); DATE(1993;9;25))
159 Simple comparison
See also DAYS, DATEDIF
Note: There is a bug in Excel versions 97 to 2007 involving dates with 28
th
February, e.g.
DAYS360(DATE(2006;2;28);DATE(2007;2;28)) returns a value of 358 instead of the expected 360 (a
full year). OOoCalc3.0 replicates this behavior for interoperability, see
http://qa.openoffice.org/issues/show_bug.cgi?id=84934. See also
http://en.wikipedia.org/wiki/360_day_calendar.
6.10.8 EDATE
Summary: Returns the serial number of a given date when MonthAdd months is added
Syntax: EDATE( DateParam StartDate ; Number MonthAdd )
Returns: Number
Constraints: None
Semantics: First truncate StartDate and MonthAdd, then add MonthAdd number of months.
MonthAdd can be positive, negative, or 0; if zero, the number representing StartDate (in the current
epoch) is returned.
If after adding the given number of months, the day of month in the new month is larger than the
number of days in the given month, the day of month is adjusted to the last day of the new month.
Then the serial number of that date is returned.
anchor:EDATE
Test Cases:
=EDATE(DATE(2006;1;1;0)=DATE
(2006;1;1)
True If zero, unchanged.
=EDATE(DATE(2006;1;1);0)=DAT
E(2006;1;1)
True
You can pass strings or serial numbers to
EDATE
=EDATE(DATE(2006;1;1);2)=DAT
E(2006;3;1)
True
=EDATE(DATE(2006;1;1);-
2)=DATE(2005;11;1)
True
=EDATE(DATE(2006;3;31);-
1)=DATE(2006;2;28)
True
2006 is not a leap year. Last day of March,
going back to February
=EDATE(DATE(2000;4;30);-
2)=DATE(2002;2;29)
True
2000 was a leap year, so the end of February is
the 29th
=EDATE(DATE(2000;4;5);24)=DA True EDATE isn't limited to 12 months
100414201 29 May 2010
TE(2002;4;5)
See also DAYS, DATEDIF, EOMONTH
Note: This tends to be an add-on function. It is an add-on for both Excel and OpenOffice.org 2.
6.10.9 EOMONTH
Summary: Returns the serial number of the end of a month, given date plus MonthAdd months
Syntax: EOMONTH( DateParam StartDate ; Integer MonthAdd )
Returns: Number
Constraints: None
Semantics: First truncate StartDate and MonthAdd, then add MonthAdd number of months.
MonthAdd can be positive, negative, or 0. Then return the serial number representing the end of that
month. Due to the semantics of this function, the value of DAY(StartDate) is irrelevant.
anchor:EOMONTH
Test Cases:
=EOMONTH(DATE(2006;1;1);0)=D
ATE(2006;1;31)
True
If zero, unchanged just returns end of that
date's month. (January in this case)
ATE(2006;3;31)
True End of month of March is March 31.
=EOMONTH(DATE(2006;1;1);-
2)=DATE(2005;11;30)
True Nov. 30 is the last day of November
1)=DATE(2006;2;28)
True
2006 is not a leap year. Last day of February is
Feb. 28.
2)=DATE(2000;2;29)
True
2000 was a leap year, so the end of February is
the 29th
=EOMONTH(DATE(2000;4;5);24)=
DATE(2002;4;30)
True Not limited to 12 months, and this tests April
ATE(2002;5;31)
End of May is May 31
ATE(2002;6;30)
June 30
ATE(2002;7;31)
July 31
ATE(2002;8;31)
August 31
ATE(2002;9;30)
Sep 30
100414201 29 May 2010
ATE(2002;10;31)
Oct 31
=EOMONTH(DATE(2006;1;5);10)=
DATE(2002;11;30)
Nov. 30
=EOMONTH(DATE(2006;1;5);11)=
DATE(2002;12;31)
Dec. 31
See also EDATE
Note: This tends to be an add-on function. It is an add-on for both Excel and OpenOffice.org 2.
6.10.10 HOUR
Summary: Extracts the hour (0 through 23) from a time.
Syntax: HOUR( TimeParam T )
Returns: Number
Constraints: None
Semantics: Extract from T the hour value, 0 through 23, as per a 24-hour clock. This is equal to:
DayFraction=(T-INT(T))
Hour=INT(DayFraction*24)
anchor:HOUR
Test Cases:
=HOUR(5/24) 5 5/24ths of a day is 5 hours, aka 5AM.
=HOUR(5/24-1/(24*60*60)) 4 A second before 5AM, it's 4AM.
=HOUR("14:00") 14 TimeParam accepts text
See also MONTH, DAY, MINUTE, SECOND
6.10.11 ISOWEEKNUM
Summary: Determines the ISO week number of the year for a given date.
Syntax: ISOWEEKNUM( DateParam Date [ ; Integer Mode = 2 ] )
Returns: Number
Constraints: None
Semantics: Returns the number of the ISO 8601 week in the year for the given date. Note that this
is not the conventional week number used by some applications (for that, see WEEKNUM). In this
system, week number 1 of any year is the week that contains January 4, because (1) Monday is
100414201 29 May 2010
considered the first day of the week, and (2) a week that lies partly in one year and partly in another
is assigned a number in the year in which most of its days lie.
Mode determines the starting day of the week:
Table 6 - ISOWEEKNUM
Mode Week starts on
1 Sunday
2 Monday
anchor:ISOWEEKNUM
Test Cases:
=ISOWEEKNUM(DATE(1995;1;1
);1)
1
January 1, 1995 was a
Sunday.
);2)
52
January 1, 1995 was a
Sunday, so if Monday is the
beginning of the week, then
it's week 52 of the previous
year
))
52
Default is Monday is
beginning of week (per ISO)
1))
1);1)
1);2)
))
))
))
See also DAY, MONTH, YEAR, WEEKDAY, WEEKNUM
Note: This is named WEEKNUM is OpenOffice.org 2.0.1, ISOWEEKNUM in Gnumeric. The
WEEKNUM in this spec, Excel and Gnumeric is called WEEKNUM_ADD in OpenOffice.org 2.0.1.
6.10.12 MINUTE
Summary: Extracts the minute (0 through 59) from a time.
100414201 29 May 2010
Syntax: MINUTE( TimeParam T )
Returns: Number
Constraints: None
Semantics: Extract from T the minute value, 0 through 59, as per a clock. This is equal to:
HourFraction=(DayFraction*24-INT(DayFraction*24))
Minute=INT(HourFraction*60)
anchor:MINUTE
Test Cases:
=MINUTE(1/(24*60)) 1 1 minute is 1/(24*60) of a day.
=MINUTE(TODAY()+1/
(24*60))
1
If you start with today, and add a minute, you get a
minute.
=MINUTE(1/24) 0 At the beginning of the hour, we have 0 minutes.
See also MONTH, DAY, HOUR, SECOND
6.10.13 MONTH
Summary: Extracts the month from a date.
Syntax: MONTH( DateParam Date )
Returns: Number
Constraints: None
Semantics: Takes a date and returns the month portion.
anchor:MONTH
Test Cases:
=MONTH([.C7]) 1 Month extraction from date in cell.
=MONTH(DATE(2006;5;21)) 5 Month extraction from DATE() value.
See also YEAR, DAY
6.10.14 NETWORKDAYS
Summary: Returns the whole number of work days between two dates.
100414201 29 May 2010
Syntax: NETWORKDAYS( DateParam Date1 ; DateParam Date2 [ ; [ DateSequence holidays ] [ ;
LogicalSequence workdays ] ] )
Returns: Number
Constraints: None
Semantics: Returns the whole number of days between two dates, ignoring weekends.
Work days are defined as non-weekend, non-holiday days. By default, weekends are Saturdays
and Sundays and there are no holidays.
The optional 3
rd
parameter Holidays can be used to specify a list of dates to be treated as holidays.
Note that this parameter can be omitted as an empty parameter (two consecutive ;; semicolons) to
be able to pass the set of Workdays without Holidays.
The optional 4
th
parameter Workdays can be used to specify a different definition for the standard
work week by passing in a list of Logical values which define which days of the week are workdays.
So, the default definition of the work week excludes Saturday and Sunday and is: {1;0;0;0;0;0;1}. To
define the workweek as excluding Friday and Saturday, the third parameter would be:
{0;0;0;0;0;1;1}.
anchor:NETWORKDAYS
Test Cases:
=NETWORKDAYS(DATE(200
7;1;1),DATE(2007;1;12))
10 Default mode of operation
7;1;1),DATE(2007;1;12);DAT
E(2007;1;1))
9 Exclude a single holiday
7;1;1),DATE(2007;1;14);DAT
E(2007;1;6))
10
Excluding a holiday that is also a weekend
does not change the results.
7;1;1),DATE(2007;1;14);;
{0;0;0;0;0;1;1})
9
Defining the weekend to be
Friday/Saturday
7;1;1),DATE(2007;1;14);DAT
E(2007;1;6);{0;0;0;0;0;1;1})
8
Exclude a holiday as well as define the
weekend to be Friday/Saturday
6.10.15 NOW
Summary: Returns the serial number of the current date and time.
Syntax: NOW()
Returns: DateTime
Constraints: None
Semantics: This returns the current day and time serial number, using the current locale. If you
want only the serial number of the current day, use TODAY.
100414201 29 May 2010
anchor:NOW
Test Cases:
=NOW()>DATE(
2006;1;3)
True NOW constantly changes, but we know it's beyond this date.
=INT(NOW())=T
ODAY()
True
NOW() is part of TODAY(). WARNING: this test is allowed to fail if
the locale transitions through midnight while computing this test; this
failure is incredibly unlikely to occur in practice.
See also DATE, TIME, TODAY
6.10.16 SECOND
Summary: Extracts the second (the integer 0 through 59) from a time. This function presumes that
leap seconds never exist.
Syntax: SECOND( TimeParam T )
Returns: Number
Constraints: None
Semantics: Extract from T the second value, 0 through 59, as per a clock. Note that this returns an
integer, without a fractional part. Note also that this rounds to the nearest second, instead of
returning the integer part of the seconds. This is equal to:
HourFraction=(DayFraction*24-INT(DayFraction*24))
MinuteFraction=(HourFraction*60-INT(HourFraction*60))
Second=ROUND(MinuteFraction*60)
anchor:SECOND
Test Cases:
=SECOND(1/(24*60*60)) 1 This is one second into today.
=SECOND(1/(24*60*60*2)) 1 Rounds.
=SECOND(1/(24*60*60*4)) 0 Rounds.
See also MONTH, DAY, HOUR, MINUTE
Rationale: Excel 2002, at least, rounds -- which is possibly counter-intuitive.
6.10.17 TIME
Summary: Constructs a time value from hours, minutes, and seconds.
100414201 29 May 2010
Syntax: TIME( Number hours ; Number minutes ; Number seconds )
Returns: Time
Constraints: None. Evaluators may first perform INT() on the hour, minute, and second before
doing the calculation.
Semantics: Returns the fraction of the day consumed by the given time, i.e.:
((hours*60*60)+(minutes*60)+seconds)/(24*60*60)
Time is a subtype of number, where a time value of 1 = 1 day = 24 hours.
Hours, minutes, and seconds may be arbitrary numbers (they shall not be limited to the ranges
0..24, 0..59, or 0..60 respectively).
anchor:TIME
Test Cases:
=TIME(0;0;0) 0
All zero arguments becomes midnight, 12:00:00
AM.
=TIME(23;59;59)*60*60*24 86399 This is 11:59:59 PM.
=TIME(11;125;144)*60*60*24 47244
Seconds and minutes roll over transitively; this is
1:07:24 PM.
=TIME(11;0; -117)*60*60*24 39483
Negative seconds roll minutes backwards,
10:58:03 AM
=TIME(11;-117;0)*60*60*24 32580
Negative minutes roll hours backwards, 9:03:00
AM
=TIME(11;-125;-144)*60*60*24 31956
Negative seconds and minutes roll backwards
transitively, 8:52:36 AM
See also DATE
Rationale: There are no tests involving fractions because there is no consensus on them. Excel
2000 performs INT() on all three parameters before doing the calculation; OOo 2.0 does not perform
an INT() first.
Note: Lotus1-2-3v9 limits TIME values to "reasonable" values, and does not roll over values. This
was not accepted, since the ability to roll over values is useful. It is not believed that many extand
documents depend on TIME being limited to reasonable values.
6.10.18 TIMEVALUE
Summary: Returns a time serial number from given text.
Syntax: TIMEVALUE( Text T )
Returns: Time
Constraints: None
100414201 29 May 2010
Semantics: This computes the serial number of the text string T, which is a time, using the current
locale. This function shall accept ISO time format (HH:MM:SS), which is locale-independent. If the
text of T has a combined date and time format, e.g. YYYY-MM-DD HH:MM:SS, the fractional part of
the date serial number is returned. If the text of T does not have a time format, an evaluatormay
attempt to convert the number another way (e.g., using VALUE), or it may return an Error (this is
implementation-dependent).
anchor:TIMEVALUE
Test Cases:
=TIMEVALUE("06:05")=TIME(6;5;0) True
=TIMEVALUE("06:05:07")=TIME(6;5;7) True
=ROUND(TIMEVALUE("1999-11-22
06:05:07");10)=ROUND(TIME(6;5;7);10)
True
Only the fractional
part is returned
See also TIME, DATE, DATEVALUE, VALUE
Note: Excel 2000 doesn't allow the input to be a reference, but Excel 2002 does (it allows normal
operations). TIMEVALUE is widespread, but is not available in SheetToGo. Other than the test for
"time-formattedness", which you can't count on, this is basically the same as VALUE().
OOo2 returns the full integer+fractional number if passed a combined date and time string.
Gnumeric 1.4 does not allow a combined date and time string.
6.10.19 TODAY
Summary: Returns the serial number of today.
Syntax: TODAY()
Returns: Date
Constraints: None
Semantics: This returns the current day's serial number, using current locale. This only returns the
date, not the datetime value. For the specific time of day as well, use NOW.
anchor:TODAY
Test Cases:
=TODAY()>DATE
(2006;1;3)
True Every date TODAY() changes, but we know it's beyond this date.
=INT(TODAY())=
TODAY()
True
TODAY() returns an integer. WARNING: this test is allowed to fail if
the locale transitions through midnight while computing this test;
because TODAY() is referenced twice, in some implementations this
would result in a race condition) This is incredibly unlikely to occur
in practice.
100414201 29 May 2010
See also TIME, NOW
6.10.20 WEEKDAY
Summary: Extracts the day of the week from a date; if text, uses current locale to convert to a date.
Syntax: WEEKDAY( DateParam Date [ ; Integer Type = 1 ] )
Returns: Number
Constraints: None
Semantics: Returns the day of the week from a date, as a number from 0 through 7. The exact
meaning depends on the value of Type:
1. When Type is 1, Sunday is the first day of the week, with value 1; Saturday has value 7.
2. When Type is 2, Monday is the first day of the week, with value 1; Sunday has value 7.
3. When Type is 3, Monday is the first day of the week, with value 0; Sunday has value 6.
Table 7 - WEEKDAY
Day of Week Type=1 Result Type=2 Result Type=3 Result
Sunday 1 7 6
Monday 2 1 0
Tuesday 3 2 1
Wednesday 4 3 2
Thursday 5 4 3
Friday 6 5 4
Saturday 7 6 5
anchor:WEEKDAY
Test Cases:
=WEEKDAY(DATE(2006;5;21)) 1 Year-month-date format
=WEEKDAY(DATE(2005;1;1)) 7 Saturday.
=WEEKDAY(DATE(2005;1;1);1) 7 Saturday.
See also DAY, MONTH, YEAR
6.10.21 WEEKNUM
Summary: Determines the week number of the year for a given date.
100414201 29 May 2010
Syntax: WEEKNUM( DateParam Date [ ; Number Mode = 1 ] )
Returns: Number
Constraints: 1 Mode 2, or 11 Mode 17, or Mode = 21, or Mode = 150
Semantics: Returns the number of the week in the year for the given date.
For Mode={1, 2, 11, 12, ..., 17} the week containing January 1 is the first week of the year, and is
numbered week 1. The week starts on {Sunday, Monday, Monday, Tuesday, ..., Sunday}.
Mode 21 or 150 are both ISO 8601, the week starts on Monday and the week containing the first
Thursday of the year is the first week of the year, and is numbered week 1.
anchor:WEEKNUM
Test Cases:
=WEEKNUM(DATE(2000;5;21)) 22
=WEEKNUM(DATE(2000;5;21);1
)
22
=WEEKNUM(DATE(2000;5;21);2
)
21
=WEEKNUM(DATE(2005;1;1))
=WEEKNUM(DATE(2005;1;1);2)
See also DAY, MONTH, YEAR, WEEKDAY, ISOWEEKNUM
6.10.22 WORKDAY
Summary: Returns the date serial number which is a specified number of days before or after an
input date.
Syntax: WORKDAY( DateParam Date ; Number Offset [ ; [ DateSequence Holidays ] [ ;
LogicalSequence Workdays ] ] )
Returns: DateTime
Constraints: None
100414201 29 May 2010
Semantics: Returns the date serial number for the day that is offset from the input Date parameter
by the number of work days specifed in the Offset parmameter. If Offset is negative, the offset will
return a date prior to Date. If Offset is positive, a date later Date is returned. If Offset is zero, then
Date is returned.
Work days are defined as non-weekend, non-holiday days. By default, weekends are Saturdays
and Sundays and there are no holidays.
The optional 3
rd
parameter Holidays can be used to specify a list of dates to be treated as holidays.
Note that this parameter can be omitted as an empty parameter (two consecutive ;; semicolons) to
be able to pass the set of Workdays without Holidays.
The optional 4
th
parameter Workdays can be used to specify a different definition for the standard
work week by passing in a list of Logical values which define which days of the week are workdays.
Note: The default definition of the work week that excludes Saturday and Sunday and is:
{1;0;0;0;0;0;1}. To define the workweek as excluding Friday and Saturday, the third parameter would
be: {0;0;0;0;0;1;1}.
anchor:WORKDAY
Test Cases:
=WORKDAY(DATE(2006;12;
31),3)=DATE(2007;1;3)
TRUE Default mode of operation
31),-5)=DATE(2006;12;25)
TRUE Negative offset
31),3,DATE(2007,1,1))=DATE
(2007;1;4)
TRUE
Holiday in the interval causes the returned
value to be pushed out
31),-
5;DATE(2006;12;25))=DATE(
2006;12;22)
TRUE Exclude a holiday with a negetive offset
31),-5;DATE(2006;12;25);
{0,0,0,0,0,1,1)=DATE(2006;1
2;21)
TRUE
Negative offset, a holiday and a Sunday-
Thursday work week
6.10.23 YEAR
Summary: Extracts the year from a date given in the current locale of the evaluator.
Syntax: YEAR( DateParam D )
Returns: Number
Constraints: None
Semantics: Parses a date-formatted string in the current locale's format and returns the year
portion.
100414201 29 May 2010
If a year is given as a two-digit number, as in "05-21-15", then the year returned is either 1915 or
2015, depending upon the break point in the calculation context. In an OpenDocument document,
this break point is determined by HOST-NULL-YEAR.
Evaluators shall support extracting the year from a date beginning in 1900. Three-digit year
numbers precede adoption of the Gregorian calendar, and may return either an Error or the year
number. Four-digit year numbers preceding 1582 (inception of the Gregorian Calendar) may return
either an Error or the year number. Four-digit year numbers following 1582 should return the year
number.
anchor:YEAR
Test Cases:
=YEAR(DATE(1904;1;1)) 1904 Extracts year from a given date.
See also MONTH, DAY, VALUE
6.10.24 YEARFRAC
Summary: Extracts the number of years (including fractional part) between two dates
Syntax: YEARFRAC( DateParam StartDate ; DateParam EndDate [ ; Basis Basis = 0 ] )
Returns: Number
Constraints: None
Semantics: Computes the fraction of the number of years between a StartDate and EndDate.
Basis is the system for determining how many days are in a month or year.
Note: The Basis default is not the actual number of days in a month or year. 4.11.6
anchor:YEARFRAC
Test Cases:
=YEARFRAC(DATE(1999;1;1);DAT
E(1999;6;30);0)
0.497222222
E(1999;6;30);1)
0.493150685
E(1999;6;30);2)
0.5
E(1999;6;30);3)
0.493150685
E(1999;6;30);4)
0.497222222
E(1999;7;1);0)
0.5
100414201 29 May 2010
E(1999;7;1);1)
0.495890411
E(1999;7;1);2)
0.502777778
E(1999;7;1);3)
0.495890411
E(2000;6;30);0)
0.497222222
E(2000;6;30);1)
0.494535519
E(2000;6;30);2)
0.502777778
E(2000;6;30);3)
0.495890411
E(2000;6;30);4)
0.497222222
=YEARFRAC(DATE(2000;1;15);DA
TE(2000;9;17);0)
0.672222222
TE(2000;9;17);1)
0.672131148
TE(2000;9;17);2)
0.683333333
TE(2000;9;17);3)
0.673972603
TE(2000;9;17);4)
0.672222222
E(2001;1;1);0)
1
E(2001;1;1);1)
1
E(2001;1;1);2)
1.016666667
E(2001;1;1);3)
1.002739726
E(2001;1;1);4)
1
E(2002;1;1);0)
1
E(2002;1;1);1)
1
100414201 29 May 2010
E(2002;1;1);2)
1.013888889
E(2002;1;1);3)
1
E(2002;1;1);4)
1
TE(2001;12;30);0)
0.069444444
TE(2001;12;30);1)
0.068493151
TE(2001;12;30);2)
0.069444444
TE(2001;12;30);3)
0.068493151
TE(2001;12;30);4)
0.069444444
E(2006;8;10);0)
6.513888889
E(2006;8;10);1)
6.509972624
E(2006;8;10);2)
6.605555556
E(2006;8;10);3)
6.515068493
E(2006;8;10);4)
6.513888889
TE(2004;3;5);1)
0.245901639
=YEARFRAC(DATE(2003;12;31);D
ATE(2004;3;31);1)
0.24863388
TE(2005;1;11);1)
0.279452055
ATE(2005;2;6);1)
0.282191781
ATE(2005;3;4);1)
0.284931507
ATE(2005;3;30);1)
0.287671233
TE(2001;1;16);1)
0.126027397
100414201 29 May 2010
ATE(2001;2;11);1)
0.128767123
=YEARFRAC(DATE(2002; 2;
28);DATE(2002; 12; 31);0)
0.836111111
Known bug in older versions of
Excel.
TE(2004;5;1);1)*1000
497.2677596
Example from ISDA, tests to make
sure that actual/actual is
actual/actual (Euro), aka AFB
Note: Date calculations are easy to get wrong, and there are multiple interpretations. This is why
there are so many test cases. http://www.isda.org/c_and_a/pdf/mktc1198.pdf describes three
different actual/actual systems; the text above uses AFB, aka actual/actual (Euro), as the
actual/actual system. The blog at http://ewbi.blogs.com/develops/2003/10/excel_yearfrac_.html
notes that =YEARFRAC(DATE(2002; 2; 28);DATE(2002; 12; 31);0) in Excel 97 SR-2 gives
0.833333333, but Exel 2003 gives 0.83611111 (a day's difference!). NASD 30/360 is defined in
http://www.investmentstudio.com/help_functions.html under YEARFRAC.
In the US (NASD) 30/360 (basis=0), months are presumed to always be 30 days long, and the year
is considered to always be 360 days long. If StartDate is day 31 of a month, it is set to be day 30 of
that month. If EndDate is day 31 of a month, then there are two possibilities: if the day of StartDate
is less than 30, it is considered day 1 of the next month; otherwise it is set to day 30 of that month.
Note: There are other actual/actual systems, for which currently there are no standard basis
assignments. Future versions of this specification may add them.
See also DATEDIF
6.11 External Access Functions
6.11.1 General
OpenFormula defines two functions, DDE and HYPERLINK, for accessing external data.
6.11.2 DDE
Summary: Returns data from a DDE request
Syntax: DDE( Text server ; Text topic ; Text item [ ; Integer Mode = 0 ] )
Returns: Number|Text
Constraints: None
Semantics: Performs a DDE request and returns its result. The request invokes the service server
on the topic named as topic, requesting that it reply with the information on item.
Evaluators may choose to not perform this function on every recalculation, but instead cache an
answer and require a separate action to re-perform these requests. Evaluators shall perform this
request on initial load when their security policies permit it.
Note: The server soffice is used for OpenOffice.org and StarOffice. In this case the topic is a
document's complete file name or IRL, including path specification. The item is a spreadsheet's cell
address respectively range address or a text document's section name.
Mode is an optional parameter that determines how the results are returned:
100414201 29 May 2010
Table 8 - DDE
Mode Effect
0 or missing Data converted to number using VALUE in the number style's locale of the
default table cell style
1 Data converted to number using VALUE in the English-US (en_US) locale
2 Data retrieved as text (not converted to number)
In an OpenDocument spreadsheet document the default table cell style is specified with
table:default-cell-style-name. Its number:number-style specified by style:data-
style-name specifies the locale to use in the conversion.
The DDE function is non-portable because it depends on availability of external programs (server
parameter) and their interpretation of the topic and item parameters.
anchor:DDE
Test Cases:
=DDE("soffice";"file:///documents
/test.ods";"Sheet1.B3")
7
/test.ods";"Sheet1.B3";1)
7
/test.ods";"Sheet1.B3";2)
"7"
Note: This is in OpenOffice.org, not in Excel.
6.11.3 HYPERLINK
Summary: Returns a Text or Number result and adds a string to the IRI part of a hyperlink cell.
Syntax: HYPERLINK( Text IRI [ ; Text|Number FunctionResult ] )
Returns: Text or Number
Constraints: None
Semantics: The IRI parameter specifies the link target added to the hyperlink cell, while the
FunctionResult parameter is shown as part of the formula result in the cell. If FunctionResult is
omitted, the IRI will be used for both the IRI and the cell result. If FunctionResult is Text, a Text
result is returned. If FunctionResult is Number, a Number result is returned.
If a formula contains a HYPERLINK function, the cell becomes a "hyperlink cell". Clicking on this cell
will execute the contained hyperlink. Therefore it is irrelevant if the HYPERLINK function is really
evaluated (it may i.e. be located in a non-executed part of an IF function) the cell will always be a
hyperlink cell, even if the formula evaluates to a number or a Boolean value. The only exception to
this rule is if an Error code would be part of the IRI. In this case no hyperlink cell will be created.
In a hyperlink cell, all other functions affect both the current IRI and the cell text. Therefore the
formula has to be evaluated twice. In the first run using the IRI part of all hyperlink functions, and in
the second run using the FunctionResult part.
100414201 29 May 2010
anchor:HYPERLINK
Test Cases:
Expression Result Hyperlink IRI Comments
=HYPERLINK( "http: //w
ww. example. org")
"http://www.exampl
e.org"
http: //www. example. o
rg
The function adds
"http://www.exampl
e.org" to the IRI of
the hyperlink cell
and returns the
same text which is
used as formula
result.
ww. example. org"; "Cli
ck here")
Click here
rg
Adds
"http://www.exampl
e.org" to the IRI of
the hyperlink cell,
but returns the text
"Click here" which
is used as formula
result.
ww. ") &
"example. org"
"http://www.exampl
e.org"
rg
Adds "http://www."
to the IRI and the
cell result. The
following text
"example.org" is
also added to both
the IRI and the cell
result
ww. "; Click ) &
"example. org"
"Click example.org"
rg
Results in a
hyperlink cell with
the IRI
http://www.exampl
e.org. The visible
result of the cell is
"Click
example.org".
=HYPERLINK( "") &
"http: //www. example.
org"
"http://www.exampl
e.org"
rg
The text following is
added to both the
IRI and the cell
result.
=HYPERLINK( ""; "Click
") &
"http: //www. example.
org"
"Click
http://www.example.
org"
rg
The text following is
added to both the
IRI and the cell
result.
=MID( HYPERLINK( "http
: //www. example. org";
"Click here") ; 1; 5)
"Click" http:
Functions operate
on both the IRI and
the cell result.
100414201 29 May 2010
=IF( TRUE( ) ; HYPERLINK
( http: //www. example
. org) ; something)
"http://www.exampl
e.org"
rg
The HYPERLINK
function is
evaluated.
=IF( FALSE( ) ; HYPERLIN
K( http: //www. exampl
e. org) ; something)
"something" something
Results in a
hyperlink cell
though the
HYPERLINK
function will not be
evaluated. The cell
contains the (not
working) IRI and
the result
"something".
e. org) ; 1)
1 1
Results in a
hyperlink cell with
the numerical result
1 and the (not
working) IRI "1".
e. org) ; 1=1)
TRUE TRUE
Results in a
hyperlink cell with
the logical result
TRUE and the (not
working) IRI
"TRUE".
=HYPERLINK( http: //w
ww. example. org) &
( 1/0)
Error
No hyperlink
created on error.
=HYPERLINK("http://www1.
example.org/";"example1")
& " or " &
HYPERLINK("http://www2.e
xample.org/";"example2")
"example1 or
example 2"
http://www1.example.org/ or
http://www2.example.org/
Again, the
operations work on
both the IRIs and
cell texts, resulting
in a non-working
IRI.
ww. example. org"; 42)
42
rg
If FunctionResult is
Number, Number is
returned.
Note: The HYPERLINK function originated in Excel. Much of its bizarre semantics results from the
fact that the Hyperlink attribute in Excel can be applied only to a whole cell, hence the weird
behavior that concatenation of HYPERLINK function's parameters and other formula text result in
the entire string being one Hyperlink, or concatenating two HYPERLINK functions does not result in
two different Hyperlinks, but instead produces a Hyperlink with an invalid IRI.
6.12 Financial Functions
6.12.1 General
The financial functions are defined for use in financial calculations.
100414201 29 May 2010
An annuity is a recurring series of payments. A "simple annuity" is one where equal payments are
made at equal intervals, and the compounding of interest occurs at those same intervals. The time
between payments is called the "payment interval". Where payments are made at the end of the
payment interval, it is called an "ordinary annuity". Where payments are made at the beginning of
the payment interval, it is called an "annuity due". Periods are numbered starting at 1.
6.12.2 ACCRINT
Summary: Calculates the accrued interest for securities with periodic interest payments.
Syntax: ACCRINT( DateParam issue ; DateParam first ; DateParam settlement ; Number coupon ;
Number par ; Integer frequency [ ; Basis basis = 0 [ ; Logical calc_method = TRUE() ] ] )
Returns: Currency
Constraints: issue < first < settlement ; coupon > 0; par > 0
frequency is one of the following values:
Table 9 - ACCRINT
frequency Frequency of coupon payments
1 Annual
2 Semiannual
4 Quarterly
12 Monthly
Semantics: Calculates the accrued interest for securities with periodic interest payments. ACCRINT
supports short, standard, and long coupon periods.
If calc_method is TRUE (the default) then ACCRINT returns the sum of the accrued interest in each
coupon period from issue date until settlement date. If calc_method is FALSE then ACCRINT
returns the sum of the accrued interest in each coupon period from first date until settlement date.
For each coupon period, the interest is par*coupon*YEARFRAC(start-of-period;end-of-period; basis)
issue The security's issue or dated date.
first The security's first interest date.
settlement The security's settlement date.
coupon The security's annual coupon rate.
par The security's par value, that is, the principal to be paid at maturity.
frequency The number of coupon payments per year.
basis The type of day-count basis to use; see section 4.11.6
calc_method A logical value that specifies how to treat the case where settlement>first.
anchor:ACCRINT
Test Cases:
=ACCRINT( 1992-12-01;
1993-06-01; 1993-07-01;
0.055; 100; 2; 0 )
3,208333
A bond has a December 1, 1992 issue date, a
June 1, 1993, first interest date, and a July 1,
1993, settlement date,. The semiannual coupon
rate is 5.50%. The bond has a $100 par value,
and a 30/360 day-count basis.
100414201 29 May 2010
=ACCRINT( 2001-02-28;
2001-08-31; 2001-05-01;
0.1; 1000; 2; 0 )
16,944444
A security is issued on 2.28.2001. First interest
is set for 8.31.2001. The settlement date is
5.1.2001. The Rate is 0.1 or 10% and Par is
1000 currency units. Interest is paid half-yearly
(frequency is 2). The basis is the US method
(0). How much interest has accrued?
=ACCRINT( 2004-02-01;
2004-04-01; 2004-05-01;
0.1; 1000; 4; 0 )
24.722222 leap year, quaterly, US (NASD) 30/360
=ACCRINT( 2004-02-01;
2004-04-01; 2004-05-01;
0.1; 1000; 4; 1 )
24.590164 leap year, quaterly, actual/acual
=ACCRINT( 2004-02-01;
2004-04-01; 2004-05-01;
0.1; 1000; 4; 2 )
25 leap year, quaterly, actual/360
=ACCRINT( 2004-02-01;
2004-04-01; 2004-05-01;
0.1; 1000; 4; 3 )
24.657534 leap year, quaterly, actual/365
=ACCRINT( 2004-02-01;
2004-04-01; 2004-05-01;
0.1; 1000; 4; 4 )
25 leap year, quaterly, European 30/360
=ACCRINT( 2004-02-01;
2004-04-01; 2004-05-01;
0.1; 1000; 1 )
24.722222 leap year, annual, US (NASD) 30/360
=ACCRINT( 2004-02-01;
2004-04-01; 2004-05-01;
0.1; 1000; 2 )
24.722222 leap year, semiannual, US 30/360
See also ACCRINTM
Note: This function has some divergent behavior in different implementations.
1-2-3 has a different parameter order: settlement;issue;first;coupon; par; frequency; basis.
Excel allows parameter par to be omitted in between, par and basis defaulted with values of 1000
and 0.
OpenOffice.org and Gnumeric allow a default value for basis only, with a value of 0.
Implementations usually don't support 12 as a valid value for frequency.
6.12.3 ACCRINTM
Summary: Calculates the accrued interest for securities that pay at maturity.
Syntax: ACCRINT( DateParam issue ; DateParam settlement ; Number coupon ; Number par [ ;
Basis basis = 0 ] )
Returns: Currency
Constraints: coupon > 0; par > 0
100414201 29 May 2010
Semantics: Calculates the accrued interest for securities that pay at maturity.
issue The security's issue or dated date.
settlement The security's maturity date.
coupon The security's annual coupon rate.
par The security's par value, that is, the principal to be paid at maturity.
anchor:ACCRINTM
Test Cases:
=ACCRINTM( DATE(2001;4
;1); DATE(2001;6;15); 0.1;
1000; 3 )
20,547945
=ACCRINTM( 2004-02-
01; 2004-05-01; 0.1;
1000; 0 )
24.722222 leap year, US (NASD) 30/360
=ACCRINTM( 2004-02-
01; 2004-05-01; 0.1;
1000; 1 )
24.590164 leap year, actual/actual
=ACCRINTM( 2004-02-
01; 2004-05-01; 0.1;
1000; 2 )
25 leap year, actual/360
=ACCRINTM( 2004-02-
01; 2004-05-01; 0.1;
1000; 3 )
24.657534 leap year, actual/365
=ACCRINTM( 2004-02-
01; 2004-05-01; 0.1;
1000; 4 )
25 leap year, European 30/360
See also ACCRINT
Note: Excel allows parameter par to be omitted in between, par and basis defaulted with values of
1000 and 0.
6.12.4 AMORDEGRC
Summary: Calculates the amortization value for the French accounting system using degressive
depreciation.
Syntax: AMORDEGRC( Number cost ; DateParam purchaseDate ; DateParam firstPeriodEndDate ;
Number salvage ; Integer period ; Number rate [ ; Basis basis = 0 ] )
Returns: Currency
Constraints: cost > 0; purchaseDate <= firstPeriodEndDate; salvage >= 0; period >= 0; rate > 0
Semantics: Calculates the amortization value for the French accounting system using degressive
depreciation.
100414201 29 May 2010
cost The value of the asset at the date of aquisition.
purchaseDate The date of aquisition.
firstPeriodEndDate The end date of the first depreciation period.
salvage The value of the asset at the end of the depreciation life time.
period The period of interest.
rate The rate of depreciation.
The asset life time is the inverse of the rate,
t =1/rate
. The depreciation factor is denoted by
factor.
Table 10 - AMORDEGRC
Asset life time (
t
) Depreciation factor (
factor
)
0t 3
1.0
3t 5
1.5
5t 6
2.0
t 6
2.5
The depreciation allowance for the period
p
is denoted by
DA
p
and takes the following values:
DA
0
=costratefactorYEARFRAC( purchaseDate , firstPeriodEndDate , basis )
DA
0pt 2
=ratefactorDA
p1
DA
t 2
=0.5DA
t 3
DA
t 1
=DA
t2
DA
pt
=0
anchor:AMORDEGRC
Test Cases:
=AMORDEGRC( 1000; 2006-02-01;
2006-12-31; 10; 0; 0.1; 1 )
228 the first period (10 years life time)
=AMORDEGRC( 1000; 2006-02-01;
2006-12-31; 10; 8; 0.1; 1 )
52 the period before last (10 years)
=AMORDEGRC( 1000; 2006-02-01;
2006-12-31; 10; 9; 0.1; 1 )
52 the last period (10 years life time)
=AMORDEGRC( 1000; 2006-02-01;
2006-12-31; 10; 10; 0.1; 1 )
0 beyond life time (10 years life time)
=AMORDEGRC( 1000; 2006-02-01;
2006-12-31; 10; 0; 0.25; 1 )
342 the first period (4 years life time)
=AMORDEGRC( 1000; 2004-02-01; 229 leap year, US (NASD) 30/360
100414201 29 May 2010
2006-12-31; 10; 0; 0.1; 0 )
=AMORDEGRC( 1000; 2004-02-01;
2006-12-31; 10; 0; 0.1; 1 )
228 leap year, actual/actual
=AMORDEGRC( 1000; 2004-02-01;
2006-12-31; 10; 0; 0.1; 2 )
=AMORDEGRC( 1000; 2004-02-01;
2006-12-31; 10; 0; 0.1; 3 )
=AMORDEGRC( 1000; 2004-02-01;
2006-12-31; 10; 0; 0.1; 4 )
228 leap year, European 30/360
See also AMORLINC , DB, DDB, YEARFRAC
6.12.5 AMORLINC
Summary: Calculates the amortization value for the French accounting system using linear
depreciation (l'amortissement linaire comptable) .
Syntax: AMORLINC( Number cost ; DateParam purchaseDate ; DateParam firstPeriodEndDate ;
Number salvage ; Integer period ; Number rate [ ; Basis basis = 0 ] )
Returns: Currency
Constraints: cost > 0; purchaseDate <= firstPeriodEndDate; salvage >= 0; period >= 0; rate > 0
Semantics: Calculates the amortization value for the French accounting system using linear
depreciation.
cost The value of the asset at the date of aquisition.
purchaseDate The date of aquisition.
firstPeriodEndDate The end date of the first depreciation period.
salvage The value of the asset at the end of the depreciation life time.
period Which period the depreciation should be calculated for.
rate The rate of depreciation.
basis Indicates the day count basis to use; see section 4.11.6
When period = 0:
AMORLINC=costrateYEARFRAC( purchaseDate , firstPeriodEndDate , basis )
For full periods, where period > 0, the depreciation is cost * rate
t=
cost salvage
costrate
For the last period, possibly a partial period, the depreciation = cost-salvage-accumulated-
depreciation, where accumulated-depreciation is the sum of the depreciation in period 0 plus any full
period depreciations.
AMORLINC=costrate
When period > depreciated life of the asset, i.e., when period > (cost-salvage)/(cost*rate) then the
depreciation is 0.
100414201 29 May 2010
AMORLINC=0
Note: The behavior of this function is implementation-defined in cases where purchaseDate =
firstPeriodEndDate.
anchor:AMORLINC
Test Cases:
=AMORLINC(1000;DATE(2004;2;1);
DATE(2004;12;31);10;0;0.1;1)
91.256831 the first period (10 years life time)
DATE(2004;12;31);10;8;0.1;1)
100 the period before last (10 years)
DATE(2004;12;31);10;9;0.1;1)
98.743169 the last period (10 years life time)
DATE(2004;12;31);10;10;0.1;1)
0 beyond life time (10 years life time)
DATE(2004;12;31);10;0;0.25;1)
248,142076 the first period (4 years life time)
DATE(2006;12;31);10;0;0.1;0)
91.666667 leap year, US (NASD) 30/360
DATE(2006;12;31);10;0;0.1;2)
DATE(2006;12;31);10;0;0.1;3)
DATE(2006;12;31);10;0;0.1;4)
91.388889 leap year, European 30/360
See also AMORDEGRC, DB, DDB, YEARFRAC
6.12.6 COUPDAYBS
Summary: Calculates the number of days between the beginning of the coupon period that
contains the settlement date and the settlement date.
Syntax: COUPDAYBS( DateParam settlement ; DateParam maturity ; Integer frequency [ ; Basis
basis = 0 ] )
Returns: Number
Constraints: settlement < maturity
100414201 29 May 2010
Table 11 - COUPDAYBS
1 Annual
2 Semiannual
4 Quarterly
Semantics: Calculate the number of days from the beginning of the coupon period to the settlement
date.
settlement The settlement date.
maturity The maturity date.
basis The type of day-count basis; see section 4.11.6
anchor:COUPDAYBS
Test Cases:
COUPDAYBS( DATE(1997;11;9);
DATE(1999;11;15); 2 )
174
COUPDAYBS( DATE(1997;11;9);
DATE(1999;11;15); 2; 1 )
178
=COUPDAYBS( DATE(2004;3;1);
DATE(2009;1;1); 4; 0 )
60 US (NASD) 30/360
DATE(2009;1;1); 4; 1 )
60 actual/actual
DATE(2009;1;1); 4; 2 )
60 actual/360
DATE(2009;1;1); 4; 3 )
60 actual/365
DATE(2009;1;1); 4; 4 )
60 European 30/360
DATE(2009;1;1); 1 )
60 annual
DATE(2009;1;1); 2 )
60 semiannual
See also COUPDAYS , COUPDAYSNC , COUPNCD , COUPNUM , COUPPCD
100414201 29 May 2010
6.12.7 COUPDAYS
Summary: Calculates the number of days in a coupon period that contains a settlement date.
Syntax: COUPDAYS( DateParam settlement ; DateParam maturity ; Integer frequency [ ; Basis
basis = 0 ] )
Returns: Number
Table 12 - COUPDAYS
1 Annual
2 Semiannual
4 Quarterly
Semantics: Calculates the number of days in the coupon period containing the settlement date.
anchor:COUPDAYS
Test Cases:
=COUPDAYS( DATE(1997;11;9);
DATE(1999;11;15); 2 )
180
DATE(1999;11;15); 2; 1 )
184
DATE(2009;1;1); 4; 0 )
90 US (NASD) 30/360
DATE(2009;1;1); 4; 1 )
91 actual/actual
DATE(2009;1;1); 4; 2 )
90 actual/360
DATE(2009;1;1); 4; 3 )
91,25 actual/365
DATE(2009;1;1); 4; 4 )
90 European 30/360
DATE(2009;1;1); 1 )
360 annual
100414201 29 May 2010
DATE(2009;1;1); 2 )
180 semiannual
See also COUPDAYBS , COUPDAYSNC , COUPNCD , COUPNUM , COUPPCD
6.12.8 COUPDAYSNC
Summary: Calculates the number of days between a settlement date and the next coupon date.
Syntax: COUPDAYNC( DateParam settlement ; DateParam maturity ; Integer frequency [ ; Basis
basis = 0 ] )
Returns: Number
Table 13 - COUPDAYSNC
1 Annual
2 Semiannual
4 Quarterly
Semantics: Calculates the number of days between the settlement date and the next coupon date.
anchor:COUPDAYSNC
Test Cases:
=COUPDAYSNC( DATE(1997;5;
19); DATE(1999;11;15); 2 )
176
19); DATE(1999;11;15); 2; 1 )
180
1); DATE(2009;1;1); 4; 0 )
60
1); DATE(2009;1;1); 4; 1 )
60
1); DATE(2009;1;1); 4; 2 )
60
=COUPDAYSNC( DATE(2004;2; 60
100414201 29 May 2010
1); DATE(2009;1;1); 4; 3 )
1); DATE(2009;1;1); 4; 4 )
60
1); DATE(2009;1;1); 1 )
330 annual
1); DATE(2009;1;1); 2 )
150 semiannual
See also COUPDAYBS , COUPDAYS , COUPNCD , COUPNUM , COUPPCD
6.12.9 COUPNCD
Summary: Calculates the next coupon date following a settlement.
Syntax: COUPNCD( DateParam settlement ; DateParam maturity ; Integer frequency [ ; Basis
basis = 0 ] )
Returns: Date
frequency is the number of coupon payments per year. frequency is one of the following values:
Table 14 - COUPNCD
1 Annual
2 Semiannual
4 Quarterly
Semantics: Calculates the next coupon date after the settlement date based on the maturity
(expiration) date of the asset, the frequency of coupon payments and the day-count basis.
anchor:COUPNCD
Test Cases:
=COUPNCD( 2004-01-01; 2007-01-
01; 1; 1 )=DATE(2005;01;01)
True Annual
=COUPNCD( 2004-01-01; 2007-01-
01; 2; 1 )=DATE(2004;07;01)
True Semiannual
=COUPNCD( 2004-01-01; 2007-01-
01; 4; 1 )=DATE(2004;04;01)
True Quarterly
=COUPNCD( 2007-01-01; 2007-01-
01; 1; 1 )
Error settlement < maturity
100414201 29 May 2010
=COUPNCD( 2004-01-01; 2009-01-
01; 4; 0 )=DATE(2004;04;01)
True
=COUPNCD( 2004-01-01; 2009-01-
01; 4; 1 )=DATE(2004;04;01)
True
=COUPNCD( 2004-01-01; 2009-01-
01; 4; 2 )=DATE(2004;04;01)
True
=COUPNCD( 2004-01-01; 2009-01-
01; 4; 3 )=DATE(2004;04;01)
True
=COUPNCD( 2004-01-01; 2009-01-
01; 4; 4 )=DATE(2004;04;01)
True
6.12.10 COUPNUM
Summary: Calculates the number of outstanding coupons between settlement and maturity dates.
Syntax: COUPNUM( DateParam settlement ; DateParam maturity ; Integer frequency [ ; Basis
basis = 0 ] )
Returns: Number
Constraints: frequency is the number of coupon payments per year. frequency is one of the
following values:
Table 15 - COUPNUM
1 Annual
2 Semiannual
4 Quarterly
Semantics: Calculates the number of coupons in the interval between the settlement and the
maturity (expiration) date of the asset, the frequency of coupon payments and the day-count basis.
anchor:COUPNUM
Test Cases:
=COUPNUM( 2004-01-01; 2007-01-
01; 1; 1 )
3 Annual
=COUPNUM( 2004-01-01; 2007-01-
01; 2; 1 )
6 Semiannual
=COUPNUM( 2004-01-01; 2007-01-
01; 4; 1 )
12 Quarterly
=COUPNUM( 2004-02-01; 2009-01- 20
100414201 29 May 2010
01; 4; 0 )
=COUPNUM( 2004-02-01; 2009-01-
01; 4; 1 )
20
=COUPNUM( 2004-02-01; 2009-01-
01; 4; 2 )
20
=COUPNUM( 2004-02-01; 2009-01-
01; 4; 3 )
20
=COUPNUM( 2004-02-01; 2009-01-
01; 4; 4 )
20
See also COUPDAYBS, COUPDAYS, COUPDAYSNC, COUPNCD, COUPPCD
6.12.11 COUPPCD
Summary: Calculates the next coupon date prior a settlement.
Syntax: COUPPCD( DateParam settlement ; DateParam maturity ; Integer frequency [ ; Basis basis
= 0 ] )
Returns: Date
frequency is the number of coupon payments per year. frequency is one of the following values:
Table 16 - COUPPCD
1 Annual
2 Semiannual
4 Quarterly
Semantics: Calculates the next coupon date prior to the settlement date based on the maturity
(expiration) date of the asset, the frequency of coupon payments and the day-count basis.
anchor:COUPPCD
Test Cases:
=COUPPCD( 2004-12-31; 2007-01-
01; 1; 1 )=DATE(2004;1;1)
True Annual
=COUPPCD( 2004-12-31; 2007-01-
01; 2; 1 )=DATE(2004;1;7)
True Semiannual
=COUPPCD( 2004-12-31; 2007-01-
01; 4; 1 )=DATE(2004;1;1)
True Quarterly
100414201 29 May 2010
=COUPPCD( 2007-01-01; 2004-01-
01; 1; 1 )
=COUPPCD( 2004-02-29; 2009-01-
01; 4; 0 )=DATE(2004;01;01)
True
=COUPPCD( 2004-02-29; 2009-01-
01; 4; 1 )=DATE(2004;01;01)
True
=COUPPCD( 2004-02-29; 2009-01-
01; 4; 2 )=DATE(2004;01;01)
True
=COUPPCD( 2004-02-29; 2009-01-
01; 4; 3 )=DATE(2004;01;01)
True
=COUPPCD( 2004-02-29; 2009-01-
01; 4; 4 )=DATE(2004;01;01)
Ture
See also COUPDAYBS, COUPDAYS, COUPDAYSNC, COUPNCD, COUPNUM
6.12.12 CUMIPMT
Summary: Calculates a cumulative interest payment.
Syntax: CUMIPMT( Number rate ; Number periods ; Number value ; Integer start ; Integer end ;
Integer type )
Returns: Currency
Constraints: rate > 0; value > 0; 1 <= start <= end <= periods
type is one of the following values:
Table 17 - CUMIPMT
type Maturity date
0 due at the end
1 due at the beginning
Semantics: Calculates the cumulative interest payment.
rate The interest rate per period.
periods The number of periods.
value The current value of the loan.
start The starting period.
end The end period.
type The maturity date, the beginning or the end of a period.
CUMIPMT=

p=start
end
IPMT(rate , p , periods , value , 0, type)
anchor:CUMIPMT
Test Cases:
100414201 29 May 2010
=CUMIPMT( 0.06/12; 5*12; 100000; 5;
12; 0 )
-3562,187023 maturity at the end of a period
=CUMIPMT( 0.06/12; 5*12; 100000; 5;
12; 1 )
-3544,464699 maturity at the beginning of a period
=CUMIPMT( 0.06/12; 5*12; 100000; 0;
0; 0 )
Error start > 0; end > 0
=CUMIPMT( 0.06/12; 5*12; 100000; 5;
61; 0 )
Error end > periods
=CUMIPMT( 0.06/12; 5*12; 100000; 15;
12; 0 )
Error start > end
See also IPMT, CUMPRINC
6.12.13 CUMPRINC
Summary: Calculates a cumulative principal payment.
Syntax: CUMPRINC( Number rate ; Number periods ; Number value ; Integer start ; Integer end ;
Integer type )
Returns: Currency
Constraints: type is one of the following values:
Table 18 - CUMPRINC
type Maturity date
0 due at the end
1 due at the beginning
Semantics: Calculates the cumulative principal payment.
periods The number of periods.
value The current value of the loan.
start The starting period.
end The end period.
type The maturity date, the beginning or the end of a period.
CUMPRINC=

p=start
end
PPMT(rate , p , periods, value , 0, type)
anchor:CUMPRINC
Test Cases:
=CUMPRINC( 0.06/12; 5*12; 100000; - maturity at the end of a period
100414201 29 May 2010
5; 12; 0 )
11904,054201
=CUMPRINC( 0.06/12; 5*12; 100000;

5; 12; 1 )
-
11844,830051
maturity at the beginning of a period

=CUMPRINC( 0.06/12; 5*12; 100000;
0; 0; 0 )
Error start > 0; end > 0
=CUMPRINC( 0.06/12; 5*12; 100000;
5; 61; 0 )
Error end > periods
=CUMPRINC( 0.06/12; 5*12; 100000;
15; 12; 0 )
Error start > end
See also PPMT , CUMIPMT
6.12.14 DB
Summary: Compute the depreciation allowance of an asset.
Syntax: DB( Number cost ; Number salvage ; Integer lifeTime ; Number period [ ; Number month =
12 ] )
Returns: Currency
Constraints: cost > 0, salvage >= 0, lifetime >0; period > 0; 0 < month < 13
Semantics: Calculate the depreciation allowance of an asset with an initial value of cost, an
expected useful lifeTime, and a final salvage value at a specified period of time, using the fixed-
declining balance method. The parameters are:
cost: the total amount paid for the asset.
salvage: the salvage value at the end of the lifeTime.
lifeTime: the number of periods that the depreciation will occur over. A positive integer.
period: the time period for which you want to find the depreciation allowance, in the same units
as lifeTime.
month: (optional) the number of months in the first year of depreciation, assumed to be 12, if not
specified. If a value is specified for month, lifeTime and period are assumed to be measured in
years.
The rate is calculated as follows:
rate=1
(
salvage
cost
)
1
lifeTime
and is rounded to 3 decimals.
For the first period the residual value is
value
1
=cost
(
1
month
12
rate
)
100414201 29 May 2010
For all periods, where period <= lifeTime, the residual value is calculated by
value
period
=value
period1
(1rate)
If month was specified, the residual value for the period after lifeTime becomes
value
lifeTime+1
=value
lifeTime
(
1
(
1
month
12
)
rate
)
The depreciation allowance for the first period is
DB
1
=costvalue
1
For all other periods the allowance is calculated by
DB
period
=value
period
value
period1
For all periods, where period > lifeTime + 1 INT(month/12), the depreciation allowance is zero.
anchor:DB
Test Cases:
=DB(4000;500;4;2) 963.90 An example of DB.
=DB(4000;500;4;2;2) 1510.65 Default month is 12.
=DB(4000;500;4;5) 0 If period > lifetime, return zero.
=DB(0;500;4;2) Error cost > 0
=DB(4000;-500;4;2) Error salvage >= 0
=DB(4000;500;0;0) Error lifeTime > 0
=DB(4000;500;2;0) Error period > 0
See also DDB, SLN
Rationale: A depreciation of an asset with no value is senseless. Thus, an Error is returned, if the
initial value, cost, is zero.
6.12.15 DDB
Summary: Compute the amount of depreciation at a given period of time.
Syntax: DDB( Number cost ; Number salvage ; Number lifeTime ; Number period [ ; Number
declinationFactor = 2 ] )
Returns: Currency
Constraints: cost >= 0, salvage >= 0, salvage <= cost, 1 <= period <= lifeTime, declinationFactor >
0
Semantics: Compute the amount of depreciation of an asset at a given period of time. The
parameters are:
100414201 29 May 2010
cost: the total amount paid for the asset.
salvage: the salvage value at the end of the LifeTime
lifeTime: the number of periods that the depreciation will occur over.
period: the period for which a depreciation value is specified.
declinationFactor: the method of calculating depreciation, the rate at which the balance
declines. Defaults to 2. If 2, double-declining balance is used.
To calculate depreciation, DDB uses a fixed rate. When declinationFactor = 2 this is the double-
declining-balance method (because it is double the straight-line rate that would depreciate the asset
to zero). The rate is given by:
rate=
declinationFactor
lifeTime
The depreciation each period is calculated as
depreciation_of_period = MIN( book_value_at_start_of_ period * rate; book_value_at_start_of_
period - salvage )
Thus the asset depreciates at rate until the book value is salvage value.
BookValueAtStartOfPeriod
p
= cost
i =1
p1
DepreciationOfPeriod
i
To allow also non-integer period values this algorithm may be used:
100414201 29 May 2010
rate=
declinationFactor
lifeTime
if rate1 then
{
rate=1
if period=1 then
oldValue=cost
else
oldValue=0
endif
}
else
{
oldValue=cost(1rate)
period 1
}
endif
newValue=cost(1rate)
period
if newValuesalvage then
DDB=oldValuesalvage
else
DDB=oldValuenewValue
endif
if DDB0 then
DDB=0
endif
If period is an Integer number, the relation between DDB and VDB is:
DDB( cost ; salvage ; lifeTime ; period ; declinationFactor )
equals
VDB( cost ; salvage ; lifeTime ; period - 1 ; period ; declinationFactor ; TRUE() )
anchor:DDB
Test Cases:
=DDB(4000;500;4;2) 1000 A trivial example of DDB.
=DDB(4000;500;4;2;2) 1000 Default method is 2 (double declining balance).
=DDB( 1100; 100; 5; 5;
2.3 )
0 Some applications create negative values here.
See also SLN, VDB
6.12.16 DISC
Summary: Returns the discount rate of a security.
100414201 29 May 2010
Syntax: DISC( DateParam settlement ; DateParam maturity ; Number price ; Number redemption [ ;
Basis basis = 0 ] )
Returns: Percentage
Semantics: Calculates the discount rate of a security.
settlement The settlement date of the security.
price The price of the security.
redemption The redemption value of the security.
basis The day-count basis; see section 4.11.6
DISC=
redemptionprice
redemption
YEARFRAC( settlement , maturity , basis )
anchor:DISC
Test Cases:
=DISC( 2004-02-29; 2009-01-01;
95000; 100000; 0 )
0.010339 US (NASD) 30/360
=DISC( 2004-02-29; 2009-01-01;
95000; 100000; 1 )
0.010333 actual/actual
=DISC( 2004-02-29; 2009-01-01;
95000; 100000; 2 )
0.010181 actual/360
=DISC( 2004-02-29; 2009-01-01;
95000; 100000; 3 )
0.010322 actual/365
=DISC( 2004-02-29; 2009-01-01;
95000; 100000; 4 )
0.010333 European 30/360
=DISC( 2006-01-01; 2008-01-01;
200; 100; 3 )
-0.5 negative discount
=DISC( 2006-01-01; 2005-07-01;
95000; 100000; 3 )
See also YEARFRAC
6.12.17 DOLLARDE
Summary: Converts a fractional dollar representation into a decimal representation.
Syntax: DOLLARDE( Number fractional ; Integer denominator )
Returns: Number
Constraints: denominator > 0
100414201 29 May 2010
Semantics: Converts a fractional dollar representation into a decimal representation.
fractional Decimal fraction.
denominator Denominator of the fraction.
DOLLARDE=TRUNC( fractional)+
fractionalTRUNC( fractional)
denominator
anchor:DOLLARDE
Test Cases:
=DOLLARDE( 1.1; 4 ) 1.25 rationale number
=DOLLARDE( 1.1; 3 ) 1.333333 irrational number
=DOLLARDE( -1.1; 10 ) -1.1 negative number
=DOLLARDE( 1.0; 5 ) 1 no fraction
=DOLLARDE( 1.1; 0 ) Error denominator > 0
See also DOLLARFR , TRUNC
6.12.18 DOLLARFR
Summary: Converts a decimal dollar representation into a fractional representation.
Syntax: DOLLARFR( Number decimal ; Integer denominator )
Returns: Number
Constraints: denominator > 0
Semantics: Converts a decimal dollar representation into a fractional representation.
decimal Decimal number.
denominator Denominator of the fraction.
DOLLARFR=TRUNC(decimal)+( decimalTRUNC(decimal))denominator
anchor:DOLLARFR
Test Cases:
=DOLLARFR( 1.1; 10 ) 1.1 a denominator of 10 is actually useless
=DOLLARFR( 1.25; 4 ) 1.1
=DOLLARFR( -1.33333; 3 ) 1.099999
=DOLLARFR( 1.0; 5 ) 1 no fraction
=DOLLARFR( 1.1; 0 ) Error denominator > 0
100414201 29 May 2010
See also DOLLARDE, TRUNC
6.12.19 DURATION
Summary: Returns the Macaulay duration of a fixed interest security in years
Syntax: DURATION( Date Settlement ; Date Maturity ; Number Coupon ; Number Yield ; Number
Frequency [ ; Basis Basis = 0 ] )
Returns: Number
Constraints: Yield >=0, Coupon >= 0, Settlement <= Maturity; Frequency = 1, 2, 4
Semantics: Computes the Macaulay duration, given:
Settlement the date of purchase of the security
Maturity the date when the security matures
Coupon the annual nominal rate of interest
Yield the annual yield of the security
Frequency number of interest payments per year
Basis Date calculation basis; see section 4.11.6
anchor:DURATION
Test Cases:
TODO: formula, test cases
See also MDURATION
6.12.20 EFFECT
Summary: Returns the net annual interest rate for a nominal interest rate.
Syntax: EFFECT( Number rate ; Integer payments )
Returns: Number
Constraints: rate >= 0; payments > 0
Semantics: Nominal interest refers to the amount of interest due at the end of a calculation period.
Effective interest increases with the number of payments made. In other words, interest is often paid
in installments (for example, monthly or quarterly) before the end of the calculation period.
payments The number of payments per period.
100414201 29 May 2010
EFFECT=
(
1+
rate
payments
)
payments
1
anchor:EFFECT
Test Cases:
=EFFECT( 0.1; 12 ) 0.104713 monthly payment
=EFFECT( 0.1; 6 ) 0.104260 bimonthly payment
=EFFECT( 0.1; 2 ) 0.1025 semiannual payment
=EFFECT( 0; 12 ) Error rate > 0
=EFFECT( 0.1; 0 ) Error payments > 0
See also NOMINAL
Note: Two functions, EFFECTIVE and EFFECT_ADD, exist in Ooo Calc 2.1. Both calculate the
same result and have the same amount of parameters. They differ in the display format of the return
value only: EFFECTIVE displays Percentage, EFFECT_ADD displays Number. Both are to be
replaced by this EFFECT function here.
6.12.21 FV
Summary: Compute the future value (FV) of an investment.
Syntax: FV( Number Rate ; Number Nper ; Number Payment [ ; [ Number Pv = 0 ] [ ; Number
PayType = 0 ] ] )
Returns: Currency
Constraints: None.
Semantics: Computes the future value of an investment. The parameters are:
Rate: the interest rate per period.
Nper: the total number of payment periods.
Payment: the payment made in each period.
Pv: the present value; default is 0.
PayType: the type of payment, defaults to 0. It is 0 if payments are due at the end of the period;
1 if they are due at the beginning of the period.
See PV for the equation this solves.
anchor:FV
Test Cases:
=FV(10%;12;-100;100) 1824.590.0 A trivial example of FV.
100414201 29 May 2010
1
See also PV, NPER, PMT, RATE
6.12.22 FVSCHEDULE
Summary: Returns the accumulated value given starting capital and a series of interest rates.
Syntax: FVSCHEDULE( Number Principal ; NumberSequence Schedule )
Returns: Currency
Constraints: None.
Semantics: Returns the accumulated value given starting capital and a series of interest rates, as
follows:
Principle
i=1
N
(1+Schedule | i )
anchor:FVSCHEDULE
Test Cases:
=FVSCHEDULE(1000000; {0.03; 0.04; 0.05}) 1124760
A trivial example of
FVSCHEDULE.
See also PV, NPER, PMT, RATE
Note: The result for the test case has +/- even though the correct result is exact, because many
implementations will have inexact representations for some of these values.
6.12.23 INTRATE
Summary: Computes the interest rate of a fully vested security.
Syntax: INTRATE( Date Settlement ; Date Maturity ; Number Investment ; Number Redemption [ ;
Basis Basis = 0 ] )
Returns: Number
Constraints: Settlement < Maturity
Semantics: Calculates the annual interest rate that results when an item is purchased at the
investment price and sold at the redemption price. No interest is paid on the investment. The
parameters are:
Settlement: the date of purchase of the security.
Maturity: the date on which the security is sold.
Investment: the purchase price.
Redemption: the selling price.
100414201 29 May 2010
Basis: [optional] indicates the day count basis to use; see section 4.11.6.
The return value for this function is:
INTRATE=
RedemptionInvestment
Investment
YEARFRAC( Settlement ; Maturity ; Basis)
anchor:INTRATE
Test Cases:
=INTRATE(DATE(2002;6;8);
DATE(1995;10;5); 100000; 200000;
0)
Error
Settlement date must be before the
maturity date.
DATE(2002;6;8); 100000; 200000; 0)
Error
Settlement date must be before the
maturity date.
DATE(2002;6;8); 100000; 200000;
50)
Error Unknown Basis returns Error.
DATE(2002;6;8); 100000; 200000; 0)
0.14981 An example of INTRATE.
DATE(2002;6;8); 100000; 200000)
0.14981 Basis defaults to 0.
DATE(2002;6;8); 100000; 200000; 1)
0.14971
DATE(2002;6;8); 100000; 200000; 2)
0.14766
DATE(2002;6;8); 100000; 200000; 3)
0.14971
DATE(2002;6;8); 100000; 200000; 4)
0.14981
See also RECEIVED, YEARFRAC
6.12.24 IPMT
Summary: Returns the amount of an annuity payment going towards interest.
Syntax: IPMT( Number Rate ; Number Period ; Number Nper ; Number PV [ ; Number FV = 0 [ ;
Number Type = 0 ] ] )
Returns: Currency
Constraints: None.
100414201 29 May 2010
Semantics: Computes the interest portion of an amortized payment for a constant interest rate and
regular payments. The interest payment is the interest rate multiplied by the balance at the
beginning of the period. The parameters are:
Rate: The periodic interest rate.
Period: The period for which the interest payment is computed.
Nper: The total number of periods for which the payments are made
PV: The present value (e.g. The initial loan amount).
FV: The future value (optional) at the end of the periods. Zero if omitted.
Type: the due date for the payments (optional). Zero if omitted. If type is 1, then payments
are made at the beginning of each period. If type is 0, then payments are made at the end
of each period.
anchor:IPMT
Test Cases:
=IPMT(5%/12;10;360;100000) -412.0850243
An example of IPMT. The interest
payment on a 100000 unit loan in the
10
th
month of a 30 year loan at 5%
annual interest.
=IPMT(5%/12;10;360;100000;0;1) -410.375128
Payments at the beginning of each
period.
See also PPMT, PMT
6.12.25 IRR
Summary: Compute the internal rate of return for a series of cash flows.
Syntax: IRR( NumberSequence Values [ ; Number Guess = 0.1 ] )
Returns: Percentage
Constraints: None.
Semantics: Compute the internal rate of return for a series of cash flows.
If provided, Guess is an estimate of the interest rate to start the iterative computation. If omitted, the
value 0.1 (10%) is assumed.
The result of IRR is the rate at which the NPV() function will return zero with the given values.
There is no closed form for IRR. Evaluators may return an approximate solution using an iterative
method, in which case the Guess parameter may be used to initialize the iteration. If the evaluator is
unable to converge on a solution given a particular Guess, it may return an Error.
anchor:IRR
Test Cases:
100414201 29 May 2010
=IRR([.F24:.F26])
0.41878700
01653411e
-5
A trivial example of IRR.
See also NPV, RATE
6.12.26 ISPMT
Summary: Compute the interest payment of an amortized loan for a given period.
Syntax: ISPMT( Number Rate ; Number Period ; Number Nper ; Number Pv )
Returns: Currency
Constraints: None.
Semantics: Computes the interest payment of an amortized loan for a given period. The
parameters are:
Period: the period for which the interest is computed
Pv: the amount of the investment
anchor:ISPMT
Test Cases:
=ISPMT(5%/12;12;360;100000) -402.780.01
A trivial example of ISPMT. A
100000 unit investment with an
annual interest rate of 5% and a 30
year term has an interest payment
of 402.78 units in month 12.
See also PV, FV, NPER, PMT, RATE
6.12.27 MDURATION
Summary: Returns the modified Macaulay duration of a fixed interest security in years
Syntax: MDURATION( Date Settlement ; Date Maturity ; Number Coupon ; Number Yield ; Number
Frequency [ ; Basis Basis = 0 ] )
Returns: Number
Constraints: Yield >= 0, Coupon >= 0, Settlement <= Maturity; Frequency = 1, 2, 4
Semantics: Computes the modified Macaulay duration, given:
Settlement the date of purchase of the security
Maturity the date when the security matures
100414201 29 May 2010
Coupon the annual nominal rate of interest
Yield the annual yield of the security
Frequency number of interest payments per year
Basis Date calculation basis; see section 4.11.6
The modified duration is computed as follows:
duration=DURATION ( Settlement , Maturity ,Coupon , Yield , Frequency , Basis )
MDURATION =
duration
1+
(
Yield
Frequency
)
anchor:MDURATION
Test Cases:
=MDURATION(DATE(2004;2;1);
DATE(2004;5;31); 0.08; 0.09; 2; 0)
0.316321106
These tests go over a leap year
day, and intentionally end on May
31, which illustrates the differences
between many bases
DATE(2004;5;31); 0.08; 0.09; 2; 1)
0.313750098
DATE(2004;5;31); 0.08; 0.09; 2; 2)
0.311004785
DATE(2004;5;31); 0.08; 0.09; 2; 3)
0.313298814 Note slight difference from basis 1
DATE(2004;5;31); 0.08; 0.09; 2; 4)
0.316321106
Basis 4 and 0 are the same in this
case
DATE(2004;6;1); 0.08; 0.09; 2; 0)
0
Basis 0 system; a start date of
2004-05-31 is moved to next day,
resulting in 0 duration
DATE(2004;6;1); 0.08; 0.09; 2; 4)
0.002658161
Basis 4 system differs from basis 0
in this case
See also DURATION
6.12.28 MIRR
Summary: Returns the modified internal rate of return (IRR) of a series of periodic investments
Syntax: MIRR( Array Values ; Number Investment ; Number ReinvestRate )
Returns: Percentage
Constraints: Values shall contain at least one positive value and at least one negative value.
100414201 29 May 2010
Semantics: Values is a series of periodic income (positive values) and payments (negative values)
at regular intervals (Text and Empty cells are ignored). Investment is the rate of interest of the
payments (negative values); ReinvestRate is the rate of interest of the reinvestment (positive
values).
Computes the modified internal rate of return, which is:
(
NPV ( ReinvestRate , Values>0)( 1+ReinvestRate)
n
NPV ( Investment ; Values0)( 1+Investment )
)
(
1
n 1
)
1
where N is the number of incomes and payments in Values (total).
anchor:MIRR
Test Cases:
=MIRR({100;200;-50;300;-200}, 5%,
6%)
0.342823387842
See also IRR
6.12.29 NOMINAL
Summary: Compute the annual nominal interest rate.
Syntax: NOMINAL( Number EffectiveRate ; Integer CompoundingPeriods )
Returns: Number
Constraints: EffectiveRate >0 , CompoundingPeriods > 0
Semantics: Returns the annual nominal interest rate based on the effective rate and the number of
compounding periods in one year. The parameters are:
EffectiveRate: effective rate
CompoundingPeriods: the compounding periods per year
Suppose that P is the present value, m is the compounding periods per year, the future value after
one year is
P
(
1+
NOMINAL
m
)
m
The mapping between nominal rate and effective rate is
EFFECT=
(
1+
NOMINAL
m
)
m
1
anchor:NOMINAL
Test Cases:
100414201 29 May 2010
=NOMINAL(8%;4) 0.077706187633
=NOMINAL(12.5%;12) 0.118362966639
=NOMINAL(1%;2) 0.004993765576
See also EFFECT
Note: Two functions, NOMINAL and NOMINAL_ADD, exist in Ooo Calc 2.1. Both calculate the
same result and have the same amount of parameters. They differ in the display format of the return
value only: NOMINAL displays Percentage, NOMINAL_ADD displays Number. Both are to be
replaced by this NOMINAL function here.
6.12.30 NPER
Summary: Compute the number of payment periods for an investment.
Syntax: NPER( Number Rate ; Number Payment ; Number Pv [ ; [ Number Fv ] [ ; Number
PayType ] ] )
Returns: Number
Constraints: None.
Semantics: Computes the number of payment periods for an investment. The parameters are:
Rate: the constant interest rate.
Pv: the present value of the investment.
Fv: the future value; default is 0.
If Rate is 0, then NPER solves this equation:
Pv =Fv( PaymentNPER)
If Rate is non-zero, then NPER solves this equation:
0 = Pv(1+Rate)
NPER
+
Payment(1+RatePaymentType)((1+Rate)
NPER
1)
Rate
+Fv
Evaluators claiming to support the Medium or Large set shall support negative rates; evaluators
only claiming to support the Small set need not.
anchor:NPER
Test Cases:
=NPER(5%;-100;1000)
14.20670.
001
A trivial example of NPER.
=NPER(5%;-100;1000;100) 15.20670. A trivial example of NPER with non-zero FV.
100414201 29 May 2010
001
=NPER(5%;-100;1000;100;1)
14.20670.
001
A trivial example of NPER with non-zero FV
and PayType.
=NPER(0;-100;1000) 10 Rate can be zero.
=NPER(-1%;-100;1000)
9.48328306
60.001
Rate can be negative.
Note: Gnumeric gives an Error for negative rates. Excel and OOo2 do not. For NPER(-1%;-
100;1000), OOo2 gives 9.48, Excel produces 9.483283066, Gnumeric gives a #DIV/0 Error. This
appears to be a bug in Gnumeric.
See also FV, RATE, PMT, PV
6.12.31 NPV
Summary: Compute the net present value (NPV) for a series of periodic cash flows.
Syntax: NPV( Number Rate ; { NumberSequenceList Value }
+
)
Returns: Currency
Constraints: None.
Semantics: Computes the net present value for a series of periodic cash flows with the discount
rate Rate. Values should be positive if they are received as income, and negative if the amounts are
paid as outgo. Because the result is affected by the order of values, evaluators shall evaluate
arguments in the order given and range reference and array arguments row-wise starting from top
left.
If n is the number of values in the Values, the formula for NPV is:
NPV =
i=1
N
Values
i
( 1+Rate)
i
anchor:NPV
Test Cases:
=NPV(100%;4;5;7) 4.125 A trivial example of NPV
=NPV(100%;[.C4:.C6]) 4.125
Note that each number in a range is
considered separately.
=NPV(10%;100;200)
256.198347
1074380.0
01
A more interesting value.
See also FV, IRR, NPER, PMT, PV, XNPV
100414201 29 May 2010
6.12.32 ODDFPRICE
Summary: Compute the value of a security per 100 currency units of face value. The security has
an irregular first interest date.
Syntax: ODDFPRICE( DateParam Settlement ; DateParam Maturity ; DateParam Issue ;
DateParam First ; Number Rate ; Number Yield ; Number Redemption ; Number Frequency [ ; Basis
Basis = 0 ] )
Returns: Number
Constraints: Rate, Yield, and Redemption should be greater than 0.
Semantics: The parameters are
Settlement: the settlement/purchase date of the security
Maturity: the maturity/expire date of the security
Issue: the issue date of the security
First: the first coupon date of the security
Rate: the interest rate of the security
Yield: the annual yield of the security
Redemption: the redemption value per 100 currency units face value
Frequency: the number of interest payments per year. 1=annual; 2=half-yearly; 4=quarterly.
Basis: the type which indicates how the year is to be calculated by days; see section 4.11.6.
anchor:ODDFPRICE
Test Cases:
Note: It seems that OpenOffice.org 2.0 can not return any valid result. The following cases use the
result of Excel.
=ODDFPRICE(DATE(1990;6;1);DATE(1
995;12;31);DATE(1990;1;1);DATE(1990
;12;31);10%;5%;100;2)
123.959071625 Without Basis parameter
995;12;31);DATE(1990;1;1);DATE(1990
;12;31);10%;5%;100;2;0)
123.959071625
With Frequency=2 and
Basis=0
995;12;31);DATE(1990;1;1);DATE(1990
;12;31);10%;5%;100;4;0)
124.051999184
Basis=0
995;12;31);DATE(1990;1;1);DATE(1990
;12;31);6%;5%;1000;1;1)
790.113232219
Basis=1
995;12;31);DATE(1990;1;1);DATE(1990
;12;31);6%;5%;1000;2;1)
787.959637188
Basis=1
100414201 29 May 2010
995;12;31);DATE(1990;1;1);DATE(1990
;12;31);6%;5%;1000;4;1)
786.814617900
Basis=1
995;12;31);DATE(1990;1;1);DATE(1990
;12;31);6%;3.5%;1000;1;2)
825.983477953
Basis=2
995;12;31);DATE(1990;1;1);DATE(1990
;12;31);6%;3.5%;1000;2;2)
854.085502820
Basis=2
995;12;31);DATE(1990;1;1);DATE(1990
;12;31);6%;3.5%;1000;4;2)
853.464549056
Basis=2
995;12;31);DATE(1990;1;1);DATE(1990
;12;31);6%;3.5%;1000;1;3)
855.173129165
Basis=3
995;12;31);DATE(1990;1;1);DATE(1990
;12;31);6%;3.5%;1000;2;3)
854.112498430
Basis=3
995;12;31);DATE(1990;1;1);DATE(1990
;12;31);6%;3.5%;1000;4;3)
853.512251235
Basis=3
995;12;31);DATE(1990;1;1);DATE(1990
;12;31);15%;3.5%;1000;1;4)
875.190231860
Basis=4
995;12;31);DATE(1990;1;1);DATE(1990
;12;31);15%;3.5%;1000;2;4)
874.167959918
Basis=4
995;12;31);DATE(1990;1;1);DATE(1990
;12;31);15%;3.5%;1000;4;4)
873.648594549
Basis=4
See also ODDLPRICE , ODDFYIELD
6.12.33 ODDFYIELD
Summary: Compute the yield of a security per 100 currency units of face value. The security has an
irregular first interest date.
Syntax: ODDFYIELD( DateParam Settlement ; DateParam Maturity ; DateParam Issue ;
DateParam First ; Number Rate ; Number Price ; Number Redemption ; Number Frequency [ ;
Basis Basis = 0 ] )
Returns: Number
Constraints: Rate, Price, and Redemption should be greater than 0. Maturity > First > Settlement >
Issue.
100414201 29 May 2010
First: the first coupon date of the security
Price: the price of the security
Basis: the type which indicates how the year is to be calculated by days; see section 4.11.6
anchor:ODDFYIELD
Test Cases:
Note: It seems that OpenOffice.org 2.0 can not return any valid result. The following cases use the
result of Excel.
=ODDFYIELD(DATE(1990;6;1);DATE(1
995;12;31);DATE(1990;1;1);DATE(1990
;12;31);10%;124;100;2)
4.992596833% Without Basis parameter
995;12;31);DATE(1990;1;1);DATE(1990
;12;31);10%;124;100;2;0)
4.992596833%
Basis=0
995;12;31);DATE(1990;1;1);DATE(1990
;12;31);10%;124;100;4;0)
5.009384625%
Basis=0
995;12;31);DATE(1990;1;1);DATE(1990
;12;31);6%;790;100;1;1)
5.002737530%
Basis=1
995;12;31);DATE(1990;1;1);DATE(1990
;12;31);6%;788;100;2;1)
4.999042749%
Basis=1
995;12;31);DATE(1990;1;1);DATE(1990
;12;31);6%;787;100;4;1)
4.995647116%
Basis=1
995;12;31);DATE(1990;1;1);DATE(1990
;12;31);6%;826;1000;1;2)
3.499682116%
Basis=2
995;12;31);DATE(1990;1;1),DATE(1990
;12;31);6%;854;2;2)
3.501855575%
Basis=2
995;12;31);DATE(1990;1;1),DATE(1990
3.488467062% With Frequency=4 and
Basis=2
100414201 29 May 2010
;12;31);6%;854;4;2)
995;12;31);DATE(1990;1;1),DATE(1990
;12;31);6%;855;1;3)
3.503809321%
Basis=3
995;12;31);DATE(1990;1;1),DATE(1990
;12;31);6%;854;2;3)
3.502441884%
Basis=3
995;12;31);DATE(1990;1;1),DATE(1990
;12;31);6%;854;4;3)
3.489492455%
Basis=3
995;12;31);DATE(1990;1;1),DATE(1990
;12;31);15%;875;1;4)
4.045647929%
Basis=4
995;12;31);DATE(1990;1;1),DATE(1990
;12;31);15%;874;2;4)
4.041480570%
Basis=4
995;12;31);DATE(1990;1;1),DATE(1990
;12;31);15%;874;4;4)
4.028403919%
Basis=4
See also ODDLYIELD , ODDFPRICE
6.12.34 ODDLPRICE
Summary: Compute the value of a security per 100 currency units of face value. The security has
an irregular last interest date.
Syntax: ODDLPRICE( DateParam Settlement ; DateParam Maturity ; DateParam Last ; Number
Rate ; Number AnnualYield ; Number Redemption ; Number Frequency [ ; Basis Basis = 0 ] )
Returns: Number
Constraints: Rate, AnnualYield, and Redemption should be greater than 0. The Maturity date
should be greater than the Settlement date, and the Settlement should be greater than the last
interest date.
Last: the last interest date of the security
AnnualYield: the annual yield of the security
Frequency: the number of interest payments per year. 1=annual; 2=half-yearly; 4=quarterly
100414201 29 May 2010
anchor:ODDLPRICE
Test Cases:
Note: OpenOffice.org 2.0 and Excel returns different results to mot of the cases. The following use
the result of Excel.
=ODDLPRICE(DATE(1990;6;1);DATE(1
995;12;31);DATE(1990;1;1);3%;5%;100
;2)
995;12;31);DATE(1990;1;1);3%;5%;100
;1;0)
90.991042345
Basis=0
995;12;31);DATE(1990;1;1);3%;5%;100
;2;0)
90.991042345
Basis=0
995;12;31);DATE(1990;1;1);3%;5%;100
;4;0)
90.991042345
Basis=0
995;12;31);DATE(1990;1;1);2%;1.5%;1
00;1;1)
102.512087534
Basis=1
995;12;31);DATE(1990;1;1);2%;1.5%;1
00;2;1)
102.510143853
Basis=1
995;12;31);DATE(1990;1;1);2%;1.5%;1
00;4;1)
102.509884509
Basis=1
995;12;31);DATE(1990;1;1);2%;1.5%;1
00;1;2)
102.512087534
Basis=2
995;12;31);DATE(1990;1;1);2%;1.5%;1
00;2;2)
102.510143853
Basis=2
995;12;31);DATE(1990;1;1);2%;1.5%;1
00;4;2)
102.509884509
Basis=2
995;12;31);DATE(1990;1;1);3%;5%;100
0;1;3)
794.575995564
Basis=3
995;12;31);DATE(1990;1;1);3%;5%;100
0;2;3)
794.671729071
Basis=3
995;12;31);DATE(1990;1;1);3%;5%;100
794.684531308 With Frequency=4 and
Basis=3
100414201 29 May 2010
0;4;3)
995;12;31);DATE(1990;1;1);2%;1.5%;1
000;1;4)
932.992137337
Basis=4
995;12;31);DATE(1990;1;1);2%;1.5%;1
000;2;4)
932.992137337
Basis=4
995;12;31);DATE(1990;1;1);2%;1.5%;1
000;4;4)
932.992137337
Basis=4
See also ODDFPRICE
6.12.35 ODDLYIELD
Summary: Compute the yield of a security which has an irregular last interest date.
Syntax: ODDLYIELD( DateParam Settlement ; DateParam Maturity ; DateParam Last ; Number
Rate ; Number Price ; Number Redemption ; Number Frequency [ ; Basis Basis = 0 ] )
Returns: Number
Constraints: Rate, Price, and Redemption should be greater than 0.
Last: the last interest date of the security
Price: the price of the security
anchor:ODDLYIELD
Test Cases:
Note: OpenOffice.org 2.0 and Excel returns different results to mot of the cases. The following use
=ODDLYIELD(DATE(1990;6;1);DATE(1
995;12;31);DATE(1990;1;1);3%;91;100;
2)
4.997775351% Without Basis parameter
=ODDLYIELD(DATE(1990;6;1);DATE(1 4.997775351% With Frequency=1 and
100414201 29 May 2010
995;12;31);DATE(1990;1;1);3%;91;100;
1;0)
Basis=0
995;12;31);DATE(1990;1;1);3%;91;100;
2;0)
4.997775351%
Basis=0
995;12;31);DATE(1990;1;1);3%;91;100;
4;0)
4.997775351%
Basis=0
995;12;31);DATE(1990;1;1);2%;103;10
0;1;1)
1.408788601%
Basis=1
995;12;31);DATE(1990;1;1);2%;103;10
0;2;1)
1.408379719%
Basis=1
995;12;31);DATE(1990;1;1);2%;103;10
0;4;1)
1.408325114%
Basis=1
995;12;31);DATE(1990;1;1);2%;103;10
0;1;2)
1.408788601%
Basis=2
995;12;31);DATE(1990;1;1);2%;103;10
0;2;2)
1.408379719%
Basis=2
995;12;31);DATE(1990;1;1);2%;103;10
0;4;2)
1.408325114%
Basis=2
995;12;31);DATE(1990;1;1);3%;795;10
00;1;3)
4.987800402%
Basis=3
995;12;31);DATE(1990;1;1);3%;795;10
00;2;3)
4.990550494%
Basis=3
995;12;31);DATE(1990;1;1);3%;795;10
00;4;3)
4.990918451%
Basis=3
995;12;31);DATE(1990;1;1);2%;933;10
00;1;4)
1.499836493%
Basis=4
995;12;31);DATE(1990;1;1);2%;933;10
00;2;4)
1.499836493%
Basis=4
995;12;31);DATE(1990;1;1);2%;933;10
00;4;4)
1.499836493%
Basis=4
100414201 29 May 2010
See also ODDLPRICE , ODDFYIELD
6.12.36 PDURATION
Summary: Returns the number of periods required by an investment to realize a specified value.
Syntax: PDURATION( Number rate ; Number currentValue ; Number specifiedValue )
Returns: Number
Constraints: rate > 0; currentValue > 0; specifiedValue > 0
Semantics: Calculates the number of periods for attaining a certain value specifiedValue, starting
from currentValue and using the interest rate rate.
currentValue The current value of the investment.
specifiedValue The value, that should be reached.
PDURATION=
log( specifiedValue)log(currentValue)
log(rate)
anchor:PDURATION
Test Cases:
=PDURATION( 0.1; 10; 100 ) 24.158858 simple use case
=PDURATION( 0.1; 100; 10 ) -24.158858 curentValue > specifiedValue
=PDURATION( 0; 10; 11 ) Error rate > 0
=PDURATION( 0.1; 0; 11 ) Error currentValue > 0
=PDURATION( 0.1; 10; 0 ) Error specifiedValue > 0
See also DURATION
Note: In OOo2, this function is named DURATION and DURATION with 6 parameters is named
DURATION_ADD. In Gnumeric, this function is name G_DURATION. Excel and Kspread don't have
it.
6.12.37 PMT
Summary: Compute the payment made each period for an investment.
Syntax: PMT( Number Rate ; Integer Nper ; Number Pv [ ; [ Number Fv = 0 ] [ ; Number PayType =
0 ] ] )
Returns: Currency
Constraints: Nper > 0
100414201 29 May 2010
Semantics: Computes the payment made each period for an investment. The parameters are:
Fv: the future value of the investment; default is 0.
1 if they are due at the beginning of the period. With PayType=1 the first payment is made on
the same day the loan is taken out.
If Rate is 0, the following equation is solved:
Pv =Fv( PMTNper )
If Rate is nonzero, then PMT solves this equation:
0 = Pv(1+Rate)
Nper
+
PMT(1+RatePayType)((1+Rate)
Nper
1)
Rate
+Fv
anchor:PMT
Test Cases:
=PMT(5%;12;1000)
-
112.82541
0.001
A trivial example of PMT.
=PMT(5%;12;1000;100)
-
119.10795
0.001
A trivial example of PMT with non-zero FV.
=PMT(5%;12;1000;100;1)
-
113.43614
0.001
A trivial example of PMT with non-zero FV
and PayType.
=PMT(0;10;1000) -100 Rate can be zero.
See also FV, NPER, PV, RATE
6.12.38 PPMT
Summary: Calculate the payment for a given period on the principal for an investment at a given
interest rate and constant payments.
Syntax: PPMT( Number Rate ; Integer Period ; Integer nPer ; Number Present [ ; Number Future =
0 [ ; Number Type = 0 ] ] )
Returns: Number
Constraints: Rate and Present should be greater than 0. 0<Period <nPer.
100414201 29 May 2010
Rate: the interest rate
Period: the given period that the payment returned is for
nPer: the total number of periods
Present: the present value
Future: optional, the future value specified after nPer periods. The default value is 0.
Type: optional, 0 or 1, respectively for payment at the end or at the beginning of a period. The
default value is 0.
anchor:PPMT
Test Cases:
=PPMT(3%;1;12;100) -7.046208547 A simple test case
=PPMT(3%;1;12;100;1;200) -21.138625642 With future value
=PPMT(3%;1;12;100;1;200;1) -23.435558876 With future value and type
=PPMT(8%;5;24;10000;0) -203.773514049 With nPer=5 and Future=0
=PPMT(8%;10;24;10000;2000) -359.292174601 With nPer=10 and Future=2000
=PPMT(8%;10;24;10000;2000;1) -332.677939445 With Type=1
See also PMT
6.12.39 PRICE
Summary: Calculates a quoted price for an interest paying security, per 100 currency units of face
value.
Syntax: PRICE( DateParam Settlement ; DateParam Maturity ; Number Rate ; Number AnnualYield
; Number Redemption ; Number Frequency [ ; Basis Basis = 0 ] )
Returns: Number
Constraints: Rate, AnnualYield, and Redemption should be greater than 0; Frequency = 1, 2 or 4.
Semantics: If A is the number of days from the Settlement date to next coupon date, B is the
number of days of the coupon period that the Settlement is in, C is the number of coupons between
Settlement date and Redemption date, D is the number of days from beginning of coupon period to
Settlement date, then PRICE is calculated as
PRICE=
Redemption
(1+
Yield
Frenquency
)
C1+
A
B
+
k=1
C
100Rate
Frequency
(1+
Yield
Frequency
)
k 1+
A
B
100
Rate
Frequency

D
B
The parameters are
100414201 29 May 2010
AnnualYield: a measure of the annual yield of a security (compounded at each interest
payment)
Basis: the date system to be used; see section 4.11.6.
anchor:PRICE
Test Cases:
Note: OpenOffice.org 2.0 and Gnumeric 1.4.3 return different results than Excel to some test cases.
The following use the result of Excel.
=PRICE(DATE(1990;6;1);DATE(1995;1
2;31);3%;5%;100;2)
=PRICE(DATE(1990;6;1);DATE(1995;1
2;31);3%;5%;100;1;0)
90.447956788
Basis=0
=PRICE(DATE(1990;6;1);DATE(1995;1
2;31);3%;5%;100;2;0)
90.362242031
Basis=0
=PRICE(DATE(1990;6;1);DATE(1995;1
2;31);3%;5%;100;4;0)
90.312119456
Basis=0
=PRICE(DATE(1990;6;1);DATE(1995;1
2;31);2%;1.5%;100;1;1)
102.655378584
Basis=1
=PRICE(DATE(1990;6;1);DATE(1995;1
2;31);2%;1.5%;100;2;1)
102.666400550
Basis=1
=PRICE(DATE(1990;6;1);DATE(1995;1
2;31);2%;1.5%;100;4;1)
102.671274947
Basis=1
=PRICE(DATE(1990;6;1);DATE(1995;1
2;31);2%;1.5%;100;1;2)
102.652722996
Basis=2
=PRICE(DATE(1990;6;1);DATE(1995;1
2;31);2%;1.5%;100;2;2)
102.665343423
Basis=2
=PRICE(DATE(1990;6;1);DATE(1995;1
2;31);2%;1.5%;100;4;2)
102.670408746
Basis=2
=PRICE(DATE(1990;6;1);DATE(1995;1
2;31);3%;5%;1000;1;3)
775.822460005
Basis=3
=PRICE(DATE(1990;6;1);DATE(1995;1
2;31);3%;5%;1000;1;3)
773.463160331
Basis=3
=PRICE(DATE(1990;6;1);DATE(1995;1
2;31);3%;5%;1000;1;3)
772.372534175
Basis=3
100414201 29 May 2010
=PRICE(DATE(1990;6;1);DATE(1995;1
2;31);2%;1.5%;1000;1;4)
930.898194736
Basis=4
=PRICE(DATE(1990;6;1);DATE(1995;1
2;31);2%;1.5%;1000;2;4)
930.654696610
Basis=4
=PRICE(DATE(1990;6;1);DATE(1995;1
2;31);2%;1.5%;1000;4;4)
930.530797527
Basis=4
See also PRICEDISC, PRICEMAT
6.12.40 PRICEDISC
Summary: Calculate the price of a security with a discount per 100 currency units of face value.
Syntax: PRICEDISC( DateParam Settlement ; DateParam Maturity ; Number Discount ; Number
Redemption [ ; Basis Basis = 0 ] )
Returns: Number
Constraints: Discount and Redemption should be greater than 0.
Discount: the discount rate of the security
anchor:PRICEDISC
Test Cases:
Note: OpenOffice.org 2.0 and Excel returns different results to some test cases. The following use
=PRICEDISC(DATE(1990;6;1);DATE(1
990;12;31);10%;1000)
990;12;31);10%;1000;1)
941.643835616 With Basis=1
990;12;31);10%;1000;2)
940.833333333 With Basis=2
990;12;31);10%;1000;3)
941.643835616 With Basis=3
990;12;31);10%;1000;4)
941.944444444 With Basis=4
=PRICEDISC(DATE(1990;1;1);DATE(1 97.082191781 With discount=5%
100414201 29 May 2010
990;12;31);5%;100;1)
990;6;30);3%;100;4)
99.758333333 With discount=3%
See also PRICE, PRICEMAT, YIELDDISC
6.12.41 PRICEMAT
Summary: Calculate the price per 100 currency units of face value of the security that pays interest
on the maturity date.
Syntax: PRICEMAT( DateParam Settlement ; DateParam Maturity ; DateParam Issue ; Number
Rate ; Number AnnualYield [ ; Basis Basis = 0 ] )
Returns: Number
Constraints: Settlement < Maturity, Rate >= 0, AnnualYield >= 0
AnnualYield: the annual yield of the security
If both, Rate and AnnualYield, are 0, the return value is 100.
anchor:PRICEMAT
Test Cases:
=PRICEMAT(DATE(1990;6;1);DATE(19
95;12;31);DATE(1990;1;1);6%;5%)
95;12;31);DATE(1990;1;1);6%;5%;1)
103.824693325 With Basis=1
95;12;31);DATE(1990;1;1);6%;5%;2)
103.858482159 With Basis=2
95;12;31);DATE(1990;1;1);6%;5%;3)
103.824693325 With Basis=3
95;12;31);DATE(1990;1;1);6%;5%;4)
103.817732653 With Basis=4
100414201 29 May 2010
92;12;31);DATE(1990;1;1);3%;2%;0)
102.395007924
91;12;31);DATE(1990;1;1);5%;3%;2)
102.967175933
See also PRICEDISC, PRICEMAT
6.12.42 PV
Summary: Compute the present value (PV) of an investment.
Syntax: PV( Number Rate ; Number Nper ; Number Payment [ ; [ Number Fv = 0 ] [ ; Number
PayType = 0 ] ] )
Returns: Currency
Constraints: None.
Semantics: Computes the present value of an investment. The parameters are:
If Rate is 0, then:
PV =Fv( PaymentNper )
If Rate is nonzero, then PV solves this equation:
0 = PV(1+Rate)
Nper
+
Payment(1+RatePayType)((1+Rate)
Nper
1)
Rate
+Fv
anchor:PV
Test Cases:
=PV(10%;12;-100;100) 649.510.01 A trivial example of PV.
See also FV, NPER, PMT, RATE
6.12.43 RATE
Summary: Compute the interest rate per period of an investment.
100414201 29 May 2010
Syntax: RATE( Number Nper ; Number Payment ; Number Pv [ ; [ Number Fv = 0 ] [ ; [ Number
PayType = 0 ] [ ; Number Guess = 0.1 ] ] ] )
Returns: Percentage
Constraints: If Nper is 0 or less than 0, the result is an Error.
Semantics: Computes the interest rate of an investment. The parameters are:
Guess: An estimate of the interest rate to start the iterative computation. If omitted, 0.1 (10%) is
assumed.
RATE solves this equation:
0 = Fv+Pv( 1+Rate)
Nper
+
Payment( 1+RatePayType)( ( 1+Rate)
Nper
1)
Rate
anchor:rate
Test Cases:
=RATE(12;-100;1000)
0.0292285
0.001
A trivial example of RATE.
=RATE(12;-100;1000;100)
0.01623133
0.001
A trivial example of RATE with non-zero
FV.
=RATE(12;-100;1000;100;1)
0.01996455
0.001
A trivial example of RATE with non-zero FV
and PayType.
=RATE(12;-100;1000;100;1;1%)
0.01996455
0.001
A trivial example of RATE with a guess.
=RATE(0;-100;1000) Error Nper must be greater than 0.
=RATE(48;-50;2000;0;1;0)
0.00805298
19239056
0.0000000
0001
Extreme test case with high precision, best
solution manually obtained would be
0.0080529819239063
=RATE(48;-50;2000;50;0;0) 0.00805298
19239056
0.0000000
0001
The result should be identical to the
previous one.
Payment in advance (Type<>0) can be
changed to normal payment with the
settings:
100414201 29 May 2010
Fv_normal = Fv_advanced
Payment_advanced*Type
Pv_normal = Pv_advanced +
Payment_advanced*Type
Therefore both examples should give the
same result.
TBD: In Gnumeric, Nper seems to be truncated if it is not an integer. In OOo2, Nper seems not to
be truncated if it is not an integer and the fractional part is included in the calculation. What does
excel do? We should include a test for this, but what is the right thing to do? For example, in
Gnumeric, RATE(12.9,-100,1000) is 2.92% but in OOo2 RATE(12.9,-100,1000) is 3.88%.
TODO: ECMA/MOOXML documents that the PayType could be either 0 or 1. However, that's not
what is implemented in Excel, it calculates different resutls for different fractional values of PayType.
It looks like PayType would be an offset to the end date of the payment period towards the start
date of the period.
See also FV, NPER, PMT, PV
6.12.44 RECEIVED
Summary: Calculates the amount received at maturity for a zero coupon bond.
Syntax: RECEIVED( DateParam Settlement ; DateParam Maturity ; Number Investment ; Number
Discount [ ; Basis Basis = 0 ] )
Returns: Number
Constraints: Investment and Discount should be greater than 0.
Semantics:
The parameters are
Investment: the amount of investment in the security
Discount: the discount rate of the security
Basis: the day count basis used in this calculation; see section 4.11.6
The return value is:
RECEIVED=
Investment
1DiscountYEARFRAC( Settlement ; Maturity ; Basis)
anchor:RECEIVED
Test Cases:
=RECEIVED(DATE(1990;6;1);DATE(19
90;12;31);10000;5%)
100414201 29 May 2010
90;12;31);10000;5%;1)
10300.5503 With Basis=1
90;12;31);10000;5%;2)
10304.8519 With Basis=2
90;12;31);10000;6%;3)
10362.8414 With Basis=3
90;12;31);10000;6%;4)
10362.6943 With Basis=4
Note: There is a differences between applications for the Basis=4 test case: Excel gets 10360.9049,
Gnumeric, Kspread and OOo all get 10362.6943 as a result. This looks like an error of Excel.
See also YEARFRAC
6.12.45 RRI
Summary: Returns an equivalent interest rate when an investment increases in value.
Syntax: RRI( Number N ; Number Pv ; Number Fv )
Returns: Percentage
Constraints: N > 0
Semantics: Returns the interest rate given N (the number of periods), Pv (present value), and Fv
(future value), calculated as follows:
(
Fv
Pv
)
(1/ N)
1
anchor:RRI
Test Cases:
=RRI(1;100;200) 1 A trivial example of RRI.
=RRI(12;5000;10000)
0.0594630
9436
RRI, practical example
=RRI(12;10000;5000)
-
0.05612568
7
If future value is less than present value,
resultant rate is negative
=RRI(0;100;200) Error N must be greater than 0.
Note: In OOo, N is NOT truncated to an integer. There doesn't seem to be a reason to require it, so
this is expected to stay a Number and not an Integer.
See also FV, NPER, PMT, PV, RATE
100414201 29 May 2010
6.12.46 SLN
Summary: Compute the amount of depreciation at a given period of time using the straight-line
depreciation method.
Syntax: DDB( Number Cost ; Number Salvage ; Number LifeTime )
Returns: Currency
Constraints: None.
Semantics: Compute the amount of depreciation of an asset at a given period of time using
straight-line depreciation. The parameters are:
Cost: the total amount paid for the asset.
Salvage: the salvage value at the end of the LifeTime (often 0)
LifeTime: the number of periods that the depreciation will occur over. A positive integer.
For alternative methods to compute depreciation, see DDB.
anchor:SLN
Test Cases:
=SLN(4000;500;4) 875 A trivial example of SLN.
See also DDB
6.12.47 SYD
Summary: Compute the amount of depreciation at a given period of time using the Sum-of-the-
Years'-Digits method.
Syntax: SYD( Number Cost ; Number Salvage ; Number LifeTime ; Number Period )
Returns: Currency
Constraints: None.
Semantics: Compute the amount of depreciation of an asset at a given period of time using the
Sum-of-the-Years'-Digits method. The parameters are:
Cost: the total amount paid for the asset.
Salvage: the salvage value at the end of the LifeTime (often 0)
LifeTime: the number of periods that the depreciation will occur over. A positive integer.
Period: the period for which the depreciation value is specified.
SYD=
(Cost Salvage)( LifeTime+1Period)2
( LifeTime+1)LifeTime
For other methods of computing depreciation, see DDB.
100414201 29 May 2010
anchor:SYD
Test Cases:
=SYD(4000;500;4;2
)
1050
A trivial example of SYD. Note that DDB would have calculated
1000 instead.
See also SLN, DDB
6.12.48 TBILLEQ
Summary: Compute the bond-equivalent yield for a treasury bill.
Syntax: TBILLEQ( DateParam Settlement ; DateParam Maturity ; Number Discount )
Returns: Number
Constraints: The maturity date should be less than one year beyond settlement date. Discount is
any positive value.
Semantics: The parameters are defined as,
Settlement: the settlement/purchase date of the treasury bill
Maturity: the maturity/expire date of the treasury bill
Discount: the discount rate of the treasury bill.
TBILLEQ is calculated as
TBILLEQ=
365rate
360(rateDSM)
where DSM is the number of days between settlement and maturity computed according to the 360
days per year basis (basis 2, 4.11.6)
anchor:TBILLEQ
Test Cases:
Note: Lotus 1-2-3 and Excel returns different results to some test cases. The following use the
result of Lotus 1-2-3, because I verified with one case by Excel formula and found that the result of
Lotus 1-2-3 is correct. To be verified with others later.
=TBILLEQ(DATE(1996;1;1);DATE(1996;2;1);5%) 0.050913656
100414201 29 May 2010
See also TBILLPRICE, TBILLYIELD
6.12.49 TBILLPRICE
Summary: Compute the price per 100 face value for a treasury bill.
Syntax: TBILLPRICE( DateParam Settlement ; DateParam Maturity ; Number Discount )
Returns: Number
Constraints: The maturity date should be less than one year beyond settlement. Discount is any
positive value.
Semantics: The parameters are:
Discount: the discount rate of the treasury bill.
anchor:TBILLPRICE
Test Cases:
=TBILLPRICE(DATE(1996;1;1);DATE(1996;2;1);5%) 99.56944444
See also TBILLEQ, TBILLYIELD
6.12.50 TBILLYIELD
Summary: Compute the yield for a treasury bill.
100414201 29 May 2010
Syntax: TBILLYIELD( DateParam Settlement ; DateParam Maturity ; Number Price )
Returns: Number
Constraints: The maturity date should be less than one year beyond settlement. Price is any
positive value.
Semantics: The parameters are:
Price: the price of the treasury bill per 100 face value
anchor:TBILLYIELD
Test Cases:
=TBILLYIELD(DATE(1996;1;1);DATE(1996;2;1);99.57) 0.0501511
See also TBILLEQ, TBILLPRICE
6.12.51 VDB
Summary: Calculates the depreciation allowance of an asset with an initial value, an expected
useful life, and a final value of salvage for a period specified, using the variable-rate declining
balance method..
Syntax: VDB( Number cost ; Number salvage ; Number lifeTime ; Number startPeriod ; Number
endPeriod [ ; Number depreciationFactor = 2 [ ; Logical noSwitch = FALSE() ] ] )
Returns: Number
Constraints: salvage < cost, lifeTime > 0, 0 startPeriod lifeTime, startPeriod endPeriod
lifeTime, depreciationFactor 0
Semantics: cost is the amount paid for the asset. cost can be any value greater than salvage.
salvage is the value of the asset at the end of its life. salvage can be any value.
100414201 29 May 2010
lifeTime is the number of periods the asset takes to depreciate to its salvage value. lifeTime can be
any value greater than 0.
startPeriod is the point in the asset's life when you want to begin calculating depreciation. start-
Period can be any value greater than or equal to 0, but cannot be greater than lifeTime.
endPeriod is the point in the asset's life when you want to stop calculating depreciation. end-Period
can be any value greater than startPeriod.
startPeriod and endPeriod correspond to the asset's life, relative to the fiscal period. For example, if
you want to find the first year's depreciation of an asset purchased at the beginning of the second
quarter of a fiscal year, start-period would be 0 and end-period would be 0.75 (1 minus 0.25 of a
year).
VDB allows for the use of an initialPeriod option to calculate depreciation for the period the asset is
placed in service. VDB uses the fractional part of startPeriod and endPeriod to determine the
initialPeriod option. If both startPeriod and endPeriod have fractional parts, then VDB uses the
fractional part of startPeriod.
depreciationFactor is an optional argument that specifies the percentage of straight-line depreciation
you want to use as the depreciation rate. If you omit this argument, VDB uses 2, which is the
double-declining balance rate. depreciation-factor can be any value greater than or equal to 0;
commonly used rates are 1.25, 1.50, 1.75, and 2.
noSwitch is an optional argument that you include if you do not want VDB to switch to straight-line
depreciation for the remaining useful life. Normally, declining-balance switches to such a straight-
line calculation when it is greater than the declining-balance calculation.
If noSwitch is FALSE() or omitted, VDB automatically switches to straight-line depreciation when
that is greater than declining-balance depreciation. If noSwitch is TRUE(), VDB never switches to
straight-line depreciation.
anchor:VDB
Test Cases:
This example calculates depreciation for an office machine, purchased in the middle of the first
quarter of the fiscal year, that cost $10,000. The useful life of the machine is 10 years, and the
salvage value after 10 years is $600. The following formulas calculate the depreciation expense for
each of the 10 years, using the variable-rate declining balance method, with a depreciation rate of
150%. Notice that the switch to straight-line depreciation occurs in the sixth year.
=VDB(10000;600;10;0;0.875;1.5) 1312.5
=VDB(10000;600;10;0.875;1.875;1.5) 1303.13
=VDB(10000;600;10;1.875;2.875;1.5) 1107.66
=VDB(10000;600;10;2.875;3.875;1.5 941.5
=VDB(10000;600;10;3.875;4.875;1.5) 800.28
=VDB(10000;600;10;4.875;5.875;1.5) 767.79
=VDB(10000;600;10;5.875;6.875;1.5) 767.79
=VDB(10000;600;10;6.875;7.875;1.5) 767.79
=VDB(10000;600;10;7.875;8.875;1.5) 767.79
100414201 29 May 2010
=VDB(10000;600;10;8.875;9.875;1.5) 767.79
=VDB(10000;600;10;9.875;10;1.5) 95.97
See also DDB, SLN
6.12.52 XIRR
Summary: Compute the internal rate of return for a non-periodic series of cash flows.
Syntax: XIRR( NumberSequence Values ; DateSequence Dates [ ; Number Guess = 0.1 ] )
Returns: Number
Constraints: The size of Values and Dates are equal. Values contains at least one positive and one
negative cash flow.
Semantics: Compute the internal rate of return for a series of cash flows which is not necessarily
periodic. The parameters are
Values: a series of cash flows. The first cash-flow amount is a negative number that represents
the investment. The later cash flows are discounted based on the annual discount rate and the
timing of the flow. The series of cash flow should contain at least one positive and one negative
value.
Dates: a series of dates that corresponds to values. The first date indicates the start of the cash
flows. The range of Values and Dates shall be the same size.
Guess: If provided, Guess is an estimate of the interest rate to start the iterative computation. If
omitted, the value 0.1 (10%) is assumed. The result of XIRR is the rate at which the XNPV()
function will return zero with the given cash flows. There is no closed form for XIRR.
Implementations may return an approximate solution using an iterative method, in which case
the Guess parameter may be used to initialize the iteration. If the implementation is unable to
converge on a solution given a particular Guess, it may return an error.
anchor:XIRR
Test Cases:
=XIRR(B1:B4;C1:C4) 0.2115964
Suppose B1:B4 contains -20000, 4000, 12000, 8000
while C1:C4 contains =DATE(2000;1;1),
=DATE(2000;6;1), =DATE(2000;12;30),
=DATE(2001;3;1)
=XIRR(B1:B2;C1:C2;
20%)
0.2492381
Suppose B1:B2 contains -20000, 25000 while C1:C2
contains =DATE(2000;1;1), =DATE(2001;1;1).
=XIRR(B1:B3;C1:C3) 0.1405418
Suppose B1:B3 contains -10000, 4000, 12000;
C1:C3 contains =DATE(2000;1;1),
=DATE(2002;6;1), =DATE(2004;1;1)
TODO: Fix test cases above so that data is actually in test case data.
See also IRR
100414201 29 May 2010
6.12.53 XNPV
Summary: Compute the net present value of a series of cash flows.
Syntax: XNPV( Number Rate ; Reference|Array Values ; Reference| Array Dates )
Returns: Number
Constraints:
Number of elements in Values equals number of elements in Dates.
All elements of Values are of type Number.
All elements of Dates are of type Number.
All elements of Dates >= Dates[1]
Semantics: Compute the net present value for a series of cash flows which is not necessarily
periodic. The parameters are
Rate: discount rate. The value should be greater than -1.
Values: a series of cash flows. The first cash-flow amount is a negative number that represents
the investment. The later cash flows are discounted based on the annual discount rate and the
timing of the flow. The series of cash flow should contain at least one positive and one negative
value.
Dates: a series of dates that corresponds to values. The first date indicates the start of the cash
flows. If the dimensions of the Values and Dates arrays differ, evaluators shall match value and
date pairs row-wise starting from top left.
With N being the number of elements in Values and Dates each, the formula is:
XNPV=
i=1
N
Values
i
( 1+Rate)
Dates
i
Dates
1
365
anchor:XNPV
Test Cases:
=XNPV(5%;B1:B4;C1:C
4)
2907.83187
Suppose B1:B4 contains -20000, 4000, 12000,
8000 while C1:C4 contains =DATE(2000;1;1),
=DATE(2000;6;1), =DATE(2000;12;30),
=DATE(2001;3;1)
=XNPV(6%;B1:B2;C1:C
2)
3581.14085
Suppose B1:B2 contains -20000, 25000 while
=DATE(2001;1;1).
=XNPV(5%;B1:B3;C1:C
3)
3426.25543
Suppose B1:B3 contains -10000, 4000, 12000;
=DATE(2002;6;1), =DATE(2004;1;1)
TODO: Fix test cases above so that data is actually in test case data.
See also NPV
100414201 29 May 2010
6.12.54 YIELD
Summary: Calculate the yield of a bond.
Syntax: YIELD( DateParam Settlement ; DateParam Maturity ; Number Rate ; Number Price ;
Number Redemption ; Number Frequency [ ; Basis Basis = 0 ] )
Returns: Number
Constraints: Rate, Price, and Redemption should be greater than 0.
Settlement: the settlement/purchase date of the bond
Maturity: the maturity/expire date of the bond
Rate: the interest rate of the bond
Price: the price of the bond per 100 currency units face value
Redemption: the redemption value of the bond per 100 currency units face value
Frequency: the number of interest payments per year. 1=annual; 2=half-yearly; 4=quarterly
Basis: the day count convention to use, see section 4.11.6
anchor:YIELD
Test Cases:
=YIELD(DATE(1990;6;1);DATE(1995;1
2;31);3%;90.36224;100;2)
=YIELD(DATE(1990;6;1);DATE(1995;1
2;31);3%;90.44796;100;1;0)
0.049999993
Basis=0
=YIELD
(DATE(1990;6;1);DATE(1995;12;31);3%
;90.36224;100;2;0)
0.050000004
Basis=0
=YIELD
(DATE(1990;6;1);DATE(1995;12;31);3%
;90.31212;100;4;0)
0.049999999
Basis=0
=YIELD
(DATE(1990;6;1);DATE(1995;12;31);2%
;102.65538;100;1;1)
0.014999997
Basis=1
=YIELD
(DATE(1990;6;1);DATE(1995;12;31);2%
;102.6664;100;2;1)
0.015000001
Basis=1
=YIELD
(DATE(1990;6;1);DATE(1995;12;31);2%
;102.671275;100;4;1)
0.015036907
Basis=1
100414201 29 May 2010
=YIELD
(DATE(1990;6;1);DATE(1995;12;31);2%
;102.652723;100;1;2)
0.015000000
Basis=2
=YIELD
(DATE(1990;6;1);DATE(1995;12;31);2%
;102.66534;100;2;2)
0.015000006
Basis=2
=YIELD
(DATE(1990;6;1);DATE(1995;12;31);2%
;102.67041;100;4;2)
0.014999998
Basis=2
=YIELD
(DATE(1990;6;1);DATE(1995;12;31);3%
;775.82246;1000;1;3)
0.050000000
Basis=3
=YIELD
(DATE(1990;6;1);DATE(1995;12;31);3%
;773.46316;1000;1;3)
0.050000000
Basis=3
=YIELD
(DATE(1990;6;1);DATE(1995;12;31);3%
;772.37253;1000;1;3)
0.050000001
Basis=3
=YIELD
(DATE(1990;6;1);DATE(1995;12;31);2%
;930.89819;1000;1;4)
0.015000001
Basis=4
=YIELD
(DATE(1990;6;1);DATE(1995;12;31);2%
;930.6547;1000;2;4)
0.014999999
Basis=4
=YIELD
(DATE(1990;6;1);DATE(1995;12;31);2%
;930.5308;1000;4;4)
0.015000000
Basis=4
See also PRICE, YIELDDISC, YIELDMAT
6.12.55 YIELDDISC
Summary: Calculate the yield of a discounted security per 100 currency units of face value.
Syntax: YIELDDISC( DateParam Settlement ; DateParam Maturity ; Number Price ; Number
Redemption [ ; Basis Basis = 0 ] )
Returns: Number
Constraints: Price and Redemption should be greater than 0.
Price: the price of the security per 100 currency units face value
100414201 29 May 2010
Basis: the day count basis for this calculation; see section 4.11.6
The return value is
YIELDDISC=
Redemption
Price
1
YEARFRAC( Settlement ; Maturity ; Basis)
anchor:YIELDDISC
Test Cases:
=YIELDDISC(DATE(1990;6;1);DATE(19
90;12;31);941.66667;1000)
90;12;31);941.64384;1000;1)
0.106238821 With Basis=1
90;12;31);940.83333;1000;2)
0.107807168 With Basis=2
90;12;31); 941.64384 ;1000;3 )
0.106238821 With Basis=3
90;12;31);941.94444;1000;4)
0.105657842 With Basis=4
90;12;31);97.08219;100;1)
0.051522942
90;6;30);99.75833;100;4)
0.030073091
See also PRICEDISC, YEARFRAC
6.12.56 YIELDMAT
Summary: Calculate the yield of the security that pays interest on the maturity date.
Syntax: YIELDMAT( DateParam Settlement ; DateParam Maturity ; DateParam Issue ; Number
Rate ; Number Price [ ; Basis Basis = 0 ] )
Returns: Number
Constraints: Rate and Price should be greater than 0.
100414201 29 May 2010
Price: the price of the security per 100 currency units face value
anchor:YIELDMAT
Test Cases:
=YIELDMAT(DATE(1990;6;1);DATE(19
95;12;31);DATE(1990; 1; 1);
6%;103.819218241)
95;12;31); DATE(1990; 1; 1);
6%;103.824693325;1)
0.050000000 With Basis=1
=YIELDMAT
(DATE(1990;6;1);DATE(1995;12;31);DA
TE(1990; 1; 1); 6%;103.858482159; 2)
0.050000000 With Basis=2
95;12;31);DATE(1990; 1; 1);
6%;103.824693325;3)
0.050000000 With Basis=3
=YIELDMAT
(DATE(1990;6;1);DATE(1992;12;31);DA
TE(1990;1;1); 6%,103.817732653,4)
0.050000000 With Basis=4
=YIELDMAT
(DATE(1990;6;1);DATE(1992;12;31);DA
TE(1990;1;1); 3%;102.395007924;0)
0.020000000 With Basis=0
=YIELDMAT
(DATE(1990;6;1);DATE(1995;12;31);DA
TE(1990;1;1); 5%;102.967175933;2))
0.030000000 With Basis=2
See also PRICE, YIELD, YIELDDISC
6.13 Information Functions
6.13.1 General
Information functions provide information about a data value, the spreadsheet, or underlying
environment, including special functions for converting between data types.
6.13.2 AREAS
Summary: Returns the number of areas in a given reference
100414201 29 May 2010
Syntax: AREAS( ReferenceList R )
Returns: Number
Constraints: None
Semantics: Returns the number of areas in the reference list.
anchor:AREAS
Test Cases:
=AREAS([.B3]) 1 A reference to a single cell has one area
=AREAS([.B3:.C4]) 1 A reference to a single range has one area
=AREAS([.B3:.C4]~[.D5:.D
6)
2 Cell concatenation creates multiple areas
=AREAS([.B3:.C4]~[.B3]) 2
Cell concatenation counts, even if the cells
are duplicated
See also Infix Operator Reference Concatenation, INDEX
6.13.3 CELL
Summary: Returns information about position, formatting or contents in a reference.
Syntax: CELL( Text Info_Type [ ; Reference R ] )
Returns: Information about position, formatting properties or content
Constraints: None
Info_Type: the text string which specifies the type of information. Please refer to the following
table.
Table 19 - CELL
Info_Type Comment
COL Returns the column number of the cell.
ROW Returns the row number of the cell.
SHEET Returns the sheet number of the cell.
ADDRESS
Returns the absolute address of the cell. The sheet name is included if
given in the reference. For an external reference a Source as specified
in the syntax rules for References is included.
FILENAME
Returns the file name of the file that contains the cell as an IRI. If the file
is newly created and has not yet been saved, the file name is empty
text .
100414201 29 May 2010
CONTENTS Returns the contents of the cell, without formatting properties.
COLOR
Returns 1 if color formatting is set for negative value in this cell;
otherwise returns 0
FORMAT
Returns a text string which shows the number format of the cell.
,(comma) = number with thousands separator
F = number without thousands separator
C = currency format
S = exponential representation
P = percentage
To indicate the number of decimal places after the decimal separator, a
number is given right after the above characters.
D1 = MMM-D-YY, MM-D-YY and similar formats
D2 = DD-MM
D3 = MM-YY
D4 = DD-MM-YYYY HH:MM:SS
D5 = MM-DD
D6 = HH:MM:SS AM/PM
D7 = HH:MM AM/PM
D8 = HH:MM:SS
D9 = HH:MM
G = All other formats
- (Minus) at the end = negative numbers in the cell have color setting
() (brackets) at the end = this cell has the format settings with
parentheses for positive or all values
TYPE
Returns the text value corresponding to the type of content in the cell:
b : blank or empty cell content
l : label or text cell content
v : number value cell content
WIDTH
Returns the column width of the cell.
The unit is the width of one zero (0) character in default font size.
PROTECT
Returns the protection status of the cell:
1 = cell is protected
0 = cell is unprotected
PARENTHESES Returns 1 if the cell has the format settings with parentheses for positive
100414201 29 May 2010
or all values, otherwise returns 0
PREFIX
Returns single character text strings corresponding to the alignment of
the cell.
' (APOSTROPHE, U+0027) = left alignment
'"' (QUOTATION MARK, U+0022) = right alignment
^(caret) = centered alignment
\(back slash) = filled alignment
otherwise, returns empty string "".
R : if R is a reference to a cell, it is the cell whose information will be returned; if R is a reference
to a range, the top-left cell in the range is the selected one; if R is omitted, the current cell is
used.
anchor:CELL
Test Cases:
=CELL("COL";[.B7]) 2 Column B is column number 2.
=CELL("ADDRESS";[.B7]) "$B$7" Absolute address
=CELL("ADDRESS";
[Sheet2.B7])
"$Sheet2.$B$7"
Absolute address including sheet
name
=CELL("ADDRESS";
['x:\sample.ods'#Sheet3.B
7])
"'file:///x:/sample.ods'#
$Sheet3.$B$7"
Absolute address including sheet
name and IRI of location of
document
=CELL("FILENAME") "file:///x:/sample.ods"
The current cell is saved in a file
named sample.ods which is
located at file:///x:/
=CELL("FORMAT";[.C7]) "D4"
C7's number format is like DD-
MM-YYYY HH:MM:SS
Rationale: COORD is one Info_Type in OpenOffice.org; it was removed because involving a
specific product's address format into the standard did not seem appropriate.
6.13.4 COLUMN
Summary: Returns the column number(s) of a reference
Syntax: COLUMN( [ Reference R ] )
Returns: Number
Constraints: AREAS(R) = 1
Semantics: Returns the column number of a reference, where A is 1, B is 2, and so on. If no
parameter is given, the current cell is used. If a reference has multiple columns, an array of numbers
is returned with all of the columns in the reference.
anchor:COLUMN
100414201 29 May 2010
Test Cases:
=COLUMN([.B7]) 2 Column B is column number 2.
=COLUMN() 5
Column of current cell is default, here
formula in column E.
{=COLUMN([.B2:.D2])} {2;3;4} Array with column numbers.
See also ROW, SHEET
6.13.5 COLUMNS
Summary: Returns the number of columns in a given range
Syntax: COLUMNS( Reference|Array R )
Returns: Number
Constraints: None
Semantics: Returns the number of columns in the range or array specified. The result is not
dependent on the cell content in the range.
anchor:COLUMNS
Test Cases:
=COLUMNS([.C1]) 1 Single cell range contains one column.
=COLUMNS([.C1:.C4]) 1 Range with only one column.
=COLUMNS([.A4:.D100]) 4 Number of columns in range.
See also ROWS
Note: Need to determine that null range and sheet traversal works in other implementations. Only
checked OO. The null range gives an Error in Gnumeric and Excel, so removed test.
Note: Excel supports inline Arrays. OpenOffice.org 2 does not support inline arrays.
6.13.6 COUNT
Summary: Count the number of Numbers provided
Syntax: COUNT( { NumberSequenceList N }
+
)
Returns: Number
Constraints: One or more parameters.
100414201 29 May 2010
Semantics: Counts the numbers in the list of NumberSequences provided. Only numbers in
references are counted; all other types are ignored. Errors are not propagated. It is implementation-
defined what happens if 0 parameters are passed, but it should be an Error or 0.
anchor:COUNT
Test Cases:
=COUNT(1;2;3) 3 Simple count.
=COUNT([.B4:.B5]) 2 Two numbers in the range.
=COUNT([.B4:.B5];
[.B4:.B5])
4 Duplicates are not removed.
=COUNT([.B4:.B9]) 2 Errors in referenced cells or ranges are ignored.
=COUNT([.B4:.B8];
1/0)
2 Errors in direct parameters are still ignored.
=COUNT([.B3:.B5]) 2 Conversion to NumberSequence ignores strings (in B3).
See also COUNTA
Note: OpenOffice.org 2.0 propagates errors, while they are skipped in Excel and Gnumeric. For the
moment, claiming that errors should be skipped. Excel 2003 documentation says that in its version
of COUNT, Arguments that are Numbers, Dates, or Text representations of numbers are counted;
arguments that are Error values or Text that cannot be translated into Numbers are ignored. If an
argument is an Array or Reference, only Numbers in that array or reference are counted. Empty
cells, Logical values, Text, or Error values in the array or reference are ignored. If you need to count
Logical values, Text, or Error values, use the COUNTA function.
6.13.7 COUNTA
Summary: Count the number of non-empty values
Syntax: COUNTA( { Any A }
+
)
Returns: Number
Constraints: None.
Semantics: Counts the number of non-blank values in the list of Any sequences provided. A value
is non-blank if it contains any content of any type, including an Error. In a reference, every cell that is
not empty is included in the count. An empty string value ("") is not considered blank. Errors
contained in a range are considered a non-blank value for purposes of the count; errors do not
propagate. Constant expressions or formulas are allowed; these are evaluated and if they produce
an Error value the Error value is counted as one non-blank value (and not propagated as an Error).
It is implementation-defined what happens if 0 parameters are passed, but it should be an Error or
0. Any A may be a ReferenceList.
anchor:COUNTA
Test Cases:
100414201 29 May 2010
=COUNTA("1";2;TRU
E())
3 Simple count of 3 constant values.
=COUNTA([.B3:.B5]) 3 Three non-empty cells in the range.
=COUNTA([.B3:.B5];
[.B3:.B5])
6 Duplicates are not removed
=COUNTA([.B3:.B9]) 6
Where B9 is "=1/0", i.e. an error, counts the error as non-empty;
errors contained in a reference do not propagate the error into
the result.
=COUNTA("1";2;1/0) 3
An error in the list of values is just counted; errors in a constant
parameter do not propagate.
=COUNTA("1";2;SU
M([.B3:.B9]))
3
Errors in an evaluated formula do not propagate; they are just
counted.
=COUNTA("1";2;
[.B3:.B9])
8
Errors in an evaluated formula do not propagate; they are just
counted.
See also COUNT, ISBLANK
6.13.8 COUNTBLANK
Summary: Count the number of blank values
Syntax: COUNTBLANK( ReferenceList R )
Returns: Number
Constraints: None.
Semantics: Counts the number of blank cells in the Reference provided. A cell is blank if the cell is
empty for purposes of COUNTBLANK. If ISBLANK(R) is true, then it is blank. A cell with numeric
value zero ('0') is not blank. It is implementation-defined whether or not a cell returning the empty
string ("") is considered blank; because of this, there is a (potential) subtle difference between
COUNTBLANK and ISBLANK.
Evaluators shall support one Reference as a parameter and may support a ReferenceList as a
parameter.
anchor:COUNTBLANK
Test Cases:
=COUNTBLANK([.B3:.B10]
)
1
Only B8 is blank. Zero ('0') in B10 is not considered
blank.
See also COUNT, COUNTA, COUNTIF, ISBLANK
Rationale: Excel's COUNTBLANK treats the empty string "" as blank, even if it's returned by a
formula, so a cell can have a formula yet be considered blank by this function. In contrast, OOo's
COUNTBLANK considers a cell with a formula that returns to be non-blank. Thus, a cell with the
100414201 29 May 2010
formula =IF(TRUE();"";"False") would be considered blank by Excel's COUNTBLANK, and non-
blank by OOo's COUNTBLANK. Excel's calculation is rather bizarre, because both would consider
ISBLANK(cell) to be FALSE(). In other words, in Excel, COUNTBLANK uses a different rule than
ISBLANK, creating a potential subtle difference between COUNTBLANK and ISBLANK. This
specification specifically avoids requiring such a bizarre semantic, but since some applications may
choose to implement it, it permits these semantics.
6.13.9 COUNTIF
Summary: Count the number of cells in a range that meet a criteria.
Syntax: COUNTIF( ReferenceList R ; Criterion C )
Returns: Number
Constraints: Does not accept constant values as the reference parameter.
Semantics: Counts the number of cells in the reference range R that meet the Criterion C (4.11.7).
The values returned may vary depending upon the HOST-USE-REGULAR-EXPRESSIONS or
HOST-USE-WILDCARDS properties. 3.4
anchor:COUNTIF
See also COUNT, COUNTA, COUNTBLANK, COUNTIFS, SUMIF, Infix Operator "=", Infix Operator
"<>", Infix Operator Ordered Comparison ("<", "<=", ">", ">=")
6.13.10 COUNTIFS
Summary: Count the number of cells that meet multiple criteria in multiple ranges.
Syntax: COUNTIFS( Reference R1 ; Criterion C1 [ ; Reference R2 ; Criterion C2 ]... )
Returns: Number
Semantics: Counts the number of cells that meet the Criterion C1 in the reference range R1 and
the Criterion C2 in the reference range R2, and so on (4.11.7). All reference ranges shall have the
same dimension and size, else an Error is returned. A logical AND is applied between each array
result of each selection; an entry is counted only if the same position in each array is the result of a
Criterion match.
anchor:COUNTIFS
See also COUNT, COUNTA, COUNTBLANK, COUNTIF, SUMIF, Infix Operator "=", Infix Operator
"<>", Infix Operator Ordered Comparison ("<", "<=", ">", ">=")
6.13.11 ERROR.TYPE
Summary: Returns Number representing the specific Error type.
Syntax: ERROR.TYPE( Error E )
Returns: Number
Constraints: None.
100414201 29 May 2010
Semantics: Returns a number representing what kind of Error has occurred. Note that unlike most
functions, this function does not propagate Error values. Receiving a non-Error value returns an
Error. In particular, ERROR.TYPE(NA()) returns 7, and ERROR.TYPE applied to a non-Error returns
an Error.
anchor:ERROR.TYPE
Test Cases:
=ERROR.TYPE(NA()) 7 By convention, the ERROR.TYPE of NA() is 7.
=ERROR.TYPE(0) Error Non-errors produce an error.
See also NA
Note: Excel 2003 has the following Error values (with ERROR.TYPE values), according to
Walkenbach 2003, page 49 and Simon's "Excel 2000 in a Nutshell" page 527:
#DIV/0! (2) - Attempt to divide by zero, including division by an empty cell.
#NAME? (5) - Unrecognized/deleted name.
#N/A (7) - NA. Lookup functions which failed and NA() return this value.
#NULL! (1) - Intersection of ranges produced zero cells.
#NUM! (6) - Failed to meet domain constraints (e.g., input was too large or too small)
#REF! (4) - Reference to invalid cell.
#VALUE! (3) - Parameter is wrong type.
Note: We have decided to not mandate a standard set of Error values. Instead, we are keeping
maximum flexibility by simply asserting that there are Error values without saying what they are
other than NA. In practice, most users just treat all Errors (other than NA) alike, so it doesnt matter
to them. However, not mandating a specific set means that applications are free to be more specific
about their errors.
Note: This function could be named "ERRORTYPE" instead of "ERROR.TYPE". Note that OOo2
uses ERRORTYPE, not ERROR.TYPE, and implementations are free to display ERROR.TYPE if
they would like to. Function names generally don't have "." in them, and the "." is also used to
separate sheetnames from cellreferences. This dual use of "." isn't a problem in the ODF exchange
syntax (because "." before a cell reference can only occur inside square brackets), but it creates a
minor parsing complication when accepting human input if (1) the human doesn't enter the square
brackets (a typical use), and (2) the number of columns greatly exceeds current common
maximums (a likely future possibility). A column named "ERROR" is obviously far beyond today's
sheets (which typically stop at "IV"), but future sheets will presumably have fewer limits, and in any
case coding around special cases is not desirable. If they must code around anything, they might
code in "ERROR.TYPE" as a special case. But in the end, there wasnt a strong reason to name it
other than ERROR.TYPE, so its been left this way.
Rationale: OpenOffice.org 2's ERRORTYPE() returns _DIFFERENT_ values, e.g.,
ERRORTYPE(NA()) returns 32767, not 7. This a reasonable reason to name this function
differently, namely, ERROR.TYPE.
100414201 29 May 2010
6.13.12 FORMULA
Summary: Returns formula at given reference as text
Syntax: FORMULA( Reference X )
Returns: String
Constraints: Reference X shall contain a formula
Semantics: Returns the formula in reference X as a string. The specific syntax of this returned
string is implementation-defined. This function is intended to aid debugging by simplifying display of
formulas in other cells. Error results of the referred formula cell are not propagated.
anchor:FORMULA
Test Cases:
=LENGTH(FORMULA([
.B7]))>0
True B7 is a formula, so this is fine and will produce a text value
=FORMULA([.B3]) True Simple formulas that produce Text are still formulas
See also ISFORMULA
6.13.13 INFO
Summary: Returns information about the environment
Syntax: INFO( Text Category )
Returns: Any (see below)
Constraints: Category shall be valid
Semantics: Returns information about the environment in the given category.
Evaluators shall support at least the following categories:
Table 20 - INFO
Category Meaning Type
"directory" Current directory. This shall be formatted so file names
can be appended to the result (e.g., on POSIX and
Windows systems it shall end with the separator / or
\ respectively).
Text
"memavail" Amount of memory available, in bytes. On many
modern (virtual memory) systems this value is not really
available, but a system should return 0 if it is known that
there is no more memory available, and greater than 0
otherwise
Number
"memused" Amount of memory used, in bytes, by the data Number
"numfile" Number of active worksheets in files Number
100414201 29 May 2010
"osversion" Operating system version Text
"origin" The top leftmost visible cell's absolute reference
prefixed with $A:. In locales where cells are ordered
right-to-left, the top rightmost visible cell is used instead.
Text
"recalc" Current recalculation mode. If the locale is English, this
is either "Automatic" or "Manual" (the exact text
depends on the locale)
Text
"release" The version of the implementation. Text
"system" The type of the operating system. Text
"totmem" Total memory available in bytes, including the memory
already used.
Number
Evaluators may support other categories.
anchor:INFO
Note: The values for INFO(system) vary. Excel 2003 returns pcdos. OpenOffice.org 2.0.1 returns
"WNT" for Microsoft Windows , "LINUX" for Linux, and "SOLARIS" for Solaris. This is fundamentally
dependent on the environment anyway, so there's been no effort to harmonize this.
Note: The format for origin is odd, but it's that way for compatibility.
Test Cases:
=INFO(recalc) Automatic
=ISTEXT(INFO(syst
em))
True
The details of system vary by system, but it is
always a text value
=ISTEXT(INFO("com
pletely-unknown-
category"))
Error Error if the category is unknown
=ISTEXT(INFO("direc
tory"))
Test to see that every required category is supported
=ISNUMBER(INFO("
memavail"))
=ISNUMBER(INFO("
memused"))
=ISNUMBER(INFO("
numfile"))
=ISTEXT(INFO("osve
rsion"))
=ISTEXT(INFO("origi
n"))
=ISTEXT(INFO("recal
100414201 29 May 2010
c"))
=ISTEXT(INFO("relea
se"))
=ISTEXT(INFO("syst
em"))
=ISNUMBER(INFO("t
otmem"))
See also CELL
6.13.14 ISBLANK
Summary: Return TRUE if the referenced cell is blank, else return FALSE
Syntax: ISBLANK( Scalar X )
Returns: Logical
Constraints: None
Semantics: If X is of type Number, Text, or Logical, return FALSE. If X is a reference to a cell,
examine the cell; if it is blank (has no value), return TRUE, but if it has a value, return FALSE. A cell
with the empty string is not considered blank.
anchor:ISBLANK
Test Cases:
=ISBLANK(1) False Numbers return false.
=ISBLANK("") False Text, even empty string, returns false.
=ISBLANK([.B8]) True Blank cell is true.
=ISBLANK([.B7]) False Non-blank cell is false.
See also ISNUMBER, ISTEXT
6.13.15 ISERR
Summary: Return True if the parameter has type Error and is not NA, else return False.
Syntax: ISERR( Scalar X )
Returns: Logical
Constraints: None
100414201 29 May 2010
Semantics: If X is of type Error, and ISNA(X) is not true, returns TRUE. Otherwise it returns FALSE.
Note that this function returns False if given NA(); if this is not desired, use ISERROR. Note that this
function does not propagate Error values.
ISERR(X) is the same as:
IF(ISNA(X),FALSE(),ISERROR(X))
anchor:ISERR
Test Cases:
=ISERR(1/0) True Error values other than NA() return true.
=ISERR(NA()) False NA() does NOT return True.
=ISERR("#N/A") False Text is not an error.
=ISERR(1) False Numbers are not an error.
See also ERROR.TYPE, ISERROR, ISNUMBER, ISTEXT, NA
Note: In Lotus 1-2-3v9, the function named ISERR actually maps to ISERROR, not to ISERR. This
is because in Lotus 1-2-3v9, @ISERR(@NA) is 1 (True). In Quattro Pro, Excel, OpenOffice.org,
SheetToGo, etc., ISERR(NA()) is 0 / False. The function named ISERR is given here with the
semantics of the majority.
6.13.16 ISERROR
Summary: Return TRUE if the parameter has type Error, else return FALSE
Syntax: ISERROR( Scalar X )
Returns: Logical
Constraints: None
Semantics: If X is of type Error, returns TRUE, else returns FALSE. Note that this function returns
True if given NA(); if this is not desired, use ISERR. Note that this function does not propagate Error
values.
anchor:ISERROR
Test Cases:
=ISERROR(1/0) True Error values return true.
=ISERROR(NA()) True Even NA().
=ISERROR("#N/A") False Text is not an error.
=ISERROR(1) False Numbers are not an error.
=ISERROR(CHOOS
E(0; "Apple";
True If CHOOSE given out-of-range
value, ISERROR needs to
100414201 29 May 2010
"Orange"; "Grape";
"Perry"))
capture it.
See also ERROR.TYPE, ISERR, ISNA, ISNUMBER, ISTEXT, NA
Note: KSpread 1.4.2 lacks ISERROR, ISERR, and ISNA. However, KSpread developer Tomas
Mecir announced on January 9, 2006, that he had added implementations of these functions due to
an early draft of the OpenFormula specification, and a future release of KSpread will include these
functions.
OOo2's ISERROR() function lets some errors slip through, instead of being captured. E.G.,
ISERROR(CHOOSE(0;"Apple";"Orange";"Grape";"Perry")) produces an Error, rather than TRUE.
Rationale: Lotus 1-2-3 and Quattro Pro lack ISERROR. They work as though NA were not an Error
value, but something else.. but it's believed NA can still be modelled as an Error value even in those
cases, because it has the same effect. We've left them in the small group, since it's hard to do
some kinds of things (including automated testing) without them.
6.13.17 ISEVEN
Summary: Return TRUE if the value is even, else return FALSE
Syntax: ISEVEN( Number X )
Returns: Logical
Constraints: None
Semantics: First, compute X1=TRUNC(X). Then, if X1 is even (a division by 2 has a remainder of
0), return True, else return False. The result is implementation-defined if given a Logical value; an
evaluator may return either an Error or the result of converting the Logical value to a Number (per
Conversion to Number ).
anchor:ISEVEN
Test Cases:
=ISEVEN(2) True 2 is even, because (2 modulo 2) = 0
=ISEVEN(6) True 6 is even, because (6 modulo 2) = 0
=ISEVEN(2.1) True
=ISEVEN(2.5) True
=ISEVEN(2.9) True TRUNC(2.9)=2, and 2 is even.
=ISEVEN(3) False 3 is not even.
=ISEVEN(3.9) False TRUNC(3.9)=3, and 3 is not even.
=ISEVEN(-2) True
=ISEVEN(-2.1) True
=ISEVEN(-2.5) True
100414201 29 May 2010
=ISEVEN(-2.9) True TRUNC(-2.9)=-2, and -2 is even.
=ISEVEN(-3) False
=ISEVEN(NA()) NA
=ISEVEN(0) True
See also ISODD
6.13.18 ISFORMULA
Summary: Return TRUE if the reference refers to a formula, else return FALSE
Syntax: ISFORMULA( Reference X )
Returns: Logical
Constraints: None
Semantics: If X refers to a cell whose value is computed by a formula, return TRUE(), else return
FALSE(). A formula itself may compute a constant; in that case it will still return TRUE() since it is
still a formula. Passing a non-reference, or a reference to more than one cell, is implementation-
defined.
anchor:ISFORMULA
Test Cases:
=ISFORMULA([.B5]) True Simple formulas that produce Number are still formulas
=ISFORMULA([.B3]) True Simple formulas that produce Text are still formulas
=ISFORMULA([.C5]) False Cell constants are not formulas
=ISFORMULA([.C7]) False Cell constants are not formulas, even if they are dates
=ISFORMULA([.B9]) True Formulas that return an error are still formulas
See also ISTEXT, ISNUMBER
6.13.19 ISLOGICAL
Summary: Return TRUE if the parameter has type Logical, else return FALSE
Syntax: ISLOGICAL( Scalar X )
Returns: Logical
Constraints: None
Semantics: If X is of type Logical, returns TRUE, else FALSE. Evaluators that do not have a distinct
Logical type will return the same value ISNUMBER(X) would return.
anchor:ISLOGICAL
100414201 29 May 2010
Test Cases:
=ISLOGICAL(TRUE()) True Logical values return true.
=ISLOGICAL(FALSE()) True Logical values return true.
=ISLOGICAL("TRUE") False Text values are not logicals, even if they can be converted.
See also ISTEXT, ISNUMBER
6.13.20 ISNA
Summary: Return True if the parameter is of type NA, else return False.
Syntax: ISERR( Scalar X )
Returns: Logical
Constraints: None
Semantics: If X is NA, return True, else return False. Note that if X is a reference, the value being
referenced is considered. This function does not propagate Error values.
anchor:ISNA
Test Cases:
=ISNA(1/0) False
Error values other than NA() return False
the error does not propagate.
=ISNA(NA()) True By definition
=ISNA(#N/A) True By definition
=ISNA("#N/A") False Text is not NA
=ISNA(1) False Numbers are not NA
See also ERROR.TYPE, ISERROR, ISERR, ISNUMBER, ISTEXT, NA
6.13.21 ISNONTEXT
Summary: Return TRUE if the parameter does not have type Text, else return FALSE
Syntax: ISNONTEXT( Scalar X )
Returns: Logical
Constraints: None
Semantics: If X is of type Text, returns FALSE, else TRUE. If X is a reference, examines what X
references. References to empty cells are NOT considered Text, so a reference to an empty cell will
return TRUE. Empty Cell 4.7
100414201 29 May 2010
ISNONTEXT(X) is equivalent to NOT(ISTEXT(X))
anchor:ISNONTEXT
Test Cases:
=ISNONTEXT(1) True Numbers are not text
=ISNONTEXT(TRUE()
)
True Logical values are not text.
=ISNONTEXT("1") False
Text values are text, even if they can be converted into a
number.
=ISNONTEXT([.B7]) False B7 is a cell with text
=ISNONTEXT([.B9]) True B9 is an error, thus not text
=ISNONTEXT([.B8]) True B8 is a blank cell, so this will return TRUE
See also ISNUMBER, ISLOGICAL, ISTEXT
6.13.22 ISNUMBER
Summary: Return TRUE if the parameter has type Number, else return FALSE
Syntax: ISNUMBER( Scalar X )
Returns: Logical
Constraints: None
Semantics: If X is of type Number, returns TRUE, else FALSE. Evaluators may not have a
distinguished Logical type; in such evaluators, ISNUMBER(TRUE()) is TRUE.
anchor:ISNUMBER
Test Cases:
=ISNUMBER(1) True Numbers are numbers
=ISNUMBER("1") False
Text values are not numbers, even if they can be converted into a
number.
See also ISTEXT, ISLOGICAL
6.13.23 ISODD
Summary: Return TRUE if the value is even, else return FALSE
Syntax: ISODD( Number X )
Returns: Logical
100414201 29 May 2010
Constraints: None
Semantics: First, compute X1=TRUNC(X). Then, if X1 is odd (a division by 2 has a remainder of 1),
return True, else return False. The result is implementation-defined if given a Logical value; an
evaluator may return either an Error or the result of converting the Logical value to a Number (per
Conversion to Number ).
anchor:ISODD
Test Cases:
=ISODD(3) True 3 is odd, because (3 modulo 2) = 0
=ISODD(5) True 5 is odd, because (5 modulo 2) = 0
=ISODD(3.1) True TRUNC(3.1)=3, and 3 is odd
=ISODD(3.5) True
=ISODD(3.9) True TRUNC(3.9)=3, and 3 is odd.
=ISODD(4) False 3 is not even.
=ISODD(4.9) False TRUNC(3.9)=3, and 3 is not even.
=ISODD(-3) True
=ISODD(-3.1) True
=ISODD(-3.5) True
=ISODD(-3.9) True TRUNC(-3.9)=-3, and -3 is odd.
=ISODD(-4) False
=ISODD(NA()) NA
=ISODD(0) False
=ISODD(1) True
=ISODD(2) False
=ISODD(2.9) False
See also ISEVEN
6.13.24 ISREF
Summary: Return True if the parameter is of type reference, else return False.
Syntax: ISREF( Any X )
Returns: Logical
Constraints: None
100414201 29 May 2010
Semantics: If X is of type Reference or ReferenceList, return True, else return False. Note that
unlike nearly all other functions, when given a reference this function does not then examine the
value being referenced. Some functions and operators return references, and thus ISREF will return
True when given their results. X may be a ReferenceList, in which case ISREF returns True.
anchor:ISREF
Test Cases:
=ISREF([.B3]) True
=ISREF([.B3]:
[.C4])
True The range operator produces references
=ISREF(1) False Numbers are not references
=ISREF("A1") False
Text is not a reference, even if it looks a little
like one
=ISREF(NA()) NA Errors propagate through this function
See also ISNUMBER, ISTEXT
6.13.25 ISTEXT
Summary: Return TRUE if the parameter has type Text, else return FALSE. If X is a reference,
examines what X references. References to empty cells are NOT considered Text, so a reference to
a empty cell will return FALSE. Empty Cell 4.7
ISTEXT(X) is equivalent to NOT(ISNONTEXT(X)).
Syntax: ISTEXT( Scalar X )
Returns: Logical
Constraints: None
Semantics: If X is of type Text, returns TRUE, else FALSE. References to blank cells are NOT
considered Text.
anchor:ISTEXT
Test Cases:
=ISTEXT(1) False Numbers are not text
=ISTEXT("1") True Text values are text, even if they can be converted into a number.
See also ISNONTEXT, ISNUMBER, ISLOGICAL
6.13.26 N
Summary: Return the number of a value.
100414201 29 May 2010
Syntax: N( Any X )
Returns: Text
Constraints: None
Semantics: If X is a Reference, it is first dereferenced to a scalar. Then its type is examined. If it is
of type Number, it is returned. If it is of type Logical, 1 is returned if TRUE else 0 is returned. It is
implementation-defined what happens if it is provided a Text value.
anchor:N
Test Cases:
=N(6) 6 N does not change numbers.
=N(TRUE()) 1 Does convert logicals.
=N(FALSE()) 0 Does convert logicals.
See also T, VALUE
Note: Many public documents inadequately describe this function; in particular, few seem to
describe exactly what happens when text is provided. N("4") produces 0 in Excel, but 4 in Ooo2.
6.13.27 NA
Summary: Return the constant Error value #N/A.
Syntax: NA()
Returns: Error
Constraints: Shall have 0 parameters
Semantics: This function takes no arguments and returns the Error NA
anchor:NA
Test Cases:
=ISERROR(NA()
)
True NA is an error.
=ISNA(NA()) True Obviously, if this doesn't work, NA() or ISNA() is broken.
=ISNA(5+NA()) True
NA propagates through various functions and operators, just like any
other error type.
See also ERROR.TYPE, ISERROR
100414201 29 May 2010
6.13.28 NUMBERVALUE
Summary: Convert text to number, in a locale-independent way
Syntax: NUMBERVALUE( Text X [ ; Text DecimalSeparator [ ; Text GroupSeparator ] ] )
Returns: Number
Constraints: LEN(DecimalSeparator) = 1, DecimalSeparator shall not appear in GroupSeparator
Semantics: Converts given Text value X into Number. If X is a Reference, it is first dereferenced.
DecimalSeparator defines the character used as the decimal separator, for example "." (period) or
"," (comma). If this parameter is not given, only integer numbers are parsed.
GroupSeparator defines the character(s) used as grouping separator, for example "," (comma) or "."
(period). If this parameter is not given, only integer or decimal numbers containing the
DecimalSeparator are parsed. If this parameter is given, all characters contained are ignored in T if
each is surrounded by a digit on each side. If GroupSeparator contains " " U+0020 (SPACE),
U+0020 and U+00A0 (NO-BREAK SPACE) shall be equally treated.
If the supplied text X cannot be converted into a Number, an Error is returned.
Regardless of the current locale, the evaluator shall accept text representations that match this
regular expression when DecimalSeparator is "." (a period) and GroupSeparator is "," (a comma):
[+|-]?([0-9]+(,[0-9])*)?(\.[0-9]+)?(([eE][+-]?[0-9]+)|%)?
If, for example, DecimalSeparator is "," (a comma) and GroupSeparator is "." (a period), use the
expression above but swapping the comma for the period (so "." is ignored).
anchor:NUMBERVALUE
Rationale: This doesn't handle all possible number format of all locales, but it handles a large
number of locales while ensuring that processing is not dependent on the current locale. Early drafts
of this specification had a VALUEL, which accepted a locale parameter, but this turned out to be
unwieldy... so this alternative was proposed instead.
Test Cases:
=NUMBERVALUE("6"; .) 6 VALUE converts text to numbers (unlike N).
=NUMBERVALUE("6,000.5"; .) 6000.5 Period works.
=NUMBERVALUE("6.000,5";,) 6000.5 Comma works
See also N, T, DATEVALUE, TIMEVALUE, VALUE
6.13.29 ROW
Summary: Returns the row number(s) of a reference
Syntax: ROW( [ Reference R ] )
Returns: Number
Constraints: AREAS(R) = 1
100414201 29 May 2010
Semantics: Returns the row number of a reference. If no parameter is given, the current cell is
used. If a reference has multiple rows, an array of numbers is returned with all of the rows in the
reference.
anchor:ROW
Test Cases:
=ROW([.B7]) 7
The second value of a cell reference is the
row number.
=ROW() 5
Row of current cell is default, here formula in
row 5.
{=ROW([.B2:.B4])} {2|3|4} Array with row numbers.
See also COLUMN, SHEET
Note: Testing the default row value is tricky the test case above simply ensure that it is legal to
have zero parameters. Real implementations actually have to get the row number correct, though of
course this is not hard to do.
6.13.30 ROWS
Summary: Returns the number of rows in a given range
Syntax: ROWS( Reference|Array R )
Returns: Number
Constraints: None
Semantics: Returns the number of rows in the range or array specified. The result is not dependent
on the cell content in the range.
anchor:ROWS
Test Cases:
=ROWS([.C1]) 1 Single cell range contains one row.
=ROWS([.C1:.C4]) 4 Range with four rows.
=ROWS([.A4:.D100]) 97 Number of rows in range.
See also COLUMNS
Note: Removed tests for null range and sheet traversal works in other implementations. Only
checked OO. The null range gives an Error in Gnumeric and in Excel.
Note: Excel supports inline Arrays. OpenOffice.org 2 does not support inline arrays.
100414201 29 May 2010
6.13.31 SHEET
Summary: Returns the sheet number of the reference or the string representing a sheet name.
Syntax: SHEET( [ Text|Reference R ] )
Returns: Number >= 1
Constraints: R shall not contain a Source Location (5.8 References)
Semantics: Returns the 1 based sheet number of the given reference or sheet name.
Hidden sheets are not excluded from the sheet count.
If no parameter is given, the result is the sheet number of the sheet containing the formula.
If a Reference is given it is not dereferenced.
If the reference encompasses more than one sheet, the result is the number of the first sheet in the
range.
If a reference does not contain a sheet reference, the result is the sheet number of the sheet
containing the formula.
anchor:SHEET
Test Cases:
=SHEET([.B7])>=1 True
If given, the sheet number of the reference is
used.
=SHEET("Sheet1")>=1 True
Given a sheet name, the sheet number is
returned.
See also COLUMN, ROW, SHEETS
6.13.32 SHEETS
Summary: Returns the number of sheets in a reference or current document
Syntax: SHEETS( [ Reference R ] )
Returns: Number >= 1
Constraints: R shall not contain a Source Location (5.8 References)
Semantics: Returns the number of sheets in the given reference.
If no parameter is given, the number of sheets in the document is returned.
Hidden sheets are not excluded from the sheet count.
anchor:SHEETS
Test Cases:
100414201 29 May 2010
=SHEETS([.B7]) 1
If given, the number of sheets in the
reference is used.
=SHEETS([Sheet1.B7:Sh
eet3.C9])
3
If given, the number of sheets in the
reference is used.
=SHEETS()>=1 True
Without a parameter, return the number of
sheets in this document.
See also COLUMNS, ROWS, SHEET
Note: These aren't rigorous tests, but they ensure that the function is defined and that it can be
called with and without a parameter.
6.13.33 TYPE
Summary: Returns a number indicating the type of the provided value.
Syntax: TYPE( Any value )
Returns: Number
Constraints: None
Semantics: Returns a number indicating the type of the value given:
Table 21 - TYPE
Value's Type TYPE Return
Number 1
Text 2
Logical 4
Error 16
Array 64
If a Reference is provided, the reference is first dereferenced, and any formulas are evaluated.
Note: Reliance on the return of 4 for TYPE() will impair the interoperability of a document containing
an expression that relies on that value.
anchor:TYPE
Test Cases:
=TYPE(1+2) 1 Number has TYPE code of 1
=TYPE(Hi&there) 2 Text has TYPE 2
=TYPE(NA()) 16 Errors have TYPE 16.
100414201 29 May 2010
See also ERROR.TYPE
Note: We don't test for array here, because not all applications that support TYPE() support inline
arrays.
6.13.34 VALUE
Summary: Convert text to number
Syntax: VALUE( Text X )
Returns: Number
Constraints: None
Semantics: Converts given text value X into Number. If X is a Reference, it is first dereferenced.
VALUE is only specified if it is given a Text value or a Reference to a single cell containing a Text
value; it is implementation-defined what happens if VALUE is given neither a Text value nor a
Reference to a Text value. If the Text has a date, time, or datetime format, it is converted into a
serial Number. In many cases the conversion of a date or datetime format is locale-dependent.
If the supplied text X cannot be converted into a Number, an Error is returned.
Regardless of the current locale, an evaluator shall accept numbers matching this regular
expression (which does not include a decimal point character) and convert it into a Number. If the
value ends in %, it shall divide the number by 100:
[+-]? [0-9]+([eE][+-]?[0-9]+)?)%?
VALUE shall accept text representations of numbers in the current locale. In the en_US locale, an
evaluator shall accept decimal numbers matching this regular expression and convert it into a
Number (the leading $ is ignored; commas are ignored if they match the rule of a thousands
separator; if the value ends in %, it shall divide the number by 100):
[+-]?\$?([0-9]+(,[0-9]{3})*)?(\.[0-9]+)?(([eE][+-]?[0-9]+)|%)?
Note: Unfortunately, VALUE is locale-dependent for issues such as decimal points and the currency
format.
Evaluators shall accept accept fractional values matching the regular expression:
[+-]? [0-9]+ \ [0-9]+/[1-9][0-9]?
A leading minus sign is considered identifying a negative number for the entire value. There is a
space between the integer and the fractional portion; values between 0 and 1 can be represented
by using 0 for the integer part.
Evaluators shall support time values in at least the HH:MM and HH:MM:SS formats, where HH is a
1-2 digit value from 0 to 23, MM is a 1-2 digit value from 0 to 59, and SS is a 1-2 digit value from 0
to 59. The hour may be one or two digits when it is less than 10. VALUE converts time values into
Numbers ranging from 0 to 1, which is percentage of day that has elapsed by that time. Thus,
VALUE("2:00") is the same as 2/24. Evaluators should accept times with fractional seconds as well
when expressed in the form HH:MM:SS.ssss...
Evaluators shall accept textual dates in ISO 8601 format (YYYY-MM-DD), converting them into
serial numbers based on the current epoch. Evaluators shall, when running in the en_US locale,
accept the format MM/DD/YYYY .
In addition, in locale en_US, evaluators shall support the following formats (where YYYY is a 4-digit
year, YY a 2-digit year, MM a numerical month, DD a numerical day, mmm a 3-character
abbreviated alphabetical name, and mmmmm a full name):
100414201 29 May 2010
Table 22 - VALUE
Format Example Comment
MM/DD/YYY
Y
5/21/2006 LOCALE-DEPENDENT; Long year format with slashes.
MM/DD/YY 5/21/06 LOCALE-DEPENDENT; Short year format with slashes
MM-DD-
YYYY
5-21-2006
LOCALE-DEPENDENT; Long year format with dashes (short year
may be supported, but it may also be used for years less than 100 .
mmm DD,
YYYY
Oct 29, 2006
LOCALE-DEPENDENT; Short alphabetic month day, year. Note:
mmm depends on the locale's language.
DD mmm
YYYY
29 Oct 2006 LOCALE-DEPENDENT; Short alphabetic day month year
mmmmm DD,
YYYY
October 29,
2006
LOCALE-DEPENDENT; Long alphabetic month day, year
DD mmmmm
YYYY
29 October
2006
LOCALE-DEPENDENT; Long alphabetic day month year
Evaluators should support other locales. Many conversions will vary by locale, including the decimal
point (comma or period), names of months, date formats (MM/DD vs. DD/MM), and so on. Dates in
particular vary by locale.
Evaluators shall support the datetime format, which is a date followed by a time, using either the
space character or the literal T character as the separator (the T is from ISO 8601). Evaluators
shall support at least the ISO date format in a datetime format; they may support other date formats
in a datetime format as well. Formats such as YYYY-MM-DD HH:MM and YYYY-MM-
DDTHH:MM:SS (where T is the literal character T) shall be accepted. The result of accepting a
datetime format shall be a representation of that specific time (without removing either the date or
the time of day, unlike DATEVALUE or TIMEVALUE).
Evaluators may accept other formats that will convert to numbers, and those conversions may be
locale-dependent, as long as they do not conflict with the above. Where no conversion is
determined, an Error is returned.
anchor:VALUE
Test Cases:
=VALUE("6") 6 VALUE converts text to numbers (unlike N).
=VALUE("1E5") 100000 Works with exponential notation.
=VALUE("200%") 2 Optional %.
=VALUE("1.5") 1.5
LOCALE-DEPENDENT: Accepts fractional values. In
en_US, this is valid.
=VALUE("7 1/4") 7.25 Fractional part.
=VALUE("0 1/2") 0.5 Fractional part.
=VALUE("-1 1/2") -1.5 -1 1/2 is interpreted as -1.5, not as (-1)+(1 / 2).
100414201 29 May 2010
=VALUE([.B3]) 7 VALUE converts references to text to numbers.
=VALUE("00:00") 0
VALUE converts time values to numbers between 0
and 1.
=VALUE("02:00")-2/24 0
VALUE converts time values to numbers between 0
and 1.
=VALUE("2:03")-(2/24)-(3/
(24*60))
0 Time value with hours and minutes.
=VALUE("2:03:05") -2/24-3/
(24*60) -5/(24*60*60)
0 Hours, minutes, and seconds.
=VALUE("3/32/2006") Error Invalid date yields an error (contrast this with DATE)
=VALUE("2/29/2006") Error
"False leap year" yields an error for 1901 and
beyond
=VALUE("2005-01-
02")=DATE(2005;1;2)
True VALUE converts dates into serial numbers.
=VALUE("2005-01-03 13:00")-
VALUE("2005-01-02 01:00")
1.5
Datetime values handled correctly, using space to
separate date from time. Note that VALUE can return
portions of a day, unlike DATEVALUE or
TIMEVALUE.
=VALUE("2005-01-03T13:00")-
VALUE("2005-01-02T01:00")
1.5
Datetime values handled correctly, using T to
separate date from time as defined by ISO 8601.
=VALUE("1/2/2005")=DATE(200
5;1;2)
True LOCALE-DEPENDENT; in en_US, this is true.
=VALUE("5/21/06")=DATE(2006
;5;21)
True
LOCALE-DEPENDENT; Short year format with
slashes
=VALUE("Oct 29,
2006")=DATE(2006;10;29)
True
LOCALE-DEPENDENT; Short alphabetic month day,
year
=VALUE("29 Oct
2006")=DATE(2006;10;29)
True
LOCALE-DEPENDENT; Short alphabetic day month
year
=VALUE("October 29,
2006")=DATE(2006;10;29)
True
LOCALE-DEPENDENT; Long alphabetic month day,
year
=VALUE("29 October
2006")=DATE(2006;10;29)
True
LOCALE-DEPENDENT; Long alphabetic day month
year
See also N, T, DATEVALUE, TIMEVALUE, NUMBERVALUE
Note: Some applications (such as Excel and Gnumeric) apply VALUE automatically when Text or a
reference to Text is provided, but a Number is required. Others, such as OOo2 and Lotus 1-2-3,
require explicit use of VALUE.
It's unfortunate that VALUE is locale-specific, even for ordinary numbers. NUMBERVALUE was
created to provide a way to deal with , vs. . as the decimal point.
100414201 29 May 2010
KSpread 1.4.2 incorrectly computes VALUE("6") as 0; it should be 6. Tomas Mecir reports that as of
January 9, 2006, the development version of KSpread (in CVS) computes VALUE("6") correctly
instead.
Note: Short year formats with dashes, like 5-21-06, aren't required here, because if an
implementation supports years before 100 they're not always distinguishable. For more on date
conversion, see "Excel 2003 Formulas" page 144-145.
Note: Lotus 1-2-3 and Quattro Pro don't support ISO date format YYYY-MM-DD. Excel,
OpenOffice.org, Gnumeric, SheetToGo, and KOffice all do.
6.14 Lookup Functions
6.14.1 General
These functions look up information. Note that IF() can be considered a trivial lookup function, but it
is listed as a logical function instead.
6.14.2 ADDRESS
Summary: Returns a cell address (reference) as text
Syntax: ADDRESS( Integer Row ; Integer Column [ ; Integer Abs = 4 [ ; Logical A1 = TRUE() [ ;
Text Sheet ] ] ] )
Returns: Text
Constraints: Row >= 1, Column >= 1, 1 <= Abs <= 4; A1 = TRUE(). Evaluators may evaluate
expressions that do not meet the constraint A1 = TRUE().
Semantics: Returns a cell address (reference) as text. The text does not include the surrounding
[...] of a reference. If a Sheet name is given, the sheet name in the text returned is followed by a .
and the column/row reference if A1 is TRUE, or a ! and the column/row reference if A1 is FALSE;
otherwise no . respectively ! is included. Columns are identified using uppercase letters. The
value of Abs determines if the column and/or row is absolute or relative. The value of A1 determines
if A1 reference style or R1C1 reference style is used.
Table 23 - ADDRESS
Abs Meaning A1 = TRUE() A1 = FALSE()
1 fully absolute $A$1 R1C1
2 row absolute, column relative A$1 R1C[1]
3 row relative, column absolute $A1 R[1]C1
4 fully relative A1 R[1]C[1]
Note that the INDIRECT function accepts this format.
anchor:ADDRESS
Test Cases:
=ADDRESS(5; 3; 2; TRUE(); Sheet1.C$5 Example showing all parameters
100414201 29 May 2010
"Sheet1")
=ADDRESS(5; 3) C5 Last three parameters can be omitted
See also INDIRECT
NOTE: Excel has a subtly incompatible format for the sheet text, using an exclamation mark as the
sheet name separator. For this reason in the non-A1 R1C1 case the exclamation mark was
specified, because applications that support the R1C1 reference style usually also support the
exclamation mark.
6.14.3 CHOOSE
Summary: Uses an index to return a value from a list of values.
Syntax: CHOOSE( Integer Index ; { Any Value }
+
)
Returns: Any
Constraints: Returns an Error if Index < 1 or if there is no corresponding value in the list of Values.
Semantics: Uses Index to determine which value, from a list of values, to return. If Index is 1,
CHOOSE returns the first Value; if Index is 2, CHOOSE returns the second value, and so on. Note
that the Values may be formula expressions. Expression paths of parameters other than the one
chosen are not calculated or evaluated for side effects.
anchor:CHOOSE
Test Cases:
=CHOOSE(3;"Apple";"Orange";"Grape";"P
erry")
"Grape" Simple selection.
erry")
Error Index has to be at least 1.
erry")
Error Index can't refer to non-existent entry.
=CHOOSE(2;SUM([.B4:.B5]);SUM([.B5])) 3 Simple selection, using a set of formulas.
=SUM(CHOOSE(2;[.B4:.B5];[.B5])) 3 CHOOSE can pass references
See also IF
Note: OOo2 produces errors if the index is too small or large, but the index cannot be captured by
ISERROR. This is probably a defect in ISERROR. Currently this ISERROR requirement assigned to
level 2, to allow automated tests to work correctly.
6.14.4 GETPIVOTDATA
Summary: Return a value from a data pilot table.
Syntax: GETPIVOTDATA( Text DataField ; Reference Table { ; Text Field ; Scalar Member }
*
)
100414201 29 May 2010
Note: This function knows two different syntaxes. This version of the syntax is distinguished by the
second parameter Table being a Reference.
Returns: Any
Semantics: Returns a single result from the calculation of a data pilot table.
The data pilot table is selected by Table, which is a reference to a cell or cell range that's within a
data pilot table or contains a data pilot table. If the cell range contains several data pilot tables, the
last one in the order of <table:data-pilot-table> elements in the file is used.
DataField selects one of the data pilot table's data fields. It can be the name of the source column,
or the given name of the data field (such as Sum of Sales).
If no Field/Member pairs are given, the grand total is returned. Otherwise, each pair adds a
constraint that the result shall satisfy. Field is the name of a field from the data pilot table. Member
is the name of a member (item) from that field. If a member is a number, Member can alternatively
be its numerical value.
If the data pilot table contains only a single result value that fulfills all of the constraints, or a subtotal
result that summarizes all matching values, that result is returned. If there is no matching result, or
several ones without a subtotal for them, an Error is returned. These conditions apply to results that
are included in the data pilot table. If the source data contains entries that are hidden by settings of
the data pilot table, they are ignored. The order of the Field/Member pairs is not significant. Field
and member names are case-insensitive.
If no constraint for a page field is given, the field's selected value is implicitly used. If a constraint for
a page field is given, it shall match the field's selected value, or an Error is returned.
Subtotal values from the data pilot table are only used if they use the function auto (except when
specified in the constraint, see below).
Alternative syntax: GETPIVOTDATA( Reference Table ; Text Constraints )
For compatibility, a second syntax is allowed. Table has the same meaning as above. This version
of the syntax is distinguished by the first parameter Table being a Reference.
Constraints is a space-separated list. Entries can be quoted (single quotes). One of the entries can
be the data field name. The data field name can be left out if the data pilot table contains only one
data field, otherwise it shall be present. Each of the other entries specifies a constraint in the form
Field[Member] (with literal characters [ and ]), or only Member if the member name is unique within
all fields that are used in the data pilot table. A function name can be added in the form
Field[Member;Function], which will cause the constraint to match only subtotal values which use
that function. The possible function names are the same as in the table:function attribute of
the <table:data-pilot-subtotal> element, case-insensitive.
anchor:GETPIVOTDATA
Test Cases:
TBD: if we wanted test cases for this, we'd have to have a sufficient data table structure, create a
DataPilot table from it, and then use the test cases with that.
6.14.5 HLOOKUP
Summary: Look for a matching value in the first row of the given table, and return the value of the
indicated row.
Syntax: HLOOKUP( Any Lookup ; Reference|Array DataSource ; Integer Row [ ; Logical
RangeLookup = TRUE() ] )
100414201 29 May 2010
Returns: Any
Constraints: Row >= 1; Searched portion of DataSource shall not include Logical values.
Evaluators may evaluate expressions that do not meet the constraint that the searched portion of a
DataSource not include Logical values.
Semantics:
If RangeLookup is omitted or TRUE or not 0, the first row of DataSource is assumed to be sorted in
ascending order, with smaller numbers before larger ones, smaller text values before larger ones
(e.g., "A" before "B", and "B" before "BA"), and False before True. If the types are mixed, Numbers
are sorted before Text, and Text before Logicals; evaluators without a separate Logical type may
include a Logical as a Number. The lookup will try to match an entry of value Lookup. If none is
found the largest entry less than Lookup is taken as a match. From a sequence of identical values
<= Lookup the last entry is taken. If there is no data less than or equal to Lookup, the #N/A Error is
returned. If Lookup is of type Text and the value found is of type Number, the #N/A Error is returned.
If DataSource is not sorted, the result is undetermined and implementation-dependent. In most
cases it will be arbitrary and just plain wrong due to binary search algorithms.
If RangeLookup is FALSE or 0, DataSource does not need to be sorted and an exact match is
searched. Each value in the first row of DataSource is examined in order (starting at the left) until its
value matches Lookup.
Both methods, if there is a match, return the corresponding value in row Row, relative to the
DataSource, where the topmost row in DataSource is 1.
anchor:HLOOKUP
Test Cases:
=HLOOKUP("Rev"; [.B18:.I31];2;FALSE()) 13 First Rev data entry.
=HLOOKUP("NOSUCHNAME";
[.B18:.I31];2;FALSE())
Error No such value.
=HLOOKUP("Rev"; [.B18:.I31];2) 13
The result is
undetermined since the
first row is not sorted
ascending!
Binary search algorithms
may accidentally deliver
the correct result because
in this case "Rev" is the
last entry and they inspect
outermost values first.
=HLOOKUP("NOSUCHNAME"; [.B18:.I31];2)
12 Mar
2005
The result is
undetermined since the
first row is not sorted
ascending!
TBD: test cases with string lookups and RangeLookup=TRUE (or omitted) aren't that useful for
understanding the functionality, numeric lookups in a set of classifications like those used in
VLOOKUP would be better suited.
See also INDEX, MATCH, OFFSET, VLOOKUP
100414201 29 May 2010
6.14.6 INDEX
Summary: Returns a value using a row and column index value (and optionally an area index).
Syntax: INDEX( ReferenceList|Array DataSource ; [ Integer Row ] [ ; [ Integer Column ] ] [ ; Integer
AreaNumber = 1 ] )
Returns: Any
Constraints: Row >= 0, Column >= 0,
1 <= AreaNumber <= number of references in DataSource if that is a ReferenceList, else
AreaNumber = 1
Semantics:
Given a DataSource, returns the value at the given Row and Column (starting numbering at 1,
relative to the top left of the DataSource) of the given area AreaNumber. If AreaNumber is not
given, it defaults to 1 (the first and possibly only area). This function is essentially a two-dimensional
version of CHOOSE, which does not accept range parameters.
If Row is omitted or an empty parameter (two consecutive ;; semicolons) or 0, an entire column of
the given area AreaNumber in DataSource is returned. If Column is omitted or an empty parameter
(two consecutive ;; semicolons) or 0, an entire row of the given area AreaNumber in DataSource is
returned. If both, Row and Column, are omitted or empty or 0, the entire given area AreaNumber is
returned.
If DataSource is a one-dimensional column vector, Column is optional or can be omitted as an
empty parameter (two consecutive ;; semicolons). If DataSource is a one-dimensional row vector,
Row is optional, which effectively makes Row act as the column offset into the vector, or can be
omitted as an empty parameter (two consecutive ;; semicolons).
If Row or Column have a value greater than the dimension of the corresponding given area
AreaNumber, an Error is returned.
anchor:INDEX
Test Cases:
=INDEX([.B3:.C5];2;1) 2 Simple index into row 2, column 1.
=INDEX([.B3:.C5]~[.B6:.C8];2;1;2) "Hello" Index into row 2, column 1, of area 2
TODO: test cases for the quite complex semantics.
See also AREAS, CHOOSE
6.14.7 INDIRECT
Summary: Return a reference given a string representation of a reference
Syntax: INDIRECT( Text Ref [ ; Logical A1 = TRUE() ] )
Returns: Reference
Constraints: Ref is valid reference
Semantics: Given text for a reference (such as A3), returns a reference. If A1 is False, it is
interpreted as an R1C1 reference style. For interoperability, if the Ref text includes a sheet name,
evaluators should be able to parse both, the . dot and the ! exclamation mark, as the sheet name
100414201 29 May 2010
separator. If evaluators support the A1=FALSE() case of the ADDRESS function and include the !
exclamation mark as the sheet name separator, evaluators shall correctly parse that in the
A1=FALSE() case of this INDIRECT function. Evaluators shall correctly parse the . dot as the
sheet name separator in the A1=TRUE() case.
anchor:INDIRECT
Test Cases:
=INDIRECT(B & 4) 2 Simple lookup
=SUM(INDIRECT(B4:
B5))
5
INDIRECT can create
references to ranges
=ISREFERENCE(INDI
RECT(B4))
True
INDIRECT returns a reference
value.
See also ADDRESS
TODO: Should we discuss external files? Here Excel and OOo differ. It's probably perfectly
reasonable to have a function that can accept either format, which would be more general.
6.14.8 LOOKUP
Summary: Look for criterion in an already-sorted array, and return a corresponding result
Syntax: LOOKUP( Any Find ; ForceArray Reference|Array Searched [ ; ForceArray Reference|
Array Results ] )
Returns: Any
Constraints: The searched portion of Searched shall be sorted in ascending order; if provided,
Results shall have the same length as Searched. The searched portion of Searched shall not
include Logical values. Evaluators may evaluate expressions that do not meet the constraint that
the searched portion of a Searched not include Logical values.
Semantics: This function searches for Find in a row or column of the previously-sorted array
Searched and returns a corresponding value. The match is the largest value in the row/column of
Searched that is less than or equal to Find (so an exact match is always preferred over inexact
ones). From a sequence of identical values <= Find the last entry is taken. If Find is smaller than the
smallest value in the first row or column (depending on the array dimensions), LOOKUP returns the
#N/A Error. If Find is of type Text and the value found is of type Number, the #N/A Error is returned.
The searched portion of Searched shall be sorted in ascending order, and so that values of type
Number precede values of type Text if both types are included (e.g., -2, 0, 2, A, B).
Note: In Excel, mixed types must be sorted as Number, Text, and Logical (in that order). This isn't
possible in general if Logical is not a distinct type, which is why the portable constraint is stated this
way.
There are two major uses for this function; the 3-parameter version (vector) and the 2-parameter
version (non-vector array).
Note: Interoperability is improved by use of HLOOKUP or VLOOKUP in expressions over LOOKUP.
When given two parameters, Searched is first examined:
100414201 29 May 2010
If Searched is square or is taller than it is wide (more rows than columns), LOOKUP searches in
the first column (similar to VLOOKUP), and returns the corresponding value in the last column.
If Searched covers an area that is wider than it is tall (more columns than rows), LOOKUP
searches in the first row (similar to HLOOKUP), and returns the corresponding value in the last
row.
When given 3 parameters, Results shall be a vector (either a row or a column) or an Error is raised.
The function determines the index of the match in the first column respectively row of Searched,
and returns the value in Results with the same index.
Searched is first examined:
If Searched is square or is taller than it is wide (more rows than columns), LOOKUP searches in
the first column (similar to VLOOKUP).
If Searched covers an area that is wider than it is tall (more columns than rows), LOOKUP
searches in the first row (similar to HLOOKUP).
The lengths of the search vector and the result vector do not need to be identical. When the match
position falls outside the length of the result vector, an Error is returned if the result vector is given
as an array object. If it is a cell range, it gets automatically extended to the length of the searched
vector, but in the direction of the result vector. If just a single cell reference was passed, a column
vector is generated. If the cell range cannot be extended due to the sheet's size limit, then the #N/A
Error is returned.
anchor:LOOKUP
Test Cases:
=LOOKUP(6;
[.B51:.B57];
[.C51:.C57])
11 Simple lookup
=LOOKUP(6;
[.B51:.B57];
[.C52:.C58])
12
Result vector doesn't need to
align with search vector
=LOOKUP(6;
[.B51:.C57])
11 Two-parameter version
=LOOKUP(0;
[.B51:.B57];
[.C52:.C58])
Error Too small produces Error
=LOOKUP(6.1;
[.B51:.B57];
[.C51:.C57])
11
Lookup if not exact, largest
available that is smaller than
value to Find
See also HLOOKUP, INDEX, MATCH, OFFSET, VLOOKUP
100414201 29 May 2010
6.14.9 MATCH
Summary: Finds a Search item in a sequence, and returns its position (starting from 1).
Syntax: MATCH( Scalar Search ; Reference|Array SearchRegion [ ; Integer MatchType = 1 ] )
Returns: Any
Constraints: -1 <= MatchType <= 1; The searched portion of SearchRegion shall not include
Logical values. Evaluators may evaluate expressions that do not meet the constraint that the
searched portion of a SearchRegion not include Logical values.
SearchRegion shall be a vector (a single row or column)
Semantics:
MatchType = -1 finds the smallest value that is greater than or equal to Search in a
SearchRegion where values are sorted in descending order. From a sequence of identical
values >= Search the last value is taken. If no value >= Search exists, the #N/A Error is
returned. If Search is of type Number and the value found is of type Text, the #N/A Error is
returned.
MatchType = 0 finds the first value that is equal to Search. Values in SearchRegion do not need
to be sorted. If no value equal to Search exists, the #N/A Error is returned.
MatchType = 1 or omitted finds the largest value that is less than or equal to Search in a
SearchRegion where values are sorted in ascending order. From a sequence of identical values
<= Search the last value is taken. If no value <= Search exists, the #N/A Error is returned. If
Search is of type Text and the value found is of type Number, the #N/A Error is returned.
If a match is found, MATCH returns the relative position (starting from 1). For Text the comparison is
case-insensitive. MatchType determines the type of search; if MatchType is 0, the SearchRegion
shall be considered unsorted, and the first match is returned. If MatchType is 1, the SearchRegion
may be assumed to be sorted in ascending order, with smaller Numbers before larger ones, smaller
Text values before larger ones (e.g., "A" before "B", and "B" before "BA"), and False before True. If
the types are mixed, Numbers are sorted before Text, and Text before Logicals; evaluators without a
separate Logical type may include a Logical as a Number. If MatchType is -1, then SearchRegion
may be assumed to be sorted in descending order (the opposite of the above). If MatchType is 1 or
-1, evaluators may use binary search or other techniques so that they do not need to examine every
value in linear order. MatchType defaults to 1.
anchor:MATCH
Test Cases:
=MATCH("HELLO";[.B3:.B7];0) 5 Simple MATCH().
=MATCH(0;[.B51:.B57]) =NA()
No value less than or equal to Search in
sorted numerical data.
=MATCH(6.1;[.B51:.B57]) 3
In sorted numerical data, 6 is the largest
value that is less than or equal to
Search
100414201 29 May 2010
See also HLOOKUP, OFFSET, VLOOKUP
TBD: Do we need test cases for sorted descending as well? Assuming not, because it's obvious.
6.14.10 MULTIPLE.OPERATIONS
Summary: Executes a formula expression while substituting a row reference and a column
reference.
Syntax: MULTIPLE.OPERATIONS( Reference FormulaCell ; Reference RowCell ; Reference
RowReplacement [ ; Reference ColumnCell ; Reference ColumnReplacement ] )
Returns: Any
Semantics:
FormulaCell reference to the cell that contains the formula expression to
calculate.
RowCell reference that is to be replaced by RowReplacement.
RowReplacement reference that replaces RowCell.
ColumnCell reference that is to be replaced by ColumnReplacement.
ColumnReplacement reference that replaces ColumnCell.
MULTIPLE.OPERATIONS executes the formula expression pointed to by FormulaCell and all
formula expressions it depends on while replacing all references to RowCell with references to
RowReplacement respectively all references to ColumnCell with references to
ColumnReplacement.
If calls to MULTIPLE.OPERATIONS are encountered in dependencies, replacements of target cells
shall occur in queued order, with each replacement using the result of the previous replacement.
Note: The function may be used to create tables of expressions that depend on two input
parameters.
Example: FormulaCell is B5, RowCell is B3, ColumnCell is B2
Table 24 - MULTIPLE.OPERATIONS
col_B col_C col_D col_E col_F
row_2 1 1 2 3
row_3 1 1
=MULTIPLE.OPER
ATIONS($B$5;$B$3
;$C3;$B$2;D$2)
=MULTIPLE.OPER
ATIONS($B$5;$B$3
;$C3;$B$2;E$2)
=MULTIPLE.OPER
ATIONS($B$5;$B$3
;$C3;$B$2;F$2)
row_4 =B2+B3 2
=MULTIPLE.OPER
ATIONS($B$5;$B$3
;$C4;$B$2;D$2)
=MULTIPLE.OPER
ATIONS($B$5;$B$3
;$C4;$B$2;E$2)
=MULTIPLE.OPER
ATIONS($B$5;$B$3
;$C4;$B$2;F$2)
row_5 =B2*B3+B4 3
=MULTIPLE.OPER
ATIONS($B$5;$B$3
;$C5;$B$2;D$2)
=MULTIPLE.OPER
ATIONS($B$5;$B$3
;$C5;$B$2;E$2)
=MULTIPLE.OPER
ATIONS($B$5;$B$3
;$C5;$B$2;F$2)
4
=MULTIPLE.OPER
ATIONS($B$5;$B$3
;$C6;$B$2;D$2)
=MULTIPLE.OPER
ATIONS($B$5;$B$3
;$C6;$B$2;E$2)
=MULTIPLE.OPER
ATIONS($B$5;$B$3
;$C6;$B$2;F$2)
100414201 29 May 2010
Result:
Table 25 - MULTIPLE.OPERATIONS
col_B col_C col_D col_E col_F
row_2 1 1 2 3
row_3 1 1 3 5 7
row_4 2 2 5 8 11
row_5 3 3 7 11 15
4 9 14 19
Note that although only cell B5 is passed as the FormulaCell parameter, also the references to B2
and B3 of the formula in cell B4 are replaced, because B5 depends on B4.
anchor:MULTIPLE.OPERATIONS
Test Cases:
TODO: test cases; how do we want to define the table layout that would be helpful here?
See also
Note: Though OpenOffice.org allows manual input of the formula, it is usually created from an area
selection by an UI dialog that asks for the positions of FormulaCell, RowCell and ColumnCell. The
positions of RowReplacement and ColumnReplacement are generated from the cell's position
containing the MULTIPLE.OPERATIONS formula and its intersection with the leftmost row /
uppermost column of the area selected. The absolute and relative references are generated such
that expanding the table with new values and formulas can be easily done by adding new rows and
columns with values and simply copying one formula cell to the clipboard and pasting it onto the
new area.
In Excel 2003 the function's name is TABLE and takes just 2 parameters, corresponding to RowCell
and ColumnCell. Manual input of the expression or extending its cell range is not accepted by Excel.
The formula is generated by a dialog and is always generated as a matrix formula. The
FormulaCell's position is implicitly assumed to be the upper left cell of the area selected. The
RowReplacement and ColumnReplacement is implicitly taken from the cell's position containing the
TABLE formula and its intersection with the leftmost row / uppermost column of the area selected.
6.14.11 OFFSET
Summary: Modifies a reference's position and dimension.
Syntax: OFFSET( Reference reference ; Integer rowOffset ; Integer columnOffset [ ; [ Integer
newHeight ] [ ; [ Integer newWidth ] ] ] )
Returns: Reference
Constraints: newWidth > 0; newHeight > 0
The modified reference shall be in a valid range, starting from column/row one to the maximum
column/row.
100414201 29 May 2010
Semantics: Shifts reference by rowOffset rows and by columnOffset columns. Optionally, the
dimension can be set to newWidth and/or newHeight, if omitted the width/height of the original
reference is taken. Note that newHeight may be empty (two consecutive semicolons ;;) followed by
a given newWidth argument. Returns the modified reference.
anchor:OFFSET
Test Cases:
=OFFSET( [.A1]; 3; 1) 2 Positive shift.
=OFFSET( [.D6]; -2; -1) 4 Negative shift.
=SUM( OFFSET( [.A1]; 1; 3; 2 ) ) 5 New width.
=SUM( OFFSET( [.A1]; 1; 3; 2; 2 ) ) 14 New width and height.
=OFFSET( [.A1]; 1; 1; 0 ) Error newWidth must be > 0
=OFFSET( [.A1]; 1; 3; 1; 0 ) Error newHeight must be > 0
=SUM(OFFSET([.A14:.A17];0;1;;2)) 20
Shifted by one column.
Same height, new width.
Note empty height parameter.
=SUM(OFFSET([.A14:.B17];0;1;2;)) 10
New height, same width.
Note empty width parameter.
=SUM(OFFSET([.A14:.B17];0;1;;)) 20
Same height, same width.
Note empty height and width parameters,
the syntax does allow this.
=SUM(OFFSET([.A14:.B17];0;1)) 20
The same as above, only with omitted
parameters.
Same height, same width.
See also COLUMN, COLUMNS, ROW, ROWS
6.14.12 VLOOKUP
Summary: Look for a matching value in the first column of the given table, and return the value of
the indicated column.
Syntax: VLOOKUP( Any Lookup ; Reference|Array DataSource ; Integer Column [ ; Logical
RangeLookup = TRUE() ] )
Returns: Any
Constraints: Column >= 1; The searched portion of DataSource shall not include Logical values.
Evaluators may evaluate expressions that do not meet the constraint that the searched portion of a
DataSource not include Logical values.
Semantics:
100414201 29 May 2010
If RangeLookup is omitted or TRUE or not 0, the first column of DataSource is assumed to be
sorted in ascending order, with smaller Numbers before larger ones, smaller Text values before
larger ones (e.g., "A" before "B", and "B" before "BA"), and False before True. If the types are
mixed, Numbers are sorted before Text, and Text before Logicals; evaluators without a separate
Logical type may include a Logical as a Number. The lookup will try to match an entry of value
Lookup. From a sequence of identical values <= Lookup the last entry is taken. If none is found the
largest entry less than Lookup is taken as a match. If there is no data less than or equal to Lookup,
the #N/A Error is returned. If Lookup is of type Text and the value found is of type Number, the #N/A
Error is returned. If DataSource is not sorted, the result is undetermined and implementation-
dependent. In most cases it will be arbitrary and just plain wrong due to binary search algorithms.
If RangeLookup is FALSE or 0, DataSource does not need to be sorted and an exact match is
searched. Each value in the first column of DataSource is examined in order (starting at the top)
until its value matches Lookup. If no value matches, the #N/A Error is returned.
Both methods, if there is a match, return the corresponding value in column Column, relative to the
DataSource, where the leftmost column in DataSource is 1.
anchor:VLOOKUP
Test Cases:
=VLOOKUP("Ursa Major";
[.B19:.I31];2;FALSE())
6 Table states Ursa Major has 6 bright stars.
=VLOOKUP("Ursa Major";
[.B19:.I31];4;FALSE())
"Uma" Table states Ursa Major has abbreviation Uma.
=VLOOKUP(2;
[.C19:.I31];3;FALSE())
"Cmi"
Can match numbers as well as text. Canis Minor
is first in table (starting from top).
=VLOOKUP("NoSuchConstellation"
; [.B19:.I31];4;FALSE())
Error Error returned if not found.
=VLOOKUP(2; [.C19:.I31];3) "Cmi"
The result is arbitrary because column C (Bright
Stars) is not sorted! It may match or it may not!
=VLOOKUP("NoSuchConstellation"
; [.B19:.I31];4)
"Her"
Column B (Constellation) is sorted. "Hercules" is
matched because it is the largest value less than
or equal to "NoSuchConstellation", the next larger
value would had been "Orion".
=VLOOKUP(0;[.B51:.B57];2) Error
No value less than or equal to Lookup in sorted
numerical data.
=VLOOKUP(6.1;[.B51:.B57];2) 11
In sorted numerical data, 6 is the largest value
that is less than or equal to Lookup.
See also HLOOKUP, INDEX, MATCH, OFFSET
100414201 29 May 2010
6.15 Logical Functions
6.15.1 General
The logical functions are the constants TRUE() and FALSE(), the functions that compute Logical
values NOT(), AND(), and OR(), and the conditional function IF(). The OpenDocument specification
mentions "logical operators"; these are another name for the logical functions.
Note that because of Error values, any logical function that accepts parameters can actually
produce TRUE, FALSE, or an Error value, instead of TRUE or FALSE.
These are not bitwise operations, e.g., AND(12;10) produces TRUE(), not 8. See the bit operation
functions for bitwise operations.
6.15.2 AND
Summary: Compute logical AND of all parameters.
Syntax: AND( { Logical|NumberSequenceList L }
+
)
Returns: Logical
Constraints: Shall have 1 or more parameters
Semantics: Computes the logical AND of the parameters. If all parameters are True, returns True; if
any are False, returns False. When given one parameter, this has the effect of converting that one
parameter into a Logical value. When given zero parameters, evaluators may return a Logical value
or an Error.
Also in array context a logical AND of all arguments is computed, range or array parameters are not
evaluated as a matrix and no array is returned. This behavior is consistent with functions like SUM.
To compute a logical AND of arrays per element use the * operator in array context.
anchor:AND
Note: Excel 2000, OpenOffice.org 2.0 and Gnumeric 1.4.3 consider AND() with no parameters an
error, Kspread 1.4.2 does not.
Test Cases:
=AND(FALSE();FALSE()) False Simple AND.
=AND(FALSE();TRUE()) False Simple AND.
=AND(TRUE();FALSE()) False Simple AND.
=AND(TRUE();TRUE()) True Simple AND.
=AND(TRUE();NA()) NA Returns an error if given one.
=AND(1;TRUE()) True Nonzero considered TRUE.
=AND(0;TRUE()) False Zero considered FALSE.
=AND(TRUE();TRUE();TRUE()) True More than two parameters okay.
=AND(TRUE()) True One parameter okay - simply returns it.
100414201 29 May 2010
TBD: Implementations of AND and OR do NOT short-circuit on True and False, because they look
for error conditions and propagate them. For example, on Excel: AND(FALSE(), #NA) is #NA.
Should the "do not short-circuit" rule be REQUIRED? Should short-circuiting be PERMITTED? If
short-circuiting is not required, should short-circuiting versions of AND() and OR() be defined, e.g.,
ANDSC() and ORSC()?
See also OR, IF
6.15.3 FALSE
Summary: Returns constant FALSE
Syntax: FALSE()
Returns: Logical
Semantics: Returns logical constant FALSE. This may be a Number or a distinct type.
anchor:FALSE
Test Cases:
=FALSE() False Constant
=IF(ISNUMBER(FALSE());
FALSE()=0;FALSE())
FALSE
Applications that implement Logical values as
0/1 must map TRUE() to 1
2+FALSE() 2 TRUE converts to 1 in Number context
See also TRUE, IF
6.15.4 IF
Summary: Return one of two values, depending on a condition
Syntax: IF( Logical Condition [ ; [ Any IfTrue ] [ ; [ Any IfFalse ] ] ] )
Returns: Any
Constraints: None.
Semantics: Computes Condition. If it is TRUE, it returns IfTrue, else it returns IfFalse. If there is
only 1 parameter, IfTrue is considered to be TRUE(). If there are less than 3 parameters, IfFalse is
considered to be FALSE(). Thus the 1 parameter version converts Condition into a Logical value. If
there are 2 or 3 parameters but the second parameter is null (two consecutive ;; semicolons),
IfFalse is considered to be 0. If there are 3 parameters but the third parameter is null, IfFalse is
considered to be 0. This function only evaluates IfTrue, or ifFalse, and never both; that is to say, it
short-circuits.
anchor:IF
Test Cases:
100414201 29 May 2010
=IF(FALSE();7;8) 8 Simple if.
=IF(TRUE();7;8) 7 Simple if.
=IF(TRUE();"HI";8) ="HI"
Can return strings, and the two sides need not have equal
types
=IF(1;7;8) 7 A non-zero is considered true.
=IF(5;7;8) 7 A non-zero is considered true.
=IF(0;7;8) 8 A zero is considered false.
=IF(TRUE();[.B4];8) 2 The result can be a reference.
=IF(TRUE();
[.B4]+5;8)
7 The result can be a formula.
=IF("x";7;8) Error Condition has to be convertible to Logical.
=IF("1";7;8) Error Condition has to be convertible to Logical.
=IF("";7;8) Error
Condition has to be convertible to Logical; empty string is not
the same as False
=IF(FALSE();7) FALSE Default IfFalse is FALSE
=IF(3) TRUE Default IfTrue is TRUE
=IF(FALSE();7;) 0 Empty parameter is considered 0
=IF(TRUE();;7) 0 Empty parameter is considered 0
=IF(TRUE();4;1/0) 4
If condition is true, ifFalse is not considered even if it would
produce Error.
=IF(FALSE();1/0;5) 5
If condition is false, ifTrue is not considered even if it would
produce Error.
anchor:IF
See also AND, OR
6.15.5 IFERROR
Summary: Return X unless it is an Error, in which case return an alternative value
Syntax: IFERROR( Any X ; Any Alternative )
Returns: Any
Constraints: None.
Semantics: Computes X. If ISERROR(X) is true, return Alternative, else return X. Thus this is
semantically equivalent to IF(ISERROR(X); Alternative; X), except that X is only computed once. If X
or Alternative is a cell reference to an empty cell, it is treated as the empty string "".
anchor:IFERROR
See also IF
100414201 29 May 2010
6.15.6 IFNA
Summary: Return X unless it is an NA, in which case return an alternative value
Syntax: IFNA( Any X ; Any Alternative )
Returns: Any
Constraints: None.
Semantics: Computes X. If ISNA(X) is true, return Alternative, else return X. Thus this is
semantically equivalent to IF(ISNA(X); Alternative; X), except that X is only computed once. If X or
Alternative is a cell reference to an empty cell, it is treated as the empty string "".
anchor:IFNA
See also IF
6.15.7 NOT
Summary: Compute logical NOT
Syntax: NOT( Logical L )
Returns: Logical
Constraints: Shall have 1 parameter
Semantics: Computes the logical NOT. If given TRUE, returns FALSE; if given FALSE, returns
TRUE.
anchor:NOT
Test Cases:
=NOT(FALSE()) True Simple NOT, given FALSE.
=NOT(TRUE()) False Simple NOT, given TRUE.
=NOT(1/0) Error
NOT returns an error if given an
error value
See also AND, IF
Note: NOT returns an Error, if given an Error, so unlike some mathematical definitions this can
return more than two values: True, False, and Error values.
6.15.8 OR
Summary: Compute logical OR of all parameters.
Syntax: OR( { Logical|NumberSequenceList L }
+
)
Returns: Logical
Constraints: Shall have 1 or more parameters
100414201 29 May 2010
Semantics: Computes the logical OR of the parameters. If all parameters are False, it shall return
False; if any are True, it shall returns True. When given one parameter, this has the effect of
converting that one parameter into a Logical value. When given zero parameters, evaluators may
return a Logical value or an Error.
Also in array context a logical OR of all arguments is computed, range or array parameters are not
evaluated as a matrix and no array is returned. This behavior is consistent with functions like SUM.
To compute a logical OR of arrays per element use the + operator in array context.
anchor:OR
Note: Excel 2000, OpenOffice.org 2.0 and Gnumeric 1.4.3 consider OR() with no parameters an
error, Kspread 1.4.2 does not.
Test Cases:
=OR(FALSE();FALSE()) False Simple OR.
=OR(FALSE();TRUE()) True Simple OR.
=OR(TRUE();FALSE()) True Simple OR.
=OR(TRUE();TRUE()) True Simple OR.
=OR(FALSE();NA()) NA Returns an error if given one.
=OR(FALSE();FALSE();TRUE()) True More than two parameters okay.
=OR(TRUE()) True One parameter okay - simply returns it
TBD: Implementations of AND and OR do NOT short-circuit on True and False, because they look
for error conditions and propagate them. For example, on Excel: AND(FALSE(), #NA) is #NA.
Should the "do not short-circuit" rule be REQUIRED? If it is required, should short-circuiting versions
of AND() and OR() be defined, e.g., ANDSC() and ORSC()?
See also AND, IF
6.15.9 TRUE
Summary: Returns constant TRUE
Syntax: TRUE()
Returns: Logical
Semantics: Returns logical constant TRUE. The result of this function may or may not be equal to 1
when compared using =. It always has the value of 1 if used in a context requiring Number
(because of the automatic conversions), so if ISNUMBER(TRUE()), then it shall have the value 1.
anchor:TRUE
Test Cases:
=TRUE() True Constant.
100414201 29 May 2010
=IF(ISNUMBER(TRUE());TRU
E()=1;TRUE())
True
Applications that implement Logical values as 0/1
must map TRUE() to 1
2+TRUE() 3 TRUE converts to 1 in Number context
See also FALSE, IF
6.15.10 XOR
Summary: Compute a logical XOR of all parameters.
Syntax: XOR( { Logical L }
+
)
Returns: Logical
Constraints: Shall have 1 or more parameters.
Semantics: Computes the logical XOR of the parameters such that the result is an addition modulo
2. If an even number of parameters is True it returns False, if an odd number of parameters is True
it returns True. When given one parameter, this has the effect of converting that one parameter into
a Logical value.
anchor:XOR
Note: The multi-argument form is different from an "exclusive disjunction" operation, which would
return True if and only if exactly one argument is True.
Test Cases:
=XOR(FALSE();FALSE()) False Simple XOR.
=XOR(FALSE();TRUE()) True Simple XOR.
=XOR(TRUE();FALSE()) True Simple XOR.
=XOR(TRUE();TRUE()) False
Simple XOR note that this one is different
from OR
=XOR(FALSE();NA()) NA Returns an error if given one.
=XOR(FALSE();FALSE();TRUE()) True More than two parameters okay.
=XOR(FALSE(); TRUE();TRUE()) False
More than two parameters okay, and notice
that this result is different from OR
=XOR(TRUE(); TRUE();TRUE()) True
More than two parameters okay, the result is
((1 XOR 1) XOR 1), thus a parity.
=XOR(TRUE()) True One parameter okay - simply returns it
See also AND, OR
Note: Excel 2003, and OpenOffice.org 2.1 don't have XOR(). Gnumeric 1.4.3 considers AND() with
no parameters an error, Kspread 1.4.2 does not.
100414201 29 May 2010
6.16 Mathematical Functions
6.16.1 General
This section describes functions for various mathematical functions, including trigonometric
functions like SIN). Note that the constraint text presumes that a value of type Number is a real
number (no imaginary component). Unless noted otherwise, all angle measurements are in radians.
Note: It's debatable if SUM and AVERAGE etc. should be listed under mathematical functions or as
statistical functions. COUNT could belong here, under statistics, or under information functions. It
doesn't really matter; these divisions are arbitrary, simply to make it easier for users to find them.
6.16.2 ABS
Summary: Return the absolute (nonnegative) value.
Syntax: ABS( Number N )
Returns: Number
Constraints: None
Semantics: If N < 0, returns -N, otherwise returns N.
anchor:ABS
Test Cases:
=ABS(-4) 4 If less than zero, return negation
=ABS(4) 4 Positive values return unchanged.
See also Prefix Operator -
6.16.3 ACOS
Summary: Returns the principal value of the arc cosine of a number. The angle is returned in
radians.
Syntax: ACOS( Number N )
Returns: Number
Constraints: -1.0 <= N <= 1.0.
Semantics: Computes the arc cosine of a number, in radians.
acos ( N )=
|
N+
1
23
N
3
+
13
245
N
5
+
135
2467
N
7
+...
Returns a principal value 0 result PI.

anchor:ACOS
Test Cases:
100414201 29 May 2010
=ACOS(SQRT(2)/2)*4
/PI()
1 arc cosine of SQRT(2)/2 is PI()/4 radians.
=ACOS(TRUE()) 0.0 TRUE() is 1 if inline.
=ACOS(-1.0)/PI() 1 The result must be between 0.0 and PI().
=ACOS(2.0) Error The argument must be between -1.0 and 1.0.
See also COS, RADIANS, DEGREES
6.16.4 ACOSH
Summary: Return the principal value of the inverse hyperbolic cosine
Syntax: ACOSH( Number N )
Returns: Number
Constraints: N >= 1
Semantics: Computes the principal value of the inverse hyperbolic cosine.
acosh ( N)=ln( N+.N
2
1)
anchor:ACOSH
Test Cases:
=ACOSH(1) 0
=ACOSH(2)
1.31695789
7
See also COSH, ASINH
6.16.5 ACOT
Summary: Return the principal value of the arc cotangent of a number. The angle is returned in
radians.
Syntax: ACOT( Number N )
Returns: Number
Semantics: Computes the arc cotangent of a number, in radians.
Returns a principal value 0 < result < PI.
anchor:ACOT
Test Cases:
100414201 29 May 2010
=ACOT(0)-PI()/2 0 arc cotangent of 0 is PI()/2 radians.
See also COT, ATAN, TAN, RADIANS, DEGREES
6.16.6 ACOTH
Summary: Return the hyperbolic arc cotangent
Syntax: ACOTH( Number N )
Returns: Number
Constraints: ABS(N) > 1
Semantics: Computes the hyperbolic arc cotangent. The hyperbolic arc cotangent is an analog of
the ordinary (circular) arc cotangent.
acoth( N )=
1
2
ln(
x+1
x1
)
anchor:ACOTH
Test Cases:
=ACOTH(2)
0.54930614
4
See also COSH, ASINH
TODO: Fill in test cases. For all hyperbolic functions, change constraints to describe domain (not
range)
6.16.7 ASIN
Summary: Return the principal value of the arc sine of a number. The angle is returned in radians.
Syntax: ASIN( Number N )
Returns: Number
Constraints: -1 <= N <= 1.
Semantics: Computes the arc sine of a number, in radians.
asin (N )=N+
1
23
N
3
+
13
245
N
5
+
135
2467
N
7
+...
Returns a principal value -PI/2 result PI/2.
anchor:ASIN
Test Cases:
100414201 29 May 2010
=ASIN(SQRT(2)/2)*4/PI() 1 arc sine of SQRT(2)/2 is PI()/4 radians.
=ASIN(TRUE())*2/PI() 1 TRUE() is 1 if inline.
=ASIN(-1)*2/PI() -1 The result must be between -PI()/2 and PI()/2.
=ASIN(2) Error The argument must be between -1.0 and 1.0.
See also SIN, RADIANS, DEGREES
6.16.8 ASINH
Summary: Return the principal value of the inverse hyperbolic sine
Syntax: ASINH( Number N )
Returns: Number
Constraints: None
Semantics: Computes the principal value of the inverse hyperbolic sine.
asinh( N )=ln( N+.N
2
+1)
anchor:ASINH
Test Cases:
=ASINH(0) 0
=ASINH(1)
0.88137358
7
See also SINH, ACOSH
6.16.9 ATAN
Summary: Return the principal value of the arc tangent of a number. The angle is returned in
radians.
Syntax: ATAN( Number N )
Returns: Number
Semantics: Computes the arc tangent of a number, in radians.
Returns a principal value -PI/2 < result < PI/2.
anchor:ATAN
Test Cases:
100414201 29 May 2010
=ATAN(1)*4/PI() 1 arc tangent of 1 is PI()/4 radians.
=ATAN(-1.0e16)
-
1.5707960
.0001
Check if ATAN gives reasonably accurate
results, and that slightly negative values as
input produce numbers near -/2.
See also ATAN2, TAN, RADIANS, DEGREES
6.16.10 ATAN2
Summary: Returns the principal value of the arc tangent given a coordinate of two numbers.
The angle is returned in radians.
Syntax: ATAN2( Number x ; Number y )
Returns: Number
Constraints: x<>0 or y<>0
Semantics: Computes the arc tangent of two numbers (the x and y coordinates of a point), in
radians. This is similar to ATAN(y/x), but the signs of the two numbers are taken into account so that
the result covers the full range from -PI() to +PI(). ATAN2(0;0) is implementation-defined, evaluators
may return 0 or an Error.
Returns a principal value -PI < result PI.
anchor:ATAN2
Test Cases:
=ATAN2(1;1)*4/PI() 1 arc tangent of 1.0/1.0 is PI()/4 radians.
=ATAN2(1;-1)*4/PI() -1 Location of sign makes a difference.
=ATAN2(-1;1)*4/PI() 3 Location of sign makes a difference.
=ATAN2(-1;-1)*4/PI() -3 Location of sign makes a difference.
=SIGN(ATAN2(-1.0;0.001)) 1 If y is small, it's still important
=SIGN(ATAN2(-1.0;-
0.001))
-1 If y is small, it's still important
=ATAN2(-1.0;0)/PI() 1
By definition ATAN2(-1,0) should give PI() rather than
-PI().
See also ATAN, TAN, RADIANS, DEGREES
6.16.11 ATANH
Summary: Return the principal value of the inverse hyperbolic tangent
100414201 29 May 2010
Syntax: ATANH( Number N )
Returns: Number
Constraints: -1 < N < 1
Semantics: Computes the principal value of the inverse hyperbolic tangent.
atanh( N )=
1
2
ln
(
1+N
1N
)
anchor:ATANH
Test Cases:
=ATANH(0) 0
=ATANH(0.5)
0.54930614
4
See also COSH, SINH, ASINH, ACOSH, ATAN, ATAN2, FISHER
6.16.12 BESSELI
Summary: Returns the modified Bessel function of integer order In(x).
Syntax: BESSELI( Integer X ; Number N )
Returns: Number
Constraints: N >= 0, INT(N)=N; Evaluators may evaluate expressions where N >= 0 returns a non-
error value.
Semantics: Computes the modified Bessel function of integer order In(x). N is also known as the
order.
anchor:BESSELI
Test Cases:
=BESSELI(2;2) 0.688948 Sample value
See also BESSELJ, BESSELK, BESSELY
Note: OOo and Excel do an INT(N) on N, but the Bessel functions in mathematics aren't just limited
to integers. Gnumeric and Kspread allow fractional values.
6.16.13 BESSELJ
Summary: Returns the Bessel function of integer order Jn(x) (cylinder function)
Syntax: BESSELJ( Integer X ; Number N )
100414201 29 May 2010
Returns: Number
error value.
Semantics: Computes the Bessel function of integer order Jn(x). N is also known as the order.
anchor:BESSELJ
Test Cases:
=BESSELJ(1;0) 0.765198 Sample value
See also BESSELI, BESSELK, BESSELY
6.16.14 BESSELK
Summary: Returns the modified Bessel function of integer order Kn(x).
Syntax: BESSELK( Integer X ; Number N )
Returns: Number
Constraints: N >= 0, INT (N)=N; Evaluators may evaluate expressions where N >= 0 returns a non-
error value.
Semantics: Computes the Bessel function of integer order Kn(x). N is also known as the order.
anchor:BESSELK
Test Cases:
=BESSELK(3;0)
0.034741e
-5
Sample value
See also BESSELI, BESSELJ, BESSELY
6.16.15 BESSELY
Summary: Returns the Bessel function of integer order Yn(x), also known as the Neumann
function.
Syntax: BESSELY( Integer X ; Number N )
Returns: Number
error value.
Semantics: Computes Bessel function of integer order Yn(x), also known as the Neumann function.
N is also known as the order.
anchor:BESSELY
100414201 29 May 2010
Test Cases:
=BESSELY(1;1) -0.781213 Sample value
See also BESSELI, BESSELJ, BESSELK
6.16.16 COMBIN
Summary: Returns the number of different R-length sets that can be selected from N items.
Syntax: COMBIN( Integer N ; Integer R )
Returns: Number
Constraints: N >= 0, R >= 0, R <= N
Semantics: COMBIN returns the binomial coefficient, which is the number of different R-length sets
that can be selected from N items. Since they are sets, order in the sets is not relevant. The
parameters are truncated (using INT) before use. For example, if a jar contains five marbles, each
one a distinct color, the number of different three-marble groups COMBIN(5;3) = 10. The result is
(
N
R
)
=
PERMUT
R!
=
N !
R! ( NR) !
Note that if order is important, use PERMUT instead.
anchor:COMBIN
Test Cases:
=COMBIN(5;3) 10
=COMBIN(6;3) 20
=COMBIN(42;3) 11480
See also PERMUT
6.16.17 COMBINA
Summary: Returns the number of combinations with repetitions.
Syntax: COMBINA( Integer N ; Integer M )
Returns: Number
Constraints: N >= 0, M >= 0, N >= M; Evaluators may evaluate expressions where N >= 0, M >= 0
returns a non-error value.
Semantics: Returns the number of possible combinations of M objects out of N possible ones, with
repetitions allowed. Actual arguments that are not integers are truncated (using INT) before use.
The result is
100414201 29 May 2010
(
N +M1
N 1
)
anchor:COMBINA
Test Cases:
=COMBINA(5;3) 35 Sample value
See also COMBIN
Note: OOo function. Not necessarily implemented elsewhere. The constraint N>=M is an
OpenOffice.org limitation.
6.16.18 CONVERT
Summary: Returns a number converted from one unit system into another
Syntax: CONVERT( Number N ; Text From ; Text Into )
Returns: Number
Constraints: From and Into shall be legal units, and shall be in the same unit group.
Note: The unit group restriction prevents nonsense such as accidentally trying to convert grams
into meters.
Semantics: Returns the number converted from the unit identified by From into the unit identified
by Into. A unit is a unit symbol , optionally preceded by a unit prefix (either a decimal prefix or a
binary prefix). Units (including both the unit symbol and the optional unit prefix) are case-sensitive.
Evaluators claiming to implement this function shall support at least the following unit symbols (with
conversions between them and other units in the same group):
Table 26 - Unit names
Unit group Unit symbol Description
Area "uk_acre" International acre (using international feet), exactly
4046.8564224 m
2
; normally not used for U.S. land areas
"us_acre" U.S. survey/statute acre (using U.S. survey/statute feet),
exactly 4046+13525426/15499969 m
2
"ang2" or
"ang^2" *
Square angstrom (an Angstrom is exactly 10
-10
m)
"ar" * are, 100 m
2
(not abbreviated as a)
"ft2" or "ft^2" Square international feet (1 foot is exactly 0.3048 m)
"ha" hectare, 10 000 m
2
"in2" or "in^2" Square international inches (1 inch is exactly 2.54 cm)
"ly" or "ly2" Square light-year (where year=365.25 days)
100414201 29 May 2010
"m2" or "m^2" * Square meters
"Morgen" Morgen, 2500 m
2
"mi2" or "mi^2" Square international miles
"Nmi2" or
"Nmi^2"
Square nautical miles (1 nautical mile is 1852 m)
"Pica2" or
"Pica^2"
Square Pica (one Pica is 1/72 in.)
"yd2" or "yd^2" Square international yards (1 yard is 0.9144 m)
Distance
(Length)
"ang" * Angstrom, exactly 10
-10
m
"ell" Ell, exactly 45 international inches
"ft"
International Foot, exactly 0.3048 m and also exactly 12
international inches.
"in" International Inch, exactly 2.54 cm.
"ly" *
Light-year, the distance light travels, in a vacuum, in a
Julian year of 365.25 days
"m" * Meter
"mi"
International Mile, exactly 1609.344 m and exactly 5280
international feet. This is not a U.S. survey/statute mile
(see smi) nor a nautical mile (see Nmi), but this is the
mile normally used in the U.S. customary system
"Nmi"
International nautical mile, exactly 1852 m. Note that this
is not the obsolete U.S. nautical mile nor the Admiralty
mile.
"parsec" or "pc"
*
Distance from sun to a point having heliocentric parallax
of one second (used for stellar distance)*
"Pica" Pica (1/72 in.)
"survey_mi"
U.S. survey mile, aka U.S. statute mile, exactly
6336000/3937 m; used in some U.S. maps. This is not
the mile (see mi) normally used in the U.S.
"yd"
International yard, exactly 0.9144 m and exactly 3
international feet.
Energy "BTU" ("btu") International Table British Thermal Unit
"c" * Thermodynamic calorie, 4.184 J. This is not a dietary
Calorie (kilocalorie). For high accuracy, use Joule, due to
100414201 29 May 2010
the many conflicting definitions of calorie.
"cal" *
International Table (IT) calorie, 4.1868 J. This is not a
dietary Calorie (kilocalorie). For high accuracy, use
Joule, due to the many conflicting definitions of calorie.
"e" * Erg
"eV" ("ev") * Electron volt (eV preferred)
"flb" Foot-pound (international foot, avoirdupois pound)
"HPh" ("hh") Horsepower-hour (HPh preferred)
"J" * Joule
"Wh" ("wh") * Watt-hour
Force
(Weight)
"dyn" ("dy") * Dyne
"N" * Newton
"lbf" Pound force (see lbm for pound mass)
"pond" * Pond, gravitational force on a mass of one gram
Information
"bit" * bit
"byte" * byte = 8 bits
Magnetic
Flux Density
"ga" * Gauss
"T" * Tesla
Mass
"g" * Gram
"grain"
Grain, 1/7000 international pound mass (avoirdupois)
(U.S. usage).
"cwt"
("shweight")
U.S. (short) hundredweight, 100 lbm
"uk_cwt" or
"lcwt"
("hweight")
Imperial hundredweight, aka long hundredweight; 112
lbm
"lbm"
International pound mass (avoirdupois), exactly
453.59237 g (see lbf for pound force)
100414201 29 May 2010
"stone" 14 international pound mass (avoirdupois)
"ton"
2000 international pound mass (avoirdupois) (U.S.
usage). Note that there are many other measures also
called ton; in particular, this is not a metric ton (tonne).
"ozm"
Ounce mass (avoirdupois), exactly 1/16 of an
international pound mass (avoirdupois) (see oz for fluid
ounce)
"sg" Slug; 32.174 international pound mass (avoirdupois)
"u" * U (atomic mass unit)
"uk_ton" or
"LTON" ("brton")
Imperial ton, aka long ton, "deadweight ton", or "weight
ton". 2240 lbm.
Power
"HP" ("h")
Horsepower. The unit h is deprecated and should be
replaced with HP.
"PS"
Pferdestrke (German horse strength, close but not
identical to HP)
"W" ("w") * Watt
Pressure
"atm" ("at") * Atmosphere
"mmHg" * mm of Mercury
"Pa" *
Pascal; Pa preferred, as it is the standard abbreviation.
Note that P or p may not be accepted.
"psi"
Pounds per square inch, using avoirdupois pounds and
international inches.
"Torr"
Torr, exactly 101325/760 Pa (this is close but not equal
to mmHg)
Speed
"admkn" Admiralty knot, exactly 6080 international feet/hour.
"kn"
Knot, exactly one Nautical mile per hour or exactly
1852/3600 m/s. Note that this is not an Admiralty knot
(admkn).
"m/h" or "m/hr" * Meters per hour
"m/s" or "m/sec"
*
Meters per second
"mph" Miles per hour (international miles)
100414201 29 May 2010
Temperature
"C" ("cel") degrees Celsius
"F" ("fah") degrees Fahrenheit
"K" ("kel") * Kelvin
"Rank" degrees Rankine
"Reau" degrees Raumur; C = R 5/4.
Time
"day" or "d" Day (exactly 24 hours)
"hr" Hour (exactly 60 minutes)
"mn" or "min" Minute (exactly 60 seconds)
"sec" or "s" *
Second (s is the official abbreviation of this SI base
unit, while sec is its traditional abbreviation in the
CONVERT function) *
"yr" Year (exactly 365.25 days, for purposes of this function)
Volume
"ang3" or
"ang^3" *
Cubic angstrom
"barrel"
U.S. oil barrel, exactly 42 U.S. customary gallons (liquid).
Note that many other units are also called barrels (e.g., a
beer barrel in the U.K. is 36 Imperial gallons)
"bushel" U.S. bushel (not Imperial bushel), interpreted as volume
"cup" Cup (U.S. customary liquid measure)
"ft3" or "ft^3" Cubic international feet
"gal" Gallon (U.S. customary liquid measure)
"GRT" ("regton") Gross Registered Ton, 100 cubic (international) feet
"in3" or "in^3" Cubic international inch
"l" or "L" ("lt")
*
Liter
"ly3" or "ly^3" Cubic light-year
"m3" or "m^3" * Cubic meter
"mi3" or "mi^3" Cubic international mile
"MTON" Measurement ton aka freight ton, 40 cubic feet
100414201 29 May 2010
"Nmi3" or
"Nmi^3"
Cubic nautical mile
"oz"
Fluid ounce (U.S. customary liquid measure; see ozm
for ounce mass)
"Pica3" or
"Pica^3"
Cubic Pica
"pt" or "us_pt" U.S. Pint (liquid measure)
"qt"
Quart (U.S. customary liquid measure). This is
0.946352946 liters, and thus not the same as the U.S.
dry quart (1.101220 liters), nor is this the same as the
Imperial quart (as used in the U.K. and Canada, which is
1.1365225 liters exactly)
"tbs"
Tablespoon (U.S. customary, traditional meaning). This
shall be 0.5 U.S. fluid ounce, not 15mL (common in U.S.)
or 20mL (common in Australia).
"tsp"
Teaspoon (U.S. customary, traditional meaning), 1/6 fluid
ounce in U.S. customary measure. This is not the 1/8
Imperial fl. oz. per Imperial units nor the modern
teaspoon of 5 mL currently used in the U.S.; see tspm
"tspm" Modern teaspoon, 5mL
"uk_gal" U.K. / Imperial gallon
"uk_pt" U.K. / Imperial pint
"uk_qt" U.K. / Imperial quart
"yd3" or "yd^3" Cubic international yard
Evaluators shall support decimal prefixes for unit symbols marked with * and binary prefixes for unit
symbols marked with . Evaluators should not support prefixes for other unit symbols.
The unit symbols in parentheses are deprecated unit symbols; evaluators shall support these unit
symbols.
Evaluators should use internationally-standardized unit name abbreviations for such additions
where possible. Evaluators may support the obsolete symbols p and P as unit names for
Pascals.
Rationale: As applications add support for other units, they could be added. Possible future
extensions include angle measures (including degrees, radians, gradians) and solid angles. Excel
supports p for Pascals, and Ecma requires P or p (and forbids the standard Pa) for Pascals,
but short unit names can interfere with other units, and wasting a single-letter unit name on a
nonstandard name appeared unwise. The standard symbol for hour is h, but this can't be done as
long as it is a supported (though obsolete) symbol for horsepower.
For purposes of this function, a year is exactly 365.25 days long.
100414201 29 May 2010
Rationale: This list of unit symbols is essentially the union of the unit symbols in Excel (~65) and
OpenOffice.org 2.1 (~91), with some changes. The primary goal was to accept existing spreadsheet
documents without data loss. In addition, there was an effort to improve unit standards compliance,
by adding standard symbols as well as nonstandard symbols like mn,. and to add critical yet
missing unit symbols. There was also an effort to define with specificity exactly which units are
meant, e.g., there are many BTUs and calories, and the English units have many different
measurements with the same name. This CONVERT continues to require that a particular string
must mean exactly one unit; this enables strong error detection and speeds calculation. Unit names
are limited to U.S. ASCII characters for maximum portability.
We have worked to improve unit standards compliance without causing loss of existing data.
Unfortunately, many original unit symbols used in existing spreadsheet CONVERT functions do not
use standard unit symbols (since the prefixes are abbreviated, only unit symbols should normally be
listed if they are used with a prefix). A few unit symbols have been added to support international
standard abbreviations (such as s for second, min for minute, d for day). In some cases this
specification explicitly recommends a standard unit symbol and deprecates an alternative non-
standard one (for example, Pa for Pascal instead of P or p; HP for horsepower instead of the
h that conflicts with hour). The result is a much more standards-compliant unit notation, which can
nevertheless accept existing documents. The intent is that over time this specification can transition
to being even more compliant in the future.
Unit symbols were also added for other units that were not covered by existing implementations but
are widely used, e.g., modern teaspoon which is not the same as the original teaspoon, various tons
and the tonne, information measures (bit and byte), and clarifying names (e.g., two difference acres,
since there are two different standard definitions. Adding these is very helpful to users. We hope
that supporting these various units will encourage the increased use of international measurement
standards (such as meter, kilogram, and second), by easing the transition to them.
Adding the OpenOffice.org units added many unit symbols not available in most other
spreadsheets, such as the ly (lightyear) and ton (U.S. customary, 2000 pounds). The following
unit names were added in this specification, even though they are not supported by OpenOffice.org
2.1, Excel 2003, nor Ecma:
s - second, because this is the standard SI abbreviation for this base unit; sec is universally
used by spreadsheet applications but this abbreviation is discouraged by various standards and
guidelines.
min - minute, because this is the standard SI abbreviation for this base unit; mn is
universally used by spreadsheet applications but this abbreviation is discouraged by various
standards and guidelines.
d - day, because this is the standard SI abbreviation for this base unit; day is universally
used by spreadsheet applications but this abbreviation is discouraged by various standards and
guidelines.
survey_mi - survey/statute mile, because U.S. maps are measured in this unit and it is
different than an International mile
uk_acre (international acre) and us_acre (U.S. survey/statute acre), to distinguish between
these two definitions of acre.
L - liter, because this is the standard NIST-recommended abbreviation for liter in U.S. The
lowercase l, while used, is easily confused with the digit 1.
tspm - modern teaspoon, because the definition of teaspoon has changed (see below)
pc - official abbreviation of parsec (CONVERT only supports abbreviated prefixes, so to use
the correct units it must support abbreviated unit names as well). This overrides pico-calorie.
100414201 29 May 2010
ly - light-year, a very common astronomical length measurement (it did not make sense to
have parsec but not light-year). There are varying lengths of the year for light-year; the one
recommended by the IAU is used.
m/hr and m/sec were added (m/h and m/s were already in OpenOffice.org 2.1), to be
consistent with the hr and sec abbreviations.
bit and byte, because information technology is becoming increasingly important. The
common symbols b and B for these units unfortunately conflict with other unit symbols
(barn and Bel), so the full unit names are used; see below for a longer explanation.
"uk_ton"/LTON - Imperial ton, mass, 2240 pounds (avoirdupois), aka "long ton", "deadweight
ton", and "weight ton".
uk_gal and uk_qt - Imperial gallon and Imperial quart; included to be consistent with
including the Imperial pint
"t" - tonne / metric ton, mass, 1000 kg.
"GRT", gross registered ton, volume, 100 cubic (international) feet.
"MTON" - Measurement ton aka freight ton, volume, 40 cubic feet.
The traditional measurement systems of many English-speaking countries, such as the U.S.
customary system (widely used in the U.S.) and the Imperial system (historically used in the U.K.,
Canada and some other countries) are very complicated. In particular, the same name can mean
several different measurements, both between the Imperial and U.S. systems, and even inside one
system. For example, the term quart could mean the U.S. customary's quart (liquid measure), the
U.S. customary's quart (dry measure), and the Imperial quart and they are all different from each
other (The UK legal definition of the (Imperial) quart is 1.1365225 litres precisely in The Units of
Measurement Regulations 1995; see http://www.hmso.gov.uk/si/si1995/Uksi_19951804_en_2.htm).
This function tends to use the U.S. customary measures as the default names, because (1) the
CONVERT function has historically done so and doing otherwise would cause dangerous silent
changes in value, and (2) countries other than the U.S. primarily use and/or are shifting to SI units
(such as liters, cubic centimeters, and cubic meters), making the U.S. meanings increasingly
common when these terms are used at all. In a few cases, additional units have been defined (such
as survey_mi for U.S. survey or statute mile, and uk_pt for Imperial/U.K. Pint).
For powers (such as square meters and cubic meters) the ^ symbol is optional. OpenOffice.org 2.1
did not include them, but many in the U.S. normally use the ^.
Even though CONVERT supports many different units, it is designed to reduce the likelihood that
unsophisticated users will make a serious mistake with it, due to the following:
1. CONVERT only permits conversions if the "from" and "into" units are in the same group. For
example, you can't convert meters into grams. So even if there are MANY units, using a
pair of units that have an unintended meaning is unlikely.
2. Because applications SHOULD NOT permit prefixes for all unit symbols, but instead for
only a limited set, we limit the number of extraneous units.
3. Unit names are case-sensitive, so "guessing wrong" (by ignoring a manual) is unlikely to
produce a valid but unintended unit.
There are a vast number of documents related to measurement systems. Here are some useful
ones, along with their symbols used below:
[BIPM] Bureau International des Poids et Mesures (BIPM), The International System of Units is
freely available online at http://www.bipm.org/en/si/si_brochure/general.html. (see also:
http://www.bipm.org/en/si/) This is particularly important; other standards are based on this
document, and it's open access.
100414201 29 May 2010
U.S.'s NIST has a lot of information about units, both SI and non-SI. See
http://www.physics.nist.gov/cuu/Units/index.html for a summary.
[NIST HBK 44] NIST Handbook 44, 2006 edition http://ts.nist.gov/WeightsAndMeasures/h44-
06.cfm In particular, its Appendix C has many useful conversions:
http://ts.nist.gov/WeightsAndMeasures/upload/AppendC-06-HB44-Final.pdf. This includes much
information about U.S. customary measures.
[NIST SP 811] NIST Special Publication 811, Guide for the Use of the International System of
Units (SI). Barry N. Taylor, Editor. Focus on usage and unit conversions.
http://www.physics.nist.gov/cuu/Units/bibliography.html. and is based on documents such as
ISO 31.
[NIST SP 330] NIST Special Publication 330, 2001 Edition, Barry N. Taylor, Editor. The
International System of Units (SI). http://www.physics.nist.gov/cuu/Units/bibliography.html.
Guide to the SI, with a focus on history. That URL has other relevant information as well.
[UNIFIED] "The Unified Code for Units of Measure", Gunther Schadow and Clement J.
McDonald, Regenstrief Institute for Health Care and Indiana University School of Medicine,
http://aurora.regenstrief.org/UCUM/ucum.html. This document defines a set of unique ASCII
representations for each unit. This is, of course, exactly what CONVERT needs as well. In many
places they identify various conflicts, and suggest solutions. For example, it specifically notes
that B is both Bel and Byte, b is both barn and bit, and a is both are and year. It also
notes that mu isn't available everywhere, which is why the prefix u is widely used as a
substitute in simple text representations. Many of their proposed text representations are
intentionally equal to, or similar to, the standard representations, which is helpful to users.
Unfortunately, [UNIFIED]'s notation is designed primarily for scientists and engineers, who will
be used to complex notation, and as a result it is unnecessarily difficult to use and/or likely to
cause errors if non-scientists try to use it directly. For example, it adds extraneous characters
such as square brackets where they are not necessary, and uses long and unfamiliar suffixes
where they are not necessary or may even be misleading to non-scientists. For example, the
English units are very awkward; their symbol for the widely-used international foot is [ft_i], not
the usual ft. What's worse, they use the suffix _us to indicate U.S. survey/statute measures
(e.g., [ft_us]); this is a dangerously misleading suffix for non-scientists, because most U.S.
length measures other than the acre use international feet/inches/etc. and not survey/statute
measures. A U.S. user would be like to see ft_us and think oh, that's what I mean by foot,
not realizing that in most cases this would not be true. [UNIFIED]'s authors are aware of this
issue, noting that: Prospective users of The Unified Code for Units of Measure may be
disappointed by the fact that there are many different symbols for foot and inch defined but all
of them have a subscript and thus none of them are equal to the ANSI X3.50 symbols. We
considered to define default symbols for customary units, where, e.g., the common units of
length (foot, inch) would default to the international customary units, while mass units (pound,
ounce) would default to the avoirdupois system. However, because the customary system is
quite complex, and units by the same names can differ by more than 20%, defining defaults will
probably cause even more confusion. There is no denial: a gallon is not just a gallon and a
pound is not just a pound, this is the disadvantage of dealing with a unit system of medieval
origin.
But since CONVERT's users are often non-experts, [UNIFIED]'s syntax (designed for use
primarily by experts) was deemed to be often unsuitable. Another problem is that CONVERT
already has wide use, and its standard practice is not the same as their subscript _ convention
(that is, U.K. pint is already uk_pt, while [UNIFIED] uses the reversed [pt_br]). For these two
reasons, [UNIFIED] was not uniformly adopted by this specification. But [UNIFIED] is still an
extremely useful document, with a great deal of valuable insight, and it was consulted as part of
development of this specification.
[UNECE] UNECE (U.N. Economic Commission for Europe) Recommendation N. 20 Codes for
Units of Measure Used in International Trade
100414201 29 May 2010
(http://www.unece.org/cefact/recommendations/rec_index.htm) has a long list of units. It has a
Common Code that unfortunately is very non-intuitive to non-experts, and thus isn't
appropriate for this function. But this document does include the standard symbols from ISO 31,
and is open access, which makes it incredibly important for getting information about standard
symbols.
[STAT1804] Statutory Instrument 1995 No. 1804, The Units of Measurement Regulations 1995
is available at http://www.opsi.gov.uk/si/si1995/Uksi_19951804_en_2.htm. This is particularly
useful for Imperial (U.K./Commonwealth) units.
[KAYE] (U.K.) National Physical Laboratory, Kaye and Laby Online,
http://www.kayelaby.npl.co.uk/
[UNITSML] Units Markup Language (UnitsML) is a draft OASIS standard. It's a markup
language for unit information; more information is at NIST ( http://unitsml.nist.gov/ ) and OASIS
( http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=unitsml ). A related draft
database (UnitsDB) containing extensive information about scientific units is also under
development. Unfortunately, at this time it appears this work is too young to formally cite, but
the subcommittee chair (David A. Wheeler) has contacted the OASIS chair for UnitsML to see
what information can be gleaned and to coordinate with them as appropriate.
[WOLFRAM] Wolfram research has a page here:
http://scienceworld.wolfram.com/physics/topics/Units.html. The conversion factors are often
imprecise, and they don't show all the alternatives, but they do present the common
abbreviations for non-SI units that aren't explained elsewhere.
[NAVY] U.S. Navy's "Military Sealift Command, Ship Inventory: Definitions, Tonnages and
Equivalents" at http://www.msc.navy.mil/inventory/glossary.htm describes ship-specific
measurements, and is representative of U.S. conventional measures for ships. It includes:
DEADWEIGHT - The total lifting capacity of a ship expressed in tons of 2240 lbs. It is the
difference between the displacement light and the displacement loaded. {This is equal in
mass to an Imperial ton. I suggest just reusing "uk_ton" instead, since don't see a need for
yet another symbol.}
BARREL - 42 gallons {we agree!}
GROSS TONNAGE (aka Gross Register and Net Register Tonnage) - The entire internal
cubic capacity of the ship expressed in tons of 100 cubic feet to the ton, except certain
spaces which are exempted... {Okay, gross register ton = 100 ft^3}
LONG TONS - One long ton is equal to 2,240 pounds; used to measure petroleum
products. {ANOTHER 2240-pound ton}
MEASUREMENT TON - Bale cubic in units of 40 cubic feet to the ton. {Agrees with earlier}
WEIGHT TON - Calculated as long ton (2,240 lbs.) Abbreviated W/T. {ANOTHER 2240-
pound ton. We don't want to use "W/T", that implies a division.}
Note that the "hundredweight" measurements are not included, which justifies the argument that
those measures are becoming less common.
[ISO 1000]. Not open access.
[ISO 31] International Standard ISO 31, Quantities and units, International Organization for
Standardization. Style guide for the use of units of measurement, and formulas involving them.
Based on BIPM SI. Not open access. However, important information from ISO 31 can be
gained from [NIST HBK 44] and [UNECE].
[IEC 60027] IEC 60027 (formerly IEC 27) is the International Electrotechnical Commission's
standard on Letter symbols to be used in electrical technology. A 1999 addendum to IEC 60027-
2 added binary prefixes. Not open access.
100414201 29 May 2010
[ISO/IEC 80000] Quantities and units. To be released. Its purpose is to harmonize ISO 31 and
IEC 60027. Not open access.
The British Standard BS 350:2004, Conversion Factors. Not open access.
The following table shows the unit symbols used by various spreadsheet applications,
specifications,standards, and related documents. The Excel column shows the Excel 2003 values;
a * indicates that decimal prefixes are permitted. The OOo column shows OpenOffice.org 2.1's
CONVERT_ADD function. The Corel column shows Corel's Word Perfect suite 12 (Quattro Pro
12)'s @CONVERT function. The 1-2-3 column shows (IBM) Lotus 1-2-3 v9.8's CONVERT
function; the ones marked with * accept decimal prefixes (note that sec permits, but yr does
not). The Gnumeric column shows the symbols as reported by the Gnumeric manual version 1.4.
[UNIFIED] shows [UNIFIED] version 1.6's case-sensitive representation, with * indicating those
where decimal prefixes are permitted. PRINT is the recommended print representation shown in
[UNIFIED], which is derived from ISO 1000.
100414201 29 May 2010
Unit
grou
p
Excel OOo Corel 1-2-3
Gnu
meri
c
[UNI
FIE
D]
Print
Ecm
a
Proposed
Unit name
Comments
A
r
e
a
acre
[acr
_br]
"uk_acre"
International acre (using international
feet), exactly 4046.8564224 m
2
[acr
_us]
"us_acre"
U.S. survey/statute acre (using U.S.
survey/statute feet), exactly
4046+13525426/15499969 m
2
ang2
ang2 or
ang^2 *
Square angstrom (an Angstrom is
exactly 10
-10
m)
ar ar * a ar * are, 100 m
2
(not abbreviated as a)
ft2
[sft_
i]
ft2 or ft^2
Square international feet (1 foot is
exactly 0.3048 m)
ha har ha ha hectare, 10 000 m
2
in2
[sin
_i]
in2 or in^2
Square international inches (1 inch is
exactly 2.54 cm)
m2 m2 or m^2 Square meters
Morge
n
Morgen Morgen, 2500 m
2
mi2
mi2 or
mi^2
Square international miles
Nmi2'
Nmi2 or
Nmi^2
Square nautical miles (1 nautical mile is
1852 m)
Pica2
Pica2 or
Pica^2
Square Pica (one Pica is 1/72 in.)
yd2
[syd
_i]
yd2 or
yd^2
Square international yards (1 yard is
0.9144 m)
D
i
s
t
a
n
c
e
"ang" "ang" ang
ang
*
ang Ao ang "ang" Angstrom, exactly 10
-10
m
AU AU
Astronomical unit. Some have ua; but
u = micro conflicts with micro-years
& micro-ares.
"ell" "ell" Ell, exactly 45 international inches
"ft" "ft" ft ft ft
[ft_i]
ft "ft"
International Foot, exactly 0.3048 m and
also exactly 12 international inches.
This is not a U.S. survey/statute foot.
"in" "in" in in in
[in_i
]
in "in" International Inch, exactly 2.54 cm.
lightye
ar
[ly] l.y. "ly" *
Light-year, the distance light travels in a
year of 365.25 days. Extant but
undocumented in OOo 2.1.
"m" * "m" m m * m m * m m "m" * Meter
"mi" "mi" mi mi mi
[mi_
i]
mi "mi"
International Mile, exactly 1609.344 m
and exactly 5280 international feet. This
is not a U.S. survey/statute mile (see
smi) nor a nautical mile (see Nmi)
"Nmi" "Nmi" Nmi Nmi
Nmi
[nmi
_i]
Nmi "Nmi"
International nautical mile, exactly 1852
m. Note that this is not the obsolete
U.S. nautical mile nor the Admiralty
mile.
100414201 29 May 2010
Unit
grou
p
Gnu
meri
c
[UNI
FIE
D]
Print
Ecm
a
Proposed
Unit name
Comments
"parse
c"
pc pc
"parsec" or
pc *
Distance from sun to a point having
heliocentric parallax of one second
(used for stellar distance)*
"Pica" "Pica" Pica
Pica
[pca
]
Pica "Pica" Pica (1/72 in.)
[mi_
us]
"statute_mi"
U.S. survey mile, aka U.S. statute mile,
exactly 6336000/3937 m and exactly
5280 U.S. survey/statute feet. This is
not an international mile (see mi).
"yd" "yd" yd yd yd
[yd_
i]
yd "yd"
International yard, exactly 0.9144 m and
exactly 3 international feet. This is not a
U.S. survey/statute yard.
E
n
e
r
g
y
"BTU" "BTU" btu BTU
"BTU
"
BTU
or
btu
"BTU" or
"btu"
BTU. Excel 2003 CONVERT(1, BTU,
kJ) reports 1.055058137867. The
closest BTU in use I can find in
[UNIFIED] is the international table
British thermal unit, which according to
[UNIFIED] is 1.05505585262 kJ. What's
disturbing is that [UNIFIED] has a
default [Btu] equal to [Btu_th], the
thermochemical British thermal unit of
1.054350 kJ.
"c" * "c" c c * c
cal_
th or
cal
calth
or
cal
c "c" *
Thermodynamic calorie, 4.184 J. This is
not a dietary Calorie (kilocalorie). Do not
use for high accuracy, due to many
conflicting definitions of calorie; use
Joule instead. Excel 2003 CONVERT(1,
c, J) reports 4.183991013637; this
far closer to the thermo calorie than any
other calorie in use, but it's somewhat
inaccurate.
"cal" * "cal" cal cal * cal
cal_
IT
calIT cal "cal" *
International Table (IT) calorie, 4.1868
J. This is not a dietary Calorie
(kilocalorie). Do not use for high
accuracy, due to many conflicting
definitions of calorie; use Joule instead.
Excel 2003 CONVERT(1, cal, J)
reports 4.186794846139; this far closer
to the IT calorie than any other calorie in
use, but it's somewhat inaccurate.
"e" "e" e e * e
erg
*
erg e "e" * Erg
"eV" "eV" ev eV * "eV" "eV" "eV"
ev
or
eV
"eV" or ev * Electron volt (eV preferred)
"flb" flb flb flb flb "flb"
Foot-pound (international foot,
avoirdupois pound). OOo doesn't
document flb.
"HPh" "HPh" hh HPh
"HPh
"
Hph
or
hh
"HPh" or hh Horsepower-hour (HPh preferred)
"J" * "J" J J J * J J "J" * Joule
"Wh" "Wh" wh Wh * "Wh"
Wh
or
wh
"Wh" or wh
*
Watt-hour
100414201 29 May 2010
Unit
grou
p
Gnu
meri
c
[UNI
FIE
D]
Print
Ecm
a
Proposed
Unit name
Comments
F
o
r
c
e
/

W
e
i
g
h
t
dyn" dyn" dy
dyn
*
dyn"
dyn
*
dyn"
dy
or
dyn
"dyn" or "dy"
*
Dyne
"N" * "N" N N * "N" N * N N "N" * Newton
"lbf" lbf lbf "lbf"
[lbf_
av]
lbf lbf "lbf" Pound force (see lbm for pound mass)
"pond" "pond" *
Pond, gravitational force on a mass of
one gram
I
n
f
o
r
m
a
t
i
o
n
bit bit * bit
By byte * Byte = 8 bits
M
a
g
n
e
t
i
c

F
l
u
x

D
e
n
s
i
t
y
"ga" * "ga" ga * "ga" G
G or
Gs
ga "ga" *
Gauss (note: Gs conflicts with Giga-
second)
"T" * "T" T * "T" T * T T "T" * Tesla
M
a
s
s
"g" * "g" g g * g g * g g "g" * Gram
"grain" "grain" 1/7000 international pound mass
(avoirdupois) (U.S. usage).
hweig
ht
uk_cwt or
lcwt
(hweight)
long hundredweight, 112lbm.
"lbm" "lbm" lbm lbm lbm [lb_
av]
lbm "lbm" International pound mass (avoirdupois),
exactly 453.59237 g (see lbf for pound
force)
"stone" [sto
ne_a
v]
"stone" 14 international pound mass
(avoirdupois)
"ton" [sto
n_av
]
"ton" U.S. short ton, 2000 international pound
mass (avoirdupois) (U.S. usage). Note
that there are many other measures
also called ton; in particular, this is not
a metric ton (tonne).
brton [lton
_av]
"uk_ton"
(brton)
brton is in OOo sources, not
mentioned in OOo 2.1 help files. It's
long ton or Imperial ton, 2240 lbm.
"ozm" "ozm" ozm ozm ozm
[oz_
av]
ozm "ozm" Ounce mass (avoirdupois), exactly 1/16
of an international pound mass
(avoirdupois) (see oz for fluid ounce)
pweig
ht
Supposed to be pennyweight, but it's
got the wrong abbreviation
100414201 29 May 2010
Unit
grou
p
Gnu
meri
c
[UNI
FIE
D]
Print
Ecm
a
Proposed
Unit name
Comments
(pennyweight is dwt which conflicts
with deadweight ton), and OOo 2.1 gets
it wrong anyway. Its
CONVERT_ADD(1;"pweight";"grain")
produces 21.88 but pennyweight should
produce 24. Nobody noticed; clear
evidence no one cares. Dropped per
2007-02-12 email on subcommittee
mailing list
"sg" "sg" sg sg sg sg "sg" Slug
shwei
ght
cwt
Short hundredweight, = 100lbm. Correct
abbreviation is cwt.
t t t * Tonne aka metric ton, 1000 kg.
"u" * "u" u u u
AM
U
u u "u" * U (atomic mass unit)
P
o
w
e
r
"HP" "HP" h HP HP
[HP]
H or
hp
"HP" or h Horsepower. Ecma wrong.
PS PS
Pferdestrke (German horse strength,
close but not identical to HP)
"W" * "W" w W * "W" W * "W"
W
or w
"W" or w * Watt
P
r
e
s
s
u
r
e
"atm" "atm" at
atm
*
"atm" "atm" "atm"
atm
or at
"atm" or at * Atmosphere
bar bar 1E5 Pa
"mmHg"
"mmHg
"
mmH
g *
"mm
Hg"
mmH
g
"mmHg" * mm of Mercury
"Pa" * "Pa" p Pa * "Pa"
Pa
*
Pa
P or
p
"Pa" *
Pascal; Pa is the standard abbreviation.
Note Ecma appears grossly
incompatible.
"psi"
[psi]
psi "psi"
Pounds per square inch, using
avoirdupois pounds and international
inches.
"Torr" "Torr"
Torr, exactly 101325/760 Pa (this is
close but not equal to mmHg)
S
p
e
e
d
admkn
admkn
Admiralty knot, exactly 6080
international feet/hour.
kn
[kn_
i]
"kn"
Knot, exactly one Nautical mile per hour
or exactly 1852/3600 m/s. Note that this
is not an Admiralty knot (admkn).
m/h
m/h or
m/hr
Meters per hour
m/s
m/s or
m/sec *
Meters per second
mph mph Miles per hour (international miles)
100414201 29 May 2010
Unit
grou
p
Gnu
meri
c
[UNI
FIE
D]
Print
Ecm
a
Proposed
Unit name
Comments
T
e
m
p
e
r
a
t
u
r
e
"C" "C" cel C "C"
Cel
*
"C"
C or
cel
"C" or cel degrees Celsius
"F" "F" fah F "F"
[deg
F]
"F"
F or
fah
"F" or fah degrees Fahrenheit
"K" * "K" kel K * "K" "K" * "K"
K or
kel
"K" or kel * Kelvin
Rank ran "Rank" Rankine
Reau Reau Raumur, [C] = [R] 5/4.
T
i
m
e
"day" "day" day day day d d day "day" or d Day (exactly 24 hours)
"hr" "hr" hr hr hr h h hr "hr"
Hour (exactly 60 minutes); h conflicts
with old horsepower.
"mn" "mn" mn mn mn min min mn "mn" or min Minute (exactly 60 seconds)
sec sec sec
sec
*
sec s * s sec "sec" or s *
Second (s is the official abbreviation of
this SI base unit, while sec is its
traditional abbreviation in the
CONVERT function) *
"yr" "yr" yr yr yr
a
or
a_j
yr "yr"
Year (exactly 365.25 days, for purposes
of this function)
V
o
l
u
m
e
ang3 "ang3" or
"ang^3"
Cubic angstrom
barrel [bbl
_us]
"barrel" U.S. oil barrel, exactly 42 U.S.

customary gallons (liquid).
bushel
"bushel" U.S. bushel (not Imperial bushel),

interpreted as volume
"cup" "cup" cup cup cup [cup
_us]
cup "cup" Cup (U.S. customary liquid measure)
ft3 [cft_
i]
"ft3" or "ft^3" Cubic international feet
"gal" "gal" gal gal [gal
_us]
gal "gal" Gallon (U.S. customary liquid measure)

in3 [cin
_i]
"in3" or "in^3" Cubic international inch
"l" "l" lt l * l l or
L *
l or
L
l or
lt
"l" or lt or
L *
Liter
"m3" "m3" or
"m^3" *
Cubic meter
mi3 "mi3" or
"mi^3"
Cubic international mile
"MTON" Measurement ton aka freight ton, 40
cubic feet.
Nmi3 "Nmi3" or Cubic nautical mile
100414201 29 May 2010
Unit
grou
p
Gnu
meri
c
[UNI
FIE
D]
Print
Ecm
a
Proposed
Unit name
Comments
"Nmi^3"
"oz" "oz" oz oz oz
[foz
_us]
oz "oz"
Fluid ounce (U.S. customary liquid
measure)
Pica3
Pica3 or
Pica^3
Cubic Pica
"pt" "pt" pt pt pt
[pt_
us]
pt or
us_p
t
"pt" or
us_pt
U.S. Pint (liquid measure)
"qt" "qt" qt qt qt
[qt_
us]
qt "qt" Quart (U.S. customary liquid)
regton
GRT
("regton")
Gross registered ton (register ton), 100
cubic (international) feet.
"tbs" "tbs" tbs tbs tbs
[tbs
_us]
tbs "tbs"
Tablespoon (U.S. customary, traditional)
0.5 U.S. fluid ounce.
"tsp" "tsp" tsp tsp tsp
[tsp
_us]
tsp "tsp"
Teaspoon (U.S. customary, traditional
meaning), 1/6 fluid ounce, U.S.
customary
"tspm" Modern teaspoon, 5mL
"uk_pt"
[pt_
br]
uk_p
t
"uk_pt" U.K. pint
yd3
[cyd
_i]
"yd3" or
"yd^3"
Cubic international yard
Schoo
ner,
Middy
,
Glass
Dropped per 2007-02-12 message
Note that existing spreadsheet implementations already have some naming conventions, namely, in
English measures the U.S. Customary is the default, and Imperial measures (where different) begin
with uk_ (as in uk_pt).
The following are more specific rationales about these units:
Area
Some of the area measures listed here are improbable, but it was felt to be important to consistently
support the square of nearly all distance measures.
The unitname acre is not required to be defined by this function, since the term has different
official meanings in different locales. Instead, two different acre-based units are given. The official
U.S. definition of acre as presented by NIST SP 811 (see B.6) uses U.S. survey/standard feet,
which are not the same as the international feet typically used in the U.S. In the Imperial system,
and in many programs such as Google's unit calculator on 2007-02-08, an acre is defined using
international feet. The names given here follow the conventions already established by pint (e.g.,
us_pt vs. uk_pt), because they are valid for acre; in the U.S. an acre is the acre defined by survey
feet (per NIST), while elsewhere an acre is defined using the more typical international feet.
The unit are (100 m
2
) is abbreviated here as ar instead of the official standard a. This is the
same abbreviation used by [UNIFIED]. One reason is that a is also strongly advocated as an
abbrevation for year. Because there are conflicting definitions for a, neither is assigned the
100414201 29 May 2010
symbol a until it is resolved. OpenOffice.org 2.1 already uses ar as the abbreviation for are, so
there is precedence in a widely-used spreadsheet implementation. Note that the common unit ha
(hectare) is separately defined, without permitting other prefixes on it; this supports the common
case (so users can use ha directly). A side-effect is that if a is someday defined as year, then
ha cannot be used as 100 years; since users are more likely to talk about centuries instead of
ha meaning 100 years, this is not likely to be a real problem.
The Morgen is included because OpenOffice.org 2.1 includes it (a Morgen is 2500 m
2
).
Distance
The official abbreviation of anstrom is , but this is difficult to type and see on many systems, so
ang is used instead. This is consistent with historical use of CONVERT, though not with [UNIFIED]
which uses Ao instead.
The U.S. Survey mile must not be us_mi, because normally miles in the U.S. are international
miles. It is only in certain land surveys that survey miles (aka statute miles) are used.
The definition of parsec is from CRC Handbook for Chemistry and Physics, 63
rd
ed. The IAU
defines the value of parsec as 30.857 Pm (http://www.iau.org/Units.234.0.html). OpenOffice.org 2.1
uses 1 parsec = 30856778570831.3 km. The standard abbreviation for parsec was not in
OpenOffice.org 2.1, so that was added. One complication is that the standard abbreviation pc
overrides the pico-calorie, but that is a very improbable measure so this is accepted.
A widely-used distance measure in astronomy is the astronomical unit (AU), the distance from Earth
to the Sun. This is not currently included, due to questions about its value and its standard symbol.
There seems to be some disagreement over its exact value. (E.G.., Wikipedia claims "The currently
accepted value of the AU is 149 597 870 691 30 metres"; Wikipedia isn't authoritative, but it's a
good hint that there is disagreement.) [UNITED] gives 149597.870 Mm as its value. We can give its
physical definition, but that implies that as the value's measure improves, applications might need to
change the conversion factor (!). Another problem is that there are many different standard symbols
used for it: ua, au, and AU. BIPM uses "ua" as its abbreviation, but the "a" is also "year" AND
"are", so "ua" would interfere with "micro-year" and "micro-are (so many conflicts are not a good
sign). The IAU recommends "au", and normally they'd be authoritative in such matters, but "au" is a
poor unit name; it conflicts with atto-u. ISO 31-1 and [UNITED] use AU, which seems the best of
these three choices, though the fact that there's conflict still gives room for pause. We really want
unique, internationally agreed-upon unit names that use solely case-sensitive ASCII characters;
here we don't have that.
A light-year is the distance light travels in a year; several different definitions of year have been
used, but the IAU recommends using a year of 365.25 days (http://www.iau.org/Units.234.0.html),
so it is defined that way here.
Energy
The unit HPh, not Hph, is used for horsepower-hour, because that is what current
implementations accept.
There are a disturbingly large number of different definitions for the calorie (e.g., see [UNIFIED]).
There are small calories and large calories, and a vast number of versions of each. Because of this
widespread confusion, calories should be avoided where accurate measures are desired. If
accuracy is desired, use Joule instead. The International Steam Table Calorie (1956) is 1.163 mW h
= 4.1868 J exactly, adopted by the Fifth International Conference on Properties of Steam (London,
July 1956). The Thermochemical/Thermodynamic calorie is 4.184 J exactly. Excel 2003 gets slightly
wrong results; in Excel, 1 c = 4.18399101363672 J, and 1 cal = 4.18679484613929 J.
A similar argument holds for BTU as for calorie.
Force/ Weight
100414201 29 May 2010
The term force is used as the primary term, not weight, because weight is simply a special case
of force (namely, the force due to gravity).
The English unit pound (traditionally abbreviated lb) can be either a measure of mass or a
measure of force. The abbreviations lbf and lbm distinguish these different uses of pound.
OpenOffice.org 2.1 grouped units somewhat differently; it had a weight group, and no mass
group, and most of its weight measures (such as grams) were really measures of mass. This
specification has two distinct groups, force and mass, because these physically distinct. This results
in lbf and lbm for pound-force and pound-mass, because the term pound is often used for
either measure.
The standard acceleration of gravity in free fall is 9.80665 m/s
2
.
Information
The information units bit and byte were added, since they are widely used, and conversions are
often needed that are nontrivial for nonexperts (e.g., between decimal and binary versions). The
octet o abbreviation was not added; the octet is a far less common term, and there was hesitation
to use up a single-letter abbreviation for such an unusual case. Support for binary prefixes was
added because as systems become more capable, the errors from misusing binary prefixes become
more serious.
The official abbreviations for bit and byte are b and B respectively. But b is also the official
abbreviation for barn, and B is the official abbreviation for Bel (as in deciBel). [UNIFIED]
defines B as Bel, b for barn, bit for bit, and By for byte. Ordinary users might consider it
confusing that bit is not abbreviated, but byte is, which is a good reason to not abbreviate either
(and thus we differ from [UNIFIED] here). More importantly, adding a symbol such as b or B that
has a known conflict with other standard symbols was considered unwise.
The solution used here is to simply use their full names as the symbol. This is extremely clear to all
readers, and is very unlikely to conflict with any agreement in the future.
A probable future addition would be information rates (bit/s and byte/s). Note that baud is not the
same as bit/s or byte/s, but instead measures signalling rates.
Magnetic Flux Density
Both the Tesla and Gauss are included because they are widely supported (e.g., in Excel and
OpenOffice.org 2.1); the Tesla is the SI derived unit, and is thus preferred internationally.
Mass
In SI, the kilogram is actually the base unit of mass. This specification does not conflict with SI on
this point; instead, it simply states that for purposes of creating unit names the base unit is the
gram, as required by SI.
There are other systems besides Avoirdupois, but they have only a specialized use (e.g., Troy is
typically only used for precious metals, and Apothecaries' has been essentially displayed by SI).
Thus only avoirdupois is required to be supported by this function because it is by far the most
common case. There is no required support for Troy, Apothecaries', or the historical Tower measures
by CONVERT.
The ton has a very large number of different definitions, but in the U.S. its common meaning is
2000 pounds (aka the short ton), and there is already precedence for this meaning in
OpenOffice.org 2.1, so this particular meaning was chosen. A similar argument holds for grain.
OpenOffice.org 2.1 included the mass unit symbols hweight (hundredweight) and shweight (short
hundredweight). These are not their standard unit symbols, which are lcwt (long hundredweight, 112
lbm) and ctw (hundredweight, 100 lbm), per
http://scienceworld.wolfram.com/physics/AvoirdupoisSystemofUnits.html. The old OOo 2.1 symbols
were poorly documented, so it is unlikely that the original symbols were actually used (and thus
100414201 29 May 2010
there's no need to include the old ones for interoperability). These measures are used, but not
extensively, even in their putative field (e.g., a U.S. Navy glossary of measures included various
tons but not these measures). So there was hestitation in adding them as required units. Note that
cwt would interfere with creating a prefixed unit symbol wt (cwt couldn't be centi-wt), but we
don't know of any wts. For the long hundredweight, another possible symbol would be uk_cwt,
because the hundredweight in the Imperial system is 112lbm while in the U.S. customary system it
is 100lbm.
The symbol dwt is not used, because this is a common abbreviation for pennyweight.
For mass unit symbols with names based on ton, see the Ton section (below).
Mass and energy can theoretically be converted to each other, per E=mc
2
, but they are considered
separate units by CONVERT to help users detect unintentional errors.
Power
Power and energy are not the same thing; power is energy/time.
Excel 2003 requires HP or h for horsepower; it does not accept hp or H. In contrast, the Excel
specification Ecma-376 (December 2006) requires hp or H, and implicitly forbids HP or h.
Since the Ecma specification is supposed to document what Excel does, we interpret this as an
error in Ecma-376, and the table above includes Excel's actual behavior not Ecma-376's
specification.
The use of h to represent horsepower is deprecated (we recommend using HP instead), so that
in a future version of this specification h could mean hour. The symbol h is the official
abbreviation for hour, but this cannot be easily supported as long as it has another conflicting
meaning.
PS is close to, but not the same as the horsepower of HP. It stands for Pferdestrke (German
horse strength), and is still a common measure for cars in Europe. It implies measurement at the
wheels, not at the engine, but that distinction is outside the scope of this document.
Pressure
Excel 2003 does not accept P for Pascal (it does accept Pa or p), while Ecma requires P or
p (and not Pa). Pa is the standard abbreviation for Pascal, and lowercase p creates ambiguity
problems (see below).
The Torr and mmHg are very similar, but not identical. The Torr is 101325/760 Pa; see the U.K.'s
National Physical Laboratory site at http://www.npl.co.uk/pressure/punits.html for more information.
Speed
This group is labelled speed, not velocity, because velocity implies a direction; the scalar absolute
value (magnitude) of velocity is speed.
Temperature
Unlike most conversions, many of the temperature unit conversions require an addition or
subtraction as well as a multiplication. However, they are still unit conversions, and have historically
been done by CONVERT, so they are included.
Rankine is R = (C + 273.15) 1.8
Kelvin is not measured in degrees but is simply a unit of measure, while Celsius and Fahrenheit
are measured in degrees, per the 13th General Conference on Weights and Measures (CGPM) in
19671968. Thus the omission of the term degrees in the cell describing Kelvin is intentional.
100414201 29 May 2010
Reau is for Raumur, a historical temperature scale used in Europe before Celcius and supported
by OpenOffice.org 2.1. See http://en.wikipedia.org/wiki/R%C3%A9aumur_scale. In this scale, 0 is
freezing, and 80 is boiling, so [C] = [R] 5/4.
Time
The Earth does not orbit the Sun in exactly 365.25 days, but for purposes of calculation it is typically
assumed to do so.
The abbreviation for year is yr; some documents advocate using a, but a is also the
abbreviation for are (and the hectare is used widely). All spreadsheets currently use yr, which is
not ambiguous, so this is retained. If a is added, and prefixes are also allowed, a conflict then
exists between Pa (Pascal) and Pa (Petayears). This is not too bad; by the rule of preferring
unprefixed unit symbols, this would be resolved as a Pascal. But given the conflict, no change has
yet been made.
Spreadsheets widely agree on non-standard symbols for time. The international system of units
includes the symbols s (second), min (minute), and d (day) these were added as alternative
unit symbols for standards compliance. In particular, note that s is a base unit in SI, and it was
particularly bizarre that s was not supported as a unit.
It is nontrivial to add the standard symbol for hour (h), because was originally used for
horsepower. This specification deprecates h, to prepare for use of h as hour.
Volume
Some of the volume measures listed here are improbable, but it was felt to be important to
consistently support the cube of nearly all distance measures.
Note that volumes are not limited to liquid measures, but also include spatial volumes. Excel
documentation refers to liquid measures, but this is excessively limiting.
There are a large number of measures all called barrel; the one labelled barrel is widely used for
measuring oil, and is the one used by OpenOffice.org 2.1. Similarly, there are many bushels, the
one used by OpenOffice.org 2.1 was chosen (since Excel does not implement one).
The definition of teaspoon and tablespoon in this function are not the same as those used today
in many countries. This is because the definitions have changed in some countries since these
measures were originally defined in CONVERT. The definitions used in CONVERT are their original
meanings in spreadsheets, which matched the U.S. standards when they were added. These have
not been changed in CONVERT, because changing the meaning in spreadsheets of tsp and tbs
now would cause a subtle change in existing spreadsheets' values. This could be dangerous since
these measures are sometimes used for medicines. In particular:
Teaspoon: Teaspoon tsp continues to have its U.S. customary, traditional meaning of 1/6 fluid
ounce, in U.S. customary measure. Note that this is not the 1/8 Imperial fl. oz. per Imperial
units. More importantly, it is not 5 mL, a common meaning today due to a change in standard
definitions. For example, U.S. federal law, 21CFR101.9(b)(5)(viii), now defines a teaspoon as
5mL for purposes of nutritional labels, as is true with many other countries such as Canada,
New Zealand, and the U.K. Since there is a consensus redefinition of teaspoon, but there was
a need to not subtly break existing documents, the tspm was created as the metric/modern
teaspoon of 5mL.
Tablespoon: Historically the traditional Imperial tablespoon could vary from 1/2 to 5/8 Imperial fl.
oz. (14.2 mL to 17.8 mL). In many countries, the tablespoon is now 15mL; e.g., U.S. federal law,
21CFR101.9(b)(5)(viii), defines a tablespoon as 5ml for purposes of nutritional labels, as is true
with many other countries such as Canada, New Zealand, and the U.K. However, in Australia,
one tablespoon is 20ml. Since there is some disagreement on a redefinition of tablespoon, no
modern/metric tablespoon measurement has been proposed. If there is consensus in the future,
tbsm would be the logical choice.
100414201 29 May 2010
A common abbreviation of cubic centimeters is cc, but this conflicts with centi-calories (cc). This is
not limiting; for cubic centimeters, simply use cm3 or cm^3. Conversions between different
groups is prohibited so accidental use of cc would normally be detected by the CONVERT
function.
L was added as a synonym for liter because the National Institute of Standards and Technology
(NIST) Special Publication (SP) 811, Guide for the Use of the International System of Units (SI),
1995, at http://physics.nist.gov/Pubs/SP811/sec06.html#6.1.2 recommends the use of L not l for
liters. The lowercase l is too easily confused with the digit 1. The abbreviation lt is nonstandard,
and is included for compatibility with older documents.
OOo 2.1 volume measures Schooner and Middy were dropped. These are Australian liquid
measures. However, these sizes vary. Australia's NSW Office of Fair Trading Trade measurement
and the sale of health products, food and alcohol document states that The colloquial terms, such
as seven, middy and schooner do not indicate any particular size of glass. Traders should be
aware that any advertising using such terms should be qualified by the indication of the actual size
of the glass being used on the premises eg middy (280 mL) middy (285 mL) or schooner (400
mL) schooner (425 mL). This document was retrieved 2007-02-11 from
http://www.fairtrading.nsw.gov.au/business/runningabusiness/trademeasurementsaleofhealthfoodalc
ohol.html
OOo 2.1's volume measure Glass was dropped. OpenOffice.org computes 1 Glass as 0.2 liters,
i.e., =CONVERT_ADD(1;"Glass";"l") is 0.2. There was no evidence this was an important unit to
support for interoperability.
For volumes with names based on ton, see the Ton section (next).
Ton
The word ton has a variety of meanings, some as mass and others as volume. The main ones in
use, and thus included here, were determined to be:
"ton", U.S. customary short ton, mass, 2000 pounds (avoirdupois) (this is the U.S. customary
ton, aka short ton). Uses the usual CONVERT convention "non-prefix is U.S. conventional".
[UNIFIED] uses the nasty symbol "[ston_av]".
"uk_ton" - Imperial ton, mass, 2240 pounds (avoirdupois). Uses the usual CONVERT naming
convention, with "uk_" prefix meaning "Imperial". [UNIFIED] uses the symbol "[lton_av]". The
"long ton", "deadweight ton", and "weight ton" are all also 2240-pound tons, just like the Imperial
ton (see http://usmilitary.about.com/od/glossarytermsm/g/m3895.htm). The suggestion is to just
use "uk_ton", continuing the tradition that the "uk_" prefix means "Imperial". The is no clear
need for additional symbols for the same measure, so only this symbol was defined. (Note that
dwt is the standard symbol for a pennyweight, a very different measure). OOo 2.1 used the
term brton, but this was naming was inconsistent with uk_pt. Instead, uk_ is used as the
prefix to mean Imperial measure, and thus uk_ton is used.
"t" - tonne / metric ton, mass, 1000 kg. "t" is the widely-used symbol; [UNIFIED] uses "t" also.
That's a really short unit name, which can be a problem, but it's the normal abbreviation and the
fact that [UNIFIED] is willing to make it "t" suggests that it's okay in practice.
"GRT", gross registered ton, volume, 100 cubic (international) feet. Not mentioned in [UNIFIED].
"MTON" - Measurement ton aka freight ton, volume, 40 cubic feet. It's a unit of volume used
for describing ship capacities (tonnage) or cargo. Not mentioned in [UNIFIED] (note that if we
use this symbol, we'll have trouble adding a prefix-permitting "TON"!). One nasty problem is that
its common abbreviations are "M/T", "MT", or "MTON". All of those abbreviations are easily
confused with the metric ton (though at least metric ton is mass, while measurement ton is
volume, so CONVERT will notice the problem). I'd prefer using "MTON", so that we don't cause
troubles with mega-T (in general, short symbols can cause more grief in CONVERT, because
we want all unit names to be unique).
100414201 29 May 2010
Prefixes are forbidden on all but "t". [UNIFIED] is willing to give "t" decimal prefixes, and tonne is
simply 1000kg, so there's some logic in using prefixes for tonne. Note that the ft (femtoton) won't
be accepted, because ft is interpreted as feet instead. This isn't considered a real problem,
because in that mass range people use grams instead.
Miscellaneous rationale:
The third parameter is named Into, not To, because To is a reserved word in some
programming languages. This should simplify some implementations.
The CONVERT function is specifically designed so that a unit name means exactly one thing,
instead of attempting to determine the meaning from context, which speeds calculation and reduces
the chance of undetected error. This means that future versions will need to beware of defining new
unit names (especially short ones) or prefixes, and examine standard abbreviations before doing so.
E.G., if a unit name d were added, and cd was interpreted as centi-d, that might later be silently
reinterpreted as candela (cd) if candela were added even later.
Early versions of this specification recommended permitting prefixes in front of any unit, but this was
instead changed to a should not:
Current applications generally do not permit prefixes in front of arbitrary units, and while there
were no strong objections, there was no strong rationale for permitting them either.
This would cause interoperability problems, because if one application accepted kmi
(kilomiles) and another didn't, users could easily create spreadsheets that failed to exchange
correctly between conforming implementations.
This could cause significant growth problems, because many obsolete and specialized units
can easily interfere this way. For example, [UNIFIED] uses [mi_i] for miles and [nmi_i] for
nautical miles. If the brackets and _i were dropped, you could have mi and nmi; these do no
conflict if neither accepts prefixes, but otherwise nmi looks like nano-miles. There are many
hidden traps in trying to add new units if all units permitted prefixes.
Evaluators claiming to support this function shall permit the following unit decimal prefixes to be
prepended to any unit symbol marked with * in the unit table cell above. Adding a unit prefix
indicates multiplication of the (scalar) unit by the given prefix value; for example km indicates
kilometres, and km2 or km^2 indicate square kilometres.
100414201 29 May 2010
Table 27 - Decimal Prefixes for use in CONVERT
Unit Prefix Description Prefix Value
"Y" yotta 1E+24
"Z" zetta 1E+21
"E" exa 1E+18
"P" peta 1E+15
"T" tera 1E+12
"G" giga 1E+09
"M" mega 1E+06
"k" kilo 1E+03
"h" hecto 1E+02
da or "e"
deka (note: e is
not a standard SI
prefix)
1E+01
"d" deci 1E-01
"c" centi 1E-02
"m" milli 1E-03
"u"
micro (note: this
is u, not the
standard SI )
1E-06
"n" nano 1E-09
"p" pico 1E-12
"f" femto 1E-15
"a" atto 1E-18
"z" zepto 1E-21
"y" yocto 1E-24
The prefix e for 10
1
is nonstandard and included for backward compatibility with legacy
applications and documents.
Rationale: These are the standard SI unit prefixes, with two exceptions: micro and deka. Officially
the prefix for micro is , but on many systems this is difficult to type and/or see, and it is not even
available in some systems, so the traditional (and universally-used) substitution of u is used here
instead ([UNIFIED] does this too). Older spreadsheet implementations only permitted the use of the
nonstandard prefix "e" for deka (10
1
), even though da is easily supported by common character
sets. This specification adds support for the standard SI prefix da to fully support SI; for
interoperability with legacy applications and documents it also permits the use of the legacy e
prefix.
100414201 29 May 2010
Excel 2003, Lotus 1-2-3, and Corel Word Perfect (Quattro Pro) 12 do not support the standard SI
prefixes Z, Y, z, and y. OpenOffice.org 2.1 and Gnumeric 1.4 do support the standard SI prefixes Z,
Y, z, and y. They have been included as required prefixes because they are standard SI prefixes,
are useful, and are already supported by some implementations. In short, we try to support standard
SI prefixes as much as possible within a narrow character set.
No spreadsheet applications currently implement the binary prefixes, but since they are a relatively
recent standard this is not surprising.
Only some unit symbols are required to support prefixes, and other unit symbols should not support
the prefixes. So "km" (kilometers) must be supported, but "kmi" (kilomiles) should not be. Reason 1:
If app A accepts a "kmi", but app B doesn't, we have an interoperability problem. Reason 2: If we
accept prefixes everywhere, there's a GREATLY increased probability of future problems with a unit
suddenly changing its meaning (because some prefixed form in an earlier version suddenly conflicts
with a new unit name). E.G., if in the future we added a new unit called the "kmi", it would conflict
with a current "kilomile". It's best to avoid this. Reason 3: Existing spreadsheet applications enforce
this restriction (such as Excel and Gnumeric), as do other systems such as [UNIFIED]. Note that
this specification identifies with specificity which units must support the prefixes; a specification
must be clear to be useful.
Informally, sometimes K is used for k or ki (see below). But this is not technically correct; by
international standards, only k is 1000 and only ki is 1024. There seemed to be no strong need
to support these informal prefixes (including for interoperability), so CONVERT is not guaranteed to
support them.
Note: Implementors must beware of the interaction of powers and prefixes. For example, 3 km
2
is
equal to 3,000,000 m
2
and not to 3000 m
2
or 9,000,000 m
2
.
The unit names marked with in the unit symbol table above (see the Information group) shall also
support the following binary prefixes per IEC 60027-2:
Table 28 - Binary prefixes for use in CONVERT
Binary Unit
Prefix
Description Prefix Value Derived from
"Yi" yobi 2^80 = 1 208 925 819 614 629 174 706 176 yotta
"Zi" zebi 2^70 = 1 180 591 620 717 411 303 424 zetta
"Ei" exbi 2^60 = 1 152 921 504 606 846 976 exa
"Pi" pebi 2^50 = 1 125 899 906 842 624 peta
"Ti" tebi 2^40 = 1 099 511 627 776 tera
"Gi" gibi 2^30 = 1 073 741 824 giga
"Mi" mebi 2^20 = 1 048 576 mega
"ki" kibi 2^10 = 1024 kilo
Note: These binary prefixes are per IEC 60027-2/IEEE 1541. The second edition of 60027-2 didn't
include Zi or Yi, but the third edition added these obvious extensions. The expectation is that
these binary prefixes would only be used for information units such as bit and byte, but these
prefixes are very useful in such cases. Binary prefixes are important; the confusion between binary
prefixes and decimal prefixes has led to litigation in multiple court cases. Legally, SI prefixes are
only base 10. When computers were less capable, the difference between binary prefixes and
100414201 29 May 2010
decimal prefixes was not significant, but the difference has become greater as computers have
become more capable. For example, 100 TB is approximately the same as 90.9 TiB. The binary
prefix value is shown here without being superscripted, because superscripting inside a table might
result in this key term being too small to be easily read.
In the case where there is a naming conflict (a unit name with a prefix is the same as an unprefixed
name), the unprefixed name shall take precedence.
Rationale: Without this rule, some naming conflicts would occur, particularly hh (hoursepower-hour
and hectohorsepower). If p is accepted for Pascal, then we would also have "hp" (horsepower and
hectoPascals). Also, pc is parsec or pico-calories. This is easily implemented, e.g., compare the
unit against a unit name first, and only when that fails should a prefix be looked for. Hectopascals
are in use, but since their standard abbreviation is hPa, this causes no real problem.
Note: The format is specifically designed so that this probable extension would be easy to do.
Evaluators may implement this conversion by first converting to some SI unit (e.g., meter and
kilogram), and then convert again to the final unit.
anchor:CONVERT
Rationale: This permission enables simple implementations. Implementations which take this
approach will in some cases have a very small roundoff error when converting between pairs of non-
SI-based units. This first A then B might be implemented by a precalculated table, but if it's not
exact the result is the same. By being explicit about SI units, we ensure that if there's a trade-off at
all, the best accuracy always goes to the SI units (which is what the most accurate measurements
are typically measured with anyway). This is merely a permission; implementations may do better.
Test Cases:
=CONVERT(1; "ft";"in") 12
1 foot is 12 inches. Conversion between units might
involve an intermediate SI unit in some
implementations, and such round-off error is considered
acceptable.
=CONVERT(1; "in";"cm") 2.54
1 inch is 2.54 cm. The result is exact, because this
needs to be represented as accurately as the underlying
numerical model permits
=CONVERT(5; "m";"mm") 5000 5 meters is 5000 millimeters
=CONVERT(100; "C";"F") 212
212 degrees F is 100 degrees C. Note that this is not
simply a multiplicative relationship. Since internally this
is (100/5*9+32), where 100/5 is exactly 20, this result
needs to be exact even on floating-point
implementations
=CONVERT(2; "Ym";"Zm") 100 Must support Y and Z prefixes.
=CONVERT(20; "F";"m") Error Different groups produce an error.
=CONVERT(1000;"qt";"l") 946.5588641 Quart is U.S. customary, liquid measure
=CONVERT(1000;"tbs";"l") 14.78998225
Tablespoon uses U.S. customary historic definition
note that there are many other definitions
=CONVERT(1000;"tsp";"l") 4.929994084 Teaspoon uses U.S. customary historic definition note
100414201 29 May 2010
that there are many other definitions
=CONVERT(1;"das";"sec") 10
Does it support both s and sec for second? Does it
support da as the SI standard deka prefix?
=CONVERT(1;"ar";"m^2") 100 A hectare (ar) is 100 square meters.
=CONVERT(1;"cal";"J") 4.18680.0001 "cal" is an International Table (IT) calorie, 4.1868 J.
=CONVERT(1;"lbf";"N")
4.4482220.0000
01
Converting pound-force to Newtons
=CONVERT(1;"HP";"W") 745.7010.001 Horsepower to Watts
=CONVERT(1;"Mibyte";"bit"
)
8388608 Converts bytes to bits, and tests binary prefixes
=CONVERT(1;"T";"ga") 10000 Tesla to Gauss
=CONVERT(1;"lbm";"g")
453.592370.000
01
International pound mass (avoirdupois) to grams. (This
is actually exact.)
=CONVERT(1;"uk_ton";"lbm
")
22400.001
Imperial ton, aka long ton, "deadweight ton", or "weight
ton", is 2240 lbm.
=CONVERT(1;"psi";"Pa") 6894.760.01 Pounds per square inch to Pascals.
=CONVERT(60;"mph";"km/
h")
96.560640.0000
1
Miles per hour to kilometers per hour.
=CONVERT(1;"day";"s") 864000.001
Day to seconds. Note: This test uses the international
standard abbreviation for second (s), not the
abbreviation traditionally used in spreadsheets (sec);
both s and sec must be supported.
=CONVERT(1;"qt";"L")
0.9463529460.0
001
Quart (U.S. customary liquid measure) to liter. This is
0.946352946 liters,
See also EUROCONVERT
Rationale: A simple implementation of this function might convert any value into some common
value (e.g., all lengths into meters) and then reconvert it into the final value. A more accurate
implementation would have exact conversions between any pair, or at least try to avoid converting
between SI and English (including U.S. and Imperial) systems unnecessarily which often induces
rounding errors. The test cases are written so that simple implementations that use an SI unit as
their common value will be acceptable.
This table does not test all of the unit symbols or all prefixes, though a compliant application would
implement them as specified. Doing so would require a much longer table, one that would probably
not significantly improve the clarity of this specification. However, all of the unit groups, as well as
some of the most likely errors, are represented.
6.16.19 COS
Summary: Return the cosine of an angle specified in radians.
Syntax: COS( Number N )
100414201 29 May 2010
Returns: Number
Constraints: None
Semantics: Computes the cosine of an angle specified in radians.
cos N=1
N
2
2!
+
N
4
4!
N
6
6!
+...
anchor:COS
Test Cases:
COS(0) 1
COS(0) is 1 require this result to be exact, since documents
may depend on it.
=COS(PI()/4)*2/SQR
T(2)
1 cosine of PI()/4 radians is SQRT(2)/2.
=COS(PI()/2) 0
cosine of PI()/2 radians is 0; the test here gives a little "wiggle
room" for computational inaccuracies.
See also ACOS, RADIANS, DEGREES
6.16.20 COSH
Summary: Return the hyperbolic cosine of the given hyperbolic angle
Syntax: COSH( Number N )
Returns: Number
Constraints: None
Semantics: Computes the hyperbolic cosine of a hyperbolic angle. The hyperbolic cosine is an
analog of the ordinary (circular) cosine. The points (cosh t, sinh t) define the right half of the
equilateral hyperbola, just as the points (cos t, sin t) define the points of a circle.
cosh( N )=
e
N
+e
N
2
anchor:COSH
Test Cases:
=COSH(0) 1 Cosh(0) is 0
=COSH(1)
1.54308063
48
=COSH(EXP(1))
7.61012513
866
100414201 29 May 2010
See also ACOSH, SINH, TANH
6.16.21 COT
Summary: Return the cotangent of an angle specified in radians
Syntax: COT( Number N )
Returns: Number
Constraints: None
Semantics: Computes the cotangent of an angle specified in radians.
COT(x) = 1 / TAN(x)
anchor:COT
Test Cases:
=COT(PI()/4.0) 1 cotangent of PI()/4.0 radians.
=COT(PI()/2.0) 0
cotangent of PI()/2 radians. Not the same as
TAN.
=COT(0) Error COT(0) = 1/TAN(0) = 1/0, a division by zero
See also ACOT, TAN, RADIANS, DEGREES, SIN, COS
6.16.22 COTH
Summary: Return the hyperbolic cotangent of the given hyperbolic angle
Syntax: COTH( Number N )
Returns: Number
Constraints: N<>0
Semantics: Computes the hyperbolic cotangent of a hyperbolic angle. The hyperbolic cotangent is
an analog of the ordinary (circular) cotangent.
coth( N )=
1
tanh( N )
=
cosh( N )
sinh( N)
=
e
N
+e
N
e
N
e
N
anchor:COTH
Test Cases:
=COTH(1)
1.31303528
5
=COTH(EXP(1))
1.00874693
100414201 29 May 2010

See also ACOSH, SINH, TANH
6.16.23 CSC
Summary: Return the cosecant of an angle specified in radians.
Syntax: CSC( Number N )
Returns: Number
Constraints: None
Semantics: Computes the cosecant cosine of an angle specified in radians. Equivalent to:
1/SIN(N)
anchor:CSC
Test Cases:
=CSC(PI()/2) 1 Exists
See also SIN
6.16.24 CSCH
Summary: Return the hyperbolic cosecant of the given angle specified in radians
Syntax: CSCH( Number N )
Returns: Number
Constraints: None
Semantics: Computes the hyperbolic cosecant of a hyperbolic angle. This is equivalent to:
1/SINH(N)
anchor:CSCH
Test Cases:
=CSCH(PI()/2) 1 Function exists
See also SINH, CSCH
6.16.25 DEGREES
Summary: Convert radians to degrees.
Syntax: DEGREES( Number N )
100414201 29 May 2010
Returns: Number
Constraints: None
Semantics: Converts a number in radians into a number in degrees. DEGREES(N) is equal to
N*180/PI().
anchor:DEGREES
Test Cases:
=DEGREES(PI()) 180 PI() radians is 180 degrees.
See also RADIANS, PI
6.16.26 DELTA
Summary: Report if two numbers are equal, returns 1 if they are equal.
Syntax: DELTA( Number X [ ; Number Y = 0 ] )
Returns: Number
Constraints: None
Semantics: If X and Y are equal, return 1, else 0. Y is set to 0 if omitted.
anchor:DELTA
Test Cases:
=DELTA(2;3) 0 Different numbers are not equal
=DELTA(2;2) 1 Same numbers are equal
=DELTA((1/
[.B5])*[.B5];1)
1 Same numbers equal
=DELTA(0) 1 0 equal to default 0
See also Infix operator =
Note: DELTA may be needed to compare two values and return a numeric result. DELTA returns 0 if
no match, 1 if match, which is important on systems with distinct Logical types because on such
systems, the result of 1=TRUE() is FALSE (e.g., in Excel 2003).
6.16.27 ERF
Summary: Calculates the error function.
Syntax: ERF( Number z0 [ ; Number z1 ] )
Returns: Number
100414201 29 May 2010
Constraints: None
Semantics: With a single argument, returns the error function of z0:
ERF (Z0 )=
2
.
(n)
0
Z0
e
t
2
dt
With two arguments, returns
ERF (Z0 ; Z1)=
2
.
(n)
Z0
Z1
e
t
2
dt
anchor:ERF
Test Cases:
=ERF(0.5) 0.520500
=ERF(0.1) 0.112463
=ERF(0.1; 0.5) 0.408037
=ERF(0.1)-ERF(0.5) -0.408037 ERF(z0,z1) equals ERF(z1) - ERF(z0)
See also ERFC
6.16.28 ERFC
Summary: Calculates the complementary error function.
Syntax: ERFC( Number z )
Returns: Number
Constraints: None
Semantics: returns the complementary error function of z: ERFC(z) = 1 ERF(z)
anchor:ERFC
Test Cases:
=ERFC(0.1)-(1-
ERF(0.1))
0 ERFC(z) = 1 ERF(z)
=ERFC(3) 2.2090e-5
ERFC is typically more accurate than 1-ERF for
larger values of z.
See also ERF
100414201 29 May 2010
6.16.29 EUROCONVERT
Summary: Converts a Number, representing a value in one European currency, to an equivalent
value in another European currency, according to the fixed conversion rates defined by the Council
of the European Union.
Syntax: EUROCONVERT( Number N ; Text From ; Text To [ ; Logical FullPrecision = FALSE() [ ;
Integer TriangulationPrecision ] ] )
Returns: Currency
Constraints: From and To shall be known to the evaluator. TriangulationPrecision shall be >= 3, if
not omitted.
If an evaluator does not support the parameters FullPrecision and TriangulationPrecision,
FullPrecision should be assumed to be false.
Note: Gnumeric 1.4 supports only 3 parameters and calculates as if FullPrecision was True.
Gnumeric developers agreed to change implementation.
Semantics: Returns the given money value of a conversion from From currency into To currency.
Both From and To shall be the official ISO 4217 abbreviation for the given currency; note that these
are in upper case, but the function accepts lower case or mixed case as well. If From and To are
equal currencies, the value N is returned, no precision or triangualation is applied.
The function shall use the rates of exchange as set by the European Commission, as follows:
Table 29 - EUROCONVERT
From To Rate Currency Decimals
"EUR" "ATS" 13.7603 Austrian Schilling 2
"EUR" "BEF" 40.3399 Belgian Franc 0
"EUR" "DEM" 1.95583 German Mark 2
"EUR" "ESP" 166.386 Spanish Peseta 0
"EUR" "FIM" 5.94573 Finnish Markka 2
"EUR" "FRF" 6.55957 French Franc 2
"EUR" "IEP" 0.787564 Irish Pound 2
"EUR" "ITL" 1936.27 Italian Lira 0
"EUR" "LUF" 40.3399 Luxembourg Franc 0
"EUR" "NLG" 2.20371 Dutch Guilder 2
"EUR" "PTE" 200.482 Portuguese Escudo 2
"EUR" "GRD" 340.750 Greek Drachma 2
"EUR" "SIT" 239.640 Slovenian Tolar 2
EUR MTL 0.429300 Maltese Lira 2
EUR CYP 0.585274 Cypriot Pound 2
100414201 29 May 2010
From To Rate Currency Decimals
"EUR" "SKK" 30.1260 Slovak Koruna 2
As new member countries adopt the Euro, new conversion rates will become active and evaluators
may add them using the respective ISO 4217 codes and fixed rates as defined by the European
Council, on the basis of a European Commission proposal.
Note:
The European Commission's Euro entry page is http://ec.europa.eu/euro/
The conversion rates and triangulation rules are available at
http://ec.europa.eu/economy_finance/euro/adoption/conversion/index_en.htm with links to the
European Council Regulation legal documents at the http://eur-lex.europa.eu/ European Union law
database server.
If FullPrecision is omitted or False, the result is rounded according to the decimals of the To
currency. If FullPrecision is True the result is not rounded.
If TriangulationPrecision is given and >=3, the intermediate result of a triangular conversion
(currency1,EUR,currency2) is rounded to that precision. If TriangulationPrecision is omitted, the
intermediate result is not rounded. Also if To currency is EUR, TriangulationPrecision precision is
used as if triangulation was needed and conversion from EUR to EUR was applied.
anchor:EUROCONVERT
Test Cases:
=EUROCONVERT(100
;"DEM";"EUR";TRUE())
51.1291881196
Convert German Mark into Euro, full
precision.
=EUROCONVERT(100
;"DEM";"EUR")
51.13
Convert German Mark into Euro,
rounded.
=EUROCONVERT(100
;"DEM";"ATS";FALSE())
703.55
Convert German Mark into Austrian
Schilling, rounded.
=EUROCONVERT(100
;"DEM";"ATS";TRUE())
703.552967282
Schilling, full precision.
=EUROCONVERT(100
;"DEM";"ATS";TRUE();
5)
703.552993157
Schilling, full precision and with
triangulation precision 5.
See also CONVERT
Note: This is simply called CONVERT in OOo 2.0.1, with 3 parameters but without triangulation.
OOo 2.0.1's CONVERT_ADD does the job of the CONVERT function defined in this document.
Gnumeric supports EUROCONVERT with 3 parameters. Excel has EUROCONVERT with 5
parameters.
TODO: EUROCONVERT is so-named because these are relatively fixed conversions. It might be
useful to have a CONVERT_MONEY function that can do lookups of tables, invoking
EUROCONVERT in cases where it's appropriate. However, unless there's an existing
implementation, that seems appropriate to add to a future version of this specification.
100414201 29 May 2010
6.16.30 EVEN
Summary: Rounds a number up to the nearest even integer. Rounding is away from zero.
Syntax: EVEN( Number N )
Returns: Number
Constraints: None
Semantics: Returns the even integer whose sign is the same as N's and whose absolute value is
greater than or equal to the absolute value of N.
anchor:EVEN
Rationale: There's no need to discuss what happens if N is not a number in this definition; that is
handled in the Conversion to Number section.
Test Cases:
=EVEN(6) 6 Positive even integers remain unchanged.
=EVEN(-4) -4 Negative even integers remain unchanged.
=EVEN(1) 2 Non-even positive integers round up.
=EVEN(0.3) 2 Positive floating values round up.
=EVEN(-1) -2 Non-even negative integers round down.
=EVEN(-0.3) -2 Negative floating values round down.
=EVEN(0) 0 Since zero is even, EVEN(0) returns zero.
See also ODD
6.16.31 EXP
Summary: Returns e raised by the given number.
Syntax: EXP( Number X )
Returns: Number
Constraints: None
Semantics: Computes
e
X
=1+
X
1!
+
X
2
2!
+
X
3
3!
+
X
n
n!
+...
anchor:EXP
Note: Test case 3 implies a very minimal precision requirement for e (i.e. Exp(1)), but this is a trivial
requirement and clearly higher accuracy is better.
Test Cases:
100414201 29 May 2010
=EXP(0) 1 Anything raised to the 0 power is 1.
=EXP(LN(2)) 2
The EXP function is the inverse of the LN
function.
=EXP(1)
2.71828182
845904523
536
The value of the natural logarithm e.
See also LOG, LN
6.16.32 FACT
Summary: Return factorial (!).
Syntax: FACT( Integer F )
Returns: Number
Constraints: F >= 0
Semantics: Return the factorial
F !=F(F1)( F2)... 1
F(0)=F(1)=1.
anchor:FACT
Test Cases:
=FACT(0) 1 Factorial of 0 is 1
=FACT(-1) Error Requires F >= 0
See also Infix Operator "*", GAMMA
6.16.33 FACTDOUBLE
Summary: Returns double factorial (!!).
Syntax: FACTDOUBLE( Integer F )
Returns: Number
Constraints: F >= 0
100414201 29 May 2010
Semantics: Return
F !=F(F2)(F4)...1
Double factorial is computed by multiplying every other number in the 1..N range, with N always
being included.
anchor:FACTDOUBLE
Test Cases:
=FACTDOUBLE(0) 1 Factorial of 0 is 1
=FACTDOUBLE(1) 1 Factorial of 1 is 1
=FACTDOUBLE(7) 105 7*5*3=105
=FACTDOUBLE(6) 48 6*4*2 = 48
=FACTDOUBLE(-1) Error Requires F >= 0
See also Infix Operator "*", GAMMA, FACT
6.16.34 GAMMA
Summary: Return gamma function value.
Syntax: GAMMA( Number N )
Returns: Number
Constraints: N<>0 and N not a negative integer.
Semantics: Return
(N) =
t
N1
e
t
dt
with (N+1) = N * (N). Note that for non-negative integers N, (N+1) = N! = FACT(N). Note that
GAMMA can accept non-integers.
anchor:GAMMA
Test Cases:
=GAMMA(1) 1 GAMMA(1) is 1
=GAMMA(1.1
0)
0.951351e
-5
GAMMA(1.1) is
0.95135 to first 5 digits
=GAMMA(1.5
0)
0.886231e
-5
GAMMA(1.5) is
0.88623 to first 5 digits
Note: Source of correct values for GAMMA(1.1) and GAMMA(1.5) is the CRC Handbook of
Chemistry and Physics, 63
rd
edition, Page A-106.
100414201 29 May 2010
Note: Calculators and the Gamma Function (http://www.rskey.org/gamma.htm) by Viktor T. Toth
discusses how to implement the gamma function.
See also FACT
Note: This is included because FACT cannot portably provide this functionality.
6.16.35 GAMMALN
Summary: Returns the natural logarithm of the GAMMA function.
Syntax: GAMMALN( Number X )
Returns: Number
Constraints: For each X, X > 0
Semantics: Returns the same value as =LN(GAMMA(X))
anchor:GAMMALN
Test Cases:
=GAMMALN(1) 0 GAMMALN of 1 is 0.
=GAMMALN(2) 0 GAMMALN of 2 is 0.
=GAMMALN(3) 0.6931471806 GAMMALN of 3.
=GAMMALN(1.5) -0.1207822376 GAMMALN of 1.5 - negative.
See also GAMMA, FACT
6.16.36 GCD
Summary: Returns the greatest common divisor (GCD)
Syntax: GCD( { NumberSequenceList X }+

)
Returns: Number
Constraints: For all a in X: INT(a) >= 0 and for at least one a in X: INT(a)>0
Semantics: Return the largest integer N such that for every a in X: INT(a) is a multiple of N.
Note: If for all a in X: INT(a)=0 the return value is implementation-defined but is either an Error or 0.
anchor:GCD
Test Cases:
=GCD(5;15;25) 5 Can handle more than two parameters
=GCD(2;3) 1 Values that
100414201 29 May 2010
=GCD(18;24) 6
=GCD(18.1;24.1) 6 Fractions have INT first.
=GCD(18.9;24.9) 6 Fractions have INT first
=GCD(7) 7 GCD of one number is itself
=GCD(5;0) 5 GCD of a number and 0 is the number.
=GCD(0;0) 0 GCD of zeros only is 0.
=GCD(-2;3) Error Negative numbers are not supported
See also LCM
Note: The GCD function is often implemented using the Euclidean algorithm, one of the world's
oldest algorithms.
Note: OpenOffice.org 2.0.3 considers the full number, it computes GCD(1.1;2.2) as 1.1, and
GCD(18.1;24.1) as 7.11E-015. It has both a GCD and a GCD_ADD, where GCD_ADD applies INT()
first. However, in January 2007, OpenOffice.org implementors agreed in OpenFormula discussions
to change GCD() to apply INT() to its arguments first, making the function compatible with other
implementations. Thus, this is another example of standards efforts between multiple suppliers
resulting in a more compatible, agreed-on definition.
6.16.37 GESTEP
Summary: Returns 1 if a number is greater than or equal to another number, else returns 0.
Syntax: GESTEP( Number X [ ; Number Step = 0 ] )
Returns: Number
Semantics: Number X is tested against number Step. If greater or equal 1 is returned, else 0. The
second parameter is assumed 0 if omitted. If one of the parameters is not a Number, the function
results in an Error.
anchor:GESTEP
Test Cases:
=GESTEP(2;1) 1
=GESTEP(-1;-2) 1 Negative arguments are valid
=GESTEP(1) 1 Second parameter assumed 0 if omitted
=GESTEP(-2;1) 0
=GESTEP(3;3) 1 Number identical to step value.
=GESTEP(1.3;1.2) 1 Floating point values where X is greater than Step.
=GESTEP(-2;"xxx") Error "xxx" is not a number
100414201 29 May 2010
=GESTEP("xxx";-2) Error "xxx" is not a number
See also
6.16.38 LCM
Summary: Returns the least common multiplier
Syntax: LCM( { NumberSequenceList X }
+
)
Returns: Number
Constraints: For all in X: INT(X)=X, X >= 0
Semantics: Return the smallest integer that is the multiple of the given values. Each value has INT
applied to it first. Note that if given two numbers, ABS(a*b)=LCM(a;b)*GCD(a;b).
anchor:LCM
Test Cases:
=LCM(5;15;25) 75 LCM accepts 3 or more numbers.
=LCM(2;3) 6
=LCM(18;12) 36
=LCM(18.1;12.1) 36
=LCM(18.9;12.9) 36
=LCM(7) 7
=LCM(5;0) 0 If any argument is 0 the result is 0.
=LCM(-2;4) Error
See also GCD
Note: OpenOffice.org 2.0.3 accepts non-integers and handles them specially, but its implementors
have agreed to change this. See GCD for more information.
6.16.39 LN
Summary: Return the natural logarithm of a number.
Syntax: LN( Number X )
Returns: Number
Constraints: X>0
Semantics: Computes the natural logarithm (base e) of the given number.
100414201 29 May 2010
ln x=2
|
x1
x+1
+
1
3
(
x1
x+1
)
3
+
1
5
(
x1
x+1
)
5
+...
anchor:LN
Test Cases:
=LN(1) 0 The logarithm of 1 (in any base) is 0.
=LN(EXP(1)) 1 The natural logarithm of e is 1.
=LN(20)
2.99573227
4
Trivial test
=LN(0.2)
-
1.60943791
2
This tests a value between 0 and 0.5. Values in this domain
are valid, but implementations that compute LN(x) by blindly
summing the series (1/n)((x-1)/x)^n won't get this value
correct, because that series requires x > 0.5.
=LN(0) Error The argument must be greater than zero.
=LN([.B7]) Error The natural logarithm of a non-number gives an error.
See also LOG, LOG10, POWER, EXP
6.16.40 LOG
Summary: Return the logarithm of a number in a specified base.
Syntax: LOG( Number N [ ; Number Base = 10 ] )
Returns: Number
Constraints: N > 0
Semantics: Computes the logarithm of a number in the specified base. Note that if the base is not
specified, the logarithm base 10 is returned.
anchor:LOG
Test Cases:
=LOG(1; 10) 0 The logarithm of 1 (in any base) is 0.
=LOG(1;EXP(1)) 0 The natural logarithm of 1 is 0.
=LOG(10;10) 1 The base 10 logarithm of 10 is 1.
=LOG(10) 1 If the base is not specified, base 10 is assumed.
=LOG(8*8*8;8) 3 Log base 8 of 8^3 should return 3.
=LOG(0;10) Error The argument must be greater than zero.
100414201 29 May 2010
See also LOG10, LN, POWER, EXP
Note: OOo2 requires the base for log, instead of allowing it to be optional. Excel, etc. consider them
optional. Making LOG's second argument optional will require a change to OOo.
6.16.41 LOG10
Summary: Return the base 10 logarithm of a number.
Syntax: LOG10( Number N )
Returns: Number
Constraints: N > 0
Semantics: Computes the base 10 logarithm of a number.
anchor:LOG10
Test Cases:
=LOG10(1) 0 The logarithm of 1 (in any base) is 0.
=LOG10(10) 1 The base 10 logarithm of 10 is 1.
=LOG10(100) 2 The base 10 logarithm of 100 is 2.
=LOG10(0) Error The argument must be greater than zero.
=LOG10("H") Error The logarithm of a non-number gives an error.
See also LOG, LN, POWER, EXP
6.16.42 MOD
Summary: Return the remainder when one number is divided by another number.
Syntax: MOD( Number a ; Number b )
Returns: Number
Constraints: b != 0
Semantics: Computes the remainder of a/b. The remainder has the same sign as b.
anchor:MOD
Test Cases:
=MOD(10;3) 1 10/3 has remainder 1.
100414201 29 May 2010
=MOD(2;8) 2 2/8 is 0 remainder 2.
=MOD(5.5;2.5) 0.5 The numbers need not be integers.
=MOD(-2;3) 1 The location of the sign matters.
=MOD(2;-3) -1 The location of the sign matters.
=MOD(-2;-3) -2 The location of the sign matters.
=MOD(10;0) Error Division by zero is not allowed
Note: MOD with negative numbers is tricky. The tests for MOD(-2;3), MOD(2;-3), and MOD(-2;-3)
work with Gnumeric, OOo2, and Excel 2002 as shown. KSpread 1.4.2 also computes MOD(-2;3) as
1. However, KSpread 1.4.2 (on Fedora Core 4) computed MOD(-2;-3) as -5 (not -1), and MOD(2;-3)
computes as 2 (not -1). On January 9, 2006, KSpread developer Tomas Mecir announced that
KSpread's development version had been changed, and the next release of KSpread would
produce the same results with these other negative values.
See also Infix Operator "/", QUOTIENT
6.16.43 MULTINOMIAL
Summary: Returns the multinomial for the given values.
Syntax: MULTINOMIAL( { NumberSequence A }
+
)
Returns: Number
Constraints: None
Semantics: Returns the multinomial of the sequence A = (a1, a2, ..., an). Multinomial is defined as
FACT(a1+a2+...+an) / (FACT(a1)*FACT(a2)*...*FACT(an))
anchor:MULTINOMIAL
Test Cases:
=MULTINOMIAL(7) 1 One parameter always return 1
=MULTINOMIAL(4;2;3) 1260 Rounding down.
See also FACT
6.16.44 ODD
Summary: Rounds a number up to the nearest odd integer, where "up" means "away from 0".
Syntax: ODD( Number N )
Returns: Number
Constraints: None
100414201 29 May 2010
Semantics: Returns the odd integer whose sign is the same as N's and whose absolute value is
greater than or equal to the absolute value of N. In other words, any "rounding" is away from zero.
By definition, ODD(0) is 1.
anchor:ODD
Rationale: There's no need to discuss what happens if N is not a number in this definition; that is
handled in the Conversion to Number section.
Test Cases:
=ODD(5) 5 Positive odd integers remain unchanged.
=ODD(-5) -5 Negative odd integers remain unchanged.
=ODD(2) 3 Non-odd positive integers round up.
=ODD(0.3) 1 Positive floating values round up.
=ODD(-2) -3 Non-odd negative integers round down.
=ODD(-0.3) -1 Negative floating values round down.
=ODD(0) 1 By definition, ODD(0) is 1.
See also EVEN
6.16.45 PI
Summary: Return the approximate value of Pi.
Syntax: PI()
Returns: Number
Constraints: None.
Semantics: This function takes no arguments and returns the (approximate) value of pi. Evaluators
should use the closest possible numerical representation that is possible in their representation of
numbers.
anchor:PI
Note: The test case below implies a very minimal precision requirement for e (i.e. Exp(1)), but this is
a trivial requirement and clearly higher accuracy is better.
Test Cases:
=PI() 3.1415926
535897932
384626433
8327950
The approximate value of pi. Lots of
digits given here, in case the
implementation can actually handle that
many, but implementations are not
required to exactly store this many
digits. PI() should return the closest
possible numeric representation in a
100414201 29 May 2010
fixed-length representation.
See also SIN, COS
6.16.46 POWER
Summary: Return the value of one number raised to the power of another number.
Syntax: POWER( Number a ; Number b )
Returns: Number
Constraints: None
Semantics: Computes a raised to the power b.
POWER(0,0) is implementation-defined, but shall be one of 0,1, or an Error.
POWER(0,b), where b < 0, shall return an Error.
POWER(a,b), where a<=0 and INT(b)!=b, is implementation-defined.
anchor:POWER
Test Cases:
=POWER(10;0) 1 Anything raised to the 0 power is 1.
=POWER(2;8) 256 2^8 is 256.
See also LOG, LOG10, LN, EXP
6.16.47 PRODUCT
Summary: Multiply the set of numbers, including all numbers inside ranges
Syntax: PRODUCT( { NumberSequence N }
+
)
Returns: Number
Constraints: None
Semantics: Returns the product of the Numbers (and only the Numbers, i.e., not Text inside
ranges). This is equivalent to SUM except that it uses the * operator instead of +.
anchor:PRODUCT
Test Cases:
=PRODUCT(2;3;4) 24 Multiply all the numbers.
=PRODUCT(TRUE(
);2;3)
6 TRUE() is 1 if inline.
100414201 29 May 2010
=PRODUCT([.B4:.B
5])
6 2*3 is 6.
=PRODUCT([.B3:.B
6])
6
In level 2 and higher, conversion to NumberSequence ignores
Text (in B3) and Logical values (a TRUE() in B6).
=PRODUCT() 0 Product with no parameters returns 0
TBD: OOo 2.0 gives an Error when a non-Number is included in the list, e.g. product(2;3;"2").
Gnumeric seems to ignore non-Numbers, even if they can be converted to a Number, but does not
give an Error, e.g. product(2,3,"2") gives 6. Excel 2002 converts these in-line values to Numbers, so
product(2,3,"2") produces 12.
Note: Lotus1-2-3v9 gives an Error for PRODUCT().
See also SUM
6.16.48 QUOTIENT
Summary: Return the integer portion of a division.
Syntax: QUOTIENT( Number A ; Number B )
Returns: Number
Constraints: B <> 0
Semantics: Return the integer portion of a division.
anchor:QUOTIENT
Test Cases:
=QUOTIENT(10;5) 2
=QUOTIENT(14;5) 2
=QUOTIENT(-204;-23) 8
=QUOTIENT(-45;8) -5
=QUOTIENT(24;-5) -4
=QUOTIENT(21;-5) -4
=QUOTIENT(-14;5) -2
=QUOTIENT(5;0) Error
See also MOD
6.16.49 RADIANS
Summary: Convert degrees to radians.
Syntax: RADIANS( Number N )
100414201 29 May 2010
Returns: Number
Constraints: None
Semantics: Converts a number in degrees into a number in radians. RADIANS(N) is equal to
N*PI()/180.
anchor:RADIANS
Test Cases:
=RADIANS(180)/PI() 1 180 degrees is PI() radians.
See also DEGREES, PI
6.16.50 RAND
Summary: Return a random number between 0 (inclusive) and 1 (exclusive).
Syntax: RAND()
Returns: Number
Semantics: This function takes no arguments and returns a random number between 0 (inclusive)
and 1 (exclusive). Note that unlike most functions, this function will typically return different values
when called each time with the same (empty set of) parameters.
anchor:RAND
Note: Some random number generators are better than others. At this time there is no particular
requirement for how random the result needs to be. Implementors should typically avoid using built-
in random number generators provided by language libraries, because they are often extremely
poor algorithms.
Test Cases:
=RAND()>=0 True The random number must be [0,1[
=RAND()<1 True The random number must be [0,1[
See also RANDBETWEEN
6.16.51 RANDBETWEEN
Summary: Return a random integer number between A and B.
Syntax: RANDBETWEEN( Integer A ; Integer B )
Returns: Integer
Constraints: A <= B
100414201 29 May 2010
Semantics: The function returns a random integer number between A and B inclusive. Note that
unlike most functions, this function will often return different values when called each time with the
same parameters.
anchor:RANDBETWEEN
Test Cases:
=RANDBETWEEN(8;8) 8 If A=B, return A.
=RANDBETWEEN(5;15)>=5 True Must return value in range
=RANDBETWEEN(5;15)<=15 True Must return value in range
=RANDBETWEEN(15;5)>=5 True Must return value in range
=RANDBETWEEN(15;5)<=15 True Must return value in range
See also RAND
6.16.52 SEC
Summary: Return the secant of an angle specified in radians.
Syntax: SEC( Number N )
Returns: Number
Constraints: None
Semantics: Computes the secant cosine of an angle specified in radians. Equivalent to:
1/COS(N)
anchor:SEC
Test Cases:
=SEC(PI()/2) 1 Exists
See also SIN
6.16.53 SERIESSUM
Summary: Returns the sum of a power series.
Syntax: SERIESSUM( Number X ; Number N ; Number M ; Array Coefficients )
X: the independent variable of the power series.
N: the initial power to which X is to be raised.
M: the increment by which to increase N for each term in the series.
100414201 29 May 2010
Coefficients: a set of coefficients by which each successive power of the variable X is multiplied.
Returns: Number
Constraints:
All elements of Coefficients are of type Number.
X < > 0 if any of the exponents, which are generated from N and M, are negative.
Semantics: Returns a sum of powers of the number X.
With C being the number of coefficients the function is computed as:
SERIESSUM=
i =1
C
Coefficient
i
X
( N +(i 1)M)
If X=0 and all of the exponents are non-negative then
0
0
shall be set to 1 and
0
(exponent >0)
shall be
set to 0.
anchor:SERIESSUM
Test Cases:
=SERIESSUM(3;1;2;[.C51:.C57]) 33628062
6.16.54 SIGN
Summary: Return the sign of a number
Syntax: SIGN( Number N )
Returns: Number
Constraints: None
Semantics: If N < 0, returns -1; if N > 0, returns +1; if N == 0, returns 0.
anchor:SIGN
Test Cases:
=SIGN(-4) -1 N < 0 returns -1
=SIGN(4) 1 N > 0 returns +1
=SIGN(0) 0 N == 0 returns 0
See also ABS
Note: This is placed at level 2, not level 1, because Sheet To Go version 6 doesn't include this
function. It can be trivially implemented using IF for level 1.
100414201 29 May 2010
6.16.55 SIN
Summary: Return the sine of an angle specified in radians
Syntax: SIN( Number N )
Returns: Number
Constraints: None
Semantics: Computes the sine of an angle specified in radians.
sin( N )=N
N
3
3!
+
N
5
5!
N
7
7!
+...
anchor:SIN
Test Cases:
=SIN(0) 0
Sine of 0 is 0; this is required to be exact, since some
documents may depend on getting this identity exactly
correct.
=SIN(PI()/4.0)*2/SQRT(2) 1 sine of PI()/4 radians is SQRT(2)/2.
=SIN(PI()/2.0) 1 sine of PI()/2 radians is 1.
See also ASIN, RADIANS, DEGREES
6.16.56 SINH
Summary: Return the hyperbolic sine of the given hyperbolic angle
Syntax: SINH( Number N )
Returns: Number
Constraints: None
Semantics: Computes the hyperbolic sine of a hyperbolic angle. The hyperbolic sine is an analog of
the ordinary (circular) sine. The points (cosh t, sinh t) define the right half of the equilateral
hyperbola, just as the points (cos t, sin t) define the points of a circle.
sinh(N )=
e
N
e
N
2
anchor:SINH
Test Cases:
=SINH(0) 0 Sinh(0) is 0
=SINH(1)
1.17520119
36
100414201 29 May 2010
=SINH(EXP(1))
7.54413710
28
See also ASINH, COSH, TANH
6.16.57 SECH
Summary: Return the hyperbolic secant of the given angle specified in radians
Syntax: SECH( Number N )
Returns: Number
Constraints: None
Semantics: Computes the hyperbolic secant of a hyperbolic angle. This is equivalent to:
1/COSH(N)
anchor:SECH
Test Cases:
=SECH(0) 1 Function exists
See also SINH, CSCH
6.16.58 SQRT
Summary: Return the square root of a number
Syntax: SQRT( Number N )
Returns: Number
Constraints: N>=0
Semantics: Returns the square root of a non-negative number. This function shall produce an Error
if given a negative number; for producing complex numbers, see IMSQRT.
anchor:SQRT
Test Cases:
=SQRT(4) 2 The square root of 4 is 2.
=SQRT(-4) Error The argument must be non-negative
See also POWER, IMSQRT, SQRTPI
100414201 29 May 2010
6.16.59 SQRTPI
Summary: Return the square root of a number multiplied by pi.
Syntax: SQRTPI( Number N )
Returns: Number
Constraints: N>=0
Semantics: Returns the square root of a non-negative number after it was first multiplied by PI, that
is, SQRT(N*PI()). This function shall produce an Error if given a negative number; for producing
complex numbers, see IMSQRT.
anchor:SQRTPI
Test Cases:
=SQRTPI(1) 1.77245385 The square root of
=SQRTPI(2) 2.5066282746 The square root of 2
=SQRTPI(-4) Error The argument must be non-negative
See also POWER, SQRT, PI, IMSQRT
6.16.60 SUBTOTAL
Summary: Evaluates a function on a range.
Syntax: SUBTOTAL( Integer function ; NumberSequence sequence )
Returns: Number
Constraints: None
Semantics: Computes a given function on a number sequence. Function is denoted by the first
parameter: The difference from standard functions is that all members of the sequence are excluded
which:
include a call to SUBTOTAL in their formula
are in a row that is hidden by a table:visibility=filter attribute of the
<table:table-row> element.
are in a row that is hidden by a table:visibility=collapse attribute of the
<table:table-row> element if the function ID is one of 101...111.
Function Exclude hidden by filter Exclude hidden by filter or
collapsed
AVERAGE 1 101
COUNT 2 102
COUNTA 3 103
100414201 29 May 2010
MAX 4 104
MIN 5 105
PRODUCT 6 106
STDEV 7 107
STDEVP 8 108
SUM 9 109
VAR 10 110
VARP 11 111
anchor:SUBTOTAL
Test Cases:
=SUBTOTAL(1;7) 7 Average.
=SUBTOTAL(2;8) 1 Count.
See also SUM, AVERAGE
6.16.61 SUM
Summary: Sum (add) the set of numbers, including all numbers in ranges
Syntax: SUM( { NumberSequenceList N }
+
)
Returns: Number
Constraints: N != {}; Evaluators may evaluate expressions that do not meet this constraint.
Semantics: Adds Numbers (and only Numbers) together (see the text on conversions).
anchor:SUM
Test Cases:
=SUM(1;2;3) 6 Simple sum.
=SUM(TRUE();2;3) 6 TRUE() is 1.
=SUM([.B4:.B5]) 5 2+3 is 5.
See also AVERAGE
Note: The exact semantics of SUM() in Excel are defined in (Walkenbach, 2004, pg 705). Lotus 1-2-
3v9.8.1 does not accept SUM with no parameters.
100414201 29 May 2010
6.16.62 SUMIF
Summary: Sum the values of cells in a range that meet a criteria.
Syntax: SUMIF( ReferenceList|Reference R ; Criterion C [ ; Reference S ] )
Returns: Number
Constraints: Does not accept constant values as the range parameter.
Semantics: Sums the values of type Number in the range R or S that meet the Criterion C (4.11.7).
If S is not given, R may be a reference list. If S is given, R shall not be a reference list with more
than 1 references and an Error be generated if it was.
If the optional range S is included, then the values of S starting from the top left cell and matching
the geometry of R (same number of rows and columns) are summed if the corresponding value in R
meets the Criterion. The actual range S is not considered. If the resulting range exceeds the sheet
bounds, column numbers larger than the maximum column and row numbers larger than the
maximum row are silently ignored, no Error is generated for this case.
anchor:SUMIF
Test Cases:
=SUMIF([.B4:.B5];">2.5") 3
B4 is 2 and B5 is 3, so only B5 has a value greater than
2.5.
=SUMIF([.B3:.B5];[.B4]) 2 Test if a cell equals the value in [.B4].
=SUMIF("";[.B4]) Error Constant values are not allowed for the range.
=SUMIF([.B3:.B4];"7") 0 [.B3] is the string "7", but only numbers are summed.
=SUMIF([.B3:.B4];"7";
[.B4:.B5])
2
[.B3] is the string "7", but its match is mapped to [.B4] for
the summation.
=SUMIF([.B3:.B10];1+1) 2 The criteria can be an expression.
TBD: SUMIF([.B3:.B10];"7";[.B4:.B5]) produces 2 in Excel 2002 and OOo2, but Gnumeric returns a
0. The test is currently set to level 2 because of the difference. Are the strings ("7") being converted
to numbers before comparison in excel and OOo2? Or are they doing a string comparison? This
difference is also encountered in COUNTIF.
See also COUNTIF, SUM, Infix Operator "=", Infix Operator "<>", Infix Operator Ordered
Comparison ("<", "<=", ">", ">=")
6.16.63 SUMIFS
Summary: Sum the values of cells in a range that meet multiple criteria in multiple ranges.
Syntax: SUMIFS( Reference R ; Reference R1 ; Criterion C1 [ ; Reference R2 ; Any C2 ]... )
Returns: Number
100414201 29 May 2010
Semantics: Sums the value of cells in range R that meet the Criterion C1 in the reference range R1
and the Criterion C2 in the reference range R2, and so on (4.11.7). All reference ranges shall have
the same dimension and size, else an Error is returned. A logical AND is applied between each array
result of each selection; an entry is counted only if the same position in each array is the result of a
criteria match.
anchor:SUMIFS
See also COUNTIFS, SUMIF, Infix Operator "=", Infix Operator "<>", Infix Operator Ordered
Comparison ("<", "<=", ">", ">=")
6.16.64 SUMPRODUCT
Summary: Returns the sum of the products of the matrix elements.
Syntax: SUMPRODUCT( { ForceArray Array A }
+
)
Returns: Number
Constraints: All matrices shall have the same dimensions.
Semantics: Multiplies the corresponding elements of all matrices and returns the sum of them.
SUMPRODUCT( A
1
, A
2
,... , A
K
)=
m=1
M
n=1
N
(

k=1
K
a
k ,mn
)
where
a
k ,mn
denotes an element of the matrix
A
K
.
anchor:SUMPRODUCT
Test Cases:
=SUMPRODUCT([.B4:.C5]) 14 only one parameter gives us just the sum
=SUMPRODUCT([.B4:.C5];[.B4:.C5]) 54 = 4 + 9 + 16 + 25
=SUMPRODUCT([.B4:.C5];[.B4:.C5];
[.B4:.C5])
224 = 8 + 27 + 64 + 125
=SUMPRODUCT([.A41:.C43];
[.A41:.C43])
109 = 1 + 4 + 1 + 4 + 16 + 9 + 9 + 49 + 16
=SUMPRODUCT([.B4:.C5];
[.A41:.C43])
Error Matrices must have the same dimensions.
Note: OOo Calc is restricted to max. 30 parameters in this case.
6.16.65 SUMSQ
Summary: Sum (add) the set of squares of numbers, including all numbers in ranges
Syntax: SUMSQ( { NumberSequence N }
+
)
Returns: Number
100414201 29 May 2010
Constraints: N != {}; Evaluators may evaluate expressions that do not meet this constraint.
Semantics: Adds squares of Numbers (and only Numbers) together. See the text on conversions.
anchor:SUMSQ
Test Cases:
=SUMSQ(1;2;3) 14 Simple sum of squares.
=SUMSQ(TRUE();2
;3)
14 TRUE() is 1.
=SUMSQ([.B4:.B5]) 13 2*2+3*3 is 13.
6.16.66 SUMX2MY2
Summary: Returns the sum of the difference between the squares of the matrices A and B.
Syntax: SUMX2MY2( ForceArray Array A ; ForceArray Array B )
Returns: Number
Constraints: Both matrices shall have the same dimensions.
Semantics: Sums up the differences of the corresponding elements squares for two matrices.
SUMX2MY2( A , B)=
m=1
M
n=1
N
(
a
mn
2
b
mn
2
)
anchor:SUMX2MY2
Test Cases:
=SUMX2MY2([.B4:.C5];[.A41:.B42]) 29 2x2 matrices
=SUMX2MY2([.A41:.B42];[.B4:.C5]) -29 exchanged parameters
=SUMX2MY2([.A41:.C43];[.D41:.F43]) 71 3x3 matrices
=SUMX2MY2([.B4:.C5];[.A41:.C43]) Error Matrices must have the same dimensions.
6.16.67 SUMX2PY2
Summary: Returns the total sum of the squares of the matrices A and B.
Syntax: SUMX2PY2( ForceArray Array A ; ForceArray Array B )
Returns: Number
100414201 29 May 2010
Semantics: Sums up the squares of each element of the two matrices.
SUMX2PY2( A , B)=
m=1
M
n=1
N
(
a
mn
2
+b
mn
2
)
anchor:SUMX2PY2
Test Cases:
=SUMX2PY2([.B4:.C5];[.A41:.B42]) 79 2x2 matrices
=SUMX2PY2([.A41:.B42];[.B4:.C5]) 79 exchanged parameters
=SUMX2PY2([.A41:.C43];[.D41:.F43]) 147 3x3 matrices
=SUMX2PY2([.B4:.C5];[.A41:.C43]) Error Matrices must have the same dimensions.
6.16.68 SUMXMY2
Summary: Returns the sum of the squares of the differences between matrix A and B.
Syntax: SUMXMY2( ForceArray Array A ; ForceArray Array B )
Returns: Number
Semantics: Sums up the squares of the differences of the corresponding elements for two
matrices.
SUMXMY2( A , B)=
m=1
M
n=1
N
(
a
mn
b
mn
)
2
anchor:SUMXMY2
Test Cases:
=SUMXMY2([.B4:.C5];[.A41:.B42]) 7 2x2 matrices
=SUMXMY2([.A41:.B42];[.B4:.C5]) 7 exchanged parameters
=SUMXMY2([.A41:.C43];[.D41:.F43]) 141 3x3 matrices
=SUMXMY2([.B4:.C5];[.A41:.C43]) Error Matrices must have the same dimensions.
6.16.69 TAN
Summary: Return the tangent of an angle specified in radians
Syntax: TAN( Number N )
100414201 29 May 2010
Returns: Number
Constraints: None
Semantics: Computes the tangent of an angle specified in radians.
TAN(x) = SIN(x) / COS(x)
anchor:TAN
Test Cases:
=TAN(PI()/4.0) 1 tangent of PI()/4.0 radians.
See also ATAN, ATAN2, RADIANS, DEGREES, SIN, COS, COT
6.16.70 TANH
Summary: Return the hyperbolic tangent of the given hyperbolic angle
Syntax: TANH( Number N )
Returns: Number
Constraints: None
Semantics: Computes the hyperbolic tangent of a hyperbolic angle. The hyperbolic tangent is an
analog of the ordinary (circular) tangent. The points (cosh t, sinh t) define the right half of the
equilateral hyperbola, just as the points (cos t, sin t) define the points of a circle.
tanh( N )=
sinh( N )
cosh( N )
=
e
N
e
N
e
N
+e
N
anchor:TANH
Test Cases:
=TANH(0) 0 tanh(0) is 0
=TANH(1)
0.76159415
5955765
=TANH(-1)
-
0.76159415
5955765
=TANH(EXP(1))
0.99132891
58
See also ATANH, SINH, COSH, FISHERINV
100414201 29 May 2010
6.17 Rounding Functions
6.17.1 General
Rounding functions convert an arbitrary Number into an Integer.
Note: Typical implementations of rounding functions first round the internal number representation
to the nearest integer if it is numerically adjacent to it in the numerical representation, then they
perform rounding. Thus, INT((1/3)*3) becomes 1. Some of these functions have bizarre semantics.
6.17.2 CEILING
Summary: Round a number N up to the nearest multiple of the second parameter, significance.
Syntax: CEILING( Number N [ ; [ Number significance ] [ ; Number mode ] ] )
Returns: Number
Constraints: Both N and significance shall be numeric and have the same sign if not 0.
Semantics: Rounds a number up to a multiple of the second number. If significance is omitted or
an empty parameter (two consecutive ;; semicolons) it is assumed to be -1 if N is negative and +1 if
N is non-negative, making the function act like the normal mathematical ceiling function if mode is
not given or zero. If mode is given and not equal to zero, the amount of N is rounded away from
zero to a multiple of significance and then the sign applied. If mode is omitted or zero, rounding is
toward positive infinity; the number is rounded to the smallest multiple of significance that is equal-
to or greater than N. If any of the two parameters N or significance is zero, the result is zero.
Note: Many application user interfaces have a CEILING function with only two parameters, and
somewhat different semantics than given here (e.g., they operate as if there was a non-zero mode
value). These CEILING functions are inconsistent with the standard mathematical definition of
CEILING.
anchor:CEILING
Test Cases:
=CEILING(2; 1) 2 Rounding an integer returns the integer.
=CEILING(2; 3) 3 Round 2 up to the nearest multiple of 3.
=CEILING(2.5; 1) 3 Round 2.5 up to the next larger integer.
=CEILING(2.5; 2) 4 Round 2.5 up to the nearest multiple of 2.
=CEILING(2.5; 2.2) 4.4 Round 2.5 up to the nearest multiple of 2.2.
=CEILING(-2.5;1) Error Sign of number and significance must match.
=CEILING(-2.5; -1) -2
This is a problem case, different programs get different results.
Some get -3, rounding away from zero instead toward a ceiling.
=CEILING(-2.5; -3 Round away from zero if third parameter given and not 0.
100414201 29 May 2010
-1;1)
=CEILING(-2.5;0) 0 Rounding any value to a multiple of 0 results in 0.
=CEILING(0;-1) 0 Rounding 0 to any multiple results in 0.
=CEILING(-1.1) -1
Single-argument version works like standard mathematical
function.
See also FLOOR, INT
Note: In Gnumeric, Kspread and Excel, CEILING(-2.5;-1) gives -3, in OOo it gives -2. Since the
function is supposed to round up, -2 seems like the correct answer. This function follows the strange
round away from zero of Excel only if the third parameter is given.
Note: Kspread 1.5.0 does not pass the CEILING(x;0) test case and generates an Error instead.
Note: Excel 2003 has only a two-parameter CEILING, with very odd semantics that are different
from the standard mathematical meaning. In Excel, CEILING(-2.5; -1) gives -3, not -2. The definition
here requires that some applications translate their CEILING (and FLOOR).
6.17.3 INT
Summary: Rounds a number down to the nearest integer.
Syntax: INT( Number N )
Returns: Number
Constraints: None
Semantics: Returns the nearest integer whose value is less than or equal to N. Rounding is
towards negative infinity.
anchor:INT
Test Cases:
=INT(2) 2 Positive integers remain unchanged
=INT(-3) -3 Negative integers remain unchanged
=INT(1.2) 1 Positive floating values are truncated
=INT(1.7) 1 It doesnt matter if the fractional part is > 0.5
=INT(-1.2) -2 Negative floating values round towards negative infinity
=INT((1/3)*3) 1
Naive users expect INT to "correctly" make integers even if there are
limits on precision.
See also ROUND, TRUNC
6.17.4 FLOOR
Summary: Round a number N down to the nearest multiple of the second parameter, significance.
100414201 29 May 2010
Syntax: FLOOR( Number N [ ; [ Number significance ] [ ; Number mode ] ] )
Returns: Number
Constraints: Both N and significance shall be numeric and have the same sign.
Semantics: Rounds a number down to a multiple of the second number. If significance is omitted or
an empty parameter (two consecutive ;; semicolons) it is assumed to be -1 if N is negative and +1 if
N is non-negative, making the function act like the normal mathematical floor function if mode is not
given or zero. If mode is given and not equal to zero, the amount of N is rounded toward zero to a
multiple of significance and then the sign applied. Otherwise, it rounds toward negative infinity, and
the result is the largest multiple of significance that is less than or equal to N. If any of the two
parameters N or significance is zero, the result is zero.
Note: Many application user interfaces have a FLOOR function with only two parameters, and
somewhat different semantics than given here (e.g., they operate as if there was a non-zero mode
value). These FLOOR functions are inconsistent with the standard mathematical definition of
FLOOR.
anchor:FLOOR
Test Cases:
=FLOOR(2; 1) 2 Rounding an integer returns the integer.
=FLOOR(2.5; 1) 2 Round 2.5 down to the next smaller integer.
=FLOOR(5; 2) 4 Round 5 down to the nearest multiple of 2.
=FLOOR(5; 2.2) 4.4 Round 5 down to the nearest multiple of 2.2.
=FLOOR(-2.5;1) Error Sign of number and significance must match.
=FLOOR(-2.5; -1) -3
This is a problem case, different programs get different results.
Some get -2, rounding toward zero instead toward a floor.
=FLOOR(-2.5; -1;1) -2 Round toward zero if third parameter given and not 0.
=FLOOR(-2.5;0) 0 Rounding any value to a multiple of 0 results in 0.
=FLOOR(0;-1) 0 Rounding 0 to any multiple results in 0.
=FLOOR(-1.1) -2 Rounds down toward negative infinity with one argument
See also CEILING, INT
Note: In Gnumeric and Excel, FLOOR(-2.5;-1) gives -2, in OOo it gives -3. Since the function is
supposed to round down, -3 seems like the correct answer. Kspread FLOOR(-2.5) gives -3. This
function follows the strange round toward zero only if the third parameter is given.
Note: Kspread 1.5.0 implements FLOOR with only one parameter.
6.17.5 MROUND
Summary: Rounds the number to given multiple.
Syntax: MROUND( Number a ; Number b )
100414201 29 May 2010
Returns: Number
Constraints: None
Semantics: Returns the number X, for which the following holds: X/b=INT(X/b) (b divides X), and
for any other Y with the same property, ABS(Y-a)>=ABS(X-a). In case that two such X exist, the
greater one is the result. In less formal language, this function rounds the number a to multiples of
b.
anchor:MROUND
Test Cases:
=MROUND(1564;100) 1600 Rounding up.
=MROUND(1520;100) 1500 Rounding down.
=MROUND(1550;100) 1600 Exactly at .5, rounding up.
=MROUND(41.89;8) 40 Can round to any multiples.
See also ROUND
6.17.6 ROUND
Summary: Rounds the value X to the nearest multiple of the power of 10 specified by Digits.
Syntax: ROUND( Number X [ ; Number Digits = 0 ] )
Returns: Number
Constraints: None
Semantics: Round number X to the precision specified by Digits. The number X is rounded to the
nearest power of 10 given by 10
Digits
. If Digits is zero, or absent, round to the nearest decimal
integer. If Digits is non-negative, round to the specified number of decimal places. If Digits is
negative, round to the left of the decimal point by -Digits places. If X is halfway between the two
nearest values, the result shall round away from zero. Note that if X is a Number, and Digits <= 0,
the results will always be an integer (without a fractional component).
anchor:ROUND
Test Cases:
=ROUND(10.1; 0) 10 If b is not specified, round to the nearest integer.
=ROUND(9.8;0) 10 Round to nearest value (different than INT)
=ROUND(0.5; 0) 1 0.5 rounds up, away from zero.
=ROUND(1/3;0) 0 Round to the nearest integer.
=ROUND(1/3;1) 0.3 Round to one decimal place.
=ROUND(1/3;2) 0.33 Round to two decimal places.
100414201 29 May 2010
=ROUND(1/3;2.9) 0.33 If b is not an integer, it is truncated.
=ROUND(5555;-1) 5560 Round to the nearest 10.
=ROUND(-1.1; 0) -1 Negative number rounded to the nearest integer
=ROUND(-1.5; 0) -2 Negative number rounds away from zero
=ROUND(-1.5) -2 Default precision is 0
=ROUND(1.1) 1
=ROUND(9.8) 10
See also TRUNC, INT
Note: Excel 2003 requires both parameters. Many other implementations, such as OpenOffice.org,
make the second parameter optional (with a default of 0).
6.17.7 ROUNDDOWN
Summary: Rounds the value X towards zero to the number of digits specified by Digits
Syntax: ROUNDDOWN( Number X [ ; Integer Digits = 0 ] )
Returns: Number
Constraints: None
Semantics: Round X towards zero, to the precision specified by Digits. The number returned is a
multiple of 10
Digits
. If Digits is zero, or absent, round to the largest decimal integer smaller or equal
to X. If Digits is positive, round towards zero to the specified number of decimal places. If Digits is
negative, round towards zero to the left of the decimal point by -Digits places.
anchor:ROUNDDOWN
Test Cases:
=ROUNDDOWN(1.
45673; -2)
1.45
=ROUNDDOWN(1;
0)
1
=ROUNDDOWN(1) 1
=ROUNDDOWN(9;
1)
0
=ROUNDDOWN(9;
0)
9
=ROUNDDOWN(-
1.1)
-2
=ROUNDDOWN(- -2
100414201 29 May 2010
1.9)
See also TRUNC, INT, ROUND, ROUNDUP
6.17.8 ROUNDUP
Summary: Rounds the value X away from zero to the number of digits specified by Digits
Syntax: ROUNDUP( Number X [ ; Integer Digits = 0 ] )
Returns: Number
Constraints: None
Semantics: Round X away from zero, to the precision specified by Digits. The number returned is a
multiple of 10
Digits
. If Digits is zero, or absent, round to the smallest decimal integer larger or equal
to X. If Digits is positive, round away from zero to the specified number of decimal places. If Digits is
negative, round away from zero to the left of the decimal point by -Digits places.
anchor:ROUNDUP
Test Cases:
=ROUNDUP(1.4567
3; -2)
1.46
=ROUNDUP(1.1;0) 2
=ROUNDUP(1.9;0) 2
=ROUNDUP(1) 1
=ROUNDUP(9;1) 10
=ROUNDUP(9;0) 9
=ROUNDUP(-1.1) -1
=ROUNDUP(-1.9) -1
See also TRUNC, INT, ROUND, ROUNDDOWN
6.17.9 TRUNC
Summary: Truncate a number to a specified number of digits.
Syntax: TRUNC( Number a ; Number b )
100414201 29 May 2010
Returns: Number
Constraints: None
Semantics: Truncate number a to the number of digits specified by b. If b is zero, or absent,
truncate to a decimal integer. If b is positive, truncate to the specified number of decimal places. If b
is negative, truncate to the left of the decimal point. If b is not an integer, it is truncated.
anchor:TRUNC
Test Cases:
=TRUNC(10.1) 10 If b is not specified, truncate to the nearest integer.
=TRUNC(0.5) 0 Truncate rather than rounding.
=TRUNC(1/3;0) 0 Truncate to an integer.
=TRUNC(1/3;1) 0.3 Truncate to one decimal place.
=TRUNC(1/3;2) 0.33 Truncate to two decimal places.
=TRUNC(1/3;2.9) 0.33 If b is not an integer, it is truncated.
=TRUNC(5555;-1) 5550 Truncate to the nearest 10.
=TRUNC(-1.1) -1 Negative number truncated to an integer
=TRUNC(-1.5) -1 Negative number truncated to an integer
See also ROUND, INT
6.18 Statistical Functions
6.18.1 General
The following are statistical functions (functions that report information on a set of numbers). Some
functions that could also be considered statistical functions, such as SUM, are listed elsewhere.
6.18.2 AVEDEV
Summary: Calculates the average of the absolute deviations of the values in list.
Syntax: AVEDEV( { NumberSequenceList N }
+
)
Returns: Number
Constraints: None.
Semantics:
1
n
i=1
n
( x
i
x)
anchor:AVEDEV
100414201 29 May 2010
Test Cases:
=AVEDEV(1;2;3;4) 1
See also SUM, AVERAGE
6.18.3 AVERAGE
Summary: Average the set of numbers
Syntax: AVERAGE( { NumberSequence N }
+
)
Returns: Number
Constraints: At least one Number included. Returns an Error if no Numbers provided.
Semantics: Computes SUM(List) / COUNT(List).
anchor:AVERAGE
Test Cases:
=AVERAGE(2;4) 3 Simple average.
See also SUM, COUNT
6.18.4 AVERAGEA
Summary: Average values, including values of type Text and Logical.
Syntax: AVERAGEA( { Any N }
+
)
Returns: Number
Constraints: At least one value included. Returns an Error if no value provided.
Semantics: A variant of the AVERAGE function that includes values of type Text and Logical. Text
values are treated as number 0. Logical True is treated as 1 and False is treated as 0. Empty cells
are not included. Any N may be of type ReferenceList.
anchor:AVERAGEA
Test Cases:
=AVERAGEA(2;4) 3 Simple average.
=AVERAGEA(TRUE();FALSE()
;5)
2
Logical values are treated as 1 and 0 if inline (this
is the same as AVERAGE)
100414201 29 May 2010
See also AVERAGE
Note: AVERAGEA handles Logical values the same way AVERAGE does on implementations
where Logical values are of type Number. By having both AVERAGEA and AVERAGE, we can
record which was intended without loss of information.
6.18.5 AVERAGEIF
Summary: Average the values of cells in a range that meet a criteria.
Syntax: AVERAGEIF( Reference R ; Criterion C [ ; Reference A ] )
Returns: Number
Constraints: Does not accept constant values as reference parameters.
Semantics: If reference A is omitted, averages the values of cells in the reference range R that
meet the Criterion C (4.11.7). If reference A is given, averages the values of cells of a range that is
constructed using the top left cell of reference A and applying the dimensions, shape and size, of
reference R. If no cell in range R matches the Criterion C, an Error is returned. If no Numbers are in
the range to be averaged, an Error is returned.
anchor:AVERAGEIF
See also AVERAGEIFS, COUNTIF, SUMIF, Infix Operator "=", Infix Operator "<>", Infix Operator
Ordered Comparison ("<", "<=", ">", ">=")
6.18.6 AVERAGEIFS
Summary: Average the values of cells that meet multiple criteria in multiple ranges.
Syntax: AVERAGEIFS( Reference A ; Reference R1 ; Criterion C1 [ ; Reference R2 ; Criterion
C2 ]... )
Returns: Number
Constraints: Does not accept constant values as reference parameters.
Semantics: Averages the values of cells in the reference range A that meet the Criterion C1 in the
reference range R1 and the Criterion C2 in the reference range R2, and so on (4.11.7). All reference
ranges shall have the same dimension and size, else an Error is returned. A logical AND is applied
between each array result of each selection; a cell of reference range A is evaluated only if the
same position in each array is the result of a Criterion match. If no numbers are in the result set to
be averaged, an Error is returned.
anchor:AVERAGEIFS
See also AVERAGEIF, COUNTIFS, Infix Operator "=", Infix Operator "<>", Infix Operator Ordered
Comparison ("<", "<=", ">", ">=")
6.18.7 BETADIST
Summary: returns the value of the probability density function or the cumulative distribution function
for the beta distribution.
100414201 29 May 2010
Syntax: BETADIST( Number x ; Number o ; Number | [ ; Number a = 0 [ ; Number b = 1 [ ; Logical
Cumulative = TRUE() ] ] ] )
Returns: Number
Constraints: o > 0, | > 0, a < b,
If o < 1, then the density function has a pole at x = a.
If | < 1, then the density function has a pole at x = b.
In both cases, if x=a respectively x=b and Cumulative=FALSE(), an Error is returned.
Semantics: If Cumulative is FALSE(), BETADIST returns 0 if x < a or x > b and the value
I(o+)
I(o) I( )
(
x a
ba
)
o1
(
1
x a
ba
)
1
1
ba
otherwise.
If Cumulative is TRUE(), BETADIST returns 0 if x < a, 1 if x > b, and the value
a
x
I(o+)
I(o) I()
(
ta
ba
)
o1
(
1
ta
ba
)
1
1
ba
dt
otherwise.
Note: With substitution
z
t a
ba
the term can be written as
0
xa
ba
I(o+)
I(o) I( )
z
o1
(1z)
1
dz
anchor:BETADIST
Test Cases:
=BETADIST(0;3;4) 0
=BETADIST(0.5;3;4) 0.65625 exact 0.65625
=BETADIST(0.9;4;3) 0.98415 exact 0.98415
=BETADIST(1.5;3;4;1;2) =BETADIST(0.5;3;4) substitution
=BETADIST(2;3;4;1;3) =BETADIST(0.5;3;4) substitution
=BETADIST(0;3;4;0;1;FALSE()) 0
=BETADIST(0.5;3;4;0;1;FALSE()) 1.875 exact 1.875
=BETADIST(0.9;4;3;0;1;FALSE()) 0.4374 exact 0.4374
=BETADIST(1.5;3;4;1;2;FALSE())
=BETADIST(0.5;3;4;0;1;FALS
E())
100414201 29 May 2010
=BETADIST(2;3;4;1;3;FALSE()) 0.9375 exact 0.9375
=BETADIST(2;3;4) 1
=BETADIST(-1;3;4) 0
=BETADIST(2;3;4;0;1;FALSE()) 0
=BETADIST(-1;3;4;0;1;FALSE()) 0
See also BETAINV
Note: Excel, OOo2, Gnumeric and KSpread do not support the last optional argument. They also
have an additional constraint
axb
.
6.18.8 BETAINV
Summary: returns the inverse of BETADIST(x;o;|;a;b;TRUE()).
Syntax: BETAINV( Number p ; Number o ; Number | [ ; Number a = 0 [ ; Number b = 1 ] ] )
Returns: Number
Constraints:
0p1
, o > 0, | > 0, a < b
Semantics: BETAINV returns the unique number x in the closed interval from a to b such that
BETADIST(x;o;|;a;b) = p.
anchor:BETAINV
Test Cases:
=BETADIST(BETAINV(0;3;4);3;4) 0
=BETADIST(BETAINV(0.1;3;4);3;4) 0.1
=BETADIST(BETAINV(1;3;4);3;4) 1
=BETADIST(BETAINV(0;3;4;1;3);3;4;1;3) 0
=BETADIST(BETAINV(0.1;3;4;1;3);3;4;1;3) 0.1
=BETADIST(BETAINV(1;3;4;1;3);3;4;1;3) 1
100414201 29 May 2010
See also BETADIST
6.18.9 BINOM.DIST.RANGE
Summary: Returns the probability of a trial result using binomial distribution.
Syntax: BINOM.DIST.RANGE( Integer N ; Number P ; Integer S [ ; Integer S2 ] )
Returns: Number
Constraints: 0<=P<=1, 0<=S<=S2<=N
Semantics: Let N be a total number of independent trials, and P be a probability of success for
each trial. This function returns the probability that the number of successful trials shall be exactly S.
If the optional parameter S2 is provided, this function returns the probability that the number of
successful trials shall lie between S and S2 inclusive.
This function is computed as follows:
If S2 is not given, let S2:=S. Then the function returns the value of
k =S
S2
(
N
k
)
P
k
(1P)
N k
anchor:BINOM.DIST.RANGE
Test Cases:
=BINOM.DIST.RANGE(10
;1;10)
1 Prob.=100% - all trials successful
=BINOM.DIST.RANGE(10
;1;9)
0 Prob. of -exactly- 9 trials successful is 0 then
=BINOM.DIST.RANGE(7;
0.5;3)
0.2734375 Some values
=BINOM.DIST.RANGE(8;
0.2;3;7)
0.20307698 Some more values, with range.
See also BINOMDIST
Note: This describes how the function works in OOo. KSpread has a similar function, called BINO,
which takes the arguments in a different order, and doesn't have the 4th argument. Gnumeric
doesn't have this function. Excel doesn't have this function.
6.18.10 BINOMDIST
Summary: Returns the binomial distribution.
Syntax: BINOMDIST( Integer S ; Integer N ; Number P ; Logical Cumulative )
Returns: Number
100414201 29 May 2010
Constraints: 0 <= P <= 1; 0 <= S <= N
Semantics: If Cumulative is FALSE(), this function returns the same result as
BINOM.DIST.RANGE(N;P;S). If Cumulative is TRUE(), it is equivalent to calling
BINOM.DIST.RANGE(N;P;0;S).
anchor:BINOMDIST
Test Cases:
=BINOMDIST(10;10;1;0) 1 Prob.=100% - all trials successful
=BINOMDIST(9;10;1;0) 0 Prob. of -exactly- 9 trials successful is 0 then
=BINOMDIST(10;10;0,1;1) 1 Sum of probabilities of 0..10 hits is 1.
=BINOMDIST(4;10;0,4;1) 0.63310326 Some random values.
See also BINOM.DIST.RANGE
6.18.11 LEGACY.CHIDIST
Summary: returns the right-tail probability for the
2
distribution.
Syntax: LEGACY.CHIDIST( Number x ; Number DegreesOfFreedom )
Returns: Number
Constraints: DegreesOfFreedom is a positive integer.
Semantics: In the following n is DegreesOfFreedom. LEGACY.CHIDIST returns 1 for
x<0
and
the value
t
n
2
1
e
t
2
2
n
2
I(n/ 2)
dt
for
x>0
.
anchor:LEGACY.CHIDIST
Test Cases:
=LEGACY.CHIDIST(-1;2) 1
=LEGACY.CHIDIST(0;2) 1
=LEGACY.CHIDIST(2;2) 0.367879
=LEGACY.CHIDIST(4;4) 0.406006
100414201 29 May 2010
See also CHISQDIST, LEGACY.CHITEST
Note: This function differs from the other distribution function in that it calculates the right-hand tail.
6.18.12 CHISQDIST
for the
2
distribution.
Syntax: CHISQDIST( Number x ; Number DegreesOfFreedom [ ; Logical Cumulative = TRUE() ] )
Returns: Number
Constraints: DegreesOfFreedom is a positive integer.
Semantics: In the following n is DegreesOfFreedom.
If Cumulative is FALSE(), CHISQDIST returns 0 for
x<0
and the value
x
n
2
1
e
x
2
2
n
2
I( n/ 2)
for
x>0
.
If Cumulative is TRUE(), CHISQDIST returns 0 for
x<0
and the value
0
x
t
n
2
1
e
t
2
2
n
2
I(n/ 2)
dt
for
x>0
.
anchor:CHISQDIST
Test Cases:
=CHISQDIST(0;2) 0
=CHISQDIST(0;2;FALSE()) 0
=CHISQDIST(2;2;FALSE()) 0.183940
=CHISQDIST(2;2;TRUE()) 0.632121
=CHISQDIST(4;2;FALSE()) 0.067668
=CHISQDIST(4;2;TRUE()) 0.864665
See also LEGACY.CHIDIST
Note: This is a version of CHIDIST consistent with the other distribution functions.
100414201 29 May 2010
6.18.13 LEGACY.CHIINV
Summary: returns the inverse of LEGACY.CHIDIST(x; DegreesOfFreedom).
Syntax: LEGACY.CHIINV( Number p ; Number DegreesOfFreedom )
Returns: Number
Constraints: DegreesOfFreedom is a positive integer and
0p1
.
Semantics: LEGACY.CHIINV returns the unique number x such that LEGACY.CHIDIST(x;
DegreesOfFreedom) = p.
anchor:LEGACY.CHIINV
Test Cases:
=LEGACY.CHIDIST(LEGACY.CHIINV(0.1;3);3) 0.1
=LEGACY.CHIDIST(LEGACY.CHIINV(1;20);20) 1
6.18.14 CHISQINV
Summary: returns the inverse of CHISQDIST(x; DegreesOfFreedom; TRUE()).
Syntax: CHISQINV( Number p ; Number DegreesOfFreedom )
Returns: Number
Constraints: DegreesOfFreedom is a positive integer and
0p1
.
Semantics: CHISQINV returns the unique number
x0
such that CHISQDIST(x;
DegreesOfFreedom;TRUE()) = p.
anchor:CHISQINV
Test Cases:
100414201 29 May 2010
=CHISQDIST(CHISQINV(0.1;3);3;TRUE() ) 0.1
=CHISQDIST(CHISQINV(0.3;3);3;TRUE()) 0.3
=CHISQDIST(CHISQINV(0;20);20;TRUE()) 0
See also CHISQDIST
6.18.15 LEGACY.CHITEST
Summary: Returns some Chi square goodness-for-fit test.
Syntax: LEGACY.CHITEST( ForceArray Array A ; ForceArray Array E )
Returns: Number
Constraints:
ROWS(A) == ROWS(E)
COLUMNS(A) == COLUMNS(E)
COLUMNS(A) * ROWS(A) > 1
Semantics:
For an empty element or an element of type Text or Boolean in A the element at the corresponding
position of E is ignored, and vice versa.
A actual observation data.
E expected values.
First a Chi square statistic is calculated:
100414201 29 May 2010
X
2
=
i=1
r
j=1
c
(
A
ij
E
ij )
2
E
ij
with
r = number of rows
c = number of columns
A
ij
= element of actual data
E
ij
= element of expected values
Then LEGACY.CHIDIST is called with the Chi-square value and a degree of freedom (df):
if r>1 and c>1
df =( r1)( c1)
else
df =rc1
LEGACY.CHITEST =LEGACY.CHIDIST (X
2
; df )
anchor:LEGACY.CHITEST
Test Cases:
=CHITEST([.B71:.D73];
[.F71:.H73])
0.992408092
Note: Applications usually describe the CHITEST function as a Chi-square independence test. From
a mathematical point of view this is not correct, as that would not involve testing some actual data
against a set of expected values. It resembles more a Goodness-for-Fit test, but how the degree of
freedom is calculated actually doesn't make sense then. This is specified to be interoperable with
Excel and OpenOffice.org. Gnumeric gets different results if the number of rows and columns both
are greater than 2. See also a comment on OFFICE-2309.
6.18.16 CONFIDENCE
Summary: Returns the confidence interval for a population mean.
Syntax: CONFIDENCE( Number alpha ; Number stddev ; Number size )
Returns: Number
Constraints: 0 < alpha < 1; stddev > 0, size >= 1
Semantics: Calling this function is equivalent to calling NORMINV(1 - alpha / 2; 0; 1) * stddev /
SQRT (size)
anchor:CONFIDENCE
Test Cases:
100414201 29 May 2010
=CONFIDENCE(0.5;1;1) 0.67448975 Test values.
=CONFIDENCE(0.25;1;1) 1.15034939 Test values.
=CONFIDENCE(0.5;4;1) 2.697959 Multiplying stddev by X multiplies result by X.
=CONFIDENCE(0.5;1;4) 0.33724488 Multiplying count by X*X divides result by X.
6.18.17 CORREL
Summary: Calculates the correlation coefficient of values in N1 and N2.
Syntax: CORREL( ForceArray Array N1 ; ForceArray Array N2 )
Returns: Number
Constraints: COLUMNS(N1) = COLUMNS(N2), ROWS(N1) = ROWS(N2), both sequences shall
contain at least one number at corresponding positions each.
Semantics: Has the same value as COVAR(N1;N2)/STDEVP(N1)*(STDEVP(N2)). The CORREL
function actually is identical to the PEARSON function.
For an empty element or an element of type Text or Boolean in N1 the element at the corresponding
position of N2 is ignored, and vice versa.
anchor:CORREL
Test Cases:
=CORREL([.B14:.B17];
[.B14:.B17])
1 Perfect positive correlation given identical sequences
[.C14:.C17])
-1 Perfect negative correlation given reversed sequences
=CORREL(1;2) Error Each list must contain at least 2 values
[.B15:.B16])
Error The length of each list must be equal
See also PEARSON
6.18.18 COVAR
Summary: Calculates covariance of two cell ranges.
Syntax: COVAR( ForceArray Array n1 ; ForceArray Array n2 )
Returns: Number
Constraints: COLUMNS(n1) = COLUMNS(n2), ROWS(n1) = ROWS(n2), both sequences shall
contain at least one number at corresponding positions each.
100414201 29 May 2010
Semantics: returns
an1, bn2
( an1)( bn2)
where
n1
is the result of calling AVERAGE(n1), and
n2
is the result of calling AVERAGE(n2).
For an empty element or an element of type Text or Boolean in n1 the element at the corresponding
position of n2 is ignored, and vice versa.
anchor:COVAR
Test Cases:
=COVAR([.C11:.C17];[.C11:.C17]) 4.9795918367 Test value.
=COVAR([.B14:.B17];[.C14:.C17]) -1.25 Test values.
=COVAR([.B14:.B17];[.C14:.C18]) Error Array sizes don't match.
6.18.19 CRITBINOM
Summary: Returns the smallest value for which the cumulative binomial distribution is greater than
or equal to a criterion value.
Syntax: CRITBINOM( Number Trials ; Number SP ; Number Alpha )
Returns: Number
Constraints: Trials >=0, 0 <= SP <= 1, Alpha >= 1
Semantics:
Trials is the total number of trials.
SP is the probability of success for one trial.
Alpha is the threshold probability to be reached or exceeded.
anchor:CRITBINOM
Test Cases:
=CRITBINOM(100;0.5;0.1) 44
6.18.20 DEVSQ
Summary: Calculates sum of squares of deviations.
Syntax: DEVSQ( { NumberSequence n }
+
)
Returns: Number
Semantics: returns
100414201 29 May 2010
xn
( xa)
2
where a is the result of calling AVERAGE(n).
anchor:DEVSQ
Test Cases:
=DEVSQ(4) 0 One value - no deviation.
=DEVSQ(5;5;5;5) 0 Identical values - no deviation.
=DEVSQ(2;4) 2 Each value deviates by 1.
=DEVSQ(-5;5;-1;1) 52 Average=0 must work properly.
=DEVSQ([.C11:.C17]) 34.8571428571 Test values.
=DEVSQ([.B14:.B17]) 5.00 Test values.
=DEVSQ([.B14]) 0 One value - no deviation.
6.18.21 EXPONDIST
for the exponential distribution.
Syntax: EXPONDIST( Number x ; Number i [; Logical Cumulative = TRUE() ] )
Returns: Number
Constraints: i > 0
Semantics: If Cumulative is FALSE(), EXPONDIST returns 0 if x < 0 and the value
\e
\x
otherwise.
If Cumulative is TRUE(), EXPONDIST returns 0 if x < 0 and the value
0
x
\e
\t
dt=1e
\x
otherwise.
anchor:EXPONDIST
Test Cases:
=EXPONDIST(1;1;TRUE()) 0.632121
=EXPONDIST(2;2;TRUE()) 0.981684
100414201 29 May 2010
=EXPONDIST(0;1;TRUE()) 0
=EXPONDIST(-1;1;TRUE()) 0
=EXPONDIST(1;1;FALSE()) 0.367879
=EXPONDIST(2;2;FALSE()) 0.036631
=EXPONDIST(0;1;FALSE()) 1
=EXPONDIST(-1;1;FALSE()) 0
=EXPONDIST(1;1) =EXPONDIST(1;1;TRUE())
6.18.22 FDIST
for the F-distribution.
Syntax: FDIST( Number x ; Number r1 ; Number r2 [ ; Logical Cumulative = TRUE() ] )
Returns: Number
Constraints: r1 and r2 are positive integers
Semantics:
r1 is the degrees of freedom in the numerator of the F distribution.
r2 is the degrees of freedom in the denominator of the F distribution.
If Cumulative is FALSE(), FDIST returns 0 if x < 0, an Error if the numerator degrees of freedom r1 =
1 and x = 0, and the value
I(
r
1
+r
2
2
)
(
r
1
r
2
)
r
1
2
I(
r
1
2
) I(
r
2
2
)

x
r
1
2
1
(
1+
r
1
r
2
x
)
r
1
+r
2
2
otherwise.
If the numerator degrees of freedom r1 = 1, then the density function has a pole at x=0, the subterm
x
r
1
2
1
=0
0.5
is not defined.
If Cumulative is TRUE(), FDIST returns 0 if x < 0 and the value
I(
r
1
+r
2
2
)
(
r
1
r
2
)
r
1
2
I(
r
1
2
) I(
r
2
2
)

0
x
t
r
1
2
1
(
1+
r
1
r
2
t
)
r
1
+r
2
2
dt
100414201 29 May 2010
otherwise.
anchor:FDIST
Test Cases:
=FDIST(1;4;5) 0.514343
=FDIST(2;5;4) 0.739202
=FDIST(0;4;5) 0
=FDIST(-1;4;5) 0
=FDIST(1;4;5;FALSE()) 0.397614
=FDIST(2;5;4;FALSE()) 0.154000
=FDIST(0;4;5;FALSE()) 0
=FDIST(-1;4;5;FALSE()) 0
=FDIST(1;4;5;TRUE()) =FDIST(1;4;5)
See also LEGACY.FDIST
Note: Ooo2, Gnumeric and KSpread do not support the last argument. They return an Error for
negative x and they calculate the right-hand tail, as does Excel97.
6.18.23 LEGACY.FDIST
Summary: returns the area of the right tail of the probability density function for the F-distribution.
Syntax: LEGACY.FDIST( Number x ; Number r1 ; Number r2 )
Returns: Number
Constraints: r1 and r2 are positive integers
Semantics:
LEGACY.FDIST returns Error if x < 0 and the value
I(
r
1
+r
2
2
)
(
r
1
r
2
)
r
1
2
I(
r
1
2
) I(
r
2
2
)

t
r
1
2
1
(
1+
r
1
r
2
t
)
r
1
+r
2
2
dt
otherwise.
Note that the latter is (1-FDIST(x; r1; r2;TRUE())).
anchor:LEGACY.FDIST
Test Cases:
100414201 29 May 2010
=LEGACY.FDIST(1;4;5) 0.485657
=LEGACY.FDIST(2;5;4) 0.260798
=LEGACY.FDIST(0;4;5) 1
=LEGACY.FDIST(-1;4;5) Error
See also FDIST
6.18.24 FINV
Summary: returns the inverse of FDIST(x;r1;r2;TRUE()).
Syntax: FINV( Number p ; Number r1 ; Number r2 )
Returns: Number
Constraints:
0p1
, r1 and r2 are positive integers
Semantics: FINV returns the unique non-negative number x such that FDIST(x;r1;r2) = p.
anchor:FINV
Test Cases:
=FDIST(FINV(0.1;3;4);3;4) 0.1
=FDIST(FINV(0.3;3;4);3;4) 0.3
=FDIST(FINV(0.5;4;3);4;3) 0.5
=FDIST(FINV(0.7;4;3);4;3) 0.7
=FDIST(FINV(0;3;4);3;4) 0
See also FDIST, LEGACY.FDIST, LEGACY.FINV
6.18.25 LEGACY.FINV
Summary: returns the inverse of LEGACY.FDIST(x;r1;r2).
Syntax: LEGACY.FINV( Number p ; Number r1 ; Number r2 )
Returns: Number
Constraints:
0p1
, r1 and r2 are positive integers
Semantics: LEGACY.FINV returns the unique non-negative number x such that
LEGACY.FDIST(x;r1;r2) = p.
anchor:LEGACY.FINV
100414201 29 May 2010
Test Cases:
=LEGACY.FDIST(LEGACY.FINV(0.1;3;4);3;4) 0.1
=LEGACY.FDIST(LEGACY.FINV(1;3;4);3;4) 1
See also FDIST, LEGACY.FDIST, FINV
6.18.26 FISHER
Summary: returns the Fisher transformation.
Syntax: FISHER( Number r )
Returns: Number
Constraints: -1 < r < 1
Semantics: Returns the Fisher transformation with a sample correlation r. This function computes
1
2
ln(
1+r
1r
)
where ln is the natural logarithm function.
FISHER is a synonym for ATANH.
anchor:FISHER
Test Cases:
=FISHER(0) 0 Fisher of 0.
=FISHER((EXP(1)-1)/(EXP(1)+1)) 0.5 Argument chosen so that ln=1
=FISHER(0.5) 0.54930614 Some random value.
=FISHER(0.47)+FISHER(-0.47) 0 Function is symetrical.
See also ATANH
6.18.27 FISHERINV
Summary: returns the inverse Fisher transformation.
Syntax: FISHERINV( Number r )
100414201 29 May 2010
Returns: Number
Constraints: none
Semantics: Returns the inverse Fisher transformation. This function computes
e
2r
1
e
2r
+1
FISHERINV is a synonym for TANH.
anchor:FISHERINV
Test Cases:
=FISHERINV(0) 0 Fisherinv of 0.
=FISHERINV(LN(2)) 0.6 e^(2*ln(2))=4
=FISHERINV(FISHER(0.5)) 0.5 Some random value.
=FISHERINV(0.47)+FISHERINV(-0.47) 0 Function is symetrical.
See also TANH
6.18.28 FORECAST
Summary: Extrapolates future values based on existing x and y values.
Syntax: FORECAST( Number Value ; ForceArray Array Data_Y ; ForceArray Array Data_X )
Returns: Number
Constraints: COLUMNS(Data_Y) = COLUMNS(Data_X), ROWS(Data_Y) = ROWS(Data_X)
Semantics:
Value is the x-value, for which the y-value on the linear regression is to be returned.
Data_Y is the array or range of known y-values.
Data_X is the array or range of known x-values.
For an empty element or an element of type Text or Boolean in Data_Y the element at the
corresponding position of Data_X is ignored, and vice versa.
anchor:FORECAST
Note: This function uses linear regression. How can we codify the specification to be actually useful
without including the whole theory behind it? For the moment, we wont give the details; they are
lengthy, and in any case well-known. Simply stating that it is a linear regression should be
sufficient for the purposes of this spec.
TODO: Test case.
6.18.29 FREQUENCY
Summary: Categorizes values into intervals and counts the number of values in each interval.
100414201 29 May 2010
Syntax: FREQUENCY( NumberSequenceList data ; NumberSequenceList bins )
Returns: Array
Constraints: Values in bins shall be sorted in ascending order and bins shall be a column vector.
Evaluators may accept unsorted values in bins.
Semantics: Counts the number of values for each interval given by the border values in bins .
The values in bins determine the upper boundaries of the intervals. The intervals include the upper
boundaries. The returned array is a column vector and has one more element than bins ; the last
element represents the number of all elements greater than the last value in bins . If bins is empty,
all values in data are counted. The values in the result array are ordered matching the original order
of bins . If the values in bins are not sorted in ascending order, they are sorted internally to form
category intervals and the counts of data values are "unsorted" to the original order of bins. If data is
empty, the value of all elements in the returned array is 0.
data The data, that should be categorized and counted according to the given intervals.
bins The upper boundaries determining the intervals the values in data should be grouped by.
anchor:FREQUENCY
Test Cases:
=FREQUENCY([.C19:.C31]; [.B14:.B17]) 3 bins were sorted ascending
2
1
2
5
=FREQUENCY([.C19:.C31]; [.C14:.C17]) 2 bins were sorted descending
1
2
3
5
6.18.30 FTEST
Summary: Calculates the probability of an F-test.
Syntax: FTEST( ForceArray NumberSequence Data_1 ; ForceArray NumberSequence Data_2 )
Returns: Number
Constraints: Data_1 and Data_2 shall both contain at least 2 numbers and shall both have nonzero
variances
Semantics: Calculates the two-tailed probability that, based on two samples from two normal
distributions, these normal distributions have different variances.
100414201 29 May 2010
Suppose the first sample has size n1 and sample variance s1^2 and the second sample has size n2
and sample variance s2^2. If s1^2>s^2 FDIST returns twice the area of the right tail of the F-
distribution with degrees of freedom n1-1,n2-1 beyond s^1/s^2. If s1^2<s^2 FDIST returns twice the
area of the left tail of the F-distribution with degrees of freedom n1-1,n2-1 below s^1/s^2.
anchor:FTEST
Test Cases:
=FTEST(B14:B17; C14:C17) 1
Same data (second reversed), so
equal variances
=FTEST(B14:B15; C13:C14)
0.311916521
Significantly different variances, so

less likely to come from same data
set.
See also TTEST
6.18.31 GAMMADIST
for the Gamma distribution.
Syntax: GAMMADIST( Number x ; Number o ; Number | [ ; Logical Cumulative = TRUE() ] )
Returns: Number
Constraints: o > 0, | > 0
Semantics: If Cumulative is FALSE(), GAMMADIST returns 0 if x < 0 and the value
1
o
I(o)
x
o1
e
otherwise.
If Cumulative is TRUE(), GAMMADIST returns 0 if x < 0 and the value
0
x
1
o
I(o)
t
o1
e
dt
otherwise.
anchor:GAMMADIST
Test Cases:
=GAMMADIST(0;3;4) 0
=GAMMADIST(0.5;3;4) 0.001724
=GAMMADIST(9;4;3) 0.066698
100414201 29 May 2010
=GAMMADIST(0;3;4;FALSE()) 0
=GAMMADIST(0.5;3;4;FALSE()) 0.000296
=GAMMADIST(9;4;3;FALSE()) 0.390661
=GAMMADIST(0;3;4;TRUE()) =GAMMADIST(0;3;4)
=GAMMADIST(0.5;3;4;TRUE()) =GAMMADIST(0.5;3;4)
=GAMMADIST(9;4;3;TRUE()) =GAMMADIST(9;4;3)
=GAMMADIST(-1;4;3;TRUE()) 0
=GAMMADIST(-1;3;4;FALSE()) 0
See also GAMMAINV
Note: Ooo2, Gnumeric, Excel and KSpread require the last argument. They also have an additional
constraint
0x
.
6.18.32 GAMMAINV
Summary: returns the inverse of GAMMADIST(x;o;|;TRUE()).
Syntax: GAMMAINV( Number p ; Number o ; Number | )
Returns: Number
Constraints:
0p1
, o > 0, | > 0
Semantics: GAMMAINV returns the unique number
x0
such that GAMMAINV(x;o;|) = p.
anchor:GAMMAINV
Test Cases:
=GAMMADIST(GAMMAINV(0.1;3;4);3;4) 0.1
=GAMMADIST(GAMMAINV(0;3;4);3;4) 0
See also GAMMADIST
6.18.33 GAUSS
Summary: Returns 0.5 less than the standard normal cumulative distribution
100414201 29 May 2010
Syntax: GAUSS( Number x )
Returns: Number
Semantics: Returns NORMDIST(x;0;1;TRUE())-0.5
anchor:GAUSS
Test Cases:
=GAUSS(0) 0 Mean of one value.
=GAUSS(1) 0.341344746 Multiple equivalent values.
See also NORMDIST
6.18.34 GEOMEAN
Summary: returns the geometric mean of a sequence
Syntax: GEOMEAN( { NumberSequenceList N }
+
)
Returns: Number
Semantics: Returns the geometric mean of a given sequence. That means
(
aN
a
)
1/ n
where n is a result of calling COUNT(N).
anchor:GEOMEAN
Test Cases:
=GEOMEAN(7) 7 Mean of one value.
=GEOMEAN(5;5;5;5) 5 Multiple equivalent values.
=GEOMEAN(2;8;2;8) 4 Some values.
=GEOMEAN(8;0;8;8;8;8) Error Error if there is a 0 in the range.
=GEOMEAN([.C11]) 5 One value, range.
=GEOMEAN([.C11:C17]) 3.4451109418 Some values, range.
=GEOMEAN([.B14:.B17]) 2.2133638394 Some values, range.
6.18.35 GROWTH
Summary: Calculates a sequence of values based on a least squares exponential fit to known
value pairs.
100414201 29 May 2010
Syntax: GROWTH( NumberSequence knownY [ ; [ NumberSequence knownX ] [ ; [
NumberSequence newX ] [ ; Logical allowConstant = TRUE() ] ] ] )
Returns: Array
Constraints: COUNT(knownY) = COUNT(knownX); COUNT(knownY), COUNT(knownX)>1.
COLUMNS(knownY) = COLUMNS(knownX), ROWS(knownY) = ROWS(knownX)
Semantics: Calculates a sequence of values based on an exponential least squares fit of known
value pairs.
If knownX is omitted or an empty parameter (two consecutive ;; semicolons), it is set to the
sequence
1,2,3, ., n
, where
n=COUNT ( knownY )
.
If newX is omitted or an empty parameter (two consecutive ;; semicolons), it is set to be equal to
knownX.
If allowConstant is TRUE, the fit is to the function
y=bm
x
, where b and m are constants
determined in the fit. If allowConstant is FALSE, the fit is to the function
y=m
x
, i.e when
allowConstant is FALSE, the constant b is set to 1. The default is TRUE.
anchor:GROWTH
Test Cases:
=GROWTH( [.A19:.A23];
[.C19:.C23]; 1 )
2.51984210
=GROWTH( [.A19:.A23];
[.C19:.C23]; 1; FALSE() )
1.48599429
See also TREND
6.18.36 HARMEAN
Summary: returns the harmonic mean of a sequence
Syntax: HARMEAN( { NumberSequenceList N }
+
)
Returns: Number
Semantics: Returns the harmonic mean of a given sequence. That means
n
i=1
n
1
a
i
where a1,a2,...,an are the numbers of the sequence N and n is a result of calling COUNT(N).
anchor:HARMEAN
Test Cases:
100414201 29 May 2010
=HARMEAN(7) 7 Mean of one value.
=HARMEAN(4;4;4;4) 4 Multiple equivalent values.
=HARMEAN(2;4;4) 3 Some values.
=HARMEAN(8;0;8;8;8;8) Error Error if there is a 0 in the range.
=HARMEAN([.C11]) 5 One value, range.
=HARMEAN([.C11:C17]) 2.7184466019 Some values, range.
=HARMEAN([.B14:.B17]) 1.92 Some values, range.
6.18.37 HYPGEOMDIST
Summary: The hypergeometric distribution returns the number of successes in a sequence of n
draws from a finite population without replacement.
Syntax: HYPGEOMDIST( Integer x ; Integer n ; Integer M ; Integer N [ ; Logical Cumulative =
FALSE() ] )
Returns: Number
Constraints: 0 <= x <= n <= N, 0 <= M <= N
Semantics:
x is the number of successes in n trials
n is the number of trials
M is the number of successes in the population
N is the total population
cumulative is a Logical parameter. If cumulative is FALSE(), return the probability of exactly x
successes. If cumulative is TRUE(), return the probability of at most x successes. If omitted,
FALSE() is assumed.
If Cumulative is FALSE(), HYPGEOMDIST returns
(
M
x
)(
NM
nx
)
(
N
n
)
If Cumulative is TRUE(), HYPGEOMDIST returns
i=0
x
(
M
i
)(
NM
ni
)
(
N
n
)
Note:
100414201 29 May 2010
(
x
y
)
=0 for y>x
anchor:HYPGEOMDIST
Test Cases:
=HYPGEOMDIST(2;3;3;6;FALSE()) 0.45
If an urn contains 3 red balls
and 3 green balls, the
probability that 2 red balls
will be selected after 3
selections without
replacement. (0.45=27/60).
=HYPGEOMDIST(2;3;3;6) 0.45
The default for cumulative is
FALSE().
=HYPGEOMDIST(0;3;3;6) 0.05
There is a small (5%)
chance of selecting only
green balls.
=HYPGEOMDIST(2;3;3;6;TRUE()) 0.95
The probability of selecting
at most two red balls (i.e 0,
1 or 2).
=HYPGEOMDIST(4;3;3;6) Error X must be <= M
=HYPGEOMDIST(2.8;3;3;6) 0.45 Non-integers are truncated.
=HYPGEOMDIST(-2;3;3;6) Error Values must be >= 0.
=HYPGEOMDIST(0;0;0;0) 1
Note: OOo 2.1 and Kspread 1.6.1 do not include the cumulative parameter. Gnumeric 1.6.3 does
include the cumulative parameter.
6.18.38 INTERCEPT
Summary: Returns the y-intercept of the linear regression line for the given data.
Syntax: INTERCEPT( ForceArray Array Data_Y ; ForceArray Array Data_X )
Returns: Number
Constraints: COLUMNS(Data_X) = COLUMNS(Data_Y), ROWS(Data_X) = ROWS(Data_Y)
Semantics:
INTERCEPT returns the intercept (a) calculated as described in 5.18.41 for the function call
LINEST(DATA_Y,DATA_X,FALSE()).
For an empty element or an element of type Text or Boolean in Data_Y the element at the
corresponding position of Data_X is ignored, and vice versa.
anchor:INTERCEPT
TODO: Test cases.
100414201 29 May 2010
6.18.39 KURT
Summary: Return the kurtosis (peakedness) of a data set.
Syntax: KURT( { NumberSequenceList X }
+
)
Returns: Number
Constraints: #Numbers>=4, STDEV(X) <> 0
Note: If there are fewer than four data points, or if the standard deviation of the sample equals zero,
KURT typically returns a #DIV/0! or similar Error value.
Semantics:
Kurtosis characterizes the relative peakedness or flatness of a distribution compared with the
normal distribution. Positive kurtosis indicates a relatively peaked distribution (compared to the
normal distribution), while negative kurtosis indicates a relatively flat distribution.
kurtosis=
(
n(n+1)
(n1)(n2)(n3)
i=1
n
(
x
i
x
s
)
4
)

3(n1)
2
(n2)(n3)
where s is the sample standard deviation, and n is the number of numbers.
anchor:KURT
Test Cases:
=KURT([.C20:.C25]) -0.446162998
=KURT([.C20:.C23];4;4) -0.446162998
6.18.40 LARGE
Summary: Finds the nth largest value in a list.
Syntax: LARGE( NumberSequenceList List ; Number|Array N )
Returns: Number or Array
Constraints: ROUNDUP(N;0)=N. If the resulting N is <1 or larger than the size of List, Error is
returned
Semantics: If N is an array of numbers, an array of largest values is returned.
anchor:LARGE
Test Cases:
=LARGE([.B14:B16];1) 3
=LARGE([.B14:B16];3) 1
=LARGE([.B14:B16];4) Error N is greater than the length of the list
100414201 29 May 2010
=LARGE([.B14:B16];{1;3}) {3;1}
See also SMALL, ROUNDUP
6.18.41 LINEST
Summary: Returns the parameters of a linear trend best fitting the given data. This function shall be
entered as an array formula.
Syntax: LINEST( Array knownY [ ; [ Array knownX ] [ ; Logical Const = TRUE() [ ; Logical Stats =
FALSE() ] ] ] )
Returns: Array
Constraints: COLUMNS(knownY) = COLUMNS(knownX), ROWS(knownY) = ROWS(knownX),
COUNT(knownY) = COUNT(knownX)
Semantics:
knownY: The set of y-values for the equation, either one single column or one single row
knownX: The set of x-values for the equation, a single column or single row matching knownY. If
omitted or an empt y parameter (two consecutive ;; semicolons), it is set to the sequence
1,2,3, ., n
, where
n=COUNT (knownY )
. If one single value, it is applied to all.
Const: If set to FALSE(), the constant a is equal to 0 and the line goes through the zero point.
Stats: If FALSE(), only the regression coefficient is to be calculated. If set to TRUE(), the result will
include other statistical data returned as an array, as shown in the table:
Table 30 - LINEST
slope (bn) slope (bn-1) ... slope (b1) intercept (a)
a Standard error for
the slope (bn)
the slope (bn-1)
a Standard error
for the slope (b1)
b Standard error for the
intercept (a)
r
2
y Standard error for
the y-Values
F Statistics degrees of freedom
(df)
SSreg Regression
sum of squares
SSresid Residual sum
of squares
Every linear equation can be written using the form
y=a+bx
or
y=a+b
1
x
1
+b
2
x
2
+.+b
n
x
n
if there are multiple x-values.
where y is the dependent y-value
a is the intercept (or constant) that represents the point at which the line crosses the y-axis.
b is the slope coefficient that corresponds to each x-value
a or the INTERCEPT is calculated using this formula :
100414201 29 May 2010
a=
(

i=1
N
( x
i
2
)
) (

i=1
N
( y
i
)
)

(

i=1
N
( x
i
)
) (

I =1
N
( x
i
y
i
)
)
N
(

i=1
N
( x
i
2
)
)

(

i =1
N
( x
i
)
)
2
b or the SLOPE is calculated using this formula:
b=
N
(

i=1
N
( x
i
y
i
)
)

(

i=1
N
( x
i
)
) (

i=1
N
( y
i
)
)
N
(

i=1
N
( x
i
2
)
)

(

i=1
N
( x
i
)
)
2
Standard Error of the Y value is calculated using this formula:
c
y
=
.
1
( N2)
i=1
N
( y
i
abx
i
)
2
Standard Error of the Slope (a) value is calculated using this formula:
c
a
=
.
c
y
2
(

i=1
N
( x
i
2
)
)
N
(

i =1
N
( x
i
2
)
)

(

i=1
N
( x
i
)
)
2
Standard Error of the Intercept (b) value is calculated using this formula:
c
b
=
.
N c
y
2
N
(

i =1
N
( x
i
2
)
)

(

i=1
N
( x
i
)
)
2
The RSQ Value (r
2
) is calculated using the following formula:
r
2
=
i=1
N
( y
i
y)
2
i=1
N
( y
i
y
calc
)
2
i=1
N
( y
i
y)
2
with
y
calc
=a+bx
The Regression Sum of squares is calculated as follows:
100414201 29 May 2010
ss
reg
=
i=1
N
( y
i
y)
2
with
y
i
=a+bx
The Residual sum of squares is calculated using this formula:
ss
resid
=
i =1
N
( y
i
y
i
)
2
with
y
i
=a+bx
100414201 29 May 2010
The degrees of freedom (df) is calculated with this formula:
df =nk1
where
n=number of data points
k=number of variables of the regression analysis (columns in knownX )
The F Statistics is calculated as follows:
F=
(
i =1
N
( y
i
y)
2
)
v1
(
i =1
N
( y
i
y
i
)
2
)
v2
y
i
=a+bx
i
v1=1
v2=degrees of freedom ( df )
calculated above
For const = FALSE() the Calculations for the INTERCEPT, the SLOPE and the other statistics are
based on the following formulas:
a or the INTERCEPT is zero by definition:
a=0
bydefinitionastheregressionlinegoesthroughthePoint (00)
b or the SLOPE is calculated using this formula:
b=
i=1
n
xy
i =1
n
x
2
Standard Error of the Y value is calculated using this formula:
c
y
=
.
(
ss
resid
df
)
Standard Error of the Slope (a) value is calculated using this formula:
c
a
=#N/A
as a=0 by definition, nothing calculated no error value possible
Standard Error of the Intercept (b) value is calculated using this formula:
100414201 29 May 2010
c
b
=
c
y
.

i=1
N
( x
i
2
)
The RSQ Value (r
2
) is calculated using the following formula:
r
2
=
(

i=1
n
xy
( .
i =1
N
( x
i
2
)
.
i =1
N
( y
i
2
)
)
)
2
The Regression Sum of squares is calculated as follows:
ss
reg
=ss
total
ss
resid
with
ss
total
=
i =1
N
( y
i
2
)
The Residual sum of squares is calculated using this formula:
ss
resid
=
i =1
N
( y
i
y
i
)
2
with
y
i
=bx
The degrees of freedom (df) is calculated with this formula:
df =nk
where
n=number of data points
k=number of variables of the regression analysis (columns in knownX )
The F Statistics is calculated as follows:
F=
(
ss
reg
( N df )
)
(
ss
resid
df
)
anchor:LINEST
Test Cases:
The output of the LINEST function for the following example gives :
100414201 29 May 2010
Expressions Result Result Result Comment
100414201 29 May 2010
{=LINEST([.D5
1:.D57];
[.C51:.C57];1;1
)}
2.4417721518987
300
80.17721518987
34000
82.333333333335600
0
0.4310192568130
110
5.805632138270
3600
9.3460531946624500
0.8652054520596
360
4.578900426294
9500
32.093488396964
7000
5.000000000000
0000
672.88264014466
00000
104.8316455696
260000
{=LINEST([.D5
1:.D57];
[.B51:.C57];1;1
)}
4.1666666666685
200
-
3.476190476194
2100
5.4613541259372
500
10.96442466692
42000
0.8685096742591
380
5.056231421767
9400
13.210244470316
0000
4.000000000000
0000
675.45238095239
60000
102.2619047618
940000
{=LINEST([.D5
1:.D57];
[.C51:.C57];0;1
)}
8.1236220472440
900
0.000000000000
0000
2.6966993125482
900
36.32330562663
00000
0.8652054520596
360
4.578900426294
9500
32.093488396964
7000
5.000000000000
0000
-
3325.8770528684
000000
4103.591338582
6900000
{=LINEST([.D5
1:.D57];
[.C51:.C57];1;0
2.4417721518987
300
80.17721518987
34000
100414201 29 May 2010
)}
{=LINEST([.D5
1:.D57];
[.C51:.C57];0;0
)}
8.1236220472440
900
0.000000000000
0000
6.18.42 LOGEST
Summary: Returns the array of values for an exponential curve that best fits your data.. This
function shall be entered as an array formula.
Syntax: LOGEST( Array knownY [ ; [ Array knownX ] [ ; Logical Const = TRUE() [ ; Logical Stats =
FALSE() ] ] ] )
Returns: Array
Constraints: COLUMNS(knownY) = COLUMNS(knownX), ROWS(knownY) = ROWS(knownX),
COUNT(knownY) = COUNT(knownX)
Semantics:
knownY: The set of y-values for the equation, either one single column or one single row
knownX: The set of x-values for the equation, a single column or single row matching knownY. If
omitted or an empty parameter (two consecutive ;; semicolons), it is set to the sequence
1,2,3, ., n
, where
n=COUNT (knownY )
. If one single value, it is applied to all.
Const: FALSE() to specify whether the constant b is equal to 1.
Stats: TRUE() to specify to return additional regression statistics.
Every exponential equation can be written using the form
y=ab
x
or
y=a
(
b
1
x
1
)
(
b
2
x
2
)
.
(
b
n
x
n
)
if there are multiple x-values.
where 'y' is the dependent y-value
The b-values are bases corresponding to each exponent x-value
a is a constant value.
The Functions used to calculate the LOGEST values are the same as for the LINEST function. You
have just to make the Y-Values the natural logarithmic of the given ones ( C=Y and the New Y=ln
(C)). The result for the 'a' and 'b' values has to be calculated by applying the EXP() function to the
values.
LOGEST with Stats parameter set to TRUE() returns additional statistical data in an array. They are
at the positions shown in the table :
Table 31 - LOGEST
slope (bn) slope (bn-1) ... slope (b1) intercept (a)
the slope (bn)
the slope (bn-1)
a Standard error
for the slope (b1)
b Standard error for the
intercept (a)
100414201 29 May 2010
r
2
y Standard error for
the y-Values
F Statistics degrees of freedom
(df)
SSreg Regression
sum of squares
SSresid Residual sum
of squares
anchor:LOGEST
Test Cases:
Expressions Result Result Result Comment
{=LOGEST([.D
51:.D57];
[.C51:.C57];1;1
)}
1.022 84.486
0.003 0.046
0.887 0.036
39.132 5.000
0.051 0.007
{=LOGEST([.D
51:.D57];
[.B51:.C57];1;1
)}
1.034 0.977 85.732
0.043 0.087 0.074
0.889 0.040 #N/A
15.979 4.000 #N/A
0.051 0.006 #N/A
{=LOGEST([.D
51:.D57];
[.C51:.C57];0;1
)}
1.399 1.000
0.147 1.985
0.887 0.036
39.132 5.000
-12.193 12.250
{=LOGEST([.D
51:.D57];
1.022 84.486
100414201 29 May 2010
[.C51:.C57];1;0
)}
{=LOGEST([.D
51:.D57];
[.C51:.C57];0;0
)}
1.399 1.000
TODO: Need to fix this to be in correct format.
6.18.43 LOGINV
Summary: returns the inverse of LOGNORMDIST(x;Mean;StandardDeviation,TRUE()).
Syntax: LOGINV( Number p [ ; Number Mean = 0 [ ; Number StandardDeviation = 1 ] ] )
Returns: Number
Constraints: StandardDeviation > 0 and 0 < p < 1.
Semantics: LOGINV returns the unique number x such that
LOGNORMDIST(x;Mean;StandardDeviation;TRUE()) = p.
anchor:LOGINV
Test Cases:
=LOGNORMDIST(LOGINV(0.1;0;1);0;1
;TRUE())
0.1
;TRUE())
0.3
;TRUE())
0.5
;TRUE())
0.7
;TRUE())
0.9
;TRUE())
0.1
;TRUE())
0.3
;TRUE())
0.5
;TRUE())
0.7
;TRUE())
0.9
100414201 29 May 2010
=LOGINV(0.5) 1
See also LOGNORMDIST
6.18.44 LOGNORMDIST
for the lognormal distribution with the mean and standard deviation given.
Syntax: LOGNORMDIST( Number x [ ; Number = 0 [ ; Number o = 1 [ ; Logical Cumulative =
TRUE() ] ] ] )
Returns: Number
Constraints: o > 0; x > 0 if Cumulative is FALSE()
Semantics: If Cumulative is FALSE(), LOGNORMDIST returns the value
e
1
2
(
ln( x)j
c
)
2
x .2nc
If Cumulative is TRUE(), LOGNORMDIST returns the value
0
x
e
1
2
(
ln( t)j
c
)
2
t .2nc
dt
if X > 0 and 0 otherwise.
anchor:LOGNORMDIST
Test Cases:
=LOGNORMDIST(1) 0.5
=LOGNORMDIST(1;1;4) 0.401294
=LOGNORMDIST(1;0;1;FALSE()) 0.398942
=LOGNORMDIST(1;0;1;TRUE()) 0.5
=LOGNORMDIST(1;1;4;FALSE()) 0.096667
=LOGNORMDIST(1;-1;4;FALSE()) 0.096667
=LOGNORMDIST(1;-1;4;TRUE()) 0.598706
=LOGNORMDIST(2;-1;4;FALSE()) 0.045595
=LOGNORMDIST(2;-1;4;TRUE()) 0.663957
100414201 29 May 2010
=LOGNORMDIST(-1;0;1;FALSE()) Error constraint failure
=LOGNORMDIST(-1;0;1;TRUE()) 0
=LOGNORMDIST(1;0;-1;FALSE()) Error constraint failure
Note: In Ooo2, Gnumeric and KSpread the second and third arguments are required and the last is
not allowed.
6.18.45 MAX
Summary: Return the maximum from a set of numbers.
Syntax: MAX( { NumberSequenceList N }
+
)
Returns: Number
Constraints: None.
Semantics: Returns the value of the maximum number in the list passed in. Non-numbers are
ignored. Note that if Logical types are a distinct type, they are not included. What happens when
MAX is provided 0 parameters is implementation-defined, but MAX with no parameters should
return 0.
anchor:MAX
Test Cases:
=MAX(2;4;1;-8) 4 Negative numbers are smaller than positive numbers.
=MAX([.B4:.B5]) 3 The maximum of (2,3) is 3.
=ISNA(MAX(NA())) True Inline errors are propagated.
=MAX([.B3:.B5]) 3 Strings are not converted to numbers and are ignored.
=MAX(-1;[.B7]) -1 Strings are not converted to numbers and are ignored.
=MAX([.B3:.B9]) Error Errors inside ranges are NOT ignored.
See also MAXA, MIN
Note: There was debate on whether or not we should we mandate support for zero parameters.
Excel 2002 and OOo dont support it. Gnumeric does. The compromise above gives a
recommendation without mandating it.
6.18.46 MAXA
Summary: Return the maximum from a set of values, including values of type Text and Logical.
Syntax: MAXA( { Any N }
+
)
Returns: Number
100414201 29 May 2010
Constraints: None.
Semantics: A variation of the MAX function that includes values of type Text and Logical. Text
values are treated as number 0. Logical True is treated as 1, and False is treated as 0. Empty cells
are not included. What happens when MAXA is provided 0 parameters is implementation-defined.
Any N may be of type ReferenceList.
anchor:MAXA
Test Cases:
=MAXA(2;4;1;-8) 4 Negative numbers are smaller than positive numbers.
=MAXA([.B4:.B5]) 3 The maximum of (2,3) is 3.
=ISNA(MAXA(NA())
)
True Inline errors are propagated.
=MAXA([.B3:.B5]) 3 Cell text is converted to 0.
=MAXA(-1;[.B7]) 0 Cell text is converted to 0.
=MAXA("a") Error Text inline is NOT ignored.
=MAXA([.B3:.B9]) Error Errors inside ranges are NOT ignored.
=MAXA([.B6:.B7] 1 Logicals are considered numbers.
See also MAX, MIN, MINA
Note: There was debate on whether or not we should we mandate support for zero parameters; see
the text for MAX.
6.18.47 MEDIAN
Summary: Returns the median (middle) value in the list.
Syntax: MEDIAN( { NumberSequenceList X}+ )
Returns: Number
Semantics:
MEDIAN logically ranks the numbers (lowest to highest). If given an odd number of values, MEDIAN
returns the middle value. If given an even number of values, MEDIAN returns the arithmetic average
of the two middle values.
100414201 29 May 2010
n=is thecount of the ranked numbersequence
x=x
(
( n+1)
2
)
for n=odd
x=
1
2 (
x
(
n
2
)
+x
(
n
2
+1)
)
for n=even
anchor:MEDIAN
Test Cases:
=MEDIAN([.E51:.E52]) 8.850000000
=MEDIAN([.E52;.E54];45) 7.200000000
=MEDIAN([.E52:.E55]) 7.650000000
=MEDIAN(1;3;13;14;15) 13.000000000
=MEDIAN(1;3;13;14;15;35) 13.500000000
6.18.48 MIN
Summary: Return the minimum from a set of numbers.
Syntax: MIN( { NumberSequenceList N }
+
)
Returns: Number
Constraints: None.
Semantics: Returns the value of the minimum number in the list passed in. Returns zero if no
numbers are provided in the list. What happens when MIN is provided 0 parameters is
implementation-defined, but MIN() with no parameters should return 0.
anchor:MIN
Test Cases:
=MIN(2;4;1;-8) -8 Negative numbers are smaller than positive numbers.
=MIN([.B4:.B5]) 2 The minimum of (2,3) is 2.
=MIN([.B3]) 0 If no numbers are provided in all ranges, MIN returns 0
=MIN("a") Error Non-numbers inline are NOT ignored.
100414201 29 May 2010
=MIN([.B3:.B5]) 2 Cell text is not converted to numbers and is ignored.
the discussion for MAX.
See also MAX, MINA
6.18.49 MINA
Summary: Return the minimum from a set of values, including values of type Text and Logical.
Syntax: MINA( { Any N }
+
)
Returns: Number
Constraints: None.
Semantics: A variation of the MIN function that includes values of type Text and Logical. Text
values are treated as number 0. Logical True is treated as 1, and False is treated as 0. Empty cells
are not included. What happens when MINA is provided 0 parameters is implementation-defined.
Any N may be of type ReferenceList.
anchor:MINA
Test Cases:
=MINA(2;4;1;-8) -8 Negative numbers are smaller than positive numbers.
=MINA([.B4:.B5]
)
2 The minimum of (2,3) is 2.
=MINA(1;[.B7]) 0 Cell text is converted to 0.
=MINA("a") Error Cell text inline is NOT ignored.
=MINA([.B3:.B5]
)
0 Cell text is converted to 0.
=MINA([.B6:.C6] 1 The value True is considered equivalent to 1.
Note: OOo2 has a bug that for MINA (and MAXA) formulas within an area reference returning text
are not considered cell text to be converted to 0, hence the =MINA([.B3:.B5]) test case fails.
the discussion for MAX.
See also MIN, MAXA
6.18.50 MODE
Summary: Returns the most common value in a data set.
Syntax: MODE( { ForceArray NumberSequence N }+ )
Semantics: Returns the most common value in a data set. If there are more than one values with
the same largest frequency, returns the smallest value. If the number sequence does no contain at
least two equal values, the MODE is not defined as no most common value can be found. Therefore
an Error message has to be shown.
100414201 29 May 2010
anchor:MODE
Test Cases:
=MODE([.F51:.F60]) 4
=MODE([.G51];[.G52];[.G53];[.G54];[.G55];
[.G56];[.G57];[.G58];[.G59];[.G60])
24
=MODE(1;2;3;4;5;6;7;8;9;10) Error
6.18.51 NEGBINOMDIST
Summary: Returns the negative binomial distribution.
Syntax: NEGBINOMDIST( Integer x ; Integer r ; Number p )
x The number of failures.
r The threshold number of successes.
p The probability of a success.
Returns: Number
Constraints:
If (x + r - 1) <= 0 NEGBINOMDIST returns an Error.
If p < 0 or p > 1 NEGBINOMDIST returns an Error.
Semantics:
NEGBINOMDIST returns the probability that there will be x failures before the r-th success, when
the constant probability of a success is p.
Note: This function is similar to the binomial distribution, except that the number of successes is
fixed, and the number of trials is variable. Like the binomial, trials are assumed to be independent.
P
r , p
( x)=
(
x+r1
r1
)
p
r
(1p)
x
(
x+r1
r1
)
is a binomial coefficient
anchor:NEGBINOMDIST
Test Cases:
=NEGBINOMDIST([.F20];[.I29];[.H6]) 0.000130947
100414201 29 May 2010
6.18.52 NORMDIST
for the normal distribution with the mean and standard deviation given.
Syntax: NORMDIST( Number x ; Number Mean ; Number StandardDeviation [ ; Logical Cumulative
= TRUE() ] )
Returns: Number
Constraints: StandardDeviation > 0.
Semantics: In the following
j
is Mean and
c
is StandardDeviation.
If Cumulative is FALSE(), NORMDIST returns the value
e
1
2
(
xj
c
)
2
.2nc
If Cumulative is TRUE(), NORMDIST returns the value
x
e
1
2
(
tj
c
)
2
.2nc
dt
anchor:NORMDIST
Test Cases:
=NORMDIST(0;1;4;TRUE()) 0.401293
=NORMDIST(0;0;1;FALSE()) 0.398942
=NORMDIST(0;0;1;TRUE()) 0.5
=NORMDIST(0;1;4;FALSE()) 0.096667
=NORMDIST(0;1;4;TRUE()) 0.401293
=NORMDIST(0;-1;4;FALSE()) 0.096667
=NORMDIST(0;-1;4;TRUE()) 0.598706
=NORMDIST(1;-1;4;FALSE()) 0.088016
=NORMDIST(1;-1;4;TRUE()) 0.691462
=NORMDIST(1.281552;0;1;TR
UE())
0.9
=NORMDIST(0;-
1.281552;1;TRUE())
0.9
=NORMDIST(0;0;-1;FALSE()) Error constraint failure
100414201 29 May 2010
See also LEGACY.NORMSDIST
6.18.53 NORMINV
Summary: returns the inverse of NORMDIST(x;Mean;StandardDeviation,TRUE()).
Syntax: NORMINV( Number p ; Number Mean ; Number StandardDeviation )
Returns: Number
Constraints: StandardDeviation > 0 and 0 < p < 1.
Semantics: NORMINV returns the unique number x such that
NORMDIST(x;Mean;StandardDeviation;TRUE()) = p.
anchor:NORMINV
Test Cases:
=NORMDIST(NORMINV(0.1;0;1);0;1;T
RUE())
0.1
RUE())
0.3
RUE())
0.5
RUE())
0.7
RUE())
0.9
RUE())
0.1
RUE())
0.3
RUE())
0.5
RUE())
0.7
RUE())
0.9
See also NORMDIST
6.18.54 LEGACY.NORMSDIST
Summary: returns the value of the cumulative distribution function for the standard normal
distribution.
100414201 29 May 2010
Syntax: LEGACY.NORMSDIST( Number x )
Returns: Number
Constraints: None
Semantics: LEGACY.NORMSDIST returns the value
x
e
1
2
t
2
.2n
dt
This is exactly NORMDIST(x;0;1;TRUE()).
anchor:LEGACY.NORMSDIST
Test Cases:
=LEGACY.NORMSDIST(-4) =NORMDIST(-4;0;1;TRUE())
=LEGACY.NORMSDIST(0) =NORMDIST(0;0;1;TRUE())
See also NORMDIST, LEGACY.NORMSINV
6.18.55 LEGACY.NORMSINV
Summary: returns the inverse of LEGACY.NORMSDIST(x).
Syntax: LEGACY.NORMSINV( Number p )
Returns: Number
Constraints: 0 < p < 1.
Semantics: LEGACY.NORMSINV returns NORMINV (p).
anchor:LEGACY.NORMSINV
Test Cases:
=LEGACY.NORMSINV(0.1) =NORMINV(0.1;0;1)
100414201 29 May 2010
See also NORMINV, LEGACY.NORMSDIST
6.18.56 PEARSON
Summary: PEARSON returns the Pearson correlation coefficient of two data sets
Syntax: PEARSON( ForceArray Array independent_Values ; ForceArray Array dependent_Values )
Returns: Number
Constraints: COLUMNS(independent_Values) = COLUMNS(dependent_Values),
ROWS(independent_Values) = ROWS(dependent_Values), both sequences shall contain at least
one number at corresponding positions each.
Semantics:
independent_Values represents the array of the first data set. (X-Values)
dependent_Values represents the array of the second data set. (Y-Values)
r=

i =1
N
( x
i
x)( y
i
y)
.
i=1
N
( x
i
x)
2
i=1
N
( y
i
y)
2
x , y arethe averages of the given x , y data
For an empty element or an element of type Text or Boolean in independent_Values the element at
the corresponding position of dependent_Values is ignored, and vice versa.
anchor:PEARSON
Test Cases:
=PEARSON([.A19:.A31];[.C19:.C31]) 0.045989147
=PEARSON([.C51:.C57];[.D51:.D57]) 0.930164207
=PEARSON([.C51:.C57];[.D51:.D56]) Error
6.18.57 PERCENTILE
Summary: Calculates the x-th sample percentile among the values in range.
100414201 29 May 2010
Syntax: PERCENTILE( NumberSequenceList Data ; Number x )
Returns: Number
Constraints:
COUNT(Data) > 0
0 <= x <= 1
Semantics:
Data The array or range of values to get the percentile from.
x The percentile value between 0 and 1, inclusive. If x is not a multiple of
1
n1
,
PERCENTILE interpolates to obtain the value between two data points.
Returns the x -th sample percentile of data values in Data . A percentile returns the scale value for a
data series which goes from the smallest (Alpha=0) to the largest value (Alpha=1) of a data series.
For Alpha = 25%, the percentile means the first quartile; Alpha = 50% is the MEDIAN.
Step 1:
Sort the list of numbers given by array Data.
Step 2:
Calculate the ranking 1, ., n, split into integer and decimal part
r=1+x( n1) =I +D
with
x = the percentile you want to find
n = the count of values
I = the integer part of the ranking = r
D = the decimal part of the ranking = rr
Step 3:
Interpolate between the necessary two numbers
PERCENTILE=Y
I
+D
(
Y
I +1
Y
I
)
with Y
I
being the data point ranked at position I
anchor:PERCENTILE
Test Cases:
=PERCENTILE([.A19:.A31];0.38) 24.960000000
=PERCENTILE([.A19:.A31];0.95) 2867.200000000
=PERCENTILE([.A19:.A31];0.05) 1.600000000
100414201 29 May 2010
See also MAX, MEDIAN, MIN, PERCENTRANK, QUARTILE, RANK
6.18.58 PERCENTRANK
Summary: Returns the percentage rank of a value in a sample.
Syntax: PERCENTRANK( NumberSequenceList Data ; Number X [ ; Integer Significance = 3 ] )
Returns: Number
Constraints:
COUNT(Data) > 0
MIN(Data) <= X <= MAX(Data)
INT(Significance) = Significance; Significance >= 1
Semantics:
Data is the array or range of data with numeric values.
X is the value whose rank is to be determined.
Significance is an optional value that identifies the number of significant digits for the
returned percentage value. If omitted, a value of 3 is used (0.xxx).
Returns the rank of a value in a data set Data as a percentage of the data set, a value between 0
and 1, inclusive. This function can be used to evaluate the relative standing of a value within a data
set.
For COUNT(Data) > 1, PERCENTRANK returns r / (COUNT(Data) -1), where r is the rank of X in
Data. The rank of the lowest number in Data is 0, and of the next lowest number 1, and so on. If X
is not in Data, it is assigned a fractional rank proportionately between the rank of the numbers on
either side. Specifically, if X lies between Y and Z=Y+1 (Y < X < Z) with Y being the largest number
smaller than X and Z the smallest number larger than X, and where Y has rank ry, the rank of X is
calculated as
rx=ry+
X Y
ZY
In the special case where COUNT(Data) == 1, the only valid value for X is the single value in Data,
in which case PERCENTRANK returns 1.
anchor:PERCENTRANK
Test Cases:
=PERCENTRANK([.A19:.A31];16;5) 0,33333
=PERCENTRANK([.A19:.A31];4096) 1
=PERCENTRANK([.A19:.A31];128;9) 0,583333333
See also PERCENTILE, RANK
100414201 29 May 2010
6.18.59 PERMUT
Note: This function really belongs in the Mathematics section!!
Summary: returns the number of permutations of k objects taken from n objects.
Syntax: PERMUT( Integer n ; Integer k )
Returns: Number
Constraints: n >= 0; k >= 0; n >= k
Semantics: PERMUT returns
(
n
k
)
k !
respectively
n!
( nk) !
anchor:PERMUT
Test Cases:
=PERMUT(2;2) 4
=PERMUT(4;2) 12
=PERMUT(4.3;2.1) =PERMUT(4;2)
=PERMUT(-4;2) Error
=PERMUT(4;-2) Error
6.18.60 PERMUTATIONA
Summary: Returns the number of permutations for a given number of objects (repetition allowed).
Syntax: PERMUTATIONA( Integer Total ; Integer Chosen )
Returns: Number
Constraints: Total >= 0, Chosen >= 0
Semantics: Given Total number of objects, return the number of permutations containing Chosen
number of objects, with repetition permitted. The result is 1 if Total = 0 and Chosen = 0, otherwise
the result is
PERMUTATIONA = Total
Chosen
anchor:PERMUTATIONA
Test Cases:
100414201 29 May 2010
=PERMUTATIONA([.A25];[.A20]) 4096
=PERMUTATIONA(6;3) 216
=PERMUTATIONA([.A25];2) 4096
6.18.61 PHI
Summary: Returns the values of the density function for a standard normal distribution.
Syntax: PHI( Number N )
Returns: Number
Semantics: PHI(N) is a synonym for NORMDIST(N,0,1,FALSE()).
anchor:PHI
Test Cases:
=PHI([.C23]/10) 0.381387815
=PHI(-[.C23]/10) 0.381387815
=PHI(0) 0.398942280
OOo function, Returns the values of the distribution function for a standard normal distribution.
6.18.62 POISSON
Summary: returns the probability or the cumulative distribution function for the Poisson distribution
Syntax: POISSON( Integer x ; Number i [ ; Logical Cumulative = TRUE() ] )
Returns: Number
Constraints: i > 0, x >= 0
Semantics: If Cumulative is FALSE(), POISSON returns the value
e
\
\
x
x !
If Cumulative is TRUE(), POISSON returns the value
k=0
k= x
e
\
\
k
k!
anchor:POISSON
Test Cases:
100414201 29 May 2010
=POISSON(0,1,FALSE()) 0.367880
=POISSON(0,2,FALSE()) 0.135335
=POISSON(0,1,TRUE()) =POISSON(0,1,FALSE())
=POISSON(1,1,TRUE())
=POISSON(0,1,FALSE()) +
POISSON(1,1,FALSE())
=POISSON(1.5,1,TRUE()) =POISSON(1,1,TRUE())
=POISSON(1.5,1,FALSE()) =POISSON(1,1,FALSE())
=POISSON(1,1) =POISSON(1,1,TRUE())
=POISSON(0,-1,TRUE()) Error
=POISSON(0,1.5,FALSE()) 0.223130
Note: In Ooo2, Gnumeric and KSpread all arguments are required.
6.18.63 PROB
Summary: Returns the probability that a discrete random variable lies between two limits.
Syntax: PROB( ForceArray Array Data ; ForceArray Array Probability ; Number Start [ ; Number
End ] )
Returns: Number
Constraints:
The sum of the probabilities in Probability shall equal 1.
All values in Probability shall be > 0 and <= 1.
COUNT(Data) = COUNT(Probability)
Semantics:
Data is the array or range of data in the sample ( the Number values in this array or
range are refered to below as
d
1,
d
2,
., d
n
).
Probability is the array or range of the corresponding probabilities ( the Number values in this
array or range are refered to below as
p
1,
p
2,
., p
n
).
Start is the start value (lower bound) of the interval whose probabilities are to be
summed.
End (optional) is the end value (upper bound) of the interval whose probabilities are to
be summed. If omitted, End = Start is used.
axb
Suppose that
I ( x , a , b)
denotes the indicator function that is 1 if and 0 otherwise.
Then PROB returns
100414201 29 May 2010
i=1
n
( I ( d
i
, Start , End)p
i
)
i.e. the sum of all probabilities p
i
whose corresponding data value d
i
satisfies Start d
i
End .
Note that if End Start then PROB returns 0 since in this case I (d
i
, Start , End )=0 for all i.
anchor:PROB
Test Cases:
=PROB([.H51:.H54];
[.I51:.I54];2;3)
0.5
=PROB([.H51:.H54];
[.I51:.I54];-1;1)
0.5
=PROB([.H51:.H54];
[.I51:.I54];1;2)
0.4
See also
6.18.64 QUARTILE
Summary: Returns a quartile of a set of data points.
Syntax: QUARTILE( NumberSequence Data ; Integer Quart )
Returns: Number
Constraints:
COUNT(Data) > 0
0 <= Quart <= 4
Semantics:
Data The cell range or data array of numeric values.
Quart The number of the quartile to return.
If Quart = 0, the minimum value is returned, which is equivalent to the MIN() function.
If Quart = 1, the value of the 25th percentile is returned.
If Quart = 2, the value of the 50th percentile is returned, which is equivalent to the MEDIAN()
function.
If Quart = 3, the value of the 75th percentile is returned.
If Quart = 4, the maximum value is returned, which is equivalent to the MAX() function.
Based on the statistical rank of the data points in Data, QUARTILE returns the percentile value
indicated by Quart. The percentile is calculated as Quart divided by 4. An algorithm to calculate the
percentile for a set of data points is given in the definition of PERCENTILE.
anchor:QUARTILE
100414201 29 May 2010
Test Cases:
=QUARTILE ([.A19:.A25];3) 24.000000000
=QUARTILE ([.F19:.F26];1) -22.250000000
=QUARTILE ([.A10:A15];2) Error
=QUARTILE ([.A19:A25];5) Error
=QUARTILE ([.F19:.F26];1.5) -22.250000000
=QUARTILE ({1,2,4,8,16,32,64};3) 24.000000000
See also MAX, MEDIAN, MIN, PERCENTILE, PERCENTRANK, RANK
6.18.65 RANK
Summary: R eturns the rank of a number in a list of numbers.
Syntax: RANK( Number Value ; NumberSequenceList Data [ ; Number Order = 0 ] )
Returns: Number
Constraints: Value shall exist in Data.
Semantics: The RANK function returns the rank of a value within a list.
Value the number for which to determine the rank.
Data numbers used to determine the ranking.
Order specifies how to rank the numbers:
If 0 or omitted, Data is ranked in descending order.
If not 0, Data is ranked in ascending order.
If a number in Data occurs more than once it is given the same rank, but increments the rank for
subsequent different numbers. If Value does not exist in Data an Error is returned.
anchor:RANK
Test Cases:
=RANK([.A20];[.A19:.A25];1) 2
=RANK([.A25];[.A19:.A25];0) 1
=RANK([.A21];[.A19:.A25]) 5
6.18.66 RSQ
Summary: Returns the square of the Pearson product moment correlation coefficient through data
points in known_y's and known_x's.
100414201 29 May 2010
Syntax: RSQ( ForceArray Array arrayY ; ForceArray Array arrayX )
Returns: Number
Constraints:
The arguments shall be either numbers or names, arrays, or references that contain numbers.
If an array or reference argument contains Text, Logical values, or empty cells, those values are
ignored; however, cells with the value zero are included.
If "arrayY" and "arrayX" are empty or have a different number of data points, then #N/A is returned.
COLUMNS(arrayY) = COLUMNS(arrayX), ROWS(arrayY) = ROWS(arrayX)
Semantics: The r-squared value can be interpreted as the proportion of the variance in y
attributable to the variance in x.
r
2
=
i=1
N
( y
i
y)
2
i=1
N
( y
i
y
calc
)
2
i=1
N
( y
i
y)
2
y
calc
=a+bx
and
a=
(

i=1
N
( x
i
2
)
) (

i=1
N
( y
i
)
)

(

i=1
N
( x
i
)
) (

I =1
N
( x
i
y
i
)
)
N
(

i=1
N
( x
i
2
)
)

(

i =1
N
( x
i
)
)
2
b=
N
(

i =1
N
( x
i
y
i
)
)

(

i =1
N
( x
i
)
) (

i=1
N
( y
i
)
)
N
(

i=1
N
( x
i
2
)
)

(

i =1
N
( x
i
)
)
2
The result of the RSQ function is the same as PEARSON * PEARSON.
For an empty element or an element of type Text or Boolean in arrayY the element at the
corresponding position of arrayX is ignored, and vice versa.
anchor:RSQ
Test Cases:
=RSQ ([.H19:.H31];[.I19:.I31]) 0.075215010
=RSQ ([.H19:.H31];[.I19:.I30]) #N/A
100414201 29 May 2010
See also PEARSON
6.18.67 SKEW
Summary: Estimates the skewness of a distribution using a sample set of numbers.
Syntax: SKEW( { NumberSequenceList sample }
+
)
Returns: Number
Constraints: The sequence shall contain three numbers at least.
Semantics: Estimates the skewness of a distribution using a sample set of numbers.
Given the expectation value
x
and the standard deviation estimate
s
, the skewness becomes
v=
N
( N1)( N2)
i=1
N
(
x
i
x
s
)
3
anchor:SKEW
Test Cases:
=SKEW( 1; 2; 4 ) 0.935219
Expectation value: 2.333333
Standard deviation: 1.257525
Third central moment: 0.740741
=SKEW( [.A19:.A23] ) 1.325315
=SKEW( 1; 2 ) Error At least three numbers.
See also SKEWP
6.18.68 SKEWP
Summary: Calculates the skewness of a distribution using the population of a random variable.
Syntax: SKEWP( { NumberSequence population }
+
)
Returns: Number
Constraints: The sequence shall contain three numbers at least.
Semantics: Calculates the skewness of a distribution using the population, i.e. the possible
outcomes, of a random variable.
x
and the standard deviation
c
, the skewness becomes
v=
1
N
i=1
N
(
x
i
x
c
)
3
anchor:SKEWP
Test Cases:
100414201 29 May 2010
=SKEWP( 1; 2; 4 ) 0.381802
Expectation value: 2.333333
Standard deviation: 1.247219
Third central moment: 0.740741
=SKEWP( [.A19:.A23] ) 0.889048
=SKEWP( 1; 2 ) Error Three numbers at least.
See also SKEW
6.18.69 SLOPE
Summary: Calculates the slope of the linear regression line.
Syntax: SLOPE( ForceArray Array y ; ForceArray Array x )
Returns: Number
Constraints: COLUMNS(y) = COLUMNS(x), ROWS(y) = ROWS(x), both sequences shall contain
at least one number at corresponding positions each.
Semantics: Calculates the slope of the linear regression line.
a=
i=1
N
( x
i
x)( y
i
y)
i=1
N
( x
i
x)
2
For an empty element or an element of type Text or Boolean in y the element at the corresponding
position of x is ignored, and vice versa.
anchor:SLOPE
Test Cases:
=SLOPE( [.B4:.B5];
[.C4:.C5] )
1
=SLOPE( [.A19:.A24];
[.A26:.A31] )
0.007813
See also INTERCEPT, STEYX
6.18.70 SMALL
Summary: Finds the nth smallest value in a list.
Syntax: SMALL( NumberSequenceList List ; Integer|Array N )
Returns: Number or Array
100414201 29 May 2010
Constraints: ROUNDDOWN(N;0)=N, effectively being INT(N)=N for positive numbers. If the
resulting N is <1 or larger than the size of List, Error is returned.
Semantics: If N is an array of numbers, an array of smallest values is returned.
anchor:SMALL
Test Cases:
=SMALL([.B14:.B16];1) 1
=SMALL([.B14:.B16];3) 3
=SMALL([.B14:.B16];4) Error N is greater than the length of the list
=SMALL([.B14:.B16];{1;3}) {1;3}
See also LARGE, ROUNDDOWN
6.18.71 STANDARDIZE
Summary: Calculates a normalized value of a random variable.
Syntax: STANDARDIZE( Number value ; Number mean ; Number sigma )
Returns: Number
Constraints: sigma > 0
Semantics: Calculates a normalized value of a random variable.
STANDARDIZE=
(valuemean)
sigma
anchor:STANDARDIZE
Test Cases:
=STANDARDIZE( 1; 2.5; 0.1
)
-15
=STANDARDIZE( -1; -2; 2 ) 0.5
=STANDARDIZE( 1; 1; 0 ) Error sigma > 0
See also GAUSS
6.18.72 STDEV
Summary: Compute the sample standard deviation of a set of numbers.
Syntax: STDEV( { NumberSequenceList N }
+
)
100414201 29 May 2010
Returns: Number
Constraints: At least two numbers shall be included. Returns an Error if less than two Numbers are
provided.
Semantics: Computes the sample standard deviation s, where
s
2
=
1
n1
i=1
n
( x
i
x)
2
with
x=
1
n
i=1
n
x
i
Note that s is not the same as the standard deviation of the set, , which uses n rather than n 1.
anchor:STDEV
Note: See "The Art of Computer Programming" by Donald E. Knuth, Volume 2, Third Edition, page
232, for an algorithm better than the naive algorithm.
Test Cases:
=STDEV(2;4)/SQRT(2) 1 The sample standard deviation of (2;4) is SQRT(2).
=STDEV([.B4:.B5])*SQRT(2
)
1 The sample standard deviation of (2;3) is 1/SQRT(2).
=STDEV([.B3:.B5])*SQRT(2
)
1 Strings are not converted to numbers and are ignored.
=STDEV({10000000001;100
00000002;10000000003;10
000000004;10000000005;1
0000000006;10000000007;
10000000008;10000000009
;10000000010})
3.027650
Ensure that implementations use a reasonably stable
way of calculating STDEV.
=STDEV(1) Error At least two numbers must be included
See also STDEVP, AVERAGE
6.18.73 STDEVA
Summary: Calculate the standard deviation using a sample set of values, including values of type
Text and Logical.
Syntax: STDEVA( { Any sample }
+
)
Returns: Number
Constraints: COUNTA(sample) > 1.
100414201 29 May 2010
Semantics: Unlike the STDEV function, includes values of type Text and Logical. Text values are
treated as number 0. Logical True is treated as 1, and False is treated as 0. Empty cells are not
included.
The handling of string constants as parameters is implementation-defined. Either, string constants
are converted to numbers, if possible and otherwise, they are treated as zero, or string constants
are always treated as zero.
Suppose the resulting sequence of values is x1, x2, , xn.Then let
x=
1
n
i=1
n
x
i
STDEVA returns
s=
.
1
n1
i=1
n
( x
i
x)
2
anchor:STDEVA
Test Cases:
=STDEVA(2;4)/SQRT(2) 1 The sample standard deviation of (2;4) is SQRT(2).
=STDEVA([.B5:.C6]) 2.581989 Logicals (referenced) are converted to numbers.
=STDEVA( TRUE();
FALSE() )
0.707107 Logicals (inlined) are converted to numbers.
=STDEVA(1) Error At least two numbers must be included
See also STDEV
Note: OOo Calc (2.02): Treats strings as zero in STDEVA, even if they would be convertible.
Ignores them for STDEV. Converts Logicals to {0,1} in both cases, STDEV and STDEVA.
Gnumeric (1.6.1): Converts logicals and strings (if possible) for STDEVA. Ignores both in STDEV.
6.18.74 STDEVP
Summary: Calculates the standard deviation using the population of a random variable, including
values of type Text and Logical.
Syntax: STDEVP( { NumberSequence N }
+
)
Returns: Number
Constraints: None.
Semantics: Computes the standard deviation of the set , where
c
2
=
1
n
i=1
n
( x
i
x)
2
Note that is not the same as the sample standard deviation, s, which uses n 1 rather than n.
100414201 29 May 2010
anchor:STDEVP
Test Cases:
=STDEVP(2;4) 1 The standard deviation of the set for (2;4) is 1.
=STDEVP([.B4:.B5])*2 1 The standard deviation of the set for (2;3) is 0.5.
=STDEVP([.B3:.B5])*2 1 Strings are not converted to numbers and are ignored.
=STDEVP(1) 0 STDEVP(1) is 0.
See also STDEV, AVERAGE
6.18.75 STDEVPA
Summary: Calculates the standard deviation using the population of a random variable, including
values of type Text and Logical.
Syntax: STDEVPA( { Any sample }
+
)
Returns: Number
Constraints: None.
Semantics: Unlike the STDEV function, includes values of type Text and Logical. Text values are
included.
x
the standard deviation becomes
c
2
=
1
n
i=1
n
( x
i
x)
2
In the sequence, only Numbers and Logical types are considered; cells with Text are converted to 0;
other types are ignored. If Logical types are a distinct type, they are still included, with True
considered 1 and False considered 0. Any sample may be of type ReferenceList.
anchor:STDEVPA
Test Cases:
=STDEVPA(2;4) 1 The sample standard deviation of (2;4) is 1.
=STDEVPA([.B5:.C6]) 2.236068 Logicals (referenced) are converted to numbers.
=STDEVPA( TRUE();
FALSE() )
100414201 29 May 2010
See also STDEVP
Note:
OOo Calc (2.02): Treats strings as zero in STDEVA, even if they would be convertible. Ignores them
for STDEV. Converts Logicals to {0,1} in both cases, STDEV and STDEVA.
Gnumeric (1.6.1): Converts logicals and strings (if possible) for STDEVA. Ignores both in STDEV.
6.18.76 STEYX
Summary: Calculates the standard error of the predicted y value for each x in the regression.
Syntax: STEYX( ForceArray Array measuredY ; ForceArray Array X )
Returns: Number
Constraints: COLUMNS(measuredY) = COLUMNS(X), ROWS(measuredY) = ROWS(X), both
sequences shall contain at least three numbers at corresponding positions each.
Semantics: Calculates the standard error of the predicted y value for each x in the regression.
STEYX=
.
1
n(n2)
(
n
n
y
i
2
(

n
y
i
)
2
(
n
n
x
i
y
i
n
x
i
n
y
i
)
2
n
n
x
2
n
x
)
2
)
For an empty element or an element of type Text or Boolean in measuredY the element at the
corresponding position of X is ignored, and vice versa.
anchor:STEYX
Test Cases:
=STEYX( [.C19:.C23];
[.A19:.A23] )
2.370953
=STEYX( [.A19:.A23];
[.A25:.A29] )
0
=STEYX( [.B4:.B5];
[.C4:.C5] )
Error at least three number per sequence
See also INTERCEPT, SLOPE
6.18.77 LEGACY.TDIST
Summary: Returns the area ot the tail or tails of the probability density function of the t-distribution.
Syntax: LEGACY.TDIST( Number x ; Integer df ; Integer tails)
Returns: Number
Constraints: x0, df 1, tails = 1 or 2
Semantics: Then LEGACY.TDIST returns
100414201 29 May 2010
tails
f (t )dt
where
f (t )=
I
(
df +1
2
)
.ndf I
(
df
2
)
(
1+
t
2
df
)
( df +1)
2
Note that df denotes the degrees of freedom of the t-distribution and is the Gamma function.
anchor:LEGACY.TDIST
Test Cases:
=LEGACY.TDIST( 0.5; 1; 1 ) 0.352416
=LEGACY.TDIST( -1.5; 2;
2 )
0.272393
=LEGACY.TDIST( 0.5; 5; 1 ) 0,319149
=LEGACY.TDIST( 1; 1; 3 ) Error mode = { 1; 2 }
=LEGACY.TDIST( 1; 0; 1 ) Error degreeOfFreedom >= 1
See also BETADIST, BINOMDIST, CHISQDIST, EXPONDIST, FDIST, GAMMADIST, GAUSS,
HYPGEOMDIST, LOGNORMDIST, NEGBINOMDIST, NORMDIST, POISSON, WEIBULL
6.18.78 TINV
Summary: Calculates the inverse of the two-tailed t-distribution.
Syntax: TINV( Number probability ; Integer degreeOfFreedom )
Returns: Number
Constraints: 0 < probability <= 1, degreeOfFreedom >= 1
Semantics: Calculates the inverse of the two-tailed t-distribution.
anchor:TINV
Test Cases:
=TINV( 1; 2 ) 0 p=1 -> t=0
=TINV( 0.5; 2 ) 0.816497
=TINV( 0.25; 3 ) 1.422625
=TINV( 2; 3 ) Error 0 <= probability <= 1
100414201 29 May 2010
=TINV( 1; 0 ) Error degreeOfFreedom >= 1
See also LEGACY.TDIST
6.18.79 TREND
Summary: Calculates a sequence of values based on a linear regression of known value pairs.
Syntax: TREND( NumberSequence knownY [ ; [ NumberSequence knownX ] [ ; [
NumberSequence newX ] [ ; Logical allowOffset = TRUE() ] ] ] )
Returns: Array
Constraints: COUNT(knownY) = COUNT(knownX), COLUMNS(knownY) = COLUMNS(knownX),
ROWS(knownY) = ROWS(knownX)
Semantics: Calculates a sequence of values based on a linear regression of known value pairs.
If knownX is omitted or an empty parameter (two consecutive ;; semicolons), it is set to the
sequence
1,2,3 ,., n
, where
n=COUNT ( knownY )
.
If newX is omitted or an empty parameter (two consecutive ;; semicolons), it is set to be equal to
knownX.
If allowOffset is TRUE:
TREND=SLOPE( knownY ; knownX )newX +INTERCEPT (knownY ; knownX )
If allowOffset is FALSE:
anchor:TREND
TODO: Formula for this case.
Test Cases:
=TREND( [.A19:.A23];
[.C19:.C23]; 1 )
4.755556
=TREND( [.A19:.A23];
[.C19:.C23]; 1; 0 )
1.682540
See also INTERCEPT, SLOPE , STEYX
6.18.80 TRIMMEAN
Summary: Returns the mean of a data set, ignoring a proportion of high and low values.
Syntax: TRIMMEAN( NumberSequenceList dataSet ; Number cutOffFraction )
Returns: Number
Constraints: 0 cutOffFraction < 1
Semantics: Returns the mean of a data set, ignoring a proportion of high and low values.
100414201 29 May 2010
Let n denote the number of elements in the data set and let
sortedDataSet
1,
sortedDataSet
2,
sortedDataSet
3,
, sortedDataSet
n
be the values in the data set sorted in ascending order. Moreover let
cutOff =INT
(
ncutOffFraction
2
)
Then TRIMMEAN returns the value
1
n2cutOff

i=cutOff +1
ncutOff
sortedDataSet
i
anchor:TRIMMEAN
Test Cases:
=TRIMMEAN( [.A19:.A23];
0.8 )
4 cutOff = 2
0.6 )
4.666667
cutOff = INT(5 * 0.6/ 2) = INT(1.5) = 1;
result = 14 / 3
0.19 )
6.2 cutOff = 0
0.999999 )
4 cutOff = 2
1)
Error 0 <= cutOffFraction < 1
See also AVERAGE , GEOMEAN , HARMEAN
6.18.81 TTEST
Summary: Calculates the p-value of a 2-sample t-test.
Syntax: TTEST( ForceArray Array X ; ForceArray Array Y ; Integer tails ; Integer type )
Returns: Number
Constraints: COUNT(X)>1, COUNT(Y)>1, tails = 1 or 2, type = 1,2, or 3, (COUNT(X)=COUNT(Y)
or type 1)
COLUMNS(X) = COLUMNS(Y), ROWS(X) = ROWS(Y)
Semantics: Let X1, X2, ,Xn be the numbers in the sequence X and Y1, Y2, ,Ym be the numbers
in the sequence Y. Then
X=
1
n
i=1
n
X
i
and
100414201 29 May 2010
Y =
1
m
i=1
m
Y
i
Moreover let
s
X
2
=
1
n1
i=1
n
( X
i
X)
2
s
Y
2
=
1
m1
i=1
m
(Y
i
Y )
2
and
f ( x , df )=
I
(
df +1
2
)
.
ndf I
(
df
2
)
(
1+
x
2
df
)
( df +1)
2
where is the Gamma function.
(1) If type = 1, TTEST calculates the p-value for a paired-sample comparison of means test.
Note that in this case due to the above constraints n=m. With
s
XY
2
=
1
n1
i=1
n
(( X
i
Y
i
)( XY ))
2
and
t =
X Y
.
s
X Y
2
. n
TTEST returns
tails
f ( x , n1)dx
(2) If type = 2, TTEST calculates the p-value of a comparison of means for independent
samples from populations with equal variance. With
s
p
2
=
(n1) s
X
2
+( m1) s
Y
2
n+m2
and
t =
XY
.
s
p
2
(
1
n
+
1
m
)
TTEST returns
tails
f ( x , n+m2)dx
(3) If type = 3, TTEST calculates the p-value of a comparison of means for independent
samples from populations with not necessarily equal variances. With
100414201 29 May 2010
t =
XY
.
s
X
2
n
+
s
Y
2
m
and
v=
(
S
X
2
n
+
S
Y
2
m
)
2
(
S
X
2
n
)
2
(n1)
+
(
S
Y
2
m
)
2
(m1)
TTEST returns
tails
f ( x , v) dx
For an empty element or an element of type Text or Boolean in X the element at the corresponding
position of Y is ignored, and vice versa.
anchor:TTEST
Test Cases:
=TTEST( [.A19:.A23];
[.A24:.A28]; 1; 1 )
0.042721
=TTEST( [.A19:.A23];
[.A24:.A28]; 2; 1 )
0.085441
=TTEST( [.A19:.A23];
[.A24:.A28]; 1; 2 )
0.029454
=TTEST( [.A19:.A23];
[.A24:.A28]; 1; 3 )
0.046213
=TTEST( [.A19:.A23];
[.A24:.A29]; 1; 1 )
Error same amount of numbers for paired samples
=TTEST( [.A19:.A19];
[.A24:.A24]; 1; 3 )
Error two numbers at least for each sequence
See also FTEST, LEGACY.TDIST, ZTEST
6.18.82 VAR
Summary: Compute the sample variance of a set of numbers.
Syntax: VAR( { NumberSequence N }
+
)
Returns: Number
100414201 29 May 2010
Constraints: At least two numbers shall be included. Returns an Error if less than two Numbers are
provided.
Semantics: Computes the sample variance s
2
, where
s
2
=
1
n1
i=1
n
( x
i
x)
2
=
1
n1
((
i =1
n
x
i
2
)
n x
2
)
Note that s
2
is not the same as the variance of the set,
2
, which uses n rather than n 1.
anchor:VAR
Test Cases:
=VAR(2;4) 2 The sample variance of (2;4) is 2.
=VAR([.B4:.B5])*2 1 The sample variance of (2;3) is 0.5.
=VAR([.B3:.B5])*2 1 Strings are not converted to numbers and are ignored.
=VAR(1) Error At least two numbers must be included
See also VARP, STDEV, AVERAGE
6.18.83 VARA
Summary: Estimates the variance using a sample set of values, including values of type Text and
Logical.
Syntax: VARA( { Any sample }
+
)
Returns: Number
Constraints: The sequence shall contain two numbers at least.
Semantics: Unlike the VAR function, includes values of type Text and Logical. Text values are
included.
x
the estimated variance becomes
s
2
=
1
n1
i=1
n
( x
i
x)
2
=
1
n1
((
i =1
n
x
i
2
)
n x
2
)
anchor:VARA
100414201 29 May 2010
Test Cases:
=VARA(2;4) 2 The sample variance of (2;4) is 2.
=VARA([.B5:.C6]) 6.666667 Logicals (referenced) are converted to numbers.
=VARA( TRUE(); FALSE() ) 1 Logicals (inlined) are converted to numbers.
=VARA(1) Error Two numbers at least.
See also VAR
Note:
OOo Calc (2.02): Treats strings as zero in VARA, even if they would be convertible. Ignores them for
VAR. Converts Logicals to {0,1} in both cases, VAR and VARA.
Gnumeric (1.6.1): Converts logicals and strings (if possible) for VARA. Ignores both in VAR.
6.18.84 VARP
Summary: Compute the variance of the set for a set of numbers.
Syntax: VARP( { NumberSequence N }
+
)
Returns: Number
Constraints: COUNT(N)>=1
Semantics: Computes the variance of the set
2
, where
c
2
=
1
n
i=1
n
( x
i
x)
2
=
1
n
((
i=1
n
x
i
2
)
n x
2
)
Note that
2
is not the same as the sample variance, s
2
, which uses n 1 rather than n.
If only one number is provided, returns 0.
anchor:VARP
Test Cases:
=VARP(2;4) 1 The variance of the set for (2;4) is 1.
=VARP([.B4:.B5])*4 1 The variance of the set for (2;3) is 0.25.
=VARP([.B3:.B5])*4 1 Strings are not converted to numbers and are ignored.
See also VAR, STDEVP, AVERAGE
100414201 29 May 2010
6.18.85 VARPA
Summary: Calculates the variance using the population of the distribution, including values of type
Text and Logical.
Syntax: VARPA( { Any sample }
+
)
Returns: Number
Constraints: None
Semantics: Unlike the VARP function, includes values of type Text and Logical. Text values are
included.
x
the variance becomes
c
2
=
1
n
i=1
n
( x
i
x)
2
=
1
n
((
i=1
n
x
i
2
)
n x
2
)
anchor:VARPA
Test Cases:
=VARPA(2;4) 1 The sample variance of (2;4) is 1.
=VARPA([.B5:.C6]) 4 Logicals (referenced) are converted to numbers.
=VARPA( TRUE();
FALSE() )
See also VARP
Note:
OOo Calc (2.02): Treats strings as zero in VARA, even if they would be convertible. Ignores them for
VAR. Converts Logicals to {0,1} in both cases, VAR and VARA.
Gnumeric (1.6.1): Converts logicals and strings (if possible) for VARA. Ignores both in VAR.
6.18.86 WEIBULL
Summary: Calculates the Weibull distribution.
Syntax: WEIBULL( Number value ; Number alpha ; Number beta ; Logical cumulative )
Returns: Number
Constraints: value >= 0; shape > 0; scale > 0
100414201 29 May 2010
Semantics: Calculates the Weibull distribution at the position value.
If cumulative is false, the probability density function is calculated:
shape
scale
(
value
scale
)
shape1
e
(
value
scale
)
shape
If cumulative is true, the cumulative distribution function is calculated:
1e
(
value
scale
)
shape
anchor:WEIBULL
Test Cases:
=WEIBULL( 2; 3; 4; 0 ) 0.165468 pdf
=WEIBULL( 2; 3; 4; 1 ) 0.117503 cdf
=WEIBULL( -1; 3; 4; 0 ) Error value >= 0
=WEIBULL( 2; 0; 4; 0 ) Error alpha > 0
=WEIBULL( 2; 3; 0; 0 ) Error beta > 0
See also BETADIST, BINOMDIST, CHISQDIST, EXPONDIST, FDIST, GAMMADIST, GAUSS,
HYPGEOMDIST, LOGNORMDIST, NEGBINOMDIST, NORMDIST, POISSON, LEGACY.TDIST
6.18.87 ZTEST
Summary: Calculates the probability of observing a sample mean as large or larger than the mean
of the given sample for samples drawn from a normal distribution.
Syntax: ZTEST( NumberSequenceList sample ; Number mean [ ; Number sigma ] )
Returns: Number
Constraints: The sequence sample shall contain at least two numbers.
Semantics: Calculates the probability of observing a sample mean as large or larger than the mean
of the given sample for samples drawn from a normal distribution with the given mean mean and the
given standard deviation sigma. If sigma is omitted, it is estimated from sample, using STDEV. With
sample being the mean of sample and
z=
samplemean
sigma
.n
ZTEST returns
P ( zZ )=
1
.2n
x
2
2
dx
anchor:ZTEST
100414201 29 May 2010
Test Cases:
=ZTEST( [.B4:.C5]; 3.5 ) 0
mean = average, estimated standard deviation:
fits well
=ZTEST( [.B4:.C5]; 3; 2 ) 0.382925
mean near average, standard deviation greater than
estimate:
probable
=ZTEST( [.B4:.C5]; 4; 0.5) 0.954500
mean near the average, but small deviation:
not probable
=ZTEST( [.B4:.C5]; 5 ) 0.979863
mean at a border value, standard deviation ~ 1,3:
nearly improbable
=ZTEST( [.B4:.C5]; 5; 0.1 ) 1
mean at a border value, small standard deviation:
improbable
See also FTEST, TTEST
6.19 Number Representation Conversion Functions
6.19.1 General
These functions convert between different representations of numbers, such as between different
bases and Roman numerals.
The base conversion functions xxx2BIN (such as DEC2BIN), xxx2OCT, and xxx2HEX functions
return Text, while the xxx2DEC functions return Number. All of the xxx2yyy functions accept either
Text or Number, though a Number is interpreted as the digits when printed in base 10. These are
intended to support relatively small numbers, and have a somewhat convoluted interface and
semantics, as described in their specifications. General base conversion capabilities are provided by
BASE and DECIMAL.
As an argument for the HEX2xxx functions, a hexadecimal number is any string consisting solely of
the characters "0","1" to "9", "a" to "f" and "A" to "F". The hexadecimal output of an xxx2HEX
function _shall_ be a string consisting solely of the characters "0","1" to "9" (U+0030 through
U+0039), "a" to "f" (U+0061 through U+0066) and "A" to "F" (U+0041 through U+0046), and should
be a string consisting solely of the characters "0","1" to "9" and "A" to "F". In both cases, the 40th bit
(from the right) is considered a sign bit.
6.19.2 ARABIC
Summary: Convert Roman numerals to Number.
Syntax: ARABIC( Text X )
Returns: Number
Constraints: X shall contain Roman numerals, or an empty string.
Semantics: Converts the Roman numeral to Number. This is the reverse of ROMAN; see ROMAN
for the values of individual Roman numeral symbols. A Roman symbol to the left of a larger symbol
100414201 29 May 2010
(directly or indirectly) reduces the final value by the symbol amount, otherwise, it increases the final
amount by the symbol's amount. Case is ignored.
The following identity shall hold: ARABIC(ROMAN(x; any)) = x, when ROMAN(x; any) is not an
Error.
If X is an empty string, 0 is returned.
anchor:ARABIC
Note: Historically, larger numbers were written by writing an overbar over the characters (which
multiplied them by 1,000); today Roman numerals are not usually used for numbers large enough to
justify mandating support for this, and supporting them is complicated since many character
systems cannot handle them.
Test Cases:
=ARABIC("I") 1 Simple value
=ARABIC("CDLII") 452 452
=ARABIC("MCDXC") 1490 1490
=ARABIC("MDCCCXCIX") 1899 1899
=ARABIC("MCMXCIX") 1999 1999
=ARABIC("MMCMXCIII") 2993 2993
=ARABIC("MMMCMXCIX") 3999 3999, the largest portable value for this function.
=ARABIC("mmmcmxcix") 3999 Case is ignored
=ARABIC("MIM") 1999
ARABIC can handle non-traditional
representations of Roman numerals
=ARABIC("IVX") Error V may not be followed by X
See also Infix Operator "&", ROMAN
Note: This is a well-known missing function in MS Excel. For example, Walkenbach's "Excel 2003
Formulas" page 163 notes how odd it is that Excel lacks this kind of functionality. This function is
already implemented in OpenOffice.org Calc and in Kspread.
6.19.3 BASE
Summary: Converts a number into a text representation with the given base.
Syntax: BASE( Integer X ; Integer Radix [ ; Integer MinimumLength ] )
Returns: Text
Constraints: X 0, 2 Radix 36, MinimumLength 0
Semantics: Converts number X into text that represents the value of X in base Radix. The symbols
0-9 (U+0030 through U+0039), then upper case A-Z (U+0041 through U+005A) are used as digits.
Thus, BASE(45745;36) returns ZAP.
100414201 29 May 2010
If MinimumLength is not supplied, the generated text uses the smallest number of characters (i.e., it
does not add leading 0s). If MinimumLength is supplied, and the resulting text would normally be
smaller than MinimumLength, leading 0s are added to produce text exactly MinimumLength
characters long. If the text is longer than the MinimumLength argument, the MinimumLength
parameter is ignored.
anchor:BASE
Test Cases:
=BASE(23;10) "23" Base 10 is permitted as a Radix
=BASE(6;2) 110 Base 2.
=BASE(0;3) 0
0 is the same in any base. Base 3 is supported,
too
=BASE(6;2;4) 0110 Base 2.
=BASE(6;2;1) 110 If minimum is too small, it's ignored
=BASE(45745;36) "ZAP"
Base 36 is sometimes used to encode values; it
is handy for such purposes, since all digits and
letters A-Z can be used. Uppercase letters used.
=ISTEXT(BASE(6;2)) True BASE produces values of type Text.
=ISNUMBER(BASE(6;2)) False BASE produces values of type Text, not Number.
=BASE(10;16) A Base 16 (hexadecimal)
=BASE(1025;2)
10000000001
Base 2; note that we aren't limited to 10 digits,

and no position is considered the sign bit.
See also DECIMAL
6.19.4 BIN2DEC
Summary: Converts a binary (base 2) number (up to 10 digits) to its decimal equivalent
Syntax: BIN2DEC( TextOrNumber X )
Returns: Number
Constraints: X shall contain only binary digits (no space or other characters), and shall contain at
least one binary digit. When considered as a Number, INT(X)=X. Evaluators may evaluate
expressions where the digits in X are only 0 or 1, no more than 10 digits.
Semantics: Converts given binary number into decimal equivalent, with the topmost 10
th
digit being
the sign bit (using a two's complement representation). If given Text, the text is considered a binary
number representation. If given a Number, the digits of the number when printed as base 10 are
considered the digits of the equivalently-represented binary number. It is implementation-defined
what happens if given a Logical value; an evaluator may produce an Error, or it may convert the
Logical to Number (per Convert to Number) and then process as a Number.
If any digits are 2 through 9, an evaluator shall return an Error. It is implementation-defined what
happens if an evaluator is given an empty string; evaluators may return an Error or 0 in such cases.
100414201 29 May 2010
anchor:BIN2DEC
Test Cases:
=BIN2DEC("101") 5 Simple translation. 101 in base 2 is 4+1 = 5.
=BIN2DEC(101) 5
Take the digits of the base 10 number, and consider it as if it
were base 2 then convert.
=ISNUMBER(BIN2D
EC("101"))
True Conversion to decimal returns a Number.
=ISTEXT(BIN2DEC(
101))
False
Conversion to decimal does not yield text (while the reverse,
DEC2BIN, does indeed yield text)
=ISNUMBER(BIN2D
EC(101))
True Conversion to decimal returns a Number.
=ISTEXT(BIN2DEC(
101))
False
Conversion to decimal does not yield text (while the reverse,
DEC2BIN, does indeed yield text)
=BIN2DEC("2") Error 2 is not a binary digit.
=BIN2DEC(2) Error 2 is not a binary digit.
=BIN2DEC("1011100
10")
370 Simple translation for 9 digits
=BIN2DEC(10111001
0)
=BIN2DEC(0) 0
=BIN2DEC(11111111
1)
=BIN2DEC("11111111
1")
=BIN2DEC("11111111
11")
-1
10 ones is -1, because the 10
th
bit is the sign, and it is two's
complement representation
=BIN2DEC(111111111
1)
-1 Can accept Number as well
=BIN2DEC("11111111
01")
-3
=BIN2DEC("1000000
000")
-512
Note: This use of the 10
th
bit as a sign bit is very odd, but it's widespread; it is implemented In
Excel2003 and OpenOffice.org 2.0.3, and almost certainly many others. Thus
=BIN2DEC("1011100100") produces the negative number -284 instead of the putatively correct
value, 740. This is a very dubious practice, but it's also extremely widespread
100414201 29 May 2010
6.19.5 BIN2HEX
Summary: Converts a binary (base 2) number (10
th
bit is sign) to its hexadecimal equivalent
Syntax: BIN2HEX( TextOrNumber X [ ; Number Digits ] )
Returns: Text
Semantics: Converts given binary number into hexadecimal (base 16) equivalent. For input value
X, the topmost 10
th
digit is considered the sign bit (using a two's complement representation). If
given Text, the text is considered a binary number representation. If given a Number, the digits of
the number when printed as base 10 are considered the digits of the equivalently-represented
binary number. It is implementation-defined what happens if given a Logical value; an evaluator may
produce an Error, or it may convert the Logical to Number (per Convert to Number) and then
process as a Number.
If any digits in X are 2 through 9, an evaluator shall return an Error. It is implementation-defined
what happens if an evaluator is given an empty string; evaluators may return an Error or 0 in such
cases.
The resulting value is a hexadecimal value, up to 10 hexadecimal digits, with the topmost bit (40
th
bit) being the sign bit and in two's complement form. The digits A through F are in uppercase. If the
input has its 10
th
bit on, the Digits argument is ignored; otherwise, the Digits indicates the number of
digits in the output, with leading 0 digits added as necessary to bring it up to that number of digits. If
there are more digits required than the Digits parameter specifies, the results are implementation-
defined.
anchor:BIN2HEX
Test Cases:
=BIN2HEX("101") "5" Simple translation. 101 in base 2 is 4+1 = 5.
=BIN2HEX(101) "5"
=ISNUMBER(BIN2H
EX("101"))
False Conversion does not return a Number.
=ISTEXT(BIN2HEX(
101))
True Conversion yields text
=ISNUMBER(BIN2H
EX(101))
=ISTEXT(BIN2HEX(
101))
=BIN2HEX("2") Error 2 is not a binary digit.
=BIN2HEX(2) Error 2 is not a binary digit.
=BIN2HEX("1011100
10")
"172" Simple translation for 9 digits
100414201 29 May 2010
=BIN2HEX(10111001
0)
=BIN2HEX(10111001
0;8)
"00000172" If digits given, adds leading zeros as necessary
=BIN2HEX(0) "0"
=BIN2HEX(11111111
1)
"1FF" Simple translation for 9 digits
=BIN2HEX("11111111
1")
"1FF" Simple translation for 9 digits
=BIN2HEX("11111111
11")
"FFFFFFFFF
F"
th
complement representation
=BIN2HEX(111111111
1)
"FFFFFFFFF
F"
Can accept Number as well
=BIN2HEX("11111111
01")
"FFFFFFFFF
D"
=BIN2HEX("1000000
000")
"FFFFFFFE0
0"
6.19.6 BIN2OCT
Summary: Converts a binary (base 2) number (10
th
bit is sign) to its octal (base 8) equivalent
Syntax: BIN2OCT( TextOrNumber X [ ; Number Digits ] )
Returns: Text
Semantics: Converts given binary number into octal (base 8) equivalent. For input value X, the
topmost 10
th
digit is considered the sign bit (using a two's complement representation). If given Text,
the text is considered a binary number representation. If given a Number, the digits of the number
when printed as base 10 are considered the digits of the equivalently-represented binary number. It
is implementation-defined what happens if given a Logical value; an evaluator may produce an
Error, or it may convert the Logical to Number (per Convert to Number) and then process as a
Number.
If any digits in X are 2 through 9, an evaluator shall return an Error. It is implementation-defined
what happens if an evaluator is given an empty string; evaluators may return an Error or 0 in such
cases.
The resulting value is an octal value, up to 10 octal digits, with the topmost bit (30
th
bit) being the
sign bit and in two's complement form. If the input has its 10
th
bit on, the Digits argument is ignored;
otherwise, the Digits indicates the number of digits in the output, with leading 0 digits added as
necessary to bring it up to that number of digits. If there are more digits than specified by the Digits
parameter, its results are implementation-defined.
anchor:BIN2OCT
100414201 29 May 2010
Test Cases:
=BIN2OCT("101") "5" Simple translation. 101 in base 2 is 4+1 = 5.
=BIN2OCT(101) "5"
=ISNUMBER(BIN2O
CT("101"))
False Conversion to octal does not return a Number.
=ISTEXT(BIN2OCT(
101))
True Conversion to octal does yield text
=ISNUMBER(BIN2O
CT(101))
False Conversion to octal does not return a Number.
=ISTEXT(BIN2OCT(
101))
True Conversion to octal yields text
=BIN2OCT("2") Error 2 is not a binary digit.
=BIN2OCT(2) Error 2 is not a binary digit.
=BIN2OCT("1011100
10")
=BIN2OCT(10111001
0)
=BIN2OCT(10111001
0;8)
"00000562" If digits given, adds leading zeros as necessary
=BIN2OCT(0) "0"
=BIN2OCT(11111111
1)
=BIN2OCT("11111111
1")
=BIN2OCT("11111111
11")
"7777777777
"
th
complement representation. Translates to octal equivalent with
10 digits, where topmost bit is sign bit
=BIN2OCT(11111111
11)
"7777777777
"
=BIN2OCT("11111111
01")
"7777777775
"
=BIN2OCT("1000000
000")
"7777777000
"
6.19.7 DEC2BIN
Summary: Converts a decimal number to base 2 (whose 10
th
bit is sign)
100414201 29 May 2010
Syntax: DEC2BIN( TextOrNumber X [ ; Number Digits ] )
Returns: Text
Constraints: X shall contain only decimal digits (no space or other characters), and shall contain at
least one decimal digit. When considered as a Number, INT(X)=X. Evaluators may evaluate
expressions where -512 <= X <= 511.
Semantics: Converts given number into binary (base 2) equivalent. If given Text, the text is
considered a decimal number representation, and may have a leading minus sign. It is
implementation-defined what happens if given a Logical value; an evaluator may produce an Error,
or it may convert the Logical to Number (per Convert to Number) and then process as a Number.
The resulting value is a binary value, up to 10 digits, with the topmost bit (10
th
bit) being the sign bit
and in two's complement form. If the input is negative, the Digits argument is ignored; otherwise, the
Digits indicates the number of digits in the output, with leading 0 digits added as necessary to bring
it up to that number of digits. If there are more digits than specified by the Digits parameter, the
results are implementation-defined.
anchor:DEC2BIN
Test Cases:
=DEC2BIN("5") "101" Simple translation. 101 in base 2 is 4+1 = 5.
=DEC2BIN(5) "101"
=ISNUMBER(DEC2B
IN("5"))
=ISTEXT(DEC2BIN(
5))
True Conversion does yield text
=ISNUMBER(DEC2B
IN(5))
=ISTEXT(DEC2BIN(
5))
=DEC2BIN("A") Error A is not a decimal digit.
=DEC2BIN("370") "101110010" Simple translation for 9 digits
=DEC2BIN(370) "101110010" Simple translation for 9 digits
=DEC2BIN(5;8) "00000101" If digits given, adds leading zeros as necessary
=DEC2BIN(0) "0"
=DEC2BIN(511) "111111111"
Simple translation to 9 digits (largest binary number supported
by this function)
=DEC2BIN("511") "111111111" Simple translation for 9 digits
=DEC2BIN("-1") "1111111111"
th
complement representation.
=DEC2BIN(-1) "1111111111" Can accept Number as well
100414201 29 May 2010
=DEC2BIN(-3) "1111111101"
=DEC2BIN(-512)
"1000000000
"
6.19.8 DEC2HEX
th
bit is sign)
Syntax: DEC2HEX( TextOrNumber X [ ; Number Digits ] )
Returns: Text
expressions where -2
39
<= X <= 2
39
-1.
Semantics: Converts given number into hexadecimal (base 16) equivalent. If given Text, the text is
The resulting value is a hexadecimal value, up to 10 digits, with the topmost bit (40
th
bit) being the
sign bit and in two's complement form. If the input is negative, the Digits argument is ignored;
parameter, the results are implementation-defined.
anchor:DEC2HEX
Test Cases:
=DEC2HEX("5") "5" Simple translation.
=DEC2HEX(5) "5"
=ISNUMBER(DEC2H
EX("5"))
=ISTEXT(DEC2HEX(
"5"))
=ISNUMBER(DEC2H
EX(5))
=ISTEXT(DEC2HEX(
5))
=DEC2HEX("A") Error A is not a decimal digit.
=DEC2HEX("590") "24E"
=DEC2HEX(590) "24E"
=DEC2HEX(590;8) "0000024E" If digits given, adds leading zeros as necessary
100414201 29 May 2010
=DEC2HEX(0) "0"
=DEC2HEX(5497558
13887)
"7FFFFFFFF
F"
Largest number
=DEC2HEX("549755
813887")
"7FFFFFFFF
F"
Largest number
=DEC2HEX(-
549755813888)
"8000000000
"
Smallest number
=DEC2HEX("-1")
"FFFFFFFFF
F"
th
complement representation.
=DEC2HEX(-1)
"FFFFFFFFF
F"
=DEC2HEX(-3)
"FFFFFFFFF
D"
=DEC2HEX(-512)
"1000000000
"
6.19.9 DEC2OCT
th
bit is sign)
Syntax: DEC2OCT( TextOrNumber X [ ; Number Digits ] )
Returns: Text
expressions where -2
29
<= X <= 2
29
-1.
Semantics: Converts given number into octal (base 8) equivalent. If given Text, the text is
The resulting value is a octal value, up to 10 digits, with the topmost bit (30
th
and in two's complement form. If the input is negative, the Digits argument is ignored; otherwise, the
Digits indicates the number of digits in the output, with leading 0 digits added as necessary to bring
it up to that number of digits. If there are more digits than specified by the Digits parameter, the
results are implementation-defined.
anchor:DEC2OCT
Test Cases:
=DEC2OCT("28") "34" Simple translation.
=DEC2OCT(28) "34"
=ISNUMBER(DEC2 False Conversion does not return a Number.
100414201 29 May 2010
OCT("5"))
=ISTEXT(DEC2OCT(
"5"))
=DEC2OCT(590;8) "00001116" If digits given, adds leading zeros as necessary
=DEC2OCT(5368709
11)
"3777777777
"
Largest number
=DEC2OCT("536870
911")
"3777777777
"
Largest number
=DEC2OCT(-
536870912)
"4000000000
"
Smallest number
=DEC2OCT("-1")
"7777777777
"
Minus one.
See also OCT2DEC
6.19.10 DECIMAL
Summary: Converts text representing a number in a given base into a base 10 number.
Syntax: DECIMAL( Text X ; Integer Radix )
Returns: Number
Constraints: 2 Radix 36
Semantics: Converts text X in base Radix to a Number. Uppercase letters (U+0041 through
U+005A) and lowercase letters (U+0061 through U+007A) are both accepted as equivalent if Radix
> 10. Thus, DECIMAL("zap";36) and DECIMAL("ZAP";36) both compute 45745.
An Error is returned if X has characters that do not belong in base Radix. However, leading spaces
and tabs in X are always ignored. If Radix is 16, a leading regular expression 0?[Xx] is ignored, as
is a trailing letter H or h. If Radix is 2, the letter b or B at the end is ignored (if present).
anchor:DECIMAL
Test Cases:
=DECIMAL(23;10) 23 Base 10 is permitted as a Radix
=DECIMAL(0110;2) 6
Base 2. Note leading zeros are fine (they have no effect on
the final answer, of course)
=DECIMAL("101B";2) 5 Letter B at end of base 2 is ignored
=DECIMAL(A;10) Error Invalid letter yields an error
=DECIMAL(A;16) 10 Hexadecimal
=DECIMAL(0xA9;1
6)
169 Hexadecimal drops leading 0x
100414201 29 May 2010
=DECIMAL(A9H;16
)
169 Trailing H dropped in base 16
=DECIMAL(0xA9H;
16)
169 Trailing H and leading 0x both dropped in base 16
=DECIMAL(
0xA9H;16)
169 Leading spaces are ignored
=DECIMAL( 0 x A 9
H ;16)
Error Spaces in between are not ignored
=DECIMAL("101001
0100110110";2)
42294
Unlike BIN2DEC, DECIMAL can handle more than 10 digits.
Note that no bit is considered to be the sign bit.
=DECIMAL("f";16) 15 Lowercase digits okay too
=DECIMAL("ZAP";36
)
45745
Base 36 is sometimes used to encode values; it is handy for
such purposes, since all digits and letters A-Z can be used
=DECIMAL("zap";36) 45745 Lowercase same as uppercase, even for base 36
=DECIMAL([.B3];10) 7 References okay too
See also BASE
6.19.11 HEX2BIN
Summary: Converts a hexadecimal number (40
th
bit is sign) to base 2 (whose 10
th
bit is sign)
Syntax: HEX2BIN( TextOrNumber X [ ; Number Digits ] )
Returns: Text
Constraints: X shall contain only hexadecimal digits (no space or other characters), and shall
contain at least one hexadecimal digit. When considered as a Number, INT(X)=X. Evaluators may
evaluate expressions where X is considered in base 10, -512 <= X <= 511.
Semantics: Converts given hexadecimal number into binary (base 2) equivalent. If given Text, the
text is considered a hexadecimal number representation; if its 40
th
bit is 1, it is considered a
negative number. It is implementation-defined what happens if given a Logical value; an evaluator
may produce an Error, or it may convert the Logical to Number (per Convert to Number) and then
th
and in two's complement form. If the input is negative (40
th
bit is 1), the Digits argument is ignored;
anchor:HEX2BIN
Test Cases:
=HEX2BIN("5") "101" Simple translation. 101 in base 2 is 4+1 = 5.
100414201 29 May 2010
=HEX2BIN(5) "101"
=ISNUMBER(HEX2B
IN("5"))
=ISTEXT(HEX2BIN(
5))
=HEX2BIN("A5") "10100101" Simple translation for 9 digits
=HEX2BIN(5;8) "00000101" If digits given, adds leading zeros as necessary
=HEX2BIN(0) "0"
=HEX2BIN("1FF") "111111111"
Simple translation to 9 digits (largest binary number supported
by this function)
=HEX2BIN("511") Error Input out of range, hex 511 == dec 1297
=HEX2BIN("FFFFFF
FE00")
"1000000000
"
Sign bit is taken into account.
=HEX2BIN("FFFFFF
FFFF")
"1111111111" Sign bit is taken into account.
=HEX2BIN("f") "1111" Hex inputs must accept lower case digits, too
6.19.12 HEX2DEC
th
bit is sign) to decimal
Syntax: HEX2DEC( TextOrNumber X )
Returns: Number
Constraints: X shall contain only hexadecimal digits (no space or other characters), and shall
contain at least one hexadecimal digit. When considered as a Number, INT(X)=X. Evaluators may
evaluate expressions where X shall have 1 though 10 (inclusive) hexadecimal digits.
Semantics: Converts given hexadecimal number into decimal equivalent. If given Text, the text is
considered a hexadecimal number representation. If X's 40
th
bit is 1, it is considered a negative
number. It is implementation-defined what happens if given a Logical value; an evaluator may
The resulting value is a decimal number.
anchor:HEX2DEC
Test Cases:
=HEX2DEC("b") 11 Simple translation. Lowercase must be accepted
=HEX2DEC(5) 5
100414201 29 May 2010
=ISNUMBER(HEX2D
EC("5"))
True
=ISTEXT(HEX2DEC(
5))
False
=HEX2DEC("7FFFF
FFFFF")
54975581388
7
Largest number
=HEX2DEC("800000
0000")
-
54975581388
8
Smallest number
=HEX2DEC("FFFFF
FFFFF")
-1
Note: OOo 2.1 gets HEX2DEC("8000000000") wrong (OOo doesn't notice the sign bit until the 10th
SYMBOL is F). This is a bug.
6.19.13 HEX2OCT
th
th
bit is sign)
Syntax: HEX2OCT( TextOrNumber X [ ; Number Digits ] )
Returns: Text
Constraints: X shall contain hexadecimal digits (no spaces or other characters), and shall contain
at least one hexadecimal digit. When considered as Number, INT(X)=X. Evaluators may evaluate
expressions where X has 1 to 10 (inclusive) hexadecimal digits, base 10 value of X is -2
29
< X < 2
29
-1.
Semantics: Converts given hexadecimal number into octal (base 8) equivalent. If given Text, the
text is considered a hexadecimal number representation; if its 40
th
The resulting value is an octal value, up to 10 digits, with the topmost bit (10
th
th
anchor:HEX2OCT
Test Cases:
=HEX2OCT("12") "22"
=HEX2OCT(12) "22"
=HEX2OCT([.B3]) "7" Even referencing text through a reference is still converted.
=ISNUMBER(HEX2O
CT("5"))
100414201 29 May 2010
=ISTEXT(HEX2OCT(
5))
=HEX2OCT("a5") "245" Lower-case hex digits are still digits
=HEX2OCT(13;8) "00000023" If digits given, adds leading zeros as necessary
=HEX2OCT(0) "0"
=HEX2OCT("1FFFF
FFF")
"3777777777
"
Largest number (2^29-1)
=HEX2OCT("FFE000
0000")
"4000000000
"
Smallest number (-2^29)
=HEX2OCT("FFFFF
FFFFF")
"7777777777
"
-1.
6.19.14 OCT2BIN
Summary: Converts an octal number (30
th
th
bit is sign)
Syntax: OCT2BIN( TextOrNumber X [ ; Number Digits ] )
Returns: Text
Constraints: X shall contain only octal digits (no space or other characters), and shall contain at
least one octal digit. When considered as a Number, INT(X)=X. Evaluators may evaluate
expressions where X is considered in base 10, -512 <= X <= 511.
Semantics: Converts given octal (base 8) number into binary (base 2) equivalent. If given Text, the
text is considered an octal number representation; if its 30
th
bit is 1, it is considered a negative
number. It is implementation-defined what happens if given a Logical value; an evaluator may
th
th
anchor:OCT2BIN
Test Cases:
=OCT2BIN("5") "101" Simple translation. 101 in base 2 is 4+1 = 5.
=OCT2BIN(5) "101"
=ISNUMBER(OCT2B
IN("5"))
=ISTEXT(OCT2BIN( True Conversion does yield text
100414201 29 May 2010
5))
=OCT2BIN("53") "101011"
=OCT2BIN(53;8) "00101011" If digits given, adds leading zeros as necessary
=OCT2BIN(0) "0"
=OCT2BIN("777") "111111111" Largest binary number (511) allowed
=OCT2BIN("777777
7000")
"1000000000
"
=OCT2BIN("777777
7777")
"1111111111"
6.19.15 OCT2DEC
Syntax: OCT2DEC( TextOrNumber X )
th
bit is sign) to decimal
Returns: Number
expressions where X shall have 1 though 10 (inclusive) octal digits.
Semantics: Converts given octal number into decimal equivalent. If given Text, the text is
considered a octal number representation. If X's 30
th
bit is 1, it is considered a negative number. It is
The resulting value is a decimal number.
anchor:OCT2DEC
Test Cases:
=OCT2DEC("31") 25 Oct 31 is Dec 25. A joke is based on this.
=OCT2DEC(31) 25
=ISNUMBER(OCT2D
EC("5"))
True
=ISTEXT(OCT2DEC(
5))
False
=OCT2DEC("377777
7777")
536870911 Largest number
=OCT2DEC("400000
0000")
-536870912 Smallest number
=OCT2DEC("777777 -1
100414201 29 May 2010
7777")
Note: OOo 2.1 doesn't recognize the sign bit in =OCT2DEC("4000000000"). This is a bug.
6.19.16 OCT2HEX
th
bit is sign) to hexadecimal (whose 40
th
bit is sign)
Syntax: OCT2HEX( TextOrNumber X [ ; Number Digits ] )
Returns: Text
expressions where X shall have 1 to 10 (inclusive) octal digits.
Semantics: Converts given octal (base 8) number into hexadecimal (base 16) equivalent. If given
Text, the text is considered an octal number representation; if its 30
th
The resulting value is a hexadecimal value, up to 10 digits, with the topmost bit (40
th
bit) being the
sign bit and in two's complement form. If the input is negative (30
th
bit is 1), the Digits argument is
ignored; otherwise, the Digits indicates the number of digits in the output, with leading 0 digits
added as necessary to bring it up to that number of digits. If there are more digits than specified by
the Digits parameter, the results are implementation-defined.
anchor:OCT2HEX
Test Cases:
=OCT2HEX("73") "3B" Simple translation.
=OCT2HEX(73) "3B"
Take the digits of the base 10 number, and consider as though
it were octal
=ISNUMBER(OCT2H
EX("5"))
=ISTEXT(OCT2HEX(
5))
=OCT2HEX("53";5) "0002B" If digits given, adds leading zeros as necessary
=OCT2HEX(0) "0"
=OCT2HEX("377777
7777")
"1FFFFFFF" Largest number allowed
=OCT2HEX("400000
0000")
"FFE0000000
"
-536870912, sign bit taken into account.
=OCT2HEX("777777
7777")
"FFFFFFFFF
F"
-1, sign bit taken into account.
Note: OOo 2.1 doesn't recognize the sign bit in =OCT2HEX("4000000000"). This is a bug.
100414201 29 May 2010
6.19.17 ROMAN
Summary: Convert to Roman numerals
Syntax: ROMAN( Integer N [ ; Integer Format = 0 ] )
Returns: Text
Constraints: N>=0, N<4000, 0 <= Format <= 4, ISLOGICAL(1) or NOT(ISLOGICAL(Format))
Semantics: Return the Roman numeral representation of N. Format specifies the level of
conciseness, and defaults to 0, the classic representation, with larger numbers requiring increasing
conciseness.
To support legacy documents, evaluators with Logical types that are distinct from Number may
accept the format parameter as a scalar, and accept TRUE() specifying format 0, and FALSE()
specifying format 4.
The following identity shall hold: ARABIC(ROMAN(x; any)) = x, when ROMAN(x; any) is not an
Error.
If N is 0, an empty string is returned.
Table 32 - ROMAN lists the values of individual roman numerals; roman numerals that precede
(directly or indirectly) a larger-valued roman number subtract their value from the final value.
Table 32 - ROMAN
Roman Numeral Value
I 1
V 5
X 10
L 50
C 100
D 500
M 1000
Evaluators that accept 0 as a value of N should return the string 0. Evaluators that accept negative
values of N should include a negative sign (-) as the first character.
The Format levels are:
Table 33 - ROMAN
Format Meaning
0
or omitted
(or TRUE)
Only subtract powers of 10, not L or V, and only if the next
number is not more than 10 times greater. A number
following the larger one shall be smaller than the subtracted
number. Also known as classic.
1 Powers of 10, and L and V may be subtracted, only if the
100414201 29 May 2010
Format Meaning
next number is not more than 10 times greater. A number
number.
2 Powers of 10 and L, but not V, may be subtracted, also if the
next number is more than 10 times greater. A number
number.
3 Powers of 10, and L and V may be subtracted, also if the
next number is more than 10 times greater. A number
number.
4
(or FALSE)
Produce the fewest Roman digits possible. Also known as
simplified.
Note: Excel 2000 in a Nutshell shows how the values change in Excel for various values of the
Format value.
Note: Historically, larger numbers were written by writing an overbar over the characters (which
multiplied them by 1,000); today Roman numerals are not usually used for numbers large enough to
justify mandating support for this.
anchor:ROMAN
Test Cases:
=ROMAN(1) "I" Simple value
=ROMAN(1;0) "I" Accepts the format parameter.
=ROMAN(452) "CDLII" 452
=ROMAN(1490) "MCDXC" 1490
=ROMAN(1899)
"MDCCCXCIX
"
1899
=ROMAN(1999) "MCMXCIX" 1999
=ROMAN(2993) "MMCMXCIII" 2993
=ROMAN(3999)
"MMMCMXCI
X"
3999, the largest portable value for this function.
=ROMAN(452;0) "CDLII" 452
=ROMAN(1490;0) "MCDXC" 1490
=ROMAN(1899;0)
"MDCCCXCIX
"
1899
=ROMAN(1999;0) "MCMXCIX" 1999
=ROMAN(2993;0) "MMCMXCIII" 2993
100414201 29 May 2010
=ROMAN(3999;0)
"MMMCMXCI
X"
3999, the largest portable value for this function.
See also Infix Operator "&", ARABIC
6.20 Text Functions
6.20.1 General
6.20.2 ASC
Summary: Converts full-width to half-width ASCII and katakana characters.
Syntax: ASC( Text T )
Returns: Text
Constraints: None
Semantics: Conversion is done for full-width ASCII and [UNICODE] katakana characters, some
characters are converted in a special way, see table below. Other characters are copied from T to
the result. This is the complementary function to JIS.
The percent sign % in the conversion table below denotes the modulo operation. A followed by
means that a character is converted to two consecutive characters.
Table 34 - ASC
From Unicode Character (c) To Unicode Character Comment
U+30a1 <= c <= U+30aa
if c%2==0
(c - 0x30a2) / 2 + 0xff71 katakana a-o
U+30a1 <= c <= U+30aa
if c%2==1
(c - 0x30a1) / 2 + 0xff67 katakana small a-o
U+30ab <= c <= U+30c2
if c%2==1
(c - 0x30ab) / 2 + 0xff76 katakana ka-chi
U+30ab <= c <= U+30c2
if c%2==0
(c - 0x30ac) / 2 + 0xff76
followed by 0xff9e
katakana ga-dhi
U+30c3 0xff6f katakana small tsu
U+30c4 <= c <= U+30c9
if c%2==0
(c - 0x30c4) / 2 + 0xff82 katakana tsu-to
U+30c4 <= c <= U+30c9
if c%2==1
(c - 0x30c5) / 2 + 0xff82
followed by 0xff9e
katakana du-do
U+30ca <= c <= U+30ce c - 0x30ca + 0xff85 katakana na-no
U+30cf <= c <= U+30dd
if c%3==0
(c - 0x30cf) / 3 + 0xff8a katakana ha-ho
100414201 29 May 2010
U+30cf <= c <= U+30dd
if c%3==1
(c - 0x30d0) / 3 + 0xff8a
followed by 0xff9e
katakana ba-bo
U+30cf <= c <= U+30dd
if c%3==2
(c - 0x30d1) / 3 + 0xff8a
followed by 0xff9f
katakana pa-po
U+30de <= c <= U+30e2 c - 0x30de + 0xff8f katakana ma-mo
U+30e3 <= c <= U+30e8
if c%2==0
(c - 0x30e4) / 2 + 0xff94) katakana ya-yo
U+30e3 <= c <= U+30e8
if c%2==1
(c - 0x30e3) / 2 + 0xff6c katakana small ya-yo
U+30e9 <= c <= U+30ed c - 0x30e9 + 0xff97 katakana ra-ro
U+30ef U+ff9c katakana wa
U+30f2 U+ff66 katakana wo
U+30f3 U+ff9d katakana nn
U+ff01 <= c <= U+ff5e c - 0xff01 + 0x0021 ASCII characters
U+2015 U+ff70 HORIZONTAL BAR =>
HALFWIDTH KATAKANA-
HIRAGANA PROLONGED
SOUND MARK
U+2018 U+0060 LEFT SINGLE QUOTATION
MARK => GRAVE ACCENT
U+2019 U+0027 RIGHT SINGLE QUOTATION
MARK => APOSTROPHE
U+201d U+0022 RIGHT DOUBLE QUOTATION
MARK => QUOTATION MARK
U+3001 U+ff64 IDEOGRAPHIC COMMA
U+3002 U+ff61 IDEOGRAPHIC FULL STOP
U+300c U+ff62 LEFT CORNER BRACKET
U+300d U+ff63 RIGHT CORNER BRACKET
U+309b U+ff9e KATAKANA-HIRAGANA
VOICED SOUND MARK
U+309c U+ff9f KATAKANA-HIRAGANA SEMI-
VOICED SOUND MARK
U+30fb U+ff65 KATAKANA MIDDLE DOT
U+30fc U+ff70 KATAKANA-HIRAGANA
PROLONGED SOUND MARK
U+ffe5 U+005c FULLWIDTH YEN SIGN =>
100414201 29 May 2010
REVERSE SOLIDUS "\"
Note: The "\" (REVERSE SOLIDUS, U+005C) is a specialty that gets displayed as a Yen sign with
some Japanese fonts, which is a legacy of code-page 932.
Note: For references regarding halfwidth and fullwidth characters see [UAX11] and the Halfwidth
and Fullwidth Code Chart of [UNICODE].
Note: For information about the mapping of JIS X 0201 and JIS X 0208 to Unicode characters see
[JISX0201] and [JISX0208].
anchor:ASC
Test Cases:
=ASC("") "ABC" "A,B,C" ASCII letters
=ASC("") "" "A,I,U" katakana letters
See also JIS
Note: This function originates from Japanese localized Excel versions. When imported into an
English localized Excel the function loses its functionality.
6.20.3 CHAR
Summary: Return character represented by the given numeric value
Syntax: CHAR( Number N )
Returns: Text
Constraints: N <= 127; Evaluators may evaluate expressions where N >= 1, N <= 255.
Semantics:
Returns character represented by the given numeric value.
Evaluators should return an Error if N > 255.
Evaluators should implement CHAR such that CODE(CHAR(N)) returns N for any 1 <= N <= 255.
Note: Beyond 127, some evaluators return a character from a system-specific code page, while
others return the [UNICODE] character. Most evaluators do not allow values greater than 255.
Note: Where interoperability is a concern, expressions should use the UNICHAR function. 6.20.25
anchor:CHAR
Test Cases:
=CHAR(65) "A" ASCII character 65 is "A".
100414201 29 May 2010
=LEN(CHAR(10)) 1 New line.
Note: Excel supports CHAR(10), though it only shows as a newline if the cell is formatted to word
wrap (else the character shows as a box character). OOo2 does not display CHAR(10) as a newline
character, but it accepts the character.
See also CODE, UNICHAR, UNICODE
6.20.4 CLEAN
Summary: Remove all non-printable characters from the string and return the result.
Syntax: CLEAN( Text T )
Returns: Text
Semantics:
Removes all non-printable characters from the string T and returns the resulting string. Evaluators
should remove each particular character from the string, if and only if the character belongs to
[UNICODE] class Cc (Other - Control), or to Unicode class Cn (Other - Not Assigned). The resulting
string shall contain all printable characters from the original string, in the same order. The space
character is considered a printable character.
anchor:CLEAN
Test Cases:
=CLEAN(Text) Text Printable characters are not affected.
=CLEAN(CHAR(7)&"
Tex" & CHAR(8) & "t"
& CHAR(9))
Text Non-printable characters are to be removed.
=CLEAN("Hi there") "Hi there" Space characters are retained.
6.20.5 CODE
Summary: Return numeric value corresponding to the first character of the text value.
Syntax: CODE( Text T )
Returns: Number
Constraints: code point <= 127 (ASCII).; Evaluators may evaluate expressions where Length(T) >
0.
Semantics:
Returns a numeric value which represents the first letter of the given text T.
Behavior for code points >= 128 is implementation-defined. Evaluators may use the underlying
system's code page. Evaluators should implement CODE such that CODE(CHAR(N)) returns N for
1 <= N <= 255.
Note: Where interoperability is a concern, expressions should use the UNICODE function. 6.20.26
100414201 29 May 2010
anchor:CODE
Test Cases:
=CODE(A) 65 ASCII character 65 is "A".
=CODE(0)>0 True Alphanumeric characters have code greater than 0.
=CODE(Text)=C
ODE(T)
True CODE only takes first character into account.
See also CHAR, UNICHAR, UNICODE
6.20.6 CONCATENATE
Summary: Concatenate the text strings
Syntax: CONCATENATE( { Text T }
+
)
Returns: Text
Constraints: None
Semantics: Concatenate each text value, in order, into a single text result.
anchor:CONCATENATE
Test Cases:
=CONCATENATE("Hi "; "there") "Hi there" Simple concatenation.
=CONCATENATE("A"; "B"; "C") "ABC" More than two parameters okay.
=CONCATENATE([.B4]; [.B5]) "23" Numbers converted to strings automatically.
See also Infix Operator "&"
6.20.7 DOLLAR
Summary: Convert the parameters to Text formatted as currency.
Syntax: DOLLAR( Number N [ ; Integer D ] )
Returns: Text
Constraints: None
Semantics: Returns the value formatted as a currency, using locale-specific data. D is the number
of decimal places used in the result string, a negative D rounds number N. If D is omitted, locale
information may be used to determine the currency's decimal places, or a value of 2 shall be
assumed.
anchor:DOLLAR
100414201 29 May 2010
Test Cases:
=DOLLAR(-12345.6789) "($12,345.68)" If in en-US locale.
=DOLLAR(-12345.6789) "-$12,345.68"
If in en-US locale and locale data says to not
use parentheses.
=DOLLAR(-12345.6789) "-12.345,68 " If in de-DE locale.
=DOLLAR(-12345.6789) "-12 345,68 " If in fr-FR locale.
=DOLLAR(-12345.6789) "SFr. -12'345.68" If in de-CH locale.
Rationale: This function is included for Excel compatibility. Portable spreadsheets should not use it,
the function result, especially the currency symbol included, depends on the locale the application
runs in and the extend to which the application supports the locale.
Note: ECMA/MOOXML has a function USDOLLAR that is claimed to not be locale dependent and
always return a string with the '$' symbol. That is not true, up to Excel2007 the function behaves
identical to DOLLAR.
6.20.8 EXACT
Summary: Report if two text values are equal using a case-sensitive comparison .
Syntax: EXACT( Text t1 ; Text t2 )
Returns: Logical
Constraints: None
Semantics: Converts both sides to Text, and then returns TRUE if the two text values are equal,
including case, otherwise it returns FALSE.
anchor:EXACT
Test Cases:
=EXACT("A";"A") True Trivial comparison.
=EXACT("A";"a") False EXACT, unlike "=", considers different cases different.
=EXACT(1;1) True EXACT does work with numbers.
=EXACT((1/3)*3;1) True
Numerical comparisons ignore "trivial" differences that depend
only on numeric precision of finite numbers.
=EXACT(TRUE();T
RUE())
True Works with Logical values.
=EXACT("1";2) False Different types with different values are different.
=EXACT("h";1) False
If text and number, and text can't be converted to a number, they
are different and NOT an error.
=EXACT("1";1) True If text and number, see if number converted to text is equal.
100414201 29 May 2010
=EXACT( 1;1) False
This converts 1 into the Text value 1, the compares and finds
that it's not the same as 1 (note the leading space).
See also FIND, SEARCH, Infix Operator "<>", Infix Operator "="
6.20.9 FIND
Summary: Return the starting position of a given text.
Syntax: FIND( Text Search ; Text T [ ; Integer Start = 1 ] )
Returns: Number
Constraints: Start >= 1
Semantics: Returns the character position where Search is first found in T, when the search is
started from character position Start. The match is case-sensitive, and no wildcards or other
instructions are considered in Search. Returns an Error if text not found.
anchor:FIND
Test Cases:
=FIND("b";"abcabc") 2 Simple FIND().
=FIND("b";"abcabcabc"; 3) 5 Start changes the start of the search.
=FIND("b";"ABC";1) Error Matching is case-sensitive.
=FIND("b";"bbbb") 1 Simple FIND(), default is 1
=FIND("b";"bbbb";2) 2
=FIND("b";"bbbb";2.9) 2 INT(Start) used as starting position
=FIND("b";"bbbb";0) Error Start >= 0
=FIND("b";"bbbb";0.9) Error
See also EXACT, SEARCH
Note: SEARCH is not part of the Small set. SEARCH allows more complex matching than simple
case-sensitive matching.
Note: Lotus 1-2-3v9's start-number is not optional, and it starts counting from 0, not 1, for string
positions. This is an area we really can't be silent about; we have to pick some convention for
position numbers. User applications now widely depend on starting positions of 1 (which are easier
for those less computer-savvy), including Excel, OpenOffice.org, Gnumeric. Also, having the default
start as beginning of string is extremely useful, so since this is a change anyway, may as well
require this useful capability. Thus, we've adopted start at 1 semantics; applications like Lotus 1-2-
3 that use 0-based string positions will have to add/subtract one, or use different functions, during
conversion to this format.
100414201 29 May 2010
6.20.10 FIXED
Summary: Round the number to a specified number of decimals and format the result as a text.
Syntax: FIXED( Number N [ ; Integer D = 2 [ ; Logical OmitSeparators = FALSE() ] ] )
Returns: Text
Constraints: None
Semantics: Rounds value N to D decimal places (after the decimal point) and returns the result
formatted as text, using locale-specific settings. If D is negative, the number is rounded to ABS(D)
places to the left from the decimal point. If the optional parameter OmitSeparators is True, then
group separators are omitted from the resulting string. Group separators are included in the
absence of this parameter. If D is a fraction, it is rounded towards 0 as an integer (ignoring what is
the closest integer).
anchor:FIXED
Test Cases:
=FIXED(12345;3)
12,345.000
Presuming en_US locale.

=ISTEXT(FIXED(
12345;3))
True
=FIXED(12345;3;
FALSE())
12,345.000
Presuming en_US locale.

=FIXED(12345;4;
TRUE())
12345.000
0
=FIXED(123.45;1
)
123.5
=FIXED(125.45;
-1.1)
130
Round D into an integer, towards 0, ignoring what is the closest
value
=FIXED(125.45;
-1.9)
130 -1.9 is rounded to -1.
6.20.11 JIS
Summary: Converts half-width to full-width ASCII and katakana characters.
Syntax: JIS( Text T )
Returns: Text
Constraints: None
Semantics: Conversion is done for half-width ASCII and [UNICODE] katakana characters, some
characters are converted in a special way, see table below. Other characters are copied from T to
the result. This is the complementary function to ASC.
A followed by means that there are two consecutive characters to convert from.
100414201 29 May 2010
Table 35 - JIS
U+0022 0x201d QUOTATION MARK => RIGHT
DOUBLE QUOTATION MARK
This is an exception to the
ASCII range that follows below.
U+005c 0xffe5 REVERSE SOLIDUS "\" =>
FULLWIDTH YEN SIGN
(code-page 932 legacy, for
details see ASC function)
U+0060 0x2018 GRAVE ACCENT => LEFT
SINGLE QUOTATION MARK
U+0027 0x2019 APOSTROPHE => RIGHT
SINGLE QUOTATION MARK
U+0021 <= c <= U+007e c - 0x0021 + 0xff01 ASCII characters
U+ff66 0x30f2 katakana wo
U+ff67 <= c <= U+ff6b (c - 0xff67) * 2 + 0x30a1 katakana small a-o
U+ff6c <= c <= U+ff6e (c - 0xff6c) * 2 + 0x30e3 katakana small ya-yo
U+ff6f 0x30c3 katakana small tsu
U+ff71 <= c <= U+ff75 (c - 0xff71) * 2 + 0x30a2 katakana a-o
U+ff76 <= c <= U+ff81
followed by U+ff9e
(c - 0xff76) * 2 + 0x30ac katakana ga-dsu
U+ff76 <= c <= U+ff81
not followed by U+ff9e
(c - 0xff76) * 2 + 0x30ab katakana ka-chi
U+ff82 <= c <= U+ff84
followed by U+ff9e
(c - 0xff82) * 2 + 0x30c5 katakana du-do
U+ff82 <= c <= U+ff84
not followed by U+ff9e
(c - 0xff82) * 2 + 0x30c4 katakana tsu-to
U+ff85 <= c <= U+ff89 c - 0xff85 + 0x30ca katakana na-no
U+ff8a <= c <= U+ff8e
followed by U+ff9e
(c - 0xff8a) * 3 + 0x30d0 katakana ba-bo
U+ff8a <= c <= U+ff8e
followed by U+ff9f
(c - 0xff8a) * 3 + 0x30d1 katakana pa-po
U+ff8a <= c <= U+ff8e (c - 0xff8a) * 3 + 0x30cf katakana ha-ho
100414201 29 May 2010
neither followed by U+ff9e nor
U+ff9f
U+ff8f <= c <= U+ff93 c - 0xff8f + 0x30de katakana ma-mo
U+ff94 <= c <= U+ff96 (c - 0xff94) * 2 + 0x30e4 katakana ya-yo
U+ff97 <= c <= U+ff9b c - 0xff97 + 0x30e9 katakana ra-ro
U+ff9c U+30ef katakana wa
U+ff9d U+30f3 katakana nn
U+ff9e U+309b HALFWIDTH KATAKANA
VOICED SOUND MARK =>
FULLWIDTH
U+ff9f U+309c HALFWIDTH KATAKANA
SEMI-VOICED SOUND MARK
=> FULLWIDTH
U+ff70 U+30fc HALFWIDTH KATAKANA-
HIRAGANA PROLONGED
SOUND MARK => FULLWIDTH
U+ff61 U+3002 HALFWIDTH IDEOGRAPHIC
FULL STOP => FULLWIDTH
U+ff62 U+300c HALFWIDTH LEFT CORNER
BRACKET => FULLWIDTH
U+ff63 U+300d HALFWIDTH RIGHT CORNER
BRACKET => FULLWIDTH
U+ff64 U+3001 HALFWIDTH IDEOGRAPHIC
COMMA => FULLWIDTH
U+ff65 U+30fb HALFWIDTH KATAKANA
MIDDLE DOT => FULLWIDTH
Note: For references regarding halfwidth and fullwidth characters see [UAX11] and the Halfwidth
and Fullwidth Code Chart of [UNICODE].
Note: For information about the mapping of JIS X 0201 and JIS X 0208 to Unicode characters see
[JISX0201] and [JISX0208].
anchor:JIS
Test Cases:
=JIS("ABC") "" "A,B,C" ASCII letters
=JIS("") "" "A,I,U" katakana letters
100414201 29 May 2010
See also ASC
Note: This function originates from Japanese localized Excel versions. When imported into an
English localized Excel the function name may be displayed as DBCS but has lost its original
functionality then.
6.20.12 LEFT
Summary: Return a selected number of text characters from the left.
Syntax: LEFT( Text T [ ; Integer Length ] )
Returns: Text
Constraints: Length >= 0
Semantics: Returns the INT(Length) number of characters of text T, starting from the left. If Length
is omitted, it defaults to 1; otherwise, it computes Length=INT(Length). If T has fewer than Length
characters, it returns T. This means that if T is an empty string (which has length 0) or the parameter
Length is 0, LEFT() will always return an empty string. Note that if Length<0, an Error is returned.
This function shall return the same string as MID(T; 1; Length).
anchor:LEFT
Test Cases:
=LEFT("Hello";2) "He" Simple LEFT().
=LEFT("Hello";2.9) "He"
INT(), not round to nearest or round towards positive infinity,
must be used to convert length into an integer.
=LEFT("Hello") "H" Length defaults to 1.
=LEFT("Hello";20) "Hello" If Length is longer than T, returns T.
=LEFT("Hello";0) "" If Length 0, returns empty string.
=LEFT("";4) "" Given an empty string, always returns empty string.
=LEFT("xxx";-0.1) Error
It makes no sense to request a negative number of
characters. Also, this tests to ensure that INT() is used to
convert non-integers to integers; if -0.1 were incorrectly
rounded to 0 (as it would be by round-to-nearest or round-
toward-zero), this would incorrectly return a null string.
=LEFT("Hello";2^15-1) "Hello" If Length > LEN(T) entire string is returned.
See also LEN, MID, RIGHT
Note: LEFT("xxx";2^32) should produce "xxx", but it's not an unusual bug to do otherwise.
Future spreadsheets may implement Text strings even larger, and we don't want to prevent that.
6.20.13 LEN
Summary: Return the length, in characters, of given text
100414201 29 May 2010
Syntax: LEN( Text T )
Returns: Integer
Constraints: None.
Semantics: Computes number of characters (not the number of bytes) in T. If T is of type Number,
it is automatically converted to Text, including a fractional part and decimal separator if necessary.
anchor:LEN
Test Cases:
=LEN("Hi There") 8 Space is a character.
=LEN("") 0 Empty string has zero characters.
=LEN(55) 2 Numbers are automatically converted.
See also TEXT, ISTEXT, LEFT, MID, RIGHT
Note: Many implementations use UTF-8 internally for text representations. This is fine, but they
must be careful to avoid mistakenly using byte length as the length.
Rationale: The emphasis is placed on characters, not bytes, because different implementations will
use a different number of characters to represent a given text value. In contrast, counting characters
is more portable, and it's closer to the user's expectations. Some implementations use a 16-bit
representation for characters. Implementations using 16 bits per character should consider any
character outside the BMP as a single character, but as a concession to buggy implementations,
this is merely specified as a 'should'.
6.20.14 LOWER
Summary: Return input string, but with all uppercase letters converted to lowercase letters.
Syntax: LOWER( Text T )
Returns: Text
Constraints: None
Semantics: Return input string, but with all uppercase letters converted to lowercase letters, as
defined by sections 3.13 Default Case Algorithms, 4.2 Case-Normative and 5.18 Case Mappings of
[UNICODE]. As with most functions, it is side-effect free (it does not modify the source values). All
Evaluators shall convert A-Z to a-z.
Note: As this function can be locale aware, results may be unexpected in certain cases. For
example in a Turkish locale an upper case "I without dot" (LATIN CAPITAL LETTER I, U+0049) is
converted to a lower case "i without dot" (LATIN SMALL LETTER DOTLESS I, U+0131).
anchor:LOWER
Test Cases:
=LOWER("HELLObc "hellobc7" Uppercase converted to lowercase; other characters just
100414201 29 May 2010
7") copied to result.
See also UPPER, PROPER
Note: Ideally, implementations could handle any [UNICODE] characters. However, it is not clear that
they actually handle all international characters. Many character sets do not really have an
"uppercase" and "lowercase" set, in which case this function just copies the character to the Result.
A-Z must map to a-z, regardless of locale. However, some mappings are specific to a locale. For
about this, see: http://unicode.org/reports/tr21/tr21-3.html.
6.20.15 MID
Summary: Returns extracted text, given an original text, starting position, and length.
Syntax: MID( Text T ; Integer Start ; Integer Length )
Returns: Text
Constraints: Start >= 1, Length >= 0.
Semantics: Returns the characters from T, starting at character position Start, for up to Length
characters. For the integer conversions, Start=INT(Start), and Length=INT(Length). If there are less
than Length characters starting at start, it returns as many characters as it can beginning with Start.
In particular, if Start > LEN(T), it returns the empty string (""). If Start < 0, it returns an Error. If Start
>=0, and Length=0, it returns the empty string. Note that MID(T;1;Length) produces the same
results as LEFT(T;Length).
anchor:MID
Test Cases:
=MID("123456789";5;3) "567" Simple use of MID.
=MID("123456789";20;3) "" If Start is beyond string, return empty string.
=MID("123456789";-1;0) Error
Start cannot be less than one; even if the length is
0
=MID("123456789";1;0) "" But otherwise, length=0 produces the empty string
=MID("123456789";2.9;1) "2" INT(Start) is used
=MID("123456789";2;2.9) "23" INT(Length) is used
See also LEFT, LEN, RIGHT, REPLACE, SUBSTITUTE
6.20.16 PROPER
Summary: Return the input string with the first letter of each word converted to an uppercase letter
and the rest of the letters in the word converted to lowercase.
Syntax: PROPER( Text T )
100414201 29 May 2010
Returns: Text
Constraints: None
Semantics: Return input string, but modified as follows:
If the first character is a letter, it is converted to its uppercase equivalent; otherwise, the
original character is returned
If a letter is preceded by a non-letter, it is converted to its uppercase equivalent
If a letter is preceded by a letter, it is converted to its lowercase equivalent.
Evaluators shall implement this for at least the Latin letters A-Z and a-z.
As with most functions, it is side-effect free, that is, it does not modify the source values.
anchor:PROPER
Test Cases:
=PROPER("hello there") "Hello There"
The first letter is uppercase and the following letter
are lowercase.
=PROPER("HELLO
THERE")
"Hello There"
The first letter is uppercase and the following letter
are lowercase.
=PROPER("HELLO.THE
RE")
"Hello.There" Words are separated by spaces, punctuation, etc.
=PROPER("ABC5DEF") Abc5Def Forced conversion to lowercase.
=PROPER("abc5def") Abc5Def Forced conversion to uppercase.
Rationale: The syntax requires exactly one parameter. An early version of this specification had
curly braces around the parameter, which would say that it took a list, but OOo2, Gnumeric, and
KSpread at least do not allow this (and Excel probably doesn't either), so presumably this was just
an accident.
See also LOWER, UPPER
Note: Ideally, implementations could handle any [UNICODE] character. However, it is not clear that
they actually handle all international characters. Many character sets do not really have an
"uppercase" and "lowercase" set, in which case this function just copies the character to the Result.
6.20.17 REPLACE
Summary: Returns text where an old text is substituted with a new text.
Syntax: REPLACE( Text T ; Number Start ; Number Count ; Text New )
Returns: Text
Constraints: Start >= 1.
Semantics: Returns text T, but remove the characters starting at character position Start for Count
characters, and instead replace them with New. Character positions defined by Start begin at 1 (for
the leftmost character). If Count=0, the text New is inserted before character position Start, and all
the text before and after Start is retained. If Start > length of text T (TLen) then Start is set to TLen.
If Count > TLen - Start then Count is set to TLen - Start.
100414201 29 May 2010
REPLACE(T;Start;Len;New) is the same as LEFT(T;Start-1) & New & MID(T; Start+Len; LEN(T)))
anchor:REPLACE
Test Cases:
=REPLACE("123456789";5;3;"Q
")
"1234Q89" Replacement text may have different length.
=REPLACE("123456789";5;0;"Q
")
"1234Q56789" If Len=0, 0 characters removed.
See also LEFT, LEN, MID, RIGHT, SUBSTITUTE
Note: OpenOffice.org 2 does not accept REPLACE("123456789";5;0;"Q"). Excel 2003 does.
6.20.18 REPT
Summary: Return text repeated Count times.
Syntax: T( Text T ; Integer Count )
Returns: Text
Constraints: Count >= 0
Semantics: Returns text T repeated Count number of times; if Count is zero, an empty string is
returned. If Count < 0, the result is Error.
anchor:REPT
Test Cases:
=REPT("X";3) "XXX" Simple REPT.
=REPT("XY";2) "XYXY" Repeated text can have length > 0.
=REPT("X";2.9) "XX" INT(Count) used if count is a fraction.
=REPT("X";0) "" If Count is zero, empty string.
=REPT("X";-1) Error If Count is negative, Error.
See also LEFT, MID, RIGHT, SUBSTITUTE
Note: This function is sometimes used as a trivial kind of text graphic.
6.20.19 RIGHT
Summary: Return a selected number of text characters from the right.
100414201 29 May 2010
Syntax: RIGHT( Text T [ ; Integer Length ] )
Returns: Text
Constraints: Length >= 0
Semantics: Returns the Length number of characters of text T, starting from the right. If Length is
omitted, it defaults to 1; otherwise, it computes Length=INT(Length). If T has fewer than Length
characters, it returns T (unchanged). This means that if T is an empty string (which has length 0) or
the parameter Length is 0, RIGHT() will always return an empty string. Note that if Length<0, an
Error is returned.
anchor:RIGHT
Test Cases:
=RIGHT("Hello";2) "lo" Simple RIGHT().
=RIGHT("Hello") "o" Length defaults to 1.
=RIGHT("Hello";20) "Hello" If Length is longer than T, returns T.
=RIGHT("Hello";0) "" If Length 0, returns empty string.
=RIGHT("Hello";2^1
5-1)
Hello
If Length is larger than T and is very large, it still returns
the original short string.
=RIGHT("";4) "" Given an empty string, always returns empty string.
=RIGHT("Hello";-1) Error
It makes no sense to request a negative number of
characters.
=RIGHT("Hello";-0.1) Error
Must use INT, not round-to-nearest or round-towards
zero, to convert Length to Integer
See also LEFT, LEN, MID
6.20.20 SEARCH
Summary: Return the starting position of a given text.
Syntax: SEARCH( Text Search ; Text T [ ; Integer Start = 1 ] )
Returns: Integer
Constraints: Start >= 1
Semantics: Returns the character position where Search is first found in T, when the search is
started from character position Start. The match is not case-sensitive. Start is 1 if omitted. Returns
an Error if text not found.
anchor:SEARCH
Test Cases:
100414201 29 May 2010
=SEARCH("b";"abcabc") 2 Simple SEARCH().
=SEARCH("b";"abcabcabc"; 3) 5 Start changes the start of the search.
=SEARCH("b";"ABC";1) 2 Matching is not case-sensitive.
=SEARCH(c?a;abcabcda) 6 Question mark matches one character
=SEARCH(e*o;yes and no) 2 Asterisk matches anything
=SEARCH(b*c;abcabcabc) 2 Asterisk matches an empty string
See also EXACT, FIND
Note: SEARCH is not part of the Small group; SEARCH allows more complex matching than
simple case-sensitive matching.
6.20.21 SUBSTITUTE
Summary: Returns text where an old text is substituted with a new text.
Syntax: SUBSTITUTE( Text T ; Text Old ; Text New [ ; Integer Which ] )
Returns: Text
Constraints: Which >= 1 (when provided)
Semantics: Returns text T, but with text Old replaced by text New (when searching from the left). If
Which is omitted, every occurrence of Old is replaced with New; if Which is provided, only that
occurrence of Old is replaced by New (starting the count from 1). If there is no match, or if Old has
length 0, the value of T is returned. Note that Old and New may have different lengths. If Which is
present and Which < 1, returns Error.
anchor:SUBSTITUTE
Test Cases:
=SUBSTITUTE("121212";"2";"ab") "1ab1ab1ab" Without Which, all replaced.
=SUBSTITUTE("121212";"2";"ab";2) "121ab12" Which starts counting from 1.
=SUBSTITUTE("Hello";"x";"ab") "Hello" If not found, returns unchanged.
=SUBSTITUTE("xyz";"";"ab") "xyz" Returns T if Old is Length 0.
=SUBSTITUTE("";"";"ab") ""
Returns T if Old is Length 0, even if T
is empty (it does not consider an
empty T to match an empty Old).
=SUBSTITUTE("Hello"; "H"; "J"; 0) Error Which cannot be less than 1.
See also LEFT, LEN, MID, REPLACE, RIGHT
100414201 29 May 2010
6.20.22 T
Summary: Return the text (if Text), else return 0-length Text value
Syntax: T( Any X )
Returns: Text
Constraints: None
Semantics: The type of (a dereferenced) X is examined; if it is of type Text, it is returned, else an
empty string (Text value of zero length) is returned. This is not a type-conversion function; T(5)
produces an empty string, not "5".
anchor:T
Test Cases:
=T("HI") "HI" T does not change text.
=T([.B3]) "7" References transformed into what they reference.
=T(5) "" Non-text converted into null string.
See also N
Note: Many public documents inadequately describe this function; in particular, few seem to
describe exactly what happens when something other than type text is provided to this function. It is
known that Excel and OOo2 both produce an empty string for T(5). In some implementations this
function is named S, for string.
6.20.23 TEXT
Summary: Return the value converted to a text.
Syntax: TEXT( Scalar X ; Text FormatCode )
Returns: Text
Constraints: The FormatCode is a sequence of characters with an implementation-defined
meaning.
Semantics: Converts the value X to a Text according to the rules of a number format code passed
as FormatCode and returns it.
anchor:TEXT
Test Cases:
=TEXT(1234
5.6789;"#,##
0.00")
"12,345.68" Non-text converted to text. This is locale-specific.
=TEXT(3;"0""
good
"3 good
things"
100414201 29 May 2010
things""")
TODO: more test cases.
See also N, T
6.20.24 TRIM
Summary: Remove leading and trailing spaces, and replace all internal multiple spaces with a
single space.
Syntax: TRIM( Text T )
Returns: Text
Constraints: None.
Semantics: Takes T and removes all leading and trailing space. Any other sequence of 2 or more
spaces is replaced with a single space.
A space is one or more, HORIZONTAL TABULATION (U+0009), LINE FEED (U+000A), CARRIAGE
RETURN (U+000D) or SPACE (U+0020) characters.
anchor:TRIM
Test Cases:
=TRIM(" HI ") "HI" Simple TRIM().
=LEN(TRIM("H" & " " & " " & "I")) 3 Multiple spaces become 1 space internally.
See also LEFT, RIGHT
Note: The following implementations are known to turn multiple internal spaces into a single space:
Microsoft Excel 2002, OOo2, Gnumeric, KSpread. If there are implementations which don't, this
could be moved to a higher level, but currently there's no reason to believe that this is necessary.
6.20.25 UNICHAR
Summary: Return character represented by the given numeric value according to the [UNICODE]
Standard.
Syntax: UNICHAR( Integer N )
Returns: Text
Constraints: N >= 0, N <= 1114111 (U+10FFFF)
Semantics: Returns the character represented by the given numeric value. Evaluators shall support
values between 1 and 0xFFFF, which is the maximum possible value in UCS-2 encoding using two
octets. Evaluators should allow N to be any legal character value in [UNICODE] assuming UCS-4
encoding. Evaluators should implement UNICHAR such that UNICODE(UNICHAR(N)) returns N for
any N >= 0 and N <= 1114111.
Note: Depending on the evaluator's encoding the string returned may be actually longer than
expected, for example in UTF-8 or UTF-16 encodings.
100414201 29 May 2010
anchor:UNICHAR
Test Cases:
=UNICHAR(65) "A" Character at code point 65 is LATIN CAPITAL LETTER A.
=UNICHAR(8364) "" Character at code point 8364 (U+20AC) is EURO SIGN.
See also UNICODE
6.20.26 UNICODE
Summary: Return the [UNICODE] code point corresponding to the first character of the text value.
Syntax: UNICODE( Text T )
Returns: Number
Constraints: Length(T) > 0.
Semantics: Returns the numeric value of the [UNICODE] code point of the first character of the
given text T.
anchor:UNICODE
Test Cases:
=UNICODE(A) 65 Character LATIN CAPITAL LETTER A is code point 65.
=UNICODE("") 8364 Character EURO SIGN is code point 8364 (U+20AC).
See also UNICHAR
6.20.27 UPPER
Summary: Return input string, but with all lowercase letters converted to uppercase letters.
Syntax: UPPER( Text T )
Returns: Text
Constraints: None
Semantics: Return input string, but with all lowercase letters converted to uppercase letters, as
defined by sections 3.13 Default Case Algorithms, 4.2 Case-Normative and 5.18 Case Mappings of
[UNICODE]. As with most functions, it is side-effect free (it does not modify the source values). All
Evaluators shall convert a-z to A-Z.
Note: As this function can be locale aware, results may be unexpected in certain cases, for example
in a Turkish locale a lower case "i with dot" (LATIN SMALL LETTER I) U+0069 is converted to an
upper case "I with dot" (LATIN CAPITAL LETTER I WITH DOT ABOVE, U+0130).
anchor:UPPER
100414201 29 May 2010
Test Cases:
=UPPER("Habc7"
)
"HABC7"
Lowercase converted to upper case; other characters just copied
to result.
See also LOWER, PROPER
Note: Ideally, implementations could handle any [UNICODE] character and convert lowercase
letters into uppercase letters. However, some implementations may not handle all international
characters. Many character sets do not really have an "uppercase" and "lowercase" set, in which
case this function just copies the character to the Result.
Some mappings are specific to a locale. For about this, see: http://unicode.org/reports/tr21/tr21-
3.html.
100414201 29 May 2010
7 Other Capabilities
7.1 General
Evaluators may implement additional abilities that are not a matter of which function they support.
The following sections describe some specific additional capabilities; evaluators may implement
them, and documents may require them (though such documents may not be correctly recalculated
on applications which do not implement them). Documents that depend on these other capabilities
can still be considered portable documents, but only if these additional capabilities are clearly
noted (since not applications implement these additional capabilities).
TODO: Place test cases for arrays here. Note that the definition of array processing goes earlier, in
the processing model section, along with a note that not all implementations support arrays.
7.2 Inline constant arrays
Evaluators claiming to implement Inline constant arrays shall support inline arrays with one matrix,
with one or more rows, and one or more columns. Such evaluators shall support these 2-
dimensional arrays as long as the number of expressions in each row is identical; evaluators may
but need not support arrays with a different number of expressions in each row. They shall support
at least the following syntactic rules in the Expression values for the inline array:
Number, optionally preceded with the prefix - operator (for negative numbers)
Text
Logical constants TRUE() and FALSE()
Error
Test Cases:
=LARGE({1;2;3};1) 3
=LARGE({1;2;3};3) 1
=LARGE({1;2;3};4) Error N is greater than the length of the list
=SMALL({1;2;3};1) 1
=SMALL({1;2;3};3) 3
=SMALL({1;2;3};4) Error N is greater than the length of the list
=CORREL({1;2;3;4};
{1;2;3;4})
1 Perfect positive correlation
=CORREL({1;2;3;4};
{4;3;2;1})
-1 Perfect negative correlation
=CORREL({1;2;3};{2;3}) Error The length of each list must be equal
TODO: Add tests for multirow, multicolumn, etc.
100414201 29 May 2010
7.3 Inline non-constant arrays
Evaluators claiming to implement Inline non-constant arrays shall support the full Expression
syntax in each component of an array (and not just constants).
TODO: Tests
7.4 Year 1583
Evaluators claiming to implement Year 1583 can correctly calculate dates correctly starting from
the January 1 of the (ISO) year 1583. This means that the evaluator correctly determines that 1900
was not a leap year, and can handle year values for dates back to at least 1583.
These calculations use the ISO (proleptic Gregorian) calendar, that is, the calculations use the usual
rules for the ISO (Gregorian) calendar, regardless of locale. This calendar began official use in some
locales in 1582, but other locales used other calendars (such as the Julian calendar) and switched
to the Gregorian calendar at different times in history, if they switched at all. Evaluators may choose
to support years even earlier than this; such evaluators should use a proleptic Gregorian system
(continuing the years backwards as if the calendar existed in those years). Note that not all people
used, or currently use, the ISO (Gregorian) calendar.
Correct date calculations in this calendar system require that leap years be handled correctly. In this
calendar system, leap years include 29 days in February (which otherwise has 28 days), for 366
total days in a leap year. In general, all years evenly divisible by 4 are leap years. However, years
that are divisible by 100 shall also be divisible by 400 to be a leap year; otherwise, they are
common (non-leap) years.
Note: Refer to ISO 8601 for more information on dates, times, and their representation.
=DATE(1900;3;1) -
DATE(1900;2;28)
1
The year 1900 was not a leap year, so the difference
between these two dates is one day
=DATE(1584;1;1)-
DATE(1583;1;1)
365 The year 1583 was an ordinary 365-day year
=DATE(1585;1;1)-
DATE(1584;1;1)
366
The year 1584 is divisible by 4, and thus was a leap
year.
=DATE(1601;1;1)-
DATE(1600;1;1)
366 1600: Leap year
=DATE(1701;1;1)-
DATE(1700;1;1)
365 1700: Not a leap year
=DATE(1801;1;1)-
DATE(1800;1;1)
=DATE(1901;1;1)-
DATE(1900;1;1)
=DATE(2001;1;1)-
DATE(2000;1;1)
366 2000: Leap year
=DATE(2101;1;1)-
DATE(2100;1;1)
100414201 29 May 2010
=DATE(2000;1;1)-
DATE(1583;1;1)
152306
Show that calculations can be correct starting from
January 1, 1583.
=DATEVALUE("2000-01-
01")-DATEVALUE("1583-01-
01")
152306 DATEVALUE needs to handle this correctly too
100414201 29 May 2010
8 Non-portable Features
8.1 General
Expressions may depend upon features that are not implemented by all evaluators. This section
identifies and defines some features not commonly implemented to enable expressions to indicate
their reliance on these features.
8.2 Distinct Logical
An evaluator may have the Distinct Logical feature, which means that its Logical type is a distinct
type from both Number and Text, and that certain other properties or queries hold true as well.
Some legacy documents depend on the distinct logical feature. An evaluator that has the distinct
logical feature as described in this specification shall have the following properties:
ISNUMBER() applied to a Logical value (constant or calculated) will return False, and
ISLOGICAL() applied to a Number will be False, either directly or via a reference
TRUE() will not be equal to 1, and FALSE() will not be equal to 0, when they are compared
using =
In a NumberSequence (such as when using SUM), Logical values are skipped when inside a
range, but are included and automatically converted to a Number if provided as the
NumberSequence itself
Test Cases:
=TRUE()=1 False True is not the same as 1.
=FALSE()=0 False False is not the same as 0.
=ISNUMBER(TRUE()) False True/false are distinct from numbers.
=ISTEXT(TRUE()) False True/false are distinct from Text, too
=ISLOGICAL(1) False Numbers are distinct from the Logical type.
=ISNUMBER([.B10]) True Zero, even if acquired via a reference, is a number.
=ISLOGICAL([.B10]) False
Zero is not a Logical value even though it could be
converted into one.
=ISNUMBER([.B6]) False A computed true value is not a number.
=ISLOGICAL([.B6]) True A computed true value is a Logical value.
=COUNT([.B6];2;3) 2 Logical types are ignored in reference parameters.
=COUNT(FALSE();2;3) 3
Logical is treated as a number if inline; it is converted to a
number before being passed to the function, and thus
counted (when inline).
=COUNT([.B3:.B6]) 2 IConversion to NumberSequence ignores strings (in B3)
100414201 29 May 2010
and Logical values (a TRUE() in B6).
=TYPE(TRUE()) 4 TYPE will return a different value than TYPE(1)
Note: Could make this a calculation setting, for legacy transition from different spreadsheets. We
could make it an explicitly optional calculation setting in terms of implementing a Logical type or not,
but ask applications to WRITE what their expected semantics were... so that applications that could
do both, could easily handle both, and those that didn't would be no worse off. But there didnt
seem to be a real need; documents tend to not depend on this.
8.3 Auto Text to Number
An evaluator may have the Auto Text to Number feature, which means that the Convert to
Number function, when receiving a Text value or a Reference to a Text value, converts the Text into
a Number, typically through calling the VALUE() function. This feature can be convenient if files
never change locale, but in today's international environment, this feature can easily lead to data
files that look correct but give subtly wrong answers, especially when shared with users who use a
different locale. This can be a problem even when the documents never leave a small geographical
area, since users may choose a locale they are familiar with that is different that the one expected
by the document sender.
=7+0 7
The + operator (which requires numbers) forces the
conversion of 7 into 7.
=[.B3]+0 7
The + operator (which requires numbers) forces the
conversion of the reference to the text value 7 into 7.
=COS(7)=COS(7) True
Function calls requiring Number cause a conversion of text,
just like operators do.
=COS([.B3])=COS(7) True
Function calls requiring Number cause a conversion of
referenced text, just like operators do.
="7"+[.B4] 9 Adding forces conversion of constant text value "7" on LHS.
=[.B4]+"7" 9 Adding forces conversion of constant text value "7" on RHS.
=("4" & "5")+2 47
Adding forces conversion of computed text value "45" on
LHS.
=2+("4" & "5") 47
Adding forces conversion of computed text value "45" on
RHS.
=[.B3]+[.B4] 9 Adding forces conversion of referenced text value "7".
=[.B3]+[.B6] 8
Neither side needs to be numeric; plus itself forces the
conversion from text.
=("2006-05-
21"+0)=DATE(2006;5;21)
True Dates are converted too.
Note: If there are many spreadsheet data files or users that depend on this, perhaps it might be
better to have a calculation setting that enabled this, with the default being false; this would ease
legacy transition.
TODO: What locale is used? The current locale?
100414201 29 May 2010
9 Test Cases (non-normative)
Test cases are defined by a table. For each test case, the following are defined:
Expression: The expression being computed for that test case, in OpenFormula format. This
begins with an = sign for non-array formulas. Array formulas begin with {=, and end with a
matching } (note that expressions are not actually stored this way in OpenDocument). In most
cases, an effort has been made to write expressions so that the results have a finite
representation in both base 2 and base 10 (e.g., integers or fractions of powers of 2) to simplify
comparisons (with the exception of test cases specifically to test representations). Many test
expressions involving trigonometric functions involve PI() to make the results easier to compare.
All quotation marks are straight (so if an expression appears to have curling quotes, it really
contains straight quotes). The expression does not display any necessary XML encoding when
it is stored in an XML document; thus an expression will show "<", not "<".
Result: The required result of the expression in a compliant implementation of OpenFormula.
This is one of the following patterns (ignoring leading and trailing whitespace):
True or False: The calculated expression shall be equal to the value of TRUE() or FALSE(),
respectively, as determined using the = operator. Note that in applications with a distinct
Logical type, 1 is not equal to TRUE().
"text": The calculated expression shall be exactly equal (including case) to the text, as
determined by the EXACT function. There is no difference in semantics between curling quotes
and straight quotes that surround the text.
Number: A number, which begins with a digit (0-9) or a minus sign, in OpenFormula syntax (so
the period is the decimal point, and scientific notation is allowed). If there is no symbol in the
result, the calculated expression shall be equal to the number as determined using the =
operator. The number may end with followed by an error range, which is either a second
number or the special symbol . The symbol (epsilon) means within a small value, and for
purposes of this specification it represents 1e-6 (so number means within 1e-6 of the
number). If there is a symbol in the result, the expression (ABS(Expression First_Number)
< Error_range)=TRUE() shall be true, where Expression is the calculated expression. Any
whitespace surrounding the symbol is irrelevant.
Error: The result shall be an Error value, where NA is considered an Error value. This is the
same as ISERROR( Expression )=TRUE(). Note that this specification permits applications to
have different kinds of Error.
NA: The result is NA. This is the same as ISNA(Expression)=TRUE().
=formula: The calculated expression shall be equal to the result of calculating OpenFormula
formula; equality is determined using the = operator.
{ array-values }: The calculated expression is distributed over a set of cells (matching the
positions in array-values), and each cell matches the given values.
Many test cases define an error range. Applications should produce correct values with significantly
less error than the given error range, but shall produce results within at least that range to pass that
test case.
To reduce the risk of misunderstanding a requirement, and to increase the likelihood of correct
implementation, this specification includes a large number of test cases that are non-normative (that
is, they are not part of the specification). In particular, every function and operator has at least one
test case, and typically many test cases. An implementation shall pass all of the test cases for a
100414201 29 May 2010
given function or operator (unless otherwise specifically noted in the text) to be able to claim
conformance with that function or operator. No set of test cases can be complete, so to claim
conformance for a given function or operator, implementations shall meet all the requirements of this
specification of it, even if there is no specific test case for some aspect of it.
For the test cases, all calculation settings are at their defaults, except that case-sensitive is false (so
"Hi"="HI" is true) and search-criteria-must-apply-to-whole-cell is false.
A very few test cases depend on a specific locale. In these cases, the presumed locale is "en_US"
(American English). This does not imply that any locale is better than another; this is done to
reduce the costs of checking compliance, and to be sure that at least one locale works correctly.
Implementations should support a large range of locales. In general, test cases have been defined
to be locale-independent where practical to do so.
TODO: There are a number of to do items that involve test cases, which have not yet been done
because their completion was not required to create a normative specification.
Note: Test cases are designed to be automatic and only test one capability at a time, where
possible. For example:
The DATE() function is used to generate most date values, and similarly for TIME(), since they
are portable everywhere. Lotus 1-2-3 has a DATEVALUE(), but its DATEVALUE() does not
accept ISO 8601 format dates. Several applications do not automatically apply VALUE() or a
similar function in their implied conversion to Number.
Many applications interpret all text values as 0 when in a number context, including Lotus 1-2-3,
Quattro Pro, and KSpread. Tests for conversions are in the conversion sections; the rest of the
test cases are designed to not require conversion of text to a non-number.
Floating-point values (including time values) are inexact in most implementations. Where this
can be an issue, test cases subtract the expected value and use ABS() to ensure that the result
is correct within a reasonable range. This is automatic when you use the character.
Not all implementations support inline arrays, so tests for a specific function that can be used in
a non-array context should not use inline arrays. There are separate tests for support of inline
arrays.
9.1 Test Case Data Set
In the test cases, the following spreadsheet values are presumed to be in the current sheet, as well
as the sheets named Sheet1 and Sheet2:
B C
3 ="7"
4 =2 4
5 =3 5
6 =1=1 7
7 ="Hello" 2005-01-31
8 2006-01-31
9 =1/0 02:00:00
10 =0 23:00:00
100414201 29 May 2010
11 3 5
12 4 6
13 2005-01-31T01:00:00 8
14 1 4
15 2 3
16 3 2
17 4 1
Note that B6 has the Logical value TRUE(), B8 is an empty cell, and B9 is an Error. C7 and C8 are
Dates, C9 and C10 are Times, and B13 is a DateTime value.
The named expressions FOUR and are assigned to cell C4 (the name is used to test for
support of international characters).
At least the data above, including the named expression FOUR, is copied to a file in the current
directory named 'openformula-testsuite.ods'.
The following is a trial test database; this range is assigned the name TESTDB. This database is
purely for testing purposes; this data is not intended to be astronomically accurate:
A B C D E F G H I
18 TestID
Constellati
on
Bright
Stars
Northern
Abbre
v
Decl
Next
South
Date
Rev
19 1 Cancer 0 TRUE Cnc 20 =B20
12 Mar
2005
13
20 =[.A19]*2 Canis Major 5 FALSE Cma 5 =B27
3 Feb
2002
12
21 =[.A20]*2 Canis Minor 2 TRUE Cmi -20 = B24
8 Mar
2005
11
22 =[.A21]*2 Carina 5 FALSE Car -60
27 Mar
1991
10
23 =[.A22]*2 Draco 3 TRUE Dra 75 =B31 5 Jul 1967 9
24 =[.A23]*2 Eridanus 4 FALSE Eri -29 =B29
23 Dec
1912
8
25 =[.A24]*2 Gemini 4 TRUE Gem 20 =B19
6 Feb
1992
7
26 =[.A25]*2 Hercules 0 TRUE Her 30 =B25 4 Jul 1934 6
27 =[.A26]*2 Orion 8 TRUE Ori 5 =B21
8 Jan
1909
5
28 =[.A27]*2 Phoenix 1 FALSE Phe -50 =B22
28 Nov
1989
4
29 =[.A28]*2 Scorpio 9 FALSE Sco -40 =B28 22 Feb 3
100414201 29 May 2010
2000
30 =[.A29]*2 Ursa Major 6 TRUE Uma 55.38 =B26
29 Mar
2004
2
31 =[.A30]*2 Ursa Minor 2 TRUE Umi 70 =B30
13 Jul
1946
1
Notes:
The TRUE and FALSE values in the database are actually =1=1 and =1=0 respectively (for
maximum compatibility).
Some of the dates are in the future. No dates are before 1904, for maximum compatibility.
The last column is there solely to test reverse searches.
The "Next south" field is for testing references. Notice that one of the references is blank.
The following are test criteria, for extracting data from the database:
B C D E F G H I
36 Bright Stars Northern Constellation Decl Rev Bright Stars Date
37 4 TRUE Ursa Major < 0 <= 7 < 4 >1950-01-01
38 <2 TRUE Constellation >= 8 CONSTELLATION
39 >1 FALSE Ursa URSA MAJOR
The following are especially helpful for some of the statistical tests:
B C D E F G H I
50 x1 x2 y Value x3 x4 x5 Probability
51 4 7 100 10.5 3 23 0 0.2
52 5 9 105 7.2 4 24 1 0.3
53 6 11 104 200 5 25 2 0.1
54 7 12 108 5.4 2 22 3 0.4
55 8 15 111 8.1 3 23
56 9 17 120 4 24
57 10 19 133 5 25
58 6 26
59 4 24
60 7 27
Test case data used with LEGACY.CHITEST:
B C D E F G H
70 a1 a2 a3 e1 e2 e3
100414201 29 May 2010
71 12 45 78 11 44 77
72 23 56 89 22 55 88
73 34 67 98 33 66 99
100414201 29 May 2010
Appendix A. Index
TODO: Insert an index here, at least one entry for every function, type, and syntactic rule.
100414201 29 May 2010

OpenDocument v1.2 Cd05 Part2 Editor Revision

Cargado por

Información del documento

Descripción original:

Derechos de autor

Formatos disponibles

Compartir este documento

Compartir o incrustar documentos

Opciones para compartir

¿Le pareció útil este documento?

¿Este contenido es inapropiado?

Copyright:

Formatos disponibles

OpenDocument v1.2 Cd05 Part2 Editor Revision

Cargado por

Copyright:

Formatos disponibles

Open Document Format for Office

Applications (OpenDocument) Version

=CUMPRINC( 0.06/12; 5*12; 100000;

maturity at the beginning of a period

Returns a principal value 0 result PI.

"barrel" U.S. oil barrel, exactly 42 U.S.

"bushel" U.S. bushel (not Imperial bushel),

gal "gal" Gallon (U.S. customary liquid measure)

100414201 29 May 2010

Significantly different variances, so

Base 2; note that we aren't limited to 10 digits,

Presuming en_US locale.

Presuming en_US locale.

También podría gustarte