Package net.sf.saxon.functions

## Class FormatNumber

- java.lang.Object
- - net.sf.saxon.functions.AbstractFunction
  - - net.sf.saxon.functions.SystemFunction
    - - net.sf.saxon.functions.FormatNumber

- All Implemented Interfaces:
    `Callable`, `StatefulSystemFunction`, `Function`, `GroundedValue`, `Item`, `Sequence`

      public class FormatNumber
      extends SystemFunction
      implements Callable, StatefulSystemFunction

  Implementation of format-number() function. Note this has no dependency on number formatting in the JDK.

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `FormatNumber()` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static java.math.BigDecimal` | `adjustToDecimal​(double value, int precision)` | Convert a double to a BigDecimal.
    `StringValue` | `call​(XPathContext context, Sequence[] arguments)` | Call the format-number function, supplying two or three arguments
    `FormatNumber` | `copy()` | Make a copy of this SystemFunction.
    `Expression` | `fixArguments​(Expression... arguments)` | Allow the function to create an optimized call based on the values of the actual arguments.
    `static java.lang.String` | `formatExponential​(DoubleValue value)` | Format a double as required by the adaptive serialization method
    `protected DecimalSymbols` | `getNamedDecimalFormat​(DecimalFormatManager dfm, java.lang.String lexicalName)` | Get a decimal format, given its lexical QName

    - ### Methods inherited from class net.sf.saxon.functions.SystemFunction

      `dependsOnContextItem, dynamicCall, equals, export, exportAdditionalArguments, exportAttributes, getArity, getCardinality, getCompilerName, getContextNode, getDescription, getDetails, getErrorCodeForTypeErrors, getFunctionItemType, getFunctionName, getIntegerBounds, getNetCost, getOperandRoles, getRequiredType, getResultItemType, getResultItemType, getRetainedStaticContext, getSpecialProperties, getStaticBaseUriString, getStreamerName, importAttributes, isTrustedResultType, makeCall, makeFunction, makeFunctionCall, makeOptimizedFunctionCall, resultIfEmpty, setArity, setDetails, setRetainedStaticContext, supplyTypeInformation, toShortString, toString, typeCheckCaller`

    - ### Methods inherited from class net.sf.saxon.functions.AbstractFunction

      `atomize, deepEquals, effectiveBooleanValue, getAnnotations, getStringValue, getStringValueCS, isArray, isMap, makeNewContext, simplify, typeCheck`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface net.sf.saxon.om.Function

      `getGenre`

    - ### Methods inherited from interface net.sf.saxon.om.GroundedValue

      `asIterable, concatenate, containsNode, materialize`

    - ### Methods inherited from interface net.sf.saxon.om.Item

      `getLength, head, isStreamed, itemAt, iterate, reduce, subsequence`

    - ### Methods inherited from interface net.sf.saxon.om.Sequence

      `makeRepeatable`

- - ### Constructor Detail

    - #### FormatNumber

          public FormatNumber()

  - ### Method Detail

    - #### fixArguments

          public Expression fixArguments​(Expression... arguments)
                                  throws XPathException

      Allow the function to create an optimized call based on the values of the actual arguments. This handles the case where the decimal format name is supplied as a literal (or defaulted), and the picture string is also supplied as a literal.
      Overrides:
        `fixArguments` in class `SystemFunction`
      Parameters:
        `arguments` - the supplied arguments to the function call
      Returns:
        either a function call on this function, or an expression that delivers the same result, or null indicating that no optimization has taken place
      Throws:
        `XPathException` - if an error is detected

    - #### adjustToDecimal

          public static java.math.BigDecimal adjustToDecimal​(double value,
                                                             int precision)

      Convert a double to a BigDecimal. In general there will be several BigDecimal values that are equal to the supplied value, and the one we want to choose is the one with fewest non-zero digits. The algorithm used is rather pragmatic: look for a string of zeroes or nines, try rounding the number down or up as appropriate, then convert the adjusted value to a double to see if it's equal to the original: if not, use the original value unchanged.
      Parameters:
        `value` - the double to be converted
        `precision` - 2 for a double, 1 for a float
      Returns:
        the result of conversion to a double

    - #### call

          public StringValue call​(XPathContext context,
                                  Sequence[] arguments)
                           throws XPathException

      Call the format-number function, supplying two or three arguments
      Specified by:
        `call` in interface `Callable`
      Specified by:
        `call` in interface `Function`
      Parameters:
        `context` - the dynamic evaluation context
        `arguments` - the values of the arguments, supplied as Sequences.

        Generally it is advisable, if calling iterate() to process a supplied sequence, to call it only once; if the value is required more than once, it should first be converted to a `GroundedValue` by calling the utility methd SequenceTool.toGroundedValue().

        If the expected value is a single item, the item should be obtained by calling Sequence.head(): it cannot be assumed that the item will be passed as an instance of `Item` or `AtomicValue`.

        It is the caller's responsibility to perform any type conversions required to convert arguments to the type expected by the callee. An exception is where this Callable is explicitly an argument-converting wrapper around the original Callable.

      Returns:
        the result of the function
      Throws:
        `XPathException` - if any dynamic error occurs

    - #### getNamedDecimalFormat

          protected DecimalSymbols getNamedDecimalFormat​(DecimalFormatManager dfm,
                                                         java.lang.String lexicalName)
                                                  throws XPathException

      Get a decimal format, given its lexical QName
      Parameters:
        `dfm` - the decimal format manager
        `lexicalName` - the lexical QName (or EQName) of the decimal format
      Returns:
        the decimal format
      Throws:
        `XPathException` - if the lexical QName is invalid or if no decimal format is found.

    - #### formatExponential

          public static java.lang.String formatExponential​(DoubleValue value)

      Format a double as required by the adaptive serialization method
      Parameters:
        `value` - the value to be formatted
      Returns:
        the formatted value

    - #### copy

          public FormatNumber copy()

      Make a copy of this SystemFunction. This is required only for system functions such as regex functions that maintain state on behalf of a particular caller.
      Specified by:
        `copy` in interface `StatefulSystemFunction`
      Returns:
        a copy of the system function able to contain its own copy of the state on behalf of the caller.