DB48X-on-DM42/doc/3-Types.md

Types

DB48X, like HP RPL, supports a wide variety of data types.

Integers

The DB48X version of RPL distinguishes between integer values, like 123, and decimal values, like 123. Integer values are represented internally in a compact and efficient format, saving memory and making computations faster. All values between -127 and 127 can be stored in two bytes. All values between -16383 and 16383 in three bytes.

Integers can be as large as memory permits.

Big integers

The DB48X version of RPL can perform computations on arbitrarily large integers, limited only by available memory, enabling for example the exact computation of 100! and making it possible to address problems that require exact integer computations, like exploring the Syracuse conjecture.

Decimal numbers

Decimal numbers are used to represent values with a fractional part. DB48X supports three decimal numbers, using the 32-bit, 64-bit and 128-bit binary decimal representation. In memory, all decimal numbers use one additional byte: a 32-bit decimal number uses 5 bytes, a 128-bit binary decimal number uses 17 bytes.

The 32-bit format offers a 7 digits mantissa and has a maximum exponent of 96. The 64-bit format offers a 16 digits mantissa and has a maximum exponent of 384. The 128-bit format offers a 34 digits mantissa and a maximum exponent of 6144.

The Precision command selects the default precision.

Note that a future implementation of DB48X is expected to feature variable-precision decimal numbers similar to newRPL.

Based numbers

Based numbers are used to perform computations in any base. The most common bases used in computer science, 2, 8, 10 and 16, have special shortcuts. The Bases Menu list operations on based numbers.

Like integers, based numbers can be arbitrary large. However, operations on based numbers can be truncated to a specific number of bits using the WordSize setting. This makes it possible to perform computations simulating a 16-bit or 256-bit processor.

Boolean values

DB48X has two boolean values, True and False. These values are typically returned by operations such as tests that return a truth value.

In addition, numerical values are interpreted as being False if the value is 0, and True otherwise. This applies to conditional tests, conditional loops, and other operations that consume a truth value.

Complex numbers

Complex numbers can be represented in rectangular form or polar form. The rectangular form will show as something like 2+3ⅈ on the display, where 2 is the real part and 3 is the imaginary part. The polar form will show as something like 1∡90° on the display, where 1 is the modulus and 90° is the argument. The two forms can be mixed and matched in operations. The calculator typically selects the most efficient form for a given operation.

Available operations on complex numbers include basic arithmetic, trigonometric, logarithms, exponential and hyperbolic functions, as well as a few specific functions such as conj or arg. These functions are available in the Complex Menu.

Expressions

Algebraic expressions and equations are represented between quotes, for example X+1 or A+B=C. Many functions such as circular functions, exponential, logs or hyperbolic functions can apply to algebraic expressions.

An expression that contains an equal sign, e.g. sin X + 1 = cos X, is called an equation. It can be given as an argument to the solver.

Lists

Lists are sequence of items between curly braces, such as { 1 'A' "Hello" }. They can contain an arbitrary number of elements, and can be nested.

Operations such as sin apply to all elements on a list.

Vectors and matrices

