Package org.djunits.formatter

Class QuantityFormat

java.lang.Object
org.djunits.formatter.Format<QuantityFormat,QuantityFormatContext>
org.djunits.formatter.QuantityFormat
public class QuantityFormat extends Format<QuantityFormat,QuantityFormatContext>
QuantityFormat stores the settings that influence both the value part and the unit part of an output string when formatting a quantity.

Copyright (c) 2026-2026 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See for project information https://djunits.org. The DJUNITS project is distributed under a three-clause BSD-style license.

Author:
Alexander Verbraeck

  • Constructor Details

    • QuantityFormat

      protected QuantityFormat(QuantityFormatContext ctx)
      Construct a QuantityFormat object with a given context. Note that the context can be an existing context that is being modified or a default context.
      Parameters:
      ctx - the quantity format context to use

  • Method Details

    • instance

      public static QuantityFormat instance()
      Return an instance of QuantityFormat, initialized with the default values.
      Returns:
      an instance of QuantityFormat, initialized with the default values

    • changeDefaults

      public static QuantityFormat changeDefaults()
      Return an instance of QuantityFormat with the DEFAULT values, which can be changed for all subsequent calls.
      Returns:
      an instance of QuantityFormat with the DEFAULT values

    • resetDefaults

      public static void resetDefaults()
      Reset the default values of QuantityFormat to their original values.

    • setAutoSiPrefix

      public QuantityFormat setAutoSiPrefix()
      Turn on the automatic allocation of the unit to its closest SI prefix. E.g., turn 20400 m into "20.4 km".
      Returns:
      QuantityFormat object for fluent design

    • setAutoSiPrefix

      public QuantityFormat setAutoSiPrefix(int minExponent, int maxExponent)
      Turn on the automatic allocation of the unit to its closest SI prefix, in case the exponent of the 10-power in scientific notation is between minExponent and maxExponent, inclusive. E.g., format 20400 m as "20.4 km" after calling setAutoSiPrefix(-9,9) but format it as 20400 m after calling setAutoSiPrefix(-9,0). Note that the kg for Mass is associated with an exponent of 3, and the g with an exponent of 0. For the LinearObjectDensity that is expressed in /m, /km is associated with an exponent of 3 and /mm with an exponent of -3. Note that the minimum and maximum exponents are clamped between -30 and 30.
      Parameters:
      minExponent - minimum exponent for the 10-power in scientific notation to use SI prefixes for (inclusive)
      maxExponent - maximum exponent for the 10-power in scientific notation to use SI prefixes for (inclusive)
      Returns:
      QuantityFormat object for fluent design
      Throws:
      IllegalArgumentException - when minExponent > maxExponent

    • setAutoSiPrefix

      public QuantityFormat setAutoSiPrefix(String minSiPrefix, String maxSiPrefix)
      Turn on the automatic allocation of the unit to its closest SI prefix, in case the exponent of the 10-power in scientific notation is between minExponent and maxExponent, inclusive. E.g., format 20400 m as "20.4 km" after calling setAutoSiPrefix("mu", "M") but format it as 20400 m after calling setAutoSiPrefix("mu", ""). Note that the kg for Mass is associated with the SI prefix "k", and the g with an SI prefix "". For the LinearObjectDensity that is expressed in /m, /km is associated with an SI prefix "k" and /mm with an SI prefix "m". Note that the minimum and maximum exponents are clamped between q (-30) and Q (30).
      Parameters:
      minSiPrefix - minimum SI prefix to use (inclusive)
      maxSiPrefix - maximum SI prefix to use (inclusive)
      Returns:
      QuantityFormat object for fluent design
      Throws:
      IllegalArgumentException - when minSiPrefix > maxSiPrefix
      IllegalArgumentException - when the minSiPrefix or maxSiPrefix does not exist

    • setAllowExponents12

      public QuantityFormat setAllowExponents12(boolean allowed)
      Set whether it is allowed to use prefixes c, d, da, h in the autoSiPrefix.
      Parameters:
      allowed - to indicate whether it is allowed or not to use prefixes c, d, da, h in the autoSiPrefix
      Returns:
      QuantityFormat object for fluent design

    • setAllowExponents12

      public QuantityFormat setAllowExponents12()
      Set that it is allowed to use prefixes c, d, da, h in the autoSiPrefix.
      Returns:
      QuantityFormat object for fluent design