Variables, Data Types, Declaring Variables, Comments, and Database Access

Throw-away identifiers: Sheerpower also reserves two special throw-away identifiers: _ for numbers and _$ for strings. Assign to them when you want an expression to run and want a visual signal that you are intentionally ignoring its return value. This makes your intent clear at a glance.

For example, the join() function quickly joins strings together and returns the final length. If we don't need the length, we can do this:

• Adapts to mixed data: Perfect for code that handles user input, file data, or API responses that might change type from one call to the next.
• Type stability after assignment: Once a value is assigned, the variable behaves as that type until it is assigned something else.

This design eliminates floating-point approximation and enables efficient comparisons and arithmetic. Expressions like (0.1 + 0.2) - 0.3 evaluate to 0 in Sheerpower.

By contrast, the same expression in IEEE math yields:
0.00000000000000005551115123125783

For statistics and large-scale data, Sheerpower supports scientific notation (e.g., 4.123e50). The REAL type provides a high-precision decimal numeric type supporting up to 54 digits before and 16 digits after the decimal point. Within this range, decimal values are represented exactly, so calculations are predictable and do not introduce binary floating-point rounding error.

When greater dynamic range or additional decimal precision is required, REAL automatically uses scientific notation while retaining up to 64 significant decimal digits. The exponent can have a magnitude of up to 1,000,000,000 (a one followed by a billion zeros), allowing REAL values to represent extremely large or extremely small numbers.

The same REAL holds three more kinds of value, with no declaration and no second type. A divide of two whole numbers whose quotient does not terminate keeps the exact fraction: a = 1 / 3 is one third, not a rounded decimal, so a * 3 is exactly 1, and it prints as the decimal you expect (.3333333333333333) until you ask for the fraction with fraction$(a). See Exact Fractions: the RATIONAL Mode.

A complex number is written with the i suffix: z = 3 + 4i. Arithmetic, abs(z) (which is 5 here), sqr(), exp(), log() and the trig functions all take one, and a negative square root that raises an error on a plain real works once you say you mean the complex plane: sqr(-4 + 0i) is 0+2i. See Processing Complex Numbers.

Finally, a REAL can hold NaN and Inf. They are never produced by ordinary arithmetic on finite values (1 / 0 still raises), but they come in through data — a val("NaN"), a CSV cell, a float field of a table — and propagate the IEEE way: x = _inf then x - x is NaN, and isnan(), isinf() and isfinite() find them.

a = 1 / 3
print a * 3                ! 1
print fraction$(a)         ! 1/3
z = 3 + 4i
print abs(z)               ! 5
print sqr(-4 + 0i)         ! 0+2i
print typeof$(a)           ! Name:A, Dtype:Real, *Rational*
print typeof$(z)           ! Name:Z, Dtype:Real, *Complex*

typeof$() names the mode a value is in (*Narrow*, *Wide*, *Sci*, *Rational*, *Complex*, *NaN*, *Inf*); the engine moves between them by value, and programs never have to.

Sheerpower is strongly typed

Sheerpower does not convert between types on your behalf. A STRING value cannot be assigned to a REAL variable, even when it looks numeric—"123.45" is still text, not a number. Assigning it directly is a compile-time error; use VAL() to convert it explicitly. DYNAMIC variables (documented above) are the one exception.

5. Constants Custom Data Types

Sheerpower lets you define your own constants and custom data types. These features make code more readable, expressive, and secure.

Constants

Freezable Variables — Runtime Immutability

A const is fixed at compile time. A variable can change forever. Configuration data lives in the gap between them: it is loaded at runtime — from a file, a logical, a table — and from that moment on it should never change again.

Freezable variables close that gap. Load the value normally, then freeze it. From then on, any attempt to change it raises a clear error instead of silently corrupting your configuration.

Declaring a Freezable Variable

Only variables declared freezable can be frozen. This is the gate: the variable's author decides whether freezing is part of its contract, and no other code can freeze a variable that was never meant to be frozen.

Cluster members may be declared freezable too, so individual fields of a configuration cluster can be protected.

FREEZE and UNFREEZE

freeze and unfreeze are runtime statements — a variable is frozen from the moment the freeze statement executes, not from where it appears in the source. A variable may be assigned freely before freezing, including many times during a loading loop.

The error is catchable with when exception, and the frozen value is untouched. Every way of writing a variable is covered — plain assignment, retries++, join() into a frozen string, lset, substring assignment (frozen$[1:2] = "ab"), a routine's returning value, and even writing through a view into a frozen string.

typeof$() reports the state at any time:

The Unfreeze Window — Reloading Configuration

unfreeze re-opens a frozen variable for writing. Use it to create a small, deliberate window for changes — such as reloading a configuration file — and refreeze immediately:

Keep the unfreeze and the matching freeze in the same routine, and keep the window small. A useful property of this habit: searching your source for unfreeze finds every place a frozen value can legitimately change. Anything else raises an exception.

PERMAFREEZE — The One-Way Ratchet

permafreeze freezes a variable permanently for the rest of the run. It cannot be thawed — unfreeze on a permafrozen variable raises an error rather than quietly reopening it.

The distinction between the two is worth stating plainly: freeze protects against accident — any code could still unfreeze it deliberately. permafreeze protects against intent — once set, nothing in the program can change the value for the rest of the run. Use freeze for values that may legitimately reload, and permafreeze for load-once values that must survive the whole run untouched.

Freezing Whole Arrays and Clusters

The things most often loaded at runtime and never meant to change are not single values but tables: a list of tax bands, the day names, a lookup cluster read from a file at startup. Those can be frozen as a whole. Declare the array or cluster freezable after the dim or cluster statement, and freeze it once it is loaded.

A frozen array is frozen in contents and shape: an element write, an append with (*), any fill, redim, or an array-expression assignment raises the same exception a frozen variable does, and the array is untouched. Reading it, size(), the statistics functions, and passing it to a routine as a with values(*) parameter are all free. The freeze travels with the data: a routine that receives the array as a returning parameter raises on its own write.

A frozen cluster is frozen in contents and row set: a field write on any row, add cluster, delete from cluster, reset cluster, cluster input and copy cluster into it all raise. Everything that only looks stays free — collect with its include and sort by, for each, findrow, set cluster: row n. One rule worth stating: a store inside a collect block, such as words->count = _extracted, is a field write and raises — that is exactly the quiet mutation freezing exists to catch. A cluster handed to a routine raises in the routine too. Freezing a member and freezing the cluster are independent: unfreezing the cluster leaves a member you froze separately still frozen. permafreeze works on both, with the same one-way rule. typeof$ reports all of it: typeof$(rates) gives Name:RATES, Dtype:Real, *Array*, Dims:1, Bounds:1:3, Size:3 , *Fixed*, *Freezable*, *Frozen*, and typeof$(cities) gives Name:CITIES, *Cluster*, Rows:2, *Freezable*, *Frozen*.

Details Worth Knowing

• Freezing a never-assigned freezable is allowed — it freezes at empty ("") or zero. Occasionally useful for "this feature stays off for this run."
• Reading a frozen variable is completely normal and costs nothing. Freezing only affects writes.
• Crash dumps and show all report the frozen state, so a "why won't this assign?" question answers itself in the diagnostics.

Custom Data Types

This makes code more self-explanatory—using money signals financial data, not just a number. Custom data types are enforced at compile time, as the next example shows.

The compiler replies:

Secure Custom Types

If the program crashes, password appears as <nodump> in debug output—helping to protect secrets from accidental exposure.

6. Formatting Your Output

Format Syntax

• $ — Literal dollar sign
• %.2m — Two decimal places in monetary format

7. A Quick Look at Database Variables

Sheerpower provides a secure way to access table fields using table_name(field_name). This separates code from data and protects against SQL injection.

Database access is an advanced feature. To learn more, see the Integrated Database Access Overview tutorial.

8. Documenting Your Code with Comments

Comments are ignored by the compiler and help others understand your code. Use // (preferred) or ! to begin a comment.

9. Converting Between Strings and Numbers

Sheerpower enforces variable types. You cannot assign a STRING directly to a REAL or vice versa — use conversion functions.

Converting a String to a Number

For a complete walkthrough, see Strings to Reals -- Extracting Numbers From Text.

Converting a Number to a String

Conversions like val() and str$() are commonly used when reading user input, importing raw data, or constructing strings for display.

10. Putting It All Together