FieldValue

public enum FieldValue: Codable, Sendable, CustomStringConvertible,
  ExpressibleByIntegerLiteral, ExpressibleByStringLiteral,
  ExpressibleByBooleanLiteral, ExpressibleByFloatLiteral,
  ExpressibleByNilLiteral
extension FieldValue: Comparable
extension FieldValue: Hashable
extension FieldValue: FieldValueConvertible

Represents a scalar value extracted from a document field, providing a total ordering for use as an index key and in range queries.

FieldValue bridges the gap between dynamically-typed document data (JSON or MessagePack) and the statically-typed index and query systems. Every value stored in an index is a FieldValue, and every predicate comparison operates on FieldValue instances.

Total ordering. FieldValue guarantees a total order across all variants, which is essential for binary-search-based indexes and correct range-scan semantics. The ordering is defined first by type rank:

null < bool < number < string

Within the same type, values are ordered naturally. The int and double cases share the “number” rank and compare numerically against each other without lossy conversion through Double:

  • int(5) == double(5.0) — exact integer equality
  • int(2^60 + 1) != double(2^60) — no silent rounding

ExpressibleBy literals. FieldValue conforms to ExpressibleByIntegerLiteral, ExpressibleByStringLiteral, ExpressibleByBooleanLiteral, ExpressibleByFloatLiteral, and ExpressibleByNilLiteral, allowing natural Swift syntax: let v: FieldValue = "hello".

  • Represents the absence of a value (null / NSNull).

    Declaration

    Swift

    case null

  • A boolean value (true or false).

    Declaration

    Swift

    case bool(Bool)

  • A 64-bit signed integer.

    Declaration

    Swift

    case int(Int64)

  • A 64-bit floating-point number. Only used when the value cannot be represented exactly as Int64 — see number(_:).

    Declaration

    Swift

    case double(Double)

  • A Unicode string value.

    Declaration

    Swift

    case string(String)

ExpressibleBy Literals

  • Declaration

    Swift

    public init(integerLiteral value: Int)

  • Declaration

    Swift

    public init(stringLiteral value: String)

  • Declaration

    Swift

    public init(booleanLiteral value: Bool)

  • Declaration

    Swift

    public init(floatLiteral value: Double)

  • Declaration

    Swift

    public init(nilLiteral: ())

  • Converts this field value back to a native Swift Any value suitable for use in [String: Any] dictionaries during patch operations.

    .null is represented as NSNull() to match Foundation convention.

    Declaration

    Swift

    public var anyValue: Any { get }

  • Canonicalises a double-precision value: if it can be represented exactly as an Int64, stores it as .int; otherwise stores it as .double.

    This ensures that whole-number doubles (e.g. 42.0) are indexed as integers and compare equal to their integer counterparts.

    Declaration

    Swift

    public static func number(_ d: Double) -> FieldValue

    Parameters

    d

    The double value to canonicalise.

    Return Value

    .int if the value fits exactly in Int64, otherwise .double.

Exact Numeric Comparison

  • Compares two FieldValue instances, providing a total order conforming to Comparable semantics.

    The comparison first orders by type rank, then by value within the same type. Cross-type comparisons between .int and .double use the exact numeric comparison to avoid precision loss.

    Declaration

    Swift

    @inlinable
public static func compare(_ lhs: FieldValue, _ rhs: FieldValue) -> Int

    Parameters

    lhs

    The left-hand value.
    rhs

    The right-hand value.

    Return Value

    -1 if lhs < rhs, 0 if equal, 1 if lhs > rhs.

  • A human-readable description of the value.

    Declaration

    Swift

    public var description: String { get }

  • Converts an arbitrary value from a deserialized dictionary into a canonical FieldValue.

    Supports nil/NSNull, Bool, Int, Int64, Double, and String. Returns nil for unrecognized types (arrays, nested dictionaries).

    Declaration

    Swift

    public static func fromAny(_ value: Any?) -> FieldValue?

    Parameters

    value

    The value to convert (may be nil).

    Return Value

    A FieldValue, or nil if the type is not supported.

Comparable / Equatable / Hashable

  • Declaration

    Swift

    @inlinable
public static func < (lhs: FieldValue, rhs: FieldValue) -> Bool

  • Declaration

    Swift

    @inlinable
public static func == (lhs: FieldValue, rhs: FieldValue) -> Bool

  • Declaration

    Swift

    public func hash(into hasher: inout Hasher)

FieldValueConvertible

  • Declaration

    Swift

    public var fieldValue: FieldValue { get }