Package org.apache.juneau.marshall

Enum Class FloatFormat

java.lang.Object

java.lang.Enum<FloatFormat>

org.apache.juneau.marshall.FloatFormat

All Implemented Interfaces:

Serializable, Comparable<FloatFormat>, Constable

public enum FloatFormat
extends Enum<FloatFormat>

Supported wire formats for non-finite Float / Double values (NaN, +Infinity, -Infinity).

Used by MarshallingContext.Builder.floatFormat(FloatFormat), Marshalled.floatFormat(), MarshalledProp.floatFormat(), and MarshalledConfig.floatFormat() to control how non-finite floating-point values are written to text-based wire formats. Finite values are unaffected and ride the natural bare-numeric-token wire form for the underlying serializer.

The default is NaN_AS_NULL which is JSON-spec-compliant per RFC 8259 §6 (non-finite floats are not valid JSON tokens; emitting null is the closest valid representation).

Precedence (highest to lowest)

1. @MarshalledProp(floatFormat=…) on the bean property.
2. @Marshalled(floatFormat=…) on the bean class.
3. @MarshalledConfig(floatFormat=…) on @Rest-annotated classes / methods.
4. Programmatic MarshallingContext.Builder.floatFormat(FloatFormat).
5. Environment variable MarshallingContext.floatFormat.
6. The default constant (NaN_AS_NULL).

Parser leniency

Parsers SHALL accept all of the following wire shapes regardless of the parser-side FloatFormat setting:

