FST (Lucene 10.5.0 core API)
Description: declaration: package: org.apache.lucene.util.fst, class: FST

Package org.apache.lucene.util.fst

# Class FST<T>

java.lang.Object
org.apache.lucene.util.fst.FST<T>

All Implemented Interfaces:
  `Accountable`

public final class FST<T> extends Object implements Accountable
Represents an finite state machine (FST), using a compact byte[] format.

The format is similar to what's used by Morfologik (https://github.com/morfologik/morfologik-stemming).

See the `package documentation` for some simple examples.

WARNING: This API is experimental and might change in incompatible ways in the next release.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static final class`
  `FST.Arc<T>`
  Represents a single arc.
  `static class`
  `FST.BytesReader`
  Reads bytes stored in an FST.
  `static final class`
  `FST.FSTMetadata<T>`
  Represents the FST metadata.
  `static enum`
  `FST.INPUT_TYPE`
  Specifies allowed range of each int input label for this FST.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final byte`
  `ARCS_FOR_BINARY_SEARCH`
  Value of the arc flags to declare a node with fixed length (sparse) arcs designed for binary search.
  `static final int`
  `BIT_ARC_HAS_OUTPUT`
  This flag is set if the arc has an output.
  `static final int`
  `END_LABEL`
  If arc has this label then that arc is final/accepted
  `final Outputs<T>`
  `outputs`
  `static final int`
  `VERSION_90`
  Version that was used when releasing Lucene 9.0.
  `static final int`
  `VERSION_CONTINUOUS_ARCS`
  Version that started storing continuous arcs.
  `static final int`
  `VERSION_CURRENT`
  Current version.
  `static final int`
  `VERSION_START`
  First supported version, this is the version that was used when releasing Lucene 7.0.

  ### Fields inherited from interface org.apache.lucene.util.Accountable

  `NULL_ACCOUNTABLE`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `FST(FST.FSTMetadata<T> metadata, DataInput in)`
  Load a previously saved FST with a DataInput for metdata using an `OnHeapFSTStore` with maxBlockBits set to `DEFAULT_MAX_BLOCK_BITS`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `FST.Arc<T>`
  `findTargetArc(int labelToMatch, FST.Arc<T> follow, FST.Arc<T> arc, FST.BytesReader in)`
  Finds an arc leaving the incoming arc, replacing the arc in place.
  `static <T> FST<T>`
  `fromFSTReader(FST.FSTMetadata<T> fstMetadata, FSTReader fstReader)`
  Create a FST from a `FSTReader`.
  `FST.BytesReader`
  `getBytesReader()`
  Returns a `FST.BytesReader` for this FST, positioned at position 0.
  `T`
  `getEmptyOutput()`
  `FST.Arc<T>`
  `getFirstArc(FST.Arc<T> arc)`
  Fills virtual 'start' arc, ie, an empty incoming arc to the FST's start node
  `FST.FSTMetadata<T>`
  `getMetadata()`
  `long`
  `numBytes()`
  `long`
  `ramBytesUsed()`
  Returns an estimate of the JVM heap memory used by this object in bytes.
  `static <T> FST<T>`
  `read(Path path, Outputs<T> outputs)`
  Reads an automaton from a file.
  `FST.Arc<T>`
  `readArcByContinuous(FST.Arc<T> arc, FST.BytesReader in, int rangeIndex)`
  Reads a Continuous node arc, with the provided index in the label range.
  `FST.Arc<T>`
  `readArcByDirectAddressing(FST.Arc<T> arc, FST.BytesReader in, int rangeIndex)`
  Reads a present direct addressing node arc, with the provided index in the label range.
  `FST.Arc<T>`
  `readArcByIndex(FST.Arc<T> arc, FST.BytesReader in, int idx)`
  `FST.Arc<T>`
  `readFirstRealTargetArc(long nodeAddress, FST.Arc<T> arc, FST.BytesReader in)`
  `FST.Arc<T>`
  `readFirstTargetArc(FST.Arc<T> follow, FST.Arc<T> arc, FST.BytesReader in)`
  Follow the `follow` arc and read the first arc of its target; this changes the provided `arc` (2nd arg) in-place and returns it.
  `int`
  `readLabel(DataInput in)`
  Reads one BYTE1/2/4 label from the provided `DataInput`.
  `FST.Arc<T>`
  `readLastArcByContinuous(FST.Arc<T> arc, FST.BytesReader in)`
  Reads the last arc of a continuous node.
  `FST.Arc<T>`
  `readLastArcByDirectAddressing(FST.Arc<T> arc, FST.BytesReader in)`
  Reads the last arc of a direct addressing node.
  `static <T> FST.FSTMetadata<T>`
  `readMetadata(DataInput metaIn, Outputs<T> outputs)`
  Read the FST metadata from DataInput
  `FST.Arc<T>`
  `readNextArc(FST.Arc<T> arc, FST.BytesReader in)`
  In-place read; returns the arc.
  `FST.Arc<T>`
  `readNextRealArc(FST.Arc<T> arc, FST.BytesReader in)`
  Never returns null, but you should never call this if arc.isLast() is true.
  `void`
  `save(Path path)`
  Writes an automaton to a file.
  `void`
  `save(DataOutput metaOut, DataOutput out)`
  Save the FST to DataOutput.
  `static <T> boolean`
  `targetHasArcs(FST.Arc<T> arc)`
  returns true if the node at this address has any outgoing arcs
  `String`
  `toString()`

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

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

  ### Methods inherited from interface org.apache.lucene.util.Accountable

  `getChildResources`

