User's Manual - version: 0.3

5. The KEYVALUE function

Cell B2 on The KEYVALUE function sheet of the example workbook contains a formula calling the function KEYVALUE:


Figure 3. Data set Triangle.

Data set Triangle.

This function call is meant to build a triangle.

We can see that cells with dark blue background contain formulas calling KEYVALUE to build polygons and to calculate their areas.

There are no functions such as BuildPolygon, CalculateArea or anything similar. Indeed, regardless the core library, KEYVALUE is the only function exported to LibreOffice Calc.

Actually, the name of this function is defined by the bridge library. In the examplary bridge, this function is called KEYVALUE and, for the sake of concreteness, in this document we shall always assume this name.

Having just one function is not as odd as it might seem (one could expect to call different functions for different tasks). Even when calling a specific function for a precise task, the function might change its behaviour depending on the data it receives. For instance, a function CreatePolygon would create a triangle or a square (or whatever) depending on the number of sides given. KeyValue goes one step further and considers the choice of the task as part of the input data as well.

Alternatively, we can think that KEYVALUE does have one single task: It creates data sets. A data set is a collection of data organized in key-value pairs (recall the stock prices example given in Section 1). The example above creates a data set called Triangle containing key-value pairs defined by the array B3:C6 (more details to follow). Analogously, the formula in cell E2


creates a data set called Square containing key-value pairs defined by array E3:F6.

Figure 4. Data set Square

Data set Square

More generally, KEYVALUE's first parameter is the name of the data set to be created. This is a compulsory parameter of text type (which might be left empty "" for anonymous data sets). Moreover, as in these examples, often the data set name is the result returned from KEYVALUE to LibreOffice Calc.

Once created, a named data set is stored in a repository and might be retrieved later through its name.

Other KEYVALUE's parameters are optional and define key-value pairs following patterns as discussed in next section.

Valid HTML 4.01 TransitionalValid CSS!