org.apache.lucene.document

## Class HalfFloatPoint

- java.lang.Object
- - org.apache.lucene.document.Field
  - - org.apache.lucene.document.HalfFloatPoint

- All Implemented Interfaces:
    IndexableField

      public final class HalfFloatPoint
      extends Field

  An indexed `half-float` field for fast range filters. If you also need to store the value, you should add a separate `StoredField` instance. If you need doc values, you can store them in a `NumericDocValuesField` and use `halfFloatToSortableShort(float)` and `sortableShortToHalfFloat(short)` for encoding/decoding.

  The API takes floats, but they will be encoded to half-floats before being indexed. In case the provided floats cannot be represented accurately as a half float, they will be rounded to the closest value that can be represented as a half float. In case of tie, values will be rounded to the value that has a zero as its least significant bit.

  Finding all documents within an N-dimensional at search time is efficient. Multiple values for the same field in one document is allowed.

  This field defines static factory methods for creating common queries:

  - `newExactQuery(String, float)` for matching an exact 1D point.
  - `newSetQuery(String, float...)` for matching a set of 1D values.
  - `newRangeQuery(String, float, float)` for matching a 1D range.
  - `newRangeQuery(String, float[], float[])` for matching points/ranges in n-dimensional space.
  See Also:
    `PointValues`

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class org.apache.lucene.document.Field

      `Field.Store`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `BYTES` The number of bytes used to represent a half-float value.

    - ### Fields inherited from class org.apache.lucene.document.Field

      `boost, fieldsData, name, tokenStream, type`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `HalfFloatPoint(String name, float... point)` Creates a new FloatPoint, indexing the provided N-dimensional float point.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static float` | `decodeDimension(byte[] value, int offset)` Decode single float dimension
    `static void` | `encodeDimension(float value, byte[] dest, int offset)` Encode single float dimension
    `static short` | `halfFloatToSortableShort(float v)` Convert a half-float to a short value that maintains ordering.
    `static Query` | `newExactQuery(String field, float value)` Create a query for matching an exact half-float value.
    `static Query` | `newRangeQuery(String field, float[] lowerValue, float[] upperValue)` Create a range query for n-dimensional half-float values.
    `static Query` | `newRangeQuery(String field, float lowerValue, float upperValue)` Create a range query for half-float values.
    `static Query` | `newSetQuery(String field, Collection<Float> values)` Create a query matching any of the specified 1D values.
    `static Query` | `newSetQuery(String field, float... values)` Create a query matching any of the specified 1D values.
    `static float` | `nextDown(float v)` Return the first half float which is immediately smaller than `v`.
    `static float` | `nextUp(float v)` Return the first half float which is immediately greater than `v`.
    `Number` | `numericValue()`
    `void` | `setBytesValue(BytesRef bytes)`
    `void` | `setFloatValue(float value)`
    `void` | `setFloatValues(float... point)` Change the values of this field
    `static float` | `sortableShortToHalfFloat(short bits)` Convert short bits to a half-float value that maintains ordering.
    `String` | `toString()`

    - ### Methods inherited from class org.apache.lucene.document.Field

      `binaryValue, boost, fieldType, name, readerValue, setBoost, setBytesValue, setByteValue, setDoubleValue, setIntValue, setLongValue, setReaderValue, setShortValue, setStringValue, setTokenStream, stringValue, tokenStream, tokenStreamValue`

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

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

- - ### Field Detail

    - #### BYTES

          public static final int BYTES

      The number of bytes used to represent a half-float value.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### HalfFloatPoint

          public HalfFloatPoint(String name,
                                float... point)

      Creates a new FloatPoint, indexing the provided N-dimensional float point.
      Parameters:
        `name` - field name
        `point` - float[] value
      Throws:
        `IllegalArgumentException` - if the field name or value is null.

  - ### Method Detail

    - #### nextUp

          public static float nextUp(float v)

      Return the first half float which is immediately greater than `v`. If the argument is `Float.NaN` then the return value is `Float.NaN`. If the argument is `Float.POSITIVE_INFINITY` then the return value is `Float.POSITIVE_INFINITY`.

    - #### nextDown

          public static float nextDown(float v)

      Return the first half float which is immediately smaller than `v`. If the argument is `Float.NaN` then the return value is `Float.NaN`. If the argument is `Float.NEGATIVE_INFINITY` then the return value is `Float.NEGATIVE_INFINITY`.

    - #### halfFloatToSortableShort

          public static short halfFloatToSortableShort(float v)

      Convert a half-float to a short value that maintains ordering.

    - #### sortableShortToHalfFloat

          public static float sortableShortToHalfFloat(short bits)

      Convert short bits to a half-float value that maintains ordering.

    - #### setFloatValue

          public void setFloatValue(float value)

      Overrides:
        `setFloatValue` in class `Field`

    - #### setFloatValues

          public void setFloatValues(float... point)

      Change the values of this field

    - #### setBytesValue

          public void setBytesValue(BytesRef bytes)

      Overrides:
        `setBytesValue` in class `Field`

    - #### numericValue

          public Number numericValue()

      Specified by:
        `numericValue` in interface `IndexableField`
      Overrides:
        `numericValue` in class `Field`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Field`

    - #### encodeDimension

          public static void encodeDimension(float value,
                                             byte[] dest,
                                             int offset)

      Encode single float dimension

    - #### decodeDimension

          public static float decodeDimension(byte[] value,
                                              int offset)

      Decode single float dimension

    - #### newExactQuery

          public static Query newExactQuery(String field,
                                            float value)

      Create a query for matching an exact half-float value. It will be rounded to the closest half-float if `value` cannot be represented accurately as a half-float.

      This is for simple one-dimension points, for multidimensional points use `newRangeQuery(String, float[], float[])` instead.

      Parameters:
        `field` - field name. must not be `null`.
        `value` - half-float value
      Returns:
        a query matching documents with this exact value
      Throws:
        `IllegalArgumentException` - if `field` is null.

    - #### newRangeQuery

          public static Query newRangeQuery(String field,
                                            float lowerValue,
                                            float upperValue)

      Create a range query for half-float values. Bounds will be rounded to the closest half-float if they cannot be represented accurately as a half-float.

      This is for simple one-dimension ranges, for multidimensional ranges use `newRangeQuery(String, float[], float[])` instead.

      You can have half-open ranges (which are in fact </≤ or >/≥ queries) by setting `lowerValue = Float.NEGATIVE_INFINITY` or `upperValue = Float.POSITIVE_INFINITY`.

      Ranges are inclusive. For exclusive ranges, pass `nextUp(lowerValue)` or `nextDown(upperValue)`.

      Range comparisons are consistent with `Float.compareTo(Float)`.

      Parameters:
        `field` - field name. must not be `null`.
        `lowerValue` - lower portion of the range (inclusive).
        `upperValue` - upper portion of the range (inclusive).
      Returns:
        a query matching documents within this range.
      Throws:
        `IllegalArgumentException` - if `field` is null.

    - #### newRangeQuery

          public static Query newRangeQuery(String field,
                                            float[] lowerValue,
                                            float[] upperValue)

      Create a range query for n-dimensional half-float values. Bounds will be rounded to the closest half-float if they cannot be represented accurately as a half-float.

      You can have half-open ranges (which are in fact </≤ or >/≥ queries) by setting `lowerValue[i] = Float.NEGATIVE_INFINITY` or `upperValue[i] = Float.POSITIVE_INFINITY`.

      Ranges are inclusive. For exclusive ranges, pass `nextUp(lowerValue[i])` or `nextDown(upperValue[i])`.

      Range comparisons are consistent with `Float.compareTo(Float)`.

      Parameters:
        `field` - field name. must not be `null`.
        `lowerValue` - lower portion of the range (inclusive). must not be `null`.
        `upperValue` - upper portion of the range (inclusive). must not be `null`.
      Returns:
        a query matching documents within this range.
      Throws:
        `IllegalArgumentException` - if `field` is null, if `lowerValue` is null, if `upperValue` is null, or if `lowerValue.length != upperValue.length`

    - #### newSetQuery

          public static Query newSetQuery(String field,
                                          float... values)

      Create a query matching any of the specified 1D values. This is the points equivalent of `TermsQuery`. Values will be rounded to the closest half-float if they cannot be represented accurately as a half-float.
      Parameters:
        `field` - field name. must not be `null`.
        `values` - all values to match

    - #### newSetQuery

          public static Query newSetQuery(String field,
                                          Collection<Float> values)

      Create a query matching any of the specified 1D values. This is the points equivalent of `TermsQuery`.
      Parameters:
        `field` - field name. must not be `null`.
        `values` - all values to match

Copyright © 2000-2019 Apache Software Foundation. All Rights Reserved.