- ## Field Details

  - ### BIT_ARC_HAS_OUTPUT

    public static final int BIT_ARC_HAS_OUTPUT
    This flag is set if the arc has an output.
    See Also:
      - Constant Field Values

  - ### ARCS_FOR_BINARY_SEARCH

    public static final byte ARCS_FOR_BINARY_SEARCH
    Value of the arc flags to declare a node with fixed length (sparse) arcs designed for binary search.
    See Also:
      - Constant Field Values

  - ### VERSION_START

    public static final int VERSION_START
    First supported version, this is the version that was used when releasing Lucene 7.0.
    See Also:
      - Constant Field Values

  - ### VERSION_CONTINUOUS_ARCS

    public static final int VERSION_CONTINUOUS_ARCS
    Version that started storing continuous arcs.
    See Also:
      - Constant Field Values

  - ### VERSION_CURRENT

    public static final int VERSION_CURRENT
    Current version.
    See Also:
      - Constant Field Values

  - ### VERSION_90

    public static final int VERSION_90
    Version that was used when releasing Lucene 9.0.
    See Also:
      - Constant Field Values

  - ### END_LABEL

    public static final int END_LABEL
    If arc has this label then that arc is final/accepted
    See Also:
      - Constant Field Values

  - ### outputs

    public final Outputs<T> outputs

- ## Constructor Details

  - ### FST

    public FST(FST.FSTMetadata<T> metadata, DataInput in) throws IOException
    Load a previously saved FST with a DataInput for metdata using an `OnHeapFSTStore` with maxBlockBits set to `DEFAULT_MAX_BLOCK_BITS`
    Throws:
      `IOException`

- ## Method Details

  - ### fromFSTReader

    public static <T> FST<T> fromFSTReader(FST.FSTMetadata<T> fstMetadata, FSTReader fstReader)
    Create a FST from a `FSTReader`. Return null if the metadata is null.
    Parameters:
      `fstMetadata` - the metadata
      `fstReader` - the FSTReader
    Returns:
      the FST

  - ### readMetadata

    public static <T> FST.FSTMetadata<T> readMetadata(DataInput metaIn, Outputs<T> outputs) throws IOException
    Read the FST metadata from DataInput
    Type Parameters:
      `T` - the output type
    Parameters:
      `metaIn` - the DataInput of the metadata
      `outputs` - the FST outputs
    Returns:
      the FST metadata
    Throws:
      `IOException` - if exception occurred during parsing

  - ### ramBytesUsed

    public long ramBytesUsed()
    Description copied from interface: `Accountable`
    Returns an estimate of the JVM heap memory used by this object in bytes. The method name uses "ram" for historical reasons; only JVM heap memory should be reported. Off-heap resources such as memory-mapped files or native direct buffers should not be included. Negative values are illegal.
    Specified by:
      `ramBytesUsed` in interface `Accountable`

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`

  - ### numBytes

    public long numBytes()

  - ### getEmptyOutput

    public T getEmptyOutput()

  - ### getMetadata

    public FST.FSTMetadata<T> getMetadata()

  - ### save

    public void save(DataOutput metaOut, DataOutput out) throws IOException
    Save the FST to DataOutput.
    Parameters:
      `metaOut` - the DataOutput to write the metadata to
      `out` - the DataOutput to write the FST bytes to
    Throws:
      `IOException`

  - ### save

    public void save(Path path) throws IOException
    Writes an automaton to a file.
    Throws:
      `IOException`

  - ### read

    public static <T> FST<T> read(Path path, Outputs<T> outputs) throws IOException
    Reads an automaton from a file.
    Throws:
      `IOException`

  - ### readLabel

    public int readLabel(DataInput in) throws IOException
    Reads one BYTE1/2/4 label from the provided `DataInput`.
    Throws:
      `IOException`

  - ### targetHasArcs

    public static <T> boolean targetHasArcs(FST.Arc<T> arc)
    returns true if the node at this address has any outgoing arcs

  - ### getFirstArc

    public FST.Arc<T> getFirstArc(FST.Arc<T> arc)
    Fills virtual 'start' arc, ie, an empty incoming arc to the FST's start node

  - ### readFirstTargetArc

    public FST.Arc<T> readFirstTargetArc(FST.Arc<T> follow, FST.Arc<T> arc, FST.BytesReader in) throws IOException
    Follow the `follow` arc and read the first arc of its target; this changes the provided `arc` (2nd arg) in-place and returns it.
    Returns:
      Returns the second argument (`arc`).
    Throws:
      `IOException`

  - ### readFirstRealTargetArc

    public FST.Arc<T> readFirstRealTargetArc(long nodeAddress, FST.Arc<T> arc, FST.BytesReader in) throws IOException
    Throws:
      `IOException`

  - ### readNextArc

    public FST.Arc<T> readNextArc(FST.Arc<T> arc, FST.BytesReader in) throws IOException
    In-place read; returns the arc.
    Throws:
      `IOException`

  - ### readArcByIndex

    public FST.Arc<T> readArcByIndex(FST.Arc<T> arc, FST.BytesReader in, int idx) throws IOException
    Throws:
      `IOException`

  - ### readArcByContinuous

    public FST.Arc<T> readArcByContinuous(FST.Arc<T> arc, FST.BytesReader in, int rangeIndex) throws IOException
    Reads a Continuous node arc, with the provided index in the label range.
    Parameters:
      `rangeIndex` - The index of the arc in the label range. It must be within the label range.
    Throws:
      `IOException`

  - ### readArcByDirectAddressing

    public FST.Arc<T> readArcByDirectAddressing(FST.Arc<T> arc, FST.BytesReader in, int rangeIndex) throws IOException
    Reads a present direct addressing node arc, with the provided index in the label range.
    Parameters:
      `rangeIndex` - The index of the arc in the label range. It must be present. The real arc offset is computed based on the presence bits of the direct addressing node.
    Throws:
      `IOException`

  - ### readLastArcByDirectAddressing

    public FST.Arc<T> readLastArcByDirectAddressing(FST.Arc<T> arc, FST.BytesReader in) throws IOException
    Reads the last arc of a direct addressing node. This method is equivalent to call `readArcByDirectAddressing(Arc, BytesReader, int)` with `rangeIndex` equal to `arc.numArcs() - 1`, but it is faster.
    Throws:
      `IOException`

  - ### readLastArcByContinuous

    public FST.Arc<T> readLastArcByContinuous(FST.Arc<T> arc, FST.BytesReader in) throws IOException
    Reads the last arc of a continuous node.
    Throws:
      `IOException`

  - ### readNextRealArc

    public FST.Arc<T> readNextRealArc(FST.Arc<T> arc, FST.BytesReader in) throws IOException
    Never returns null, but you should never call this if arc.isLast() is true.
    Throws:
      `IOException`

  - ### findTargetArc

    public FST.Arc<T> findTargetArc(int labelToMatch, FST.Arc<T> follow, FST.Arc<T> arc, FST.BytesReader in) throws IOException
    Finds an arc leaving the incoming arc, replacing the arc in place. This returns null if the arc was not found, else the incoming arc.
    Throws:
      `IOException`

  - ### getBytesReader

    public FST.BytesReader getBytesReader()
    Returns a `FST.BytesReader` for this FST, positioned at position 0.