Module java.base
Package java.lang.foreign

# Class FunctionDescriptor

java.lang.Object
java.lang.foreign.FunctionDescriptor

public sealed class FunctionDescriptor extends Object
`FunctionDescriptor` is a preview API of the Java platform.
Programs can only use `FunctionDescriptor` when preview features are enabled.
Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
A function descriptor is made up of zero or more argument layouts and zero or one return layout. A function descriptor is used to model the signature of foreign functions when creating downcall method handlesPREVIEW or upcall stubsPREVIEW.

Since:
  19
See Also:
  - `MemoryLayout`PREVIEW
Implementation Requirements:
  This class is immutable, thread-safe and value-based.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `FunctionDescriptorPREVIEW`
  `appendArgumentLayouts(MemoryLayoutPREVIEW... addedLayouts)`
  Returns a function descriptor with the given argument layouts appended to the argument layout array of this function descriptor.
  `List<MemoryLayoutPREVIEW>`
  `argumentLayouts()`
  Returns the argument layouts associated with this function descriptor (as an immutable list).
  `FunctionDescriptorPREVIEW`
  `asVariadic(MemoryLayoutPREVIEW... variadicLayouts)`
  Creates a specialized variadic function descriptor, by appending given variadic layouts to this function descriptor argument layouts.
  `FunctionDescriptorPREVIEW`
  `changeReturnLayout(MemoryLayoutPREVIEW newReturn)`
  Returns a function descriptor with the given memory layout as the new return layout.
  `FunctionDescriptorPREVIEW`
  `dropReturnLayout()`
  Returns a function descriptor with the return layout dropped.
  `boolean`
  `equals(Object other)`
  Compares the specified object with this function descriptor for equality.
  `int`
  `firstVariadicArgumentIndex()`
  The index of the first variadic argument layout (where defined).
  `int`
  `hashCode()`
  Returns the hash code value for this function descriptor.
  `FunctionDescriptorPREVIEW`
  `insertArgumentLayouts(int index, MemoryLayoutPREVIEW... addedLayouts)`
  Returns a function descriptor with the given argument layouts inserted at the given index, into the argument layout array of this function descriptor.
  `static FunctionDescriptorPREVIEW`
  `of(MemoryLayoutPREVIEW resLayout, MemoryLayoutPREVIEW... argLayouts)`
  Creates a function descriptor with the given return and argument layouts.
  `static FunctionDescriptorPREVIEW`
  `ofVoid(MemoryLayoutPREVIEW... argLayouts)`
  Creates a function descriptor with the given argument layouts and no return layout.
  `Optional<MemoryLayoutPREVIEW>`
  `returnLayout()`
  Returns the return layout (if any) associated with this function descriptor.
  `String`
  `toString()`
  Returns the string representation of this function descriptor.

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

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

- ## Method Details

  - ### returnLayout

    public Optional<MemoryLayoutPREVIEW> returnLayout()
    Returns the return layout (if any) associated with this function descriptor.
    Returns:
      the return layout (if any) associated with this function descriptor

  - ### argumentLayouts

    public List<MemoryLayoutPREVIEW> argumentLayouts()
    Returns the argument layouts associated with this function descriptor (as an immutable list)..
    Returns:
      the argument layouts associated with this function descriptor (as an immutable list)

  - ### of

    public static FunctionDescriptorPREVIEW of(MemoryLayoutPREVIEW resLayout, MemoryLayoutPREVIEW... argLayouts)
    Creates a function descriptor with the given return and argument layouts.
    Parameters:
      `resLayout` - the return layout.
      `argLayouts` - the argument layouts.
    Returns:
      the new function descriptor.

  - ### ofVoid

    public static FunctionDescriptorPREVIEW ofVoid(MemoryLayoutPREVIEW... argLayouts)
    Creates a function descriptor with the given argument layouts and no return layout.
    Parameters:
      `argLayouts` - the argument layouts.
    Returns:
      the new function descriptor.

  - ### asVariadic

    public FunctionDescriptorPREVIEW asVariadic(MemoryLayoutPREVIEW... variadicLayouts)
    Creates a specialized variadic function descriptor, by appending given variadic layouts to this function descriptor argument layouts. The resulting function descriptor can report the position of the first variadic argument, and cannot be altered in any way: for instance, calling `changeReturnLayout(MemoryLayout)` on the resulting descriptor will throw an `UnsupportedOperationException`.
    Parameters:
      `variadicLayouts` - the variadic argument layouts to be appended to this descriptor argument layouts.
    Returns:
      a variadic function descriptor, or this descriptor if `variadicLayouts.length == 0`.

  - ### firstVariadicArgumentIndex

    public int firstVariadicArgumentIndex()
    The index of the first variadic argument layout (where defined).
    Returns:
      The index of the first variadic argument layout, or `-1` if this is not a variadic layout.

  - ### appendArgumentLayouts

    public FunctionDescriptorPREVIEW appendArgumentLayouts(MemoryLayoutPREVIEW... addedLayouts)
    Returns a function descriptor with the given argument layouts appended to the argument layout array of this function descriptor.
    Parameters:
      `addedLayouts` - the argument layouts to append.
    Returns:
      the new function descriptor.

  - ### insertArgumentLayouts

    public FunctionDescriptorPREVIEW insertArgumentLayouts(int index, MemoryLayoutPREVIEW... addedLayouts)
    Returns a function descriptor with the given argument layouts inserted at the given index, into the argument layout array of this function descriptor.
    Parameters:
      `index` - the index at which to insert the arguments
      `addedLayouts` - the argument layouts to insert at given index.
    Returns:
      the new function descriptor.
    Throws:
      `IllegalArgumentException` - if `index < 0 || index > argumentLayouts().size()`.

  - ### changeReturnLayout

    public FunctionDescriptorPREVIEW changeReturnLayout(MemoryLayoutPREVIEW newReturn)
    Returns a function descriptor with the given memory layout as the new return layout.
    Parameters:
      `newReturn` - the new return layout.
    Returns:
      the new function descriptor.

  - ### dropReturnLayout

    public FunctionDescriptorPREVIEW dropReturnLayout()
    Returns a function descriptor with the return layout dropped. This is useful to model functions which return no values.
    Returns:
      the new function descriptor.

  - ### toString

    public String toString()
    Returns the string representation of this function descriptor.
    Overrides:
      `toString` in class `Object`
    Returns:
      the string representation of this function descriptor

  - ### equals

    public boolean equals(Object other)
    Compares the specified object with this function descriptor for equality. Returns `true` if and only if the specified object is also a function descriptor, and all the following conditions are met:
    - the two function descriptors have equals return layouts (see `MemoryLayout.equals(Object)`PREVIEW), or both have no return layout;
    - the two function descriptors have argument layouts that are pair-wise equalPREVIEW; and
    - the two function descriptors have the same leading variadic argument index
    Overrides:
      `equals` in class `Object`
    Parameters:
      `other` - the object to be compared for equality with this function descriptor.
    Returns:
      `true` if the specified object is equal to this function descriptor.
    See Also:
      - `Object.hashCode()`
      - `HashMap`

  - ### hashCode

    public int hashCode()
    Returns the hash code value for this function descriptor.
    Overrides:
      `hashCode` in class `Object`
    Returns:
      the hash code value for this function descriptor
    See Also:
      - `Object.equals(java.lang.Object)`
      - `System.identityHashCode(java.lang.Object)`