NumFmt Reference

Table of contents

• Introduction
• Format string
• Constructor
• Instance methods
  • apply()
  • clamp()
  • fmtVal()
  • isValid()
  • round()
• Instance Properties
  • fmtStr
  • fDigits
  • iDigits
  • max
  • min
  • rndMult
  • 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.
• \d+ (required)
  The number of integer digits in the formatted value.
• \.\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.
• 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.
• 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 - is not present in the fmtStr, the minimum is 0. If - is present in the fmtStr, 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.

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 false, the value will be clamped according to the clamp setting in the fmtStr.

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.

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.

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.

max

Get/set the current maximum value. If set to undefined, the current maximum value will be set to the maximum representable by fmtStr by assuming the digit '9' for each integer and fractional position.

Value

A string.

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 - is not present in the fmtStr, the minimum is 0. If - is present in the fmtStr, the minimum is the negative of the maximum value representable by the fmtStr by assuming the digit '9' for each integer and fractional position.

Value

A string.

rndMult

The rounding multiple and increment/decrement step specified by the fmtStr. Formatted values will be rounded to rndMult. Read-only.

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. Read-only.