feat: Allow expressions in region functions and add count() accumulator (#86)
Co-authored-by: Glen Whitney <glen@studioinfinity.org> Reviewed-on: #86
This commit is contained in:
parent
eb5d576349
commit
7f005f171e
3 changed files with 430 additions and 445 deletions
716
doc/teapot.lyx
716
doc/teapot.lyx
|
|
@ -6169,9 +6169,8 @@ Functions
|
|||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
This section documents all available functions in alphabetical order (except
|
||||
for the short addressing/value fetching functions, which are listed together
|
||||
at the beginning).
|
||||
This section documents all available functions.
|
||||
Functions are listed within each section in alphabetical order.
|
||||
The functions are described in a C-like notation; you don't have to write
|
||||
the types when you use the function in a formula.
|
||||
For example, use
|
||||
|
|
@ -6186,7 +6185,38 @@ This section documents all available functions in alphabetical order (except
|
|||
If no type is given for the result of a function, it means the result type
|
||||
depends on the arguments.
|
||||
Brackets mark optional arguments.
|
||||
|
||||
\end_layout
|
||||
|
||||
\begin_layout Subsubsection
|
||||
Addressing/value fetching functions
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
All of these functions come in pairs, an
|
||||
\begin_inset Quotes eld
|
||||
\end_inset
|
||||
|
||||
addressing
|
||||
\begin_inset Quotes erd
|
||||
\end_inset
|
||||
|
||||
one whose value is a
|
||||
\emph on
|
||||
location
|
||||
\emph default
|
||||
, and a corresponding
|
||||
\begin_inset Quotes eld
|
||||
\end_inset
|
||||
|
||||
fetching
|
||||
\begin_inset Quotes erd
|
||||
\end_inset
|
||||
|
||||
one that produces the
|
||||
\emph on
|
||||
value
|
||||
\emph default
|
||||
of the cell at the corresponding location.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Description
|
||||
|
|
@ -6665,15 +6695,310 @@ X&
|
|||
\series default
|
||||
()
|
||||
\family default
|
||||
as well, which takes exactly the same arguments with the same meanings,
|
||||
but it is rarely needed.
|
||||
It is provided for completeness.
|
||||
as well, which takes exactly the same arguments with the same meanings
|
||||
and returns the corresponding location, rather than the value there, but
|
||||
it is rarely needed.
|
||||
It is provided for completeness of the pairing described in the introduction
|
||||
to this section.
|
||||
\begin_inset Newline newline
|
||||
\end_inset
|
||||
|
||||
See the FAQ below for further discussion of cell references.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Subsubsection
|
||||
Accumulation functions
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
All of these functions accumulate an entire array of values in some way.
|
||||
They differ only in how the values are accumulated, and otherwise have
|
||||
exactly the same behavior/signature, namely:
|
||||
\end_layout
|
||||
|
||||
\begin_layout Description
|
||||
|
||||
\series bold
|
||||
\emph on
|
||||
accumulator
|
||||
\family sans
|
||||
\series default
|
||||
\emph default
|
||||
(
|
||||
\family default
|
||||
\series medium
|
||||
[location
|
||||
\emph on
|
||||
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
l1
|
||||
\emph default
|
||||
[,
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
location
|
||||
\emph on
|
||||
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
l2
|
||||
\emph default
|
||||
[,
|
||||
\emph on
|
||||
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
expr
|
||||
\emph default
|
||||
]]])
|
||||
\emph on
|
||||
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
|
||||
\emph default
|
||||
|
|
||||
\emph on
|
||||
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
|
||||
\series bold
|
||||
accumulator
|
||||
\series medium
|
||||
\emph default
|
||||
(
|
||||
\emph on
|
||||
v1
|
||||
\family roman
|
||||
,
|
||||
\family default
|
||||
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
v2,
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
...
|
||||
\emph default
|
||||
)
|
||||
\series default
|
||||
The first form evaluates to the accumulation of
|
||||
\emph on
|
||||
expr
|
||||
\emph default
|
||||
computed for each location in the block defined by corner locations
|
||||
\emph on
|
||||
l1
|
||||
\emph default
|
||||
and
|
||||
\emph on
|
||||
l2
|
||||
\emph default
|
||||
.
|
||||
(Note that negative coordinates in the block corners are simply interpreted
|
||||
as zero.) The expression
|
||||
\emph on
|
||||
expr
|
||||
\emph default
|
||||
defaults to
|
||||
\begin_inset Quotes eld
|
||||
\end_inset
|
||||
|
||||
|
||||
\series bold
|
||||
@
|
||||
\series default
|
||||
|
||||
\begin_inset Quotes erd
|
||||
\end_inset
|
||||
|
||||
– in other words, it accumulates the values in that block.
|
||||
The location
|
||||
\emph on
|
||||
l2
|
||||
\emph default
|
||||
defaults to
|
||||
\emph on
|
||||
l1
|
||||
\emph default
|
||||
, corresponding to a one-cell block, and
|
||||
\emph on
|
||||
l1
|
||||
\emph default
|
||||
in turn defaults to the current location.
|
||||
The second form simply accumulates all of the argument values.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
The available accumulators are:
|
||||
\end_layout
|
||||
|
||||
\begin_layout Description
|
||||
|
||||
\series medium
|
||||
int
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
|
||||
\series default
|
||||
count Returns the number of accumulated values that are true when converted
|
||||
to a boolean value.
|
||||
For a block defined by corner locations
|
||||
\emph on
|
||||
l1
|
||||
\emph default
|
||||
and
|
||||
\emph on
|
||||
l2
|
||||
\emph default
|
||||
,
|
||||
\begin_inset Quotes eld
|
||||
\end_inset
|
||||
|
||||
count(
|
||||
\emph on
|
||||
l1,l2
|
||||
\emph default
|
||||
)
|
||||
\begin_inset Quotes erd
|
||||
\end_inset
|
||||
|
||||
is essentially a shorthand for
|
||||
\begin_inset Quotes eld
|
||||
\end_inset
|
||||
|
||||
sum(
|
||||
\emph on
|
||||
l1, l2,
|
||||
\emph default
|
||||
int(bool()))
|
||||
\begin_inset Quotes erd
|
||||
\end_inset
|
||||
|
||||
.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Description
|
||||
max In the first form, returns the
|
||||
\emph on
|
||||
location
|
||||
\emph default
|
||||
within the block of the maximum value being accumulated; to get the maximum
|
||||
value occurring in the block with corners
|
||||
\emph on
|
||||
l1
|
||||
\emph default
|
||||
and
|
||||
\emph on
|
||||
l2
|
||||
\emph default
|
||||
, use
|
||||
\begin_inset Quotes eld
|
||||
\end_inset
|
||||
|
||||
@(max(
|
||||
\emph on
|
||||
l1
|
||||
\emph default
|
||||
,
|
||||
\emph on
|
||||
l2
|
||||
\emph default
|
||||
))
|
||||
\begin_inset Quotes erd
|
||||
\end_inset
|
||||
|
||||
instead.
|
||||
In the second form, simply returns the maximum of the argument values.
|
||||
Recall that in comparisons with the corresponding types, an empty cell
|
||||
corresponds to 0, 0.0, or
|
||||
\begin_inset Quotes eld
|
||||
\end_inset
|
||||
|
||||
|
||||
\begin_inset Quotes erd
|
||||
\end_inset
|
||||
|
||||
, as needed.
|
||||
This accumulator returns an error if it encounters values that are not
|
||||
comparable (like a string and an integer).
|
||||
\end_layout
|
||||
|
||||
\begin_layout Description
|
||||
min Just like
|
||||
\family sans
|
||||
max
|
||||
\family default
|
||||
but for the minimum of the accumulated values.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Description
|
||||
|
||||
\series medium
|
||||
int
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
|
||||
\series default
|
||||
n Returns the number of accumulated values that are not empty.
|
||||
For a block defined by corner locations
|
||||
\emph on
|
||||
l1
|
||||
\emph default
|
||||
and
|
||||
\emph on
|
||||
l2
|
||||
\emph default
|
||||
,
|
||||
\begin_inset Quotes eld
|
||||
\end_inset
|
||||
|
||||
n(
|
||||
\emph on
|
||||
l1,l2
|
||||
\emph default
|
||||
)
|
||||
\begin_inset Quotes erd
|
||||
\end_inset
|
||||
|
||||
is essentially a shorthand for
|
||||
\begin_inset Quotes eld
|
||||
\end_inset
|
||||
|
||||
sum(
|
||||
\emph on
|
||||
l1, l2,
|
||||
\emph default
|
||||
int(-is(@,empty)))
|
||||
\begin_inset Quotes erd
|
||||
\end_inset
|
||||
|
||||
.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Description
|
||||
sum Returns the sum of the accumulated values (recall for strings this is
|
||||
the concatenation).
|
||||
This accumulator returns an error if encounters values that cannot be added
|
||||
(like a string and an integer).
|
||||
\end_layout
|
||||
|
||||
\begin_layout Subsubsection
|
||||
All other functions
|
||||
\end_layout
|
||||
|
||||
\begin_layout Description
|
||||
|
||||
\series medium
|
||||
|
|
@ -8177,302 +8502,6 @@ is
|
|||
to convert three integers to a location.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Description
|
||||
|
||||
\series medium
|
||||
location
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
|
||||
\series default
|
||||
max
|
||||
\series medium
|
||||
(location
|
||||
\emph on
|
||||
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
l1
|
||||
\emph default
|
||||
,
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
location
|
||||
\emph on
|
||||
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
l2
|
||||
\emph default
|
||||
)
|
||||
\emph on
|
||||
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
|
||||
\emph default
|
||||
|
|
||||
\emph on
|
||||
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
|
||||
\series default
|
||||
\emph default
|
||||
max
|
||||
\series medium
|
||||
(
|
||||
\emph on
|
||||
v1
|
||||
\emph default
|
||||
,
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
|
||||
\emph on
|
||||
v2
|
||||
\emph default
|
||||
,
|
||||
\emph on
|
||||
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
|
||||
\emph default
|
||||
...)
|
||||
\series default
|
||||
evaluates to the maximum in the same way min does for the minimum.
|
||||
|
||||
\end_layout
|
||||
|
||||
\begin_layout Description
|
||||
|
||||
\series medium
|
||||
location
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
|
||||
\series default
|
||||
min
|
||||
\series medium
|
||||
(location
|
||||
\emph on
|
||||
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
l1
|
||||
\emph default
|
||||
,
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
location
|
||||
\emph on
|
||||
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
l2
|
||||
\emph default
|
||||
)
|
||||
\emph on
|
||||
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
|
||||
\emph default
|
||||
|
|
||||
\emph on
|
||||
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
|
||||
\series default
|
||||
\emph default
|
||||
min
|
||||
\series medium
|
||||
(
|
||||
\emph on
|
||||
v1
|
||||
\emph default
|
||||
,
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
|
||||
\emph on
|
||||
v2
|
||||
\emph default
|
||||
,
|
||||
\emph on
|
||||
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
|
||||
\emph default
|
||||
...)
|
||||
\series default
|
||||
The first form evaluates to the location of the minimum of all values in
|
||||
the block marked by the corners pointed to by
|
||||
\emph on
|
||||
l1
|
||||
\emph default
|
||||
and
|
||||
\emph on
|
||||
l2
|
||||
\emph default
|
||||
.
|
||||
Note that the empty cell is equal to 0, 0.0 and "", so if the first minimum
|
||||
is an empty cell, the result will be a pointer to this cell, too.
|
||||
If you are not interested in the location of the minimum but the value
|
||||
itself, use @(min(
|
||||
\emph on
|
||||
l1
|
||||
\emph default
|
||||
,
|
||||
\emph on
|
||||
l2
|
||||
\emph default
|
||||
)).
|
||||
The second form simply returns the smallest of the specified values, returning
|
||||
an error if it encounters two that are not comparable (like a string and
|
||||
an integer).
|
||||
\end_layout
|
||||
|
||||
\begin_layout Description
|
||||
|
||||
\series medium
|
||||
int
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
|
||||
\series default
|
||||
n
|
||||
\series medium
|
||||
([location
|
||||
\emph on
|
||||
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
l1
|
||||
\emph default
|
||||
[,
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
location
|
||||
\emph on
|
||||
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
l2
|
||||
\emph default
|
||||
])
|
||||
\emph on
|
||||
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
|
||||
\emph default
|
||||
|
|
||||
\emph on
|
||||
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
|
||||
\series default
|
||||
\emph default
|
||||
n
|
||||
\series medium
|
||||
(
|
||||
\family roman
|
||||
\emph on
|
||||
v1,
|
||||
\family default
|
||||
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
v2,
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
...
|
||||
\emph default
|
||||
)
|
||||
\series default
|
||||
The first form evaluates to the number of non-empty cells in the block
|
||||
with corners at location
|
||||
\emph on
|
||||
s l1
|
||||
\emph default
|
||||
and
|
||||
\emph on
|
||||
l2
|
||||
\emph default
|
||||
.
|
||||
Location
|
||||
\emph on
|
||||
l2
|
||||
\emph default
|
||||
defaults to
|
||||
\emph on
|
||||
l1
|
||||
\emph default
|
||||
; i.e., with a single location argument
|
||||
\family sans
|
||||
\series bold
|
||||
n
|
||||
\family default
|
||||
\series medium
|
||||
(
|
||||
\family sans
|
||||
\series default
|
||||
\emph on
|
||||
l1
|
||||
\family default
|
||||
\series medium
|
||||
\emph default
|
||||
)
|
||||
\series default
|
||||
just tests whether the cell at
|
||||
\emph on
|
||||
l1
|
||||
\emph default
|
||||
is empty.
|
||||
Location
|
||||
\emph on
|
||||
l1
|
||||
\emph default
|
||||
defaults to the current location.
|
||||
If any dimension of either location is negative, that component is simply
|
||||
taken as 0.
|
||||
In other words, locations off the sheet are considered empty, but it is
|
||||
not an error to access them.
|
||||
\begin_inset Newline newline
|
||||
\end_inset
|
||||
|
||||
The second form simply returns the number of its arguments which are nonempty.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Description
|
||||
number
|
||||
\series medium
|
||||
|
|
@ -9117,87 +9146,6 @@ y
|
|||
If is omitted, the substring proceeds to the end of the string.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Description
|
||||
sum
|
||||
\series medium
|
||||
(location
|
||||
\emph on
|
||||
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
l1
|
||||
\emph default
|
||||
,
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
location
|
||||
\emph on
|
||||
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
l2
|
||||
\emph default
|
||||
)
|
||||
\emph on
|
||||
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
|
||||
\emph default
|
||||
|
|
||||
\emph on
|
||||
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
|
||||
\series default
|
||||
\emph default
|
||||
sum
|
||||
\series medium
|
||||
(
|
||||
\family roman
|
||||
\emph on
|
||||
v1,
|
||||
\family default
|
||||
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
|
||||
\family roman
|
||||
v2,
|
||||
\family default
|
||||
|
||||
\begin_inset space ~
|
||||
\end_inset
|
||||
|
||||
|
||||
\family roman
|
||||
...
|
||||
\emph default
|
||||
)
|
||||
\family default
|
||||
|
||||
\series default
|
||||
The first form evaluates to the sum of all values in the block with corners
|
||||
at locations
|
||||
\emph on
|
||||
l1
|
||||
\emph default
|
||||
and
|
||||
\emph on
|
||||
l2
|
||||
\emph default
|
||||
.
|
||||
The second form simply adds all of its arguments.
|
||||
|
||||
\end_layout
|
||||
|
||||
\begin_layout Description
|
||||
|
||||
\series medium
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue