Format Macros¶

Turning computed values into something a student should read.

shownum, number_format, mathquill and htmlspecialchars do not exist

Earlier versions of this page documented all four. None is on the allowlist. The engine's own display macros are below — there are far more of them, and they handle the cases that matter in maths questions: reduced fractions, significant figures, and expressions that should not print as 1*x^1.

Whole numbers and decimals¶

`prettyint($n)`¶

An integer with thousands separators. Non-numeric input passes through untouched.

$population = prettyint(1234567)   // "1,234,567"

`prettyreal($value, $decimals, $comma)`¶

A decimal rounded to $decimals places, with separators. Accepts an array as well as a single value, so a whole data set formats in one call.

$price = prettyreal(1234.5678, 2)   // "1,234.57"

prettyreal_instring($str, $d) does the same to every number found inside a string, which is the way to format a sentence you have already assembled.

`round($n, $decimals)`¶

Rounds the value itself rather than its display. Use round when the number feeds further calculation and a pretty* macro when it is about to be shown. round_instring($str, $d) rounds every number in a string.

Significant figures¶

`prettysigfig($value, $sigfig, $comma, $choptrailing, $orscinot, $sigfigbar)`¶

The macro to reach for whenever a question is about measurement or precision.

$measured = prettysigfig(0.0023456, 3)   // 3 significant figures

$choptrailing drops padding zeros when the value is exact (2.5 to 3 figures gives 2.5, not 2.50); a zero produced by rounding stays (2.501 still gives 2.50)
$orscinot switches to scientific notation (1.23*10^(5)) whenever the absolute value is above 1000 or below 0.001
$sigfigbar resolves ambiguous trailing zeros in whole numbers. prettysigfig(12000, 3, ",", false, false, true) gives 12,overline(0)00, and 120 to 3 figures gives 120.. It never marks a nonzero digit, and overline(...) only renders inside backticks

prettysigfig_instring($str, $sigfig) applies it throughout a string. Only $sigfig takes effect: the engine resets $comma, $choptrailing, $orscinot and $sigfigbar to their defaults, so passing them changes nothing. And roundsigfig($val, $sigfig) rounds the value itself.

Scientific notation¶

`makescinot($n, $decimals, $symbol)`¶

$decimals sets the mantissa precision and defaults to 8; pass -1 to let it choose. $symbol picks the form: "x" (the default) writes the AsciiMath xx, which displays as ×; "*" writes *; "E" gives E-notation.

$sci = makescinot(0.000123, 2)        // "1.23 xx 10^(-4)"
$sci = makescinot(0.000123, 2, "*")   // "1.23*10^(-4)"
$sci = makescinot(0.000123, 2, "E")   // "1.23E-4"

Zero returns "0", and non-numeric input prints an error.

`prettysmallnumber($n, $space)`¶

The opposite move — expands a small number out of E-notation into ordinary decimal form, so 1.0E-5 displays as 0.00001. Pass true to group the digits with thin spaces.

Fractions¶

Macro	Produces
`makereducedfraction($n, $d, $dblslash, $varinnum)`	the fraction in lowest terms
`dispreducedfraction($n, $d, $dblslash, $varinnum)`	the same, for display
`makereducedmixednumber($n, $d)`	a mixed number
`fractowords($numer, $denom, $options)`	the fraction written out in words

$frac = makereducedfraction(6, 8)   // "3/4"

$dblslash set to true writes //, which AsciiMath displays as a plain inline slash instead of a stacked fraction. With makereducedfraction, set it to "parts" to get [numerator, denominator] back as an array (dispreducedfraction cannot return the parts). $varinnum is a variable name to put in the numerator: makereducedfraction(6, 4, false, "x") gives (3x)/2, and a reduced numerator of 1 gives (x)/2. The numerator and denominator themselves must be numbers.

Expressions¶

A computed expression printed raw looks wrong — 1*x^1 + -3 rather than x - 3. The *pretty* family fixes that.

Macro	Use for
`makepretty($exp)`	tidying sign pairs only (`+-` → `-`, `--` → `+`); it leaves `1*` and `^1` in place
`makexpretty($exp)`	an expression in `x`
`makexxpretty($exp, $funcs)`	an expression with named functions
`polymakepretty($exp)`	a polynomial
`prettynegs($a)`	replacing every hyphen with a true minus sign (`−`) in display text
`makeprettynegative($exp)`	putting negatives in brackets: `3--4` → `3-(-4)`, `3+-4` → `3+(-4)`

The first four have a *disp variant — makeprettydisp, makexprettydisp, makexxprettydisp, polymakeprettydisp — which wraps the result in backticks for display rather than further processing. prettynegs and makeprettynegative have no *disp variant.

$shown = polymakepretty($poly)

Words, dates and time¶

Macro	Produces
`numtowords($num, $doth, $addcontractiontonum, $addcommas)`	"forty-two"; `$doth` gives ordinals
`numtoroman($n, $uc)`	Roman numerals; `$uc` selects upper case
`prettytime($time, $in, $out)`	a time converted between formats
`today($format)`	today's date, default `"F j, Y"`
`formatcomplex($real, $imag)`	a complex number

HTML¶

`htmldisp($str, $var)`¶

Writes a simple expression as HTML without maths rendering. Letters are italicised (only the names listed in $var, comma-separated, if given), and ^2 / _1 become superscripts and subscripts: htmldisp("x^2+y_1") gives x2+y1. It does not escape HTML. There is no htmlspecialchars; the allowlisted native escape is htmlentities($s).

`formpopup`, `formhoverover`, `forminlinebutton`¶

Interactive display helpers — a popup, a tooltip and an inline expander:

$hint = formhoverover("hint", "The slope is the coefficient of `x`.")

Do not hide anything a student needs

Content behind a hover is unreachable on touch devices and awkward with a screen reader. Use these for optional extras, never for information required to answer.

Math display uses backticks, not a macro¶

There is no mathquill macro. Maths is written in AsciiMath between backticks, in the question text:

<p>Solve `x^2 - 5x + 6 = 0` for `x`.</p>

Never LaTeX — \frac, \sqrt and friends do not render.

For the maths input box a student types into, formatting is controlled by the question's answer type and options such as $answerformat, not by a macro. (The setupmathquillfillin helper exists upstream but is not available on this platform's engine build.)

Examples¶

A currency answer¶

$cost = rrand(10, 90, 0.05)
$display = "$" . prettyreal($cost, 2)

A percentage¶

$rate = rrand(0.02, 0.15, 0.01)
$shown = prettyreal($rate * 100, 1) . "%"

A measurement to three significant figures¶

$mass = rrand(1.5, 9.5, 0.01)
$shown = prettysigfig($mass, 3)

A polynomial that reads properly¶

$a = nonzerorand(-5, 5)
$b = nonzerorand(-9, 9)
$poly = polymakepretty("$a*x^2 + $b*x")

Tips¶

pretty* for display, round for arithmetic. Formatting returns a string; feeding it back into a calculation gives the wrong answer.
prettysigfig, not round, whenever the question is about precision.
Format the string, not each number, when a sentence is already assembled — that is what the *_instring variants are for.
Use htmlentities, not htmlspecialchars, to escape student input.