NumFmt Reference

Table of contents

• Introduction
• Format string
• Constructor
• Instance methods
  • apply()
  • clamp()
  • fmtVal()
  • isValid()
  • round()
• Instance Properties
  • fmtStr
  • fDigits
  • iDigits
  • max
  • min
  • rndMult
  • step
  • twFmt
  • width

Introduction

The NumFmt class rounds and formats numbers according to a format specification. A NumFmt instance can be used to apply several operations according to the specified format, including:

• Rounding
• Clamping the number to be between a minimum and maximum
• Converting the number to a formatted string.

NumFmt is used by the numeric state variables to specify how to present numbers. It provides a common and compact way of specifying numeric formatting.

The NumFmt class is a global property and does not have to be imported.

Format string

The format string specifies the formatting and rounding that will be applied to instance operations. It is set during construction and may be modified using the fmtStr instance property. It may contain the following RegExp specifications in order:

• +|-|+- (optional)
  A '+' in the string means to use a '+' for positive numbers in the formatted value. A '-' in the string means the format includes negative values in the integer digits. If either '+' or '-' is present, the minimum value implied by the format is negative.
• \d+ (optional)
  The number of integer digits in the formatted value. If omitted, the default is 8.
• \.\d+ (optional)
  The number of fraction digits in the formatted value.
• ',' (optional)
  Include thousands separators in the formatted value.
• m(?<number>\d*(\.\d+)?) (optional)
  Round formatted values to a multiple of . The default rounding value is 1. If is less than 1, the number of fraction digits is derived from and overrides any \.\d+ specification. If is 1 or greater, the number of fraction digits is forced to 0. If m is omitted but fraction digits are specified, the rounding multiple is 10^{-fraction digits}.
• u|d (optional)
  Round up or down to the nearest multiple.
• c (optional)
  Clamp the formatted value to the minimum and maximum values.
• s(?<number>\d*(\.\d+)?) (optional)
  The step for numeric inputs: The amount to increment or decrement an input value, rounded to a multiple of the rounding multiple. If omitted, the step is the rounding multiple.
• T.* (optional).
  A numeric thumbwheel format string. If omitted, there will be one wheel for each digit when a Thumbwheel is used for input. See Thumbwheel Reference.

Constructor

Syntax

new NumFmt(fmtStr)
new NumFmt(fmtStr, min)
new NumFmt(fmtStr, min, max)

The NumFmt constructor sets up formatting according to the fmtStr. It may also optionally set a minimum or maximum value.

Parameters

• fmtStr
  A NumFmt format string.
• min (optional)
  The minimum formatted value. If omitted, the minimum value is set to the minimum implied by fmtStr. If neither - nor + is present in the fmtStr, the minimum is 0. If either is present, the minimum is the negative of the maximum value representable by the fmtStr.
• max (optional)
  The maximum formatted value. If omitted, the maximum value is set to the maximum representable by fmtStr by assuming the digit '9' for each integer and fractional position.

Instance methods

apply()

Syntax

apply(value)
apply(value, clampIt)

Apply a format to value. Returns a Number rounded and clamped according to the current fmtStr. If clampIt is true, the number will clamped to be between the current minimum and maximum values regardless of the clamp setting in fmtStr. If clampIt is false, the number is not clamped even if fmtStr contains c.

Non-finite values are returned as is.

Parameters

• value
  The value to be rounded and clamped.
• clampIt (optional)
  If clampIt is true, the value will be clamped to be between the current minimum and maximum values. If omitted or undefined, the value will be clamped according to the clamp setting in the fmtStr. If false, the value will not be clamped, even if the fmtStr has the clamp setting.

Return value

A Number.

clamp()

Syntax

clamp(value)

Return value clamped to be between the current minimum and maximum values. The current fmtStr is ignored.

Return value

A Number.

fmtVal()

Syntax

fmtVal(value)

Return a string rounded, clamped, and formatted according to the current fmtStr. If value is not valid (see isValid(): not finite or outside the current minimum and maximum), the string 'NaN' is returned. If the fmtStr contains +, non-negative values are prefixed with +. If the fmtStr contains ,, thousands separators are included using fmtNum().

Return value

A String.

isValid()

Syntax

isValid(value)

Returns true if value is finite and within the current minimum and maximum values.

Return value

A Boolean.

round()

Syntax

round(value)

Return value rounded according to the current rndMult value. The value is not clamped. NaN is passed through unmodified.

Return value

A Number.

Instance Properties

fmtStr

Get/set the current format string. The properties that depend on the format string are recomputed if the fmtStr is set, except for min and max, which keep their current values. The limits implied by the new format are used only when min or max is subsequently set to undefined.

Value

A string.

fDigits

The number of fractional digits in the number specified by the fmtStr. For example, '4.2' has two fractional digits.

iDigits

The number of integer digits in the number. For example, '4.2' has four integer digits. Defaults to 8 if the fmtStr has no integer digit count.

max

Get/set the current maximum value. If set to undefined or NaN, the current maximum value will be set to the maximum representable by fmtStr by assuming the digit '9' for each integer and fractional position. Otherwise, the value must not exceed that maximum (this is asserted) and is rounded down to a multiple of rndMult.

Value

A Number.

min

Get/set the current minimum value. If set to undefined, the current minimum value will be set to the minimum implied by fmtStr. If neither - nor + is present in the fmtStr, the minimum is 0. If either is present, the minimum is the negative of the maximum value representable by the fmtStr by assuming the digit '9' for each integer and fractional position. Otherwise, the value must not be less than that minimum (this is asserted) and is rounded up to a multiple of rndMult.

Value

A Number.

rndMult

The rounding multiple specified by the fmtStr. Formatted values will be rounded to rndMult. It is a plain field and is recomputed when fmtStr is set.

step

The increment/decrement step for numeric inputs. It defaults to rndMult and is overridden by the s<number> specification in the fmtStr (rounded to a multiple of rndMult).

twFmt

The Thumbwheel format that was extracted from the fmtStr.

width

The field width implied by the fmtStr. Includes a sign, integer digits, and any fraction digits with '.'. If thousand separators are requested, it includes the maximum number of separators for the number of integer digits. For example, '-4.2,' has a width of 9. It is a plain field set from the fmtStr; it should be treated as read-only.