Vector and matrices represent tables of numbers, and are represented between square brackets, for example [1 2 3] for a vector and [[1 2] [3 4] for a 2x2 matrix.

Vector and matrices follow their own arithmetic rules. Vectors are one-dimensional, matrices are two-dimensional. DB48X also supports tables with a higher number of dimensions, but only offers limited operations on them.

DB48X implements vector addition, subtraction, multiplication and division, which apply component-wise. Multiplication and division are an extension compared to the HP48.

DB48X also implements matrix addition, subtraction, multiplication and division. Like on the HP48, the division of matrix A by matrix B is interpreted as left-multiplying A by the inverse of B.

As another extension, algebraic functions such as sin apply to all elements in a vector or matrix in turn.

Units

Unit objects represent values with an associated unit. They are represented using the _ operator, e.g. 1_km/s, although on display this operator is shown as a thin space, e.g. 1 km/s.

Units as implemented in DB48X are modernized compared to what the HP48 implements, and differ from the HP RPL implementation in the following ways:

• Add recent SI prefixes, Z (zetta), Y (yotta), R (ronna) and Q (quetta) for large scale, z (zepto), y (yocto), r (ronto) and q (quecto) for small scale.

• Take into account the impact on unit conversions of the revised 2023 definition of the foot.

• Use exact (fraction-based) conversions wherever possible. This notably matters for the conversions of pre-2023 US Survey units, where the ratio is 1_ft = 1200/3937_m, which is not well represented using decimal values.

• Add computer-related units, like the byte, the bit, the baud, as well as a menu supporting these units.

• In order to support the computer-related units better, also recognize the power-of-two variants, e.g. 1_kiB is 1024_B. Also recogize the K prefix in addition to k.

Units file

The built-in units can be overriden by your own set of units, which is defined in a CSV file called config/units.csv in the calculator. CSV stands for "Comma separated values, and is a common interchange format for spreadsheet data.

Here is an example of file that would let you have a units menu called Money to convert between various monetary units:

"Money"
"USD", "1_USD"
"EUR", "1.07_USD"
"GBP", "1.24_USD"
"CAD", "0.73_USD"
"AUD", "0.65_USD"
"CHF", "1.11_USD"

• All values must be placed between quotes. Separators between text values are mostly ignored.

• Rows in a file containing a single value denote unit menus, unless the value begins with an = sign.

• Rows in a file containing two ore more values denote unit menu entries, which will be added to the previous menu.

• The first column in these rows give the name of the unit as shown in the menu.

• The second column in these rows gives the definition of the unit.

• The definition should be reduced to = if the first column contains what would be a valid unit expression. For example, to place km/h in a menu, use "km/h", "=" since km can be deduced from existing unit m using the standard "kilo" unit prefix, and h is an existing unit.

A unit where the value is 1 of the same unit is a base unit. This is the case for USD in the example above, which is considered the base units for monetary exchanges. Units that refer to the same base unit can be converted with one another. For example, you can convert between GBP and AUD because they both have the same USD base unit.

The commands ShowBuiltinUnits and HideBuiltinUnits indicate if the built-in uits should be shown after the units loaded from the file. The default is that when a units file is present, the built-in units are hidden. This only affects the menus. Built-in units can always be used in expressions if they are typed manually. However, units loaded from file will be looked up first, so that a built-in unit can be overriden by the units file, which can be useful if a definition changes like the US Survey foot changed on January 1st, 2023.

If you build a units file, it is recommended that you do not exceed 17 unit submenus so that all unit categories fit on a single screen.

Cycle command customization

The menu name "=Cycle" is reserved to define sequences of units that the Cycle command (bound to the ×10ⁿ key) will recognize as special. For example, you can ensure that mm and in convert to one another as follows:

"=Cycle"
"in", "mm"
"mm", "in"
"USD", "EUR"
"EUR", "CHF"
"CHF", "USD"

If you do provide a Cycle customization for a unit, other normal behaviours of the Cycle command for units are disabled, notably conversion between various relevant scales and conversion between fractions and decimal. To force a particular conversion to happen in decimal, you can override the definition of the corresponding unit in the units file, for example:

"in",   "25.4_mm"

Constants

Constant objects represent named values like Euler's constant e, the ratio between circumference and diameter of a circle π, or the speed of light c. They are represented by a name, and have an associated value.

Like units, there are some built-in constants, and additional constants can be provided by a config/constants.csv file, which has the same format as for the units file.

On the command-line, constant names are prefixed with CST, which is a way to distinguish them from normal symbols.

You can edit the constants catalog by recalling its content on the stack using "config:equations.csv" RCL, editing the values, and then storing the content back to disk using "config:equations.csv" STO.

Infinite results

Some operations such as 1/0 or tan 90 ° are said to produce an infinite result. Like HP calculators, DB48X can either generate an error or produce a special result in these cases.

• If the InfinityValue (-22) flag is clear, corresponding to the InfinityError setting, then the operation generates a Division by zero error. Note that the text of the error is different than for Hewlett-Packard calculators, which generate an Infinite result error.

• If the InfinityValue flag is set and NumericalConstants (-2) flag is clear, corresponding to the SymbolicConstants setting, then the operation generates the ∞ (infinity) constant with the appropriate sign for the result, and the InfiniteResultIndicator (-26) flag is set.

• If the InfinityValue flag is set and NumericalConstants flag is set, then the operation generates the numerical value associated to the ∞ constant with the appropriate sign for the result, and set the InfiniteResultIndicator flag.

By default, the numerical value of the ∞ constant is set to 9.99999E999999, which is significantly smaller than what would actually cause a numerical overflow, but is easy to read. This value can be changed in the config/constants.csv file.

Overflow and underflow

There is a maximum representable value for decimal numbers. This value is significantly larger than on HP calculators. Whereas HP RPL implementations could not represent decimal numbers with an exponent bigger than 499 or smaller than -499, DB48X supports exponents ranging from -2^60 to 2^60 (±1 152 921 504 606 846 976).

An overflow happens if the result would have an exponent higher than the maximum. An underflow happens if the result would have an exponent lower than the minimum. Like HP calculators, DB48X can either generate an error or produce a special result in these cases.

• If the UnderflowValue (-20) or OverflowValue (-21) is clear, corresponding to the UnderflowError or OverflowError setting, then the operation generates a Positive numerical underflow, Negative numerical underflow or Numerical overflow error depending on the computation. Note that the text of the error is different than for Hewlett-Packard calculators, which generate an Overflow, Positive Underflow or Negative Underflow error.

• If the UnderflowValue or OverflowValue is set, and NumericalConstants (-2) flag is clear, corresponding to the SymbolicConstants setting, then overflowing operations generate the ∞ (infinity) constant with the appropriate sign for the result, and underflowing operations generate a zero value. The operation also sets the NegativeUnderflowIndicator (-23), PositiveOverflowIndicator (-24) or OverflowIndicator (-25) flag.

• If the UnderflowValue or OverflowValue is set, and NumericalConstants flag is set, then overflowing operations generate the numerical value associated to the ∞ constant, and underflowing operations generate a zero value. The operation also sets the NegativeUnderflowIndicator (-23), PositiveOverflowIndicator (-24) or OverflowIndicator (-25) flag.

Undefined

Some operations such as 0/0 are undefined, meaning that there isn't a single possible answer.

If the UndefinedValue flag is set, such operations return the constant ?, and further operations on the value will keep returning the same undefined result.

If the UndefinedValue flag is is clear, which corresponds to UndefinedError being set, such operations will generate an Undefined operation error.

Library

The Library is a catalog of frequently used and rarely modified objects that are stored on disk in the config/library.csv file.

You can edit it by recalling its content on the stack using "config:library.csv" RCL, editing the values, and then storing the content back to disk using "config:library.csv" STO.

Equations Library

The equations library is a catalog of common equations that are stored on disk in the config/equations.csv file.

You can edit it by recalling its content on the stack using "config:equations.csv" RCL, editing the values, and then storing the content back to disk using "config:equations.csv" STO.