• Bare numeric tokens including the non-standard NaN / Infinity / -Infinity tokens (Juneau's lenient parser accepts these by default).
• Quoted-string forms — "NaN", "Infinity", "-Infinity" (case-insensitive).
• null — reconstructed as Double.NaN when reading into a primitive double / float; preserved as null when reading into a boxed Double / Float.

JSON-spec compliance

NaN_AS_NUMBER is non-standard JSON per RFC 8259 §6 — JSON does not permit NaN / Infinity / -Infinity tokens. Juneau's own JSON parser accepts these in lenient mode, but strict-mode consumers (e.g. some browser JSON.parse pipelines) will reject them. Use only when you control both ends of the wire.

Binary serializers

Binary serializers (BSON / CBOR / MsgPack / Prototext / Parquet) emit native IEEE-754 floats regardless of this setting; native non-finite representations exist in every supported binary format (BSON double / decimal128; CBOR's tag 22 / 23 / 24 for special floats; MsgPack float64). This setting only affects text-based serializers.

Nested Class Summary

Nested classes/interfaces inherited from class java.lang.Enum

Enum.EnumDesc<E extends Enum<E>>

Enum Constant Summary

Enum Constants

Enum Constant	Description
NaN_AS_ERROR	Throw IllegalArgumentException when a non-finite value is encountered.
NaN_AS_NULL	Emit null for NaN / ±Infinity (the default).
NaN_AS_NUMBER	Emit the bare NaN / Infinity / -Infinity token.
NaN_AS_STRING	Emit the quoted string "NaN" / "Infinity" / "-Infinity".
NOT_SET	Sentinel meaning "no value configured" — falls through to the next-higher precedence level.

Method Summary

Modifier and Type	Method	Description
static Object	format(double value, FloatFormat format)	Formats the specified double using this format.
static Object	format(float value, FloatFormat format)	Formats the specified float using this format.
boolean	isNumeric()	Returns true if this format always emits a bare numeric wire token for non-finite values.
static <T extends Number> T	parse(String value, FloatFormat format, Class<T> targetType)	Parses the specified wire value into a non-finite-aware Double or Float.
static FloatFormat	valueOf(String name)	Returns the enum constant of this class with the specified name.
static FloatFormat[]	values()	Returns an array containing the constants of this enum class, in the order they are declared.

Methods inherited from class java.lang.Enum

clone, compareTo, describeConstable, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Details

NOT_SET

public static final FloatFormat NOT_SET

Sentinel meaning "no value configured" — falls through to the next-higher precedence level.

NaN_AS_NULL

public static final FloatFormat NaN_AS_NULL

Emit null for NaN / ±Infinity (the default).

JSON-spec compliant. Loses the ability to distinguish NaN from +Infinity from -Infinity on the wire — all three become null. Round-trips back to Double.NaN when reading into a primitive double; into a boxed Double field, null stays null.

NaN_AS_STRING

public static final FloatFormat NaN_AS_STRING

Emit the quoted string "NaN" / "Infinity" / "-Infinity".

Round-trip preserving. The parser unambiguously decodes the string back to the original non-finite value.

NaN_AS_NUMBER

public static final FloatFormat NaN_AS_NUMBER

Emit the bare NaN / Infinity / -Infinity token.

Non-standard JSON per RFC 8259 §6. Accepted by Juneau's lenient parser and V8 / several Python libs; rejected by strict consumers. Use only when you control both ends of the wire.

NaN_AS_ERROR

public static final FloatFormat NaN_AS_ERROR

Throw IllegalArgumentException when a non-finite value is encountered.

Fail-fast for data-cleanliness pipelines where a NaN indicates upstream corruption.

Method Details

values

public static FloatFormat[] values()

Returns an array containing the constants of this enum class, in the order they are declared.

Returns:

an array containing the constants of this enum class, in the order they are declared

valueOf

public static FloatFormat valueOf(String name)

Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)

Parameters:

name - the name of the enum constant to be returned.

Returns:

the enum constant with the specified name

Throws:

IllegalArgumentException - if this enum class has no constant with the specified name

NullPointerException - if the argument is null

format

public static Object format(double value,
 FloatFormat format)

Formats the specified double using this format.

Finite values always return the boxed Double so text serializers emit the bare numeric token. Non-finite values are dispatched per the constant:

• NaN_AS_NULL → null.
• NaN_AS_STRING → "NaN" / "Infinity" / "-Infinity".
• NaN_AS_NUMBER → boxed Double (non-finite); text serializers emit the bare token.
• NaN_AS_ERROR → throws IllegalArgumentException.

NOT_SET / null format are treated as NaN_AS_NULL.

Parameters:

value - The value to format.

format - The configured format. Can be null (treated as NaN_AS_NULL).

Returns:

The formatted value — a Double for finite or NaN_AS_NUMBER, a String for NaN_AS_STRING, or null for non-finite under NaN_AS_NULL.

Throws:

IllegalArgumentException - If format is NaN_AS_ERROR and the value is non-finite.

format

public static Object format(float value,
 FloatFormat format)

Formats the specified float using this format.

Finite values return the boxed Float. Non-finite values follow the same rules as format(double, FloatFormat) except that NaN_AS_NUMBER returns the boxed Float (not Double).

Parameters:

value - The value to format.

format - The configured format. Can be null (treated as NaN_AS_NULL).

Returns:

The formatted value — a Float for finite or NaN_AS_NUMBER, a String for NaN_AS_STRING, or null for non-finite under NaN_AS_NULL.

Throws:

IllegalArgumentException - If format is NaN_AS_ERROR and the value is non-finite.

parse

public static <T extends Number> T parse(String value,
 FloatFormat format,
 Class<T> targetType)

Parses the specified wire value into a non-finite-aware Double or Float.

Lenient parsing — accepts bare numeric, quoted-string "NaN" / "Infinity" / "-Infinity" (case-insensitive), and unquoted NaN / Infinity / -Infinity tokens regardless of the format hint. The hint is informational only.

Type Parameters:

T - The target type (Double or Float).

Parameters:

value - The wire value. Can be null or blank (returns null).

format - The configured format hint (informational only — parsing is format-agnostic). Can be null (ignored; parsing is format-agnostic).

targetType - The desired return type — Double or Float.

Returns:

The parsed value, or null if value is null or blank.

Throws:

IllegalArgumentException - If the value cannot be parsed or targetType is unsupported.

isNumeric

public boolean isNumeric()

Returns true if this format always emits a bare numeric wire token for non-finite values.

Only NaN_AS_NUMBER returns true. NaN_AS_NULL may emit null; NaN_AS_STRING emits a quoted string; NaN_AS_ERROR throws. Finite values are always emitted as bare numeric tokens regardless of this setting.

Returns:

true if this format emits a bare numeric wire token for non-finite values.