Objects  >  Formula
Search

Module:Editor

Version:2.2.1 +

User:Developer

Object Type:Calculation Object

Parent of:

no children

Child of:

- Action

- XmlBuilder

- Node

- Document

- DatabaseView

- XmlNode

 

Description

With a Formula you can make calculations involving numbers, booleans and dates as well as perform operations on strings. Formulas can handle scalars as well as tables.

Properties

DebugLogMode (from version 4.1)

Indicates the level of detail of debug information that is logged when running a Futurama application (website, webservice, console application) to the trace, a logfile, a database etc. The possible values are:

  • None: no debug information is logged
  • Simple: only basic information is given
  • Extended: in addition to the information in the Simple mode the values of all the properties of the object are shown

IsCircular

This is an automatic property indicating whether the Formula refers to itself, either directly (in case of a recursive Formula) or indirectly (in case of a circular reference).

IsPublic

Possible values are True or False. If the value is False, then the object can only be used within the document where it is created. If the value is True, then also from other Futurama documents can be referred to this object. This means that changes in the object also affect the document in which is referred to this object. If the value is True and you attempt to move or delete the object, a warning will be given. To limit these warnings to a minimum it is recommended to set IsPublic to True only when necessary.

NoCache (from version 24.11)

Possible values are True or False. By default Futurama remembers all results of its objects and retrieves them from cache whenever these are requested again unchanged. In some cases however, it is desirable not to cache its result. For performance reasons, if the result of this Formula is solely used by another Formula that caches its result, caching its result would mean using memory that will never be consulted again. If the value is False, then the Formula will use the default method to determine whether its result should be cached. If the value is True, then the Formula will never cache its result.

ReturnsTable (until version 5.0)

This is an automatic property indicating whether the result of the Calculation Object is a table. For a Formula the value depends on the sort of mathematical calculation that is performed. From version 5.1.0 the ReturnsTable property is replaced by the Rank property (see property below).

Rank (from version 5.1)

The Rank property is an automatic property indicating the rank of the Calculation Object. Rank=0 implies a scalar. Rank=1 a vector and Rank=2 a matrix. Depending on the Formula that is chosen the Rank is determined. Matrix formula's for example always have Rank=2.  Depending on the rank of the Formula other calculations can be done.

XmlName

The name of the object as it is shown in the source of the website. By default the XmlName is equal to the name given in the property (Name) with spaces replaced by underscores, but you are free to change it.

(Name)

The name of the object.

Comment

Here a comment can be entered. For example a short description of the object.

ID

The unique identification number of the object. This number is automatically generated by Futurama on the moment of creation. This number can be used when searching for a certain object in the Find Window.

Arguments

If the Formula is to return a value which depends on the value of certain input parameters then these parameters are to be passed to the Formula as arguments. Here these arguments can be defined. See the paragraph Arguments below for more information.

Method

This is an automatic property indicating the operation that is being performed. For example if you have chosen to muliply two numbers it will state 'Multiply'.

Text

Here the Formula can be created and edited. See the paragraph Editing a Formula below for more information. From Futurama version 18.02 it is also possible to define the texts within a ResourceDocument. See the page Text management and Multi-language.

Type

The value of this property determines what kind of values can be entered at the property Text. The following types are available:

  • Long (an integer)
  • Double (a broken number)
  • Date
  • String
  • Boolean (a logical value which can be True or False)

Editing a Formula

If you click in the Properties Window on the property Text on the right of this property the editing box appears. If you click on this button the Define Formula window will open in which the Formula can be defined. Before editing a Formula make sure you have selected the correct Type of the Formula. Changing the Type of an existing Formula will result in the Formula being erased. After selecting the proper Type the Formula can be created.

Depending on the chosen Type a number of categories will be available each containing a number of formulas which belong to the chosen Type. For example if the chosen Type is a Double, the Category Math will be available to perform all sorts of mathematical operations. When Type string is chosen this Category is not available at all.

After a category is chosen (for example the category Math) the next step is to chose one of the available formulas. When hovering over the available formulas an explanation of the formula will appear in the top of the Define Formula window. Once a formula is selected a follow-up window will appear in which the parameters have to be defined that the formula requires. Suppose we have chosen for the mathematical operation Add. In the follow-up window we can choose which elements we want to add together. These elements can be Fixed values, References to other objects of Type long or double, or even another Formula.

To see the creation of a Formula in action see the Relevant Tutorials.

Arguments

Arguments make Formulas more flexible. Suppose we want to determine the age of a person on a certain date. A Formula could be made that determines the age using just two Fixeds of Type date, one is the birthdate and the other the date on which we want to know the age. This would, however, make the Formula rather inflexible. If we want to determine the age at another date, another Formula would have to be made. Recommendable is to introduce an argument which represents the date on which we want to know the age. When using the Formula, by making a Reference to it, we would pass a date and the Formula would return the age at that specific date.

If you have an argument with type integer, then you can specify the range of allowed values for this argument.  If you do that, you will speed up the calculations when you use CalculationMode compile. See Config – Calculation. Note that in the situation that an argument is used that isn’t part of the defined range an error will occur.

Starting with version 18.12, for Arguments you can specify a DimensionGroup. This is used when you call a Formula with multiple arguments from a Reference and you pass a vector for these arguments. If all the arguments have the same DimensionGroup, then the Rank of the resulting matrix will be the same as the rank of the input.

If you specify different DimensionGroups, then the arguments that have DimensionGroup  ‘First’ will determine the number of rows of the result, and the arguments that have DimensionGroup ‘Second’ will determine the number of columns of the result.

For example, if you have a Formula f with arguments ‘a’ and ‘b’ that looks like this: f = a*b.

If a and b both have DimensionGroup ‘First’ then you can only pass two vectors with the same length. So if you pass a vector with the range [ 1.. 10] for a and b you will get a vector of length 10, with in each element a[i] * b[i].

If a has DimensionGroup ‘First’ and b has DimensionGroup ‘second’ then you will get a matrix of 10 * 10. In each element [i,j] with row i and column j the value will be a[i] *b[j]. If a is a range of [1..5] and b a range of [1..10] then the result matrix will be [5*10].

Related Topics

- DataTable

- Fixed

- Range

- Reference

- UserVariable

- UserTable

Relevant Tutorials

- Creating formulas with futurama: Select part 2 and further of this tutorial to see how a basic Formula is created.

- Working with Tables: This tutorial shows how Formulas can be created which work with tables.

 

Updated: 2012-07-20
Home   |   About   |   Installation   |   Editor   |   Formulas   |   Objects   |   Vision References   |   Vision   |   FICO   |   Web API   |   Tutorials   |   Miscellaneous
Futurama Support Site