Module java.base
Package java.lang.foreign

# Interface MemorySegment

public sealed interface MemorySegment
`MemorySegment` is a preview API of the Java platform.
Programs can only use `MemorySegment` when preview features are enabled.
Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
A memory segment provides access to a contiguous region of memory.

There are two kinds of memory segments:

- A heap segment is backed by, and provides access to, a region of memory inside the Java heap (an "on-heap" region).
- A native segment is backed by, and provides access to, a region of memory outside the Java heap (an "off-heap" region).

Heap segments can be obtained by calling one of the `ofArray(int[])` factory methods. These methods return a memory segment backed by the on-heap region that holds the specified Java array.

Native segments can be obtained by calling one of the `allocateNative(long, long, SegmentScope)` factory methods, which return a memory segment backed by a newly allocated off-heap region with the given size and aligned to the given alignment constraint. Alternatively, native segments can be obtained by `mapping`PREVIEW a file into a new off-heap region (in some systems, this operation is sometimes referred to as `mmap`). Segments obtained in this way are called mapped segments, and their contents can be persisted and loaded to and from the underlying memory-mapped file.

Both kinds of segments are read and written using the same methods, known as access operations. An access operation on a memory segment always and only provides access to the region for which the segment was obtained.

## Characteristics of memory segments

Every memory segment has an address, expressed as a `long` value. The nature of a segment's address depends on the kind of the segment:

- The address of a heap segment is not a physical address, but rather an offset within the region of memory which backs the segment. The region is inside the Java heap, so garbage collection might cause the region to be relocated in physical memory over time, but this is not exposed to clients of the `MemorySegment` API who see a stable virtualized address for a heap segment backed by the region. A heap segment obtained from one of the `ofArray(int[])` factory methods has an address of zero.
- The address of a native segment (including mapped segments) denotes the physical address of the region of memory which backs the segment.

Every memory segment has a size. The size of a heap segment is derived from the Java array from which it is obtained. This size is predictable across Java runtimes. The size of a native segment is either passed explicitly (as in `allocateNative(long, SegmentScope)`) or derived from a `MemoryLayout`PREVIEW (as in `allocateNative(MemoryLayout, SegmentScope)`). The size of a memory segment is typically a positive number but may be zero, but never negative.

The address and size of a memory segment jointly ensure that access operations on the segment cannot fall outside the boundaries of the region of memory which backs the segment. That is, a memory segment has spatial bounds.

Every memory segment is associated with a scopePREVIEW. This ensures that access operations on a memory segment cannot occur when the region of memory which backs the memory segment is no longer available (e.g., after the scope associated with the accessed memory segment is no longer alivePREVIEW). That is, a memory segment has temporal bounds.

Finally, access operations on a memory segment are subject to the thread-confinement checks enforced by the associated scope; that is, if the segment is associated with the global scopePREVIEW or an automatic scopePREVIEW, it can be accessed by multiple threads. If the segment is associated with an arena scope, then it can only be accessed compatibly with the arena confinement characteristics.

## Accessing memory segments

A memory segment can be read or written using various access operations provided in this class (e.g. `get(ValueLayout.OfInt, long)`). Each access operation takes a value layoutPREVIEW, which specifies the size and shape of the value, and an offset, expressed in bytes. For instance, to read an int from a segment, using default endianness, the following code can be used:

    MemorySegment segment = ...
    int value = segment.get(ValueLayout.JAVA_INT, 0);

If the value to be read is stored in memory using big-endian encoding, the access operation can be expressed as follows:

    MemorySegment segment = ...
    int value = segment.get(ValueLayout.JAVA_INT.withOrder(BIG_ENDIAN), 0);

For more complex access operations (e.g. structured memory access), clients can obtain a var handlePREVIEW that accepts a segment and a `long` offset. More complex var handles can be obtained by adapting a segment var handle view using the var handle combinator functions defined in the `MethodHandles` class:

    MemorySegment segment = ...
    VarHandle intHandle = MethodHandles.memorySegmentViewVarHandle(ValueLayout.JAVA_INT);
    MethodHandle multiplyExact = MethodHandles.lookup()
                                              .findStatic(Math.class, "multiplyExact",
                                                                      MethodType.methodType(long.class, long.class, long.class));
    intHandle = MethodHandles.filterCoordinates(intHandle, 1,
                                                MethodHandles.insertArguments(multiplyExact, 0, 4L));
    intHandle.get(segment, 3L); // get int element at offset 3 * 4 = 12

Alternatively, complex var handles can can be obtained from memory layoutsPREVIEW by providing a so called layout path:

    MemorySegment segment = ...
    VarHandle intHandle = ValueLayout.JAVA_INT.arrayElementVarHandle();
    intHandle.get(segment, 3L); // get int element at offset 3 * 4 = 12

## Slicing memory segments

Memory segments support slicing. Slicing a memory segment returns a new memory segment that is backed by the same region of memory as the original. The address of the sliced segment is derived from the address of the original segment, by adding an offset (expressed in bytes). The size of the sliced segment is either derived implicitly (by subtracting the specified offset from the size of the original segment), or provided explicitly. In other words, a sliced segment has stricter spatial bounds than those of the original segment:

    Arena arena = ...
    MemorySegment segment = arena.allocate(100);
    MemorySegment slice = segment.asSlice(50, 10);
    slice.get(ValueLayout.JAVA_INT, 20); // Out of bounds!
    arena.close();
    slice.get(ValueLayout.JAVA_INT, 0); // Already closed!

The above code creates a native segment that is 100 bytes long; then, it creates a slice that starts at offset 50 of `segment`, and is 10 bytes long. That is, the address of the `slice` is `segment.address() + 50`, and its size is 10. As a result, attempting to read an int value at offset 20 of the `slice` segment will result in an exception. The temporal boundsPREVIEW of the original segment is inherited by its slices; that is, when the scope associated with `segment` is no longer alivePREVIEW, `slice` will also be become inaccessible.

A client might obtain a `Stream` from a segment, which can then be used to slice the segment (according to a given element layout) and even allow multiple threads to work in parallel on disjoint segment slices (to do this, the segment has to be associated with a scope that allows accessPREVIEW from multiple threads). The following code can be used to sum all int values in a memory segment in parallel:

     try (Arena arena = Arena.openShared()) {
         SequenceLayout SEQUENCE_LAYOUT = MemoryLayout.sequenceLayout(1024, ValueLayout.JAVA_INT);
         MemorySegment segment = arena.allocate(SEQUENCE_LAYOUT);
         int sum = segment.elements(ValueLayout.JAVA_INT).parallel()
                          .mapToInt(s -> s.get(ValueLayout.JAVA_INT, 0))
                          .sum();
     }

## Alignment

Access operations on a memory segment are constrained not only by the spatial and temporal bounds of the segment, but also by the alignment constraint of the value layout specified to the operation. An access operation can access only those offsets in the segment that denote addresses in physical memory which are aligned according to the layout. An address in physical memory is aligned according to a layout if the address is an integer multiple of the layout's alignment constraint. For example, the address 1000 is aligned according to an 8-byte alignment constraint (because 1000 is an integer multiple of 8), and to a 4-byte alignment constraint, and to a 2-byte alignment constraint; in contrast, the address 1004 is aligned according to a 4-byte alignment constraint, and to a 2-byte alignment constraint, but not to an 8-byte alignment constraint. Access operations are required to respect alignment because it can impact the performance of access operations, and can also determine which access operations are available at a given physical address. For instance, atomic access operations operations using `VarHandle` are only permitted at aligned addresses. In addition, alignment applies to an access operation whether the segment being accessed is a native segment or a heap segment.

If the segment being accessed is a native segment, then its address in physical memory can be combined with the offset to obtain the target address in physical memory. The pseudo-function below demonstrates this:

    boolean isAligned(MemorySegment segment, long offset, MemoryLayout layout) {
      return ((segment.address() + offset) % layout.byteAlignment()) == 0;
    }

For example:

- A native segment with address 1000 can be accessed at offsets 0, 8, 16, 24, etc under an 8-byte alignment constraint, because the target addresses (1000, 1008, 1016, 1024) are 8-byte aligned. Access at offsets 1-7 or 9-15 or 17-23 is disallowed because the target addresses would not be 8-byte aligned.
- A native segment with address 1000 can be accessed at offsets 0, 4, 8, 12, etc under a 4-byte alignment constraint, because the target addresses (1000, 1004, 1008, 1012) are 4-byte aligned. Access at offsets 1-3 or 5-7 or 9-11 is disallowed because the target addresses would not be 4-byte aligned.
- A native segment with address 1000 can be accessed at offsets 0, 2, 4, 6, etc under a 2-byte alignment constraint, because the target addresses (1000, 1002, 1004, 1006) are 2-byte aligned. Access at offsets 1 or 3 or 5 is disallowed because the target addresses would not be 2-byte aligned.
- A native segment with address 1004 can be accessed at offsets 0, 4, 8, 12, etc under a 4-byte alignment constraint, and at offsets 0, 2, 4, 6, etc under a 2-byte alignment constraint. Under an 8-byte alignment constraint, it can be accessed at offsets 4, 12, 20, 28, etc.
- A native segment with address 1006 can be accessed at offsets 0, 2, 4, 6, etc under a 2-byte alignment constraint. Under a 4-byte alignment constraint, it can be accessed at offsets 2, 6, 10, 14, etc. Under an 8-byte alignment constraint, it can be accessed at offsets 2, 10, 18, 26, etc.
- A native segment with address 1007 can be accessed at offsets 0, 1, 2, 3, etc under a 1-byte alignment constraint. Under a 2-byte alignment constraint, it can be accessed at offsets 1, 3, 5, 7, etc. Under a 4-byte alignment constraint, it can be accessed at offsets 1, 5, 9, 13, etc. Under an 8-byte alignment constraint, it can be accessed at offsets 1, 9, 17, 25, etc.

The alignment constraint used to access a segment is typically dictated by the shape of the data structure stored in the segment. For example, if the programmer wishes to store a sequence of 8-byte values in a native segment, then the segment should be allocated by specifying a 8-byte alignment constraint, either via `allocateNative(long, long, SegmentScope)` or `allocateNative(MemoryLayout, SegmentScope)`. These factories ensure that the off-heap region of memory backing the returned segment has a starting address that is 8-byte aligned. Subsequently, the programmer can access the segment at the offsets of interest -- 0, 8, 16, 24, etc -- in the knowledge that every such access is aligned.

If the segment being accessed is a heap segment, then determining whether access is aligned is more complex. The address of the segment in physical memory is not known, and is not even fixed (it may change when the segment is relocated during garbage collection). This means that the address cannot be combined with the specified offset to determine a target address in physical memory. Since the alignment constraint always refers to alignment of addresses in physical memory, it is not possible in principle to determine if any offset in a heap segment is aligned. For example, suppose the programmer chooses a 8-byte alignment constraint and tries to access offset 16 in a heap segment. If the heap segment's address 0 corresponds to physical address 1000, then the target address (1016) would be aligned, but if address 0 corresponds to physical address 1004, then the target address (1020) would not be aligned. It is undesirable to allow access to target addresses that are aligned according to the programmer's chosen alignment constraint, but might not be predictably aligned in physical memory (e.g. because of platform considerations and/or garbage collection behavior).

In practice, the Java runtime lays out arrays in memory so that each n-byte element occurs at an n-byte aligned physical address. The runtime preserves this invariant even if the array is relocated during garbage collection. Access operations rely on this invariant to determine if the specified offset in a heap segment refers to an aligned address in physical memory. For example:

- The starting physical address of a `long[]` array will be 8-byte aligned (e.g. 1000), so that successive long elements occur at 8-byte aligned addresses (e.g., 1000, 1008, 1016, 1024, etc.) A heap segment backed by a `long[]` array can be accessed at offsets 0, 8, 16, 24, etc under an 8-byte alignment constraint. In addition, the segment can be accessed at offsets 0, 4, 8, 12, etc under a 4-byte alignment constraint, because the target addresses (1000, 1004, 1008, 1012) are 4-byte aligned. And, the segment can be accessed at offsets 0, 2, 4, 6, etc under a 2-byte alignment constraint, because the target addresses (e.g. 1000, 1002, 1004, 1006) are 2-byte aligned.
- The starting physical address of a `short[]` array will be 2-byte aligned (e.g. 1006) so that successive short elements occur at 2-byte aligned addresses (e.g. 1006, 1008, 1010, 1012, etc). A heap segment backed by a `short[]` array can be accessed at offsets 0, 2, 4, 6, etc under a 2-byte alignment constraint. The segment cannot be accessed at any offset under a 4-byte alignment constraint, because there is no guarantee that the target address would be 4-byte aligned, e.g., offset 0 would correspond to physical address 1006 while offset 1 would correspond to physical address 1007. Similarly, the segment cannot be accessed at any offset under an 8-byte alignment constraint, because because there is no guarantee that the target address would be 8-byte aligned, e.g., offset 2 would correspond to physical address 1008 but offset 4 would correspond to physical address 1010.

In other words, heap segments feature a maximum alignment which is derived from the size of the elements of the Java array backing the segment, as shown in the following table:

> Maximum alignment of heap segments
> Array type (of backing region) | Maximum supported alignment (in bytes)
> --- | ---
> `boolean[]` | `1`
> `byte[]` | `1`
> `char[]` | `2`
> `short[]` | `2`
> `int[]` | `4`
> `float[]` | `4`
> `long[]` | `8`
> `double[]` | `8`

Heap segments can only be accessed using a layout whose alignment is smaller or equal to the maximum alignment associated with the heap segment. Attempting to access a heap segment using a layout whose alignment is greater than the maximum alignment associated with the heap segment will fail, as demonstrated in the following example:

    MemorySegment byteSegment = MemorySegment.ofArray(new byte[10]);
    byteSegment.get(ValueLayout.JAVA_INT, 0); // fails: layout alignment is 4, segment max alignment is 1

In such circumstances, clients have two options. They can use a heap segment backed by a different array type (e.g. `long[]`), capable of supporting greater maximum alignment:

    MemorySegment longSegment = MemorySegment.ofArray(new long[10]);
    longSegment.get(ValueLayout.JAVA_INT, 0); // ok: layout alignment is 4, segment max alignment is 8

Alternatively, they can invoke the access operation with an unaligned layout. All unaligned layout constants (e.g. `ValueLayout.JAVA_INT_UNALIGNED`PREVIEW) have their alignment constraint set to 1:

    MemorySegment byteSegment = MemorySegment.ofArray(new byte[10]);
    byteSegment.get(ValueLayout.JAVA_INT_UNALIGNED, 0); // ok: layout alignment is 1, segment max alignment is 1

## Zero-length memory segments

When interacting with foreign functions, it is common for those functions to allocate a region of memory and return a pointer to that region. Modeling the region of memory with a memory segment is challenging because the Java runtime has no insight into the size of the region. Only the address of the start of the region, stored in the pointer, is available. For example, a C function with return type `char*` might return a pointer to a region containing a single `char` value, or to a region containing an array of `char` values, where the size of the array might be provided in a separate parameter. The size of the array is not readily apparent to the code calling the foreign function and hoping to use its result.

The `Linker`PREVIEW represents a pointer returned from a foreign function with a zero-length memory segment. The address of the segment is the address stored in the pointer. The size of the segment is zero. Similarly, when a client reads an address from a memory segment, a zero-length memory segment is returned.

Since a zero-length segment features trivial spatial bounds, any attempt to access these segments will fail with `IndexOutOfBoundsException`. This is a crucial safety feature: as these segments are associated with a region of memory whose size is not known, any access operations involving these segments cannot be validated. In effect, a zero-length memory segment wraps an address, and it cannot be used without explicit intent.

Zero-length memory segments obtained when interacting with foreign functions are associated with the `global scope`PREVIEW. This is because the Java runtime, in addition to having no insight into the size of the region of memory backing a pointer returned from a foreign function, also has no insight into the lifetime intended for said region of memory by the foreign function that allocated it. The global scope ensures that the obtained segment can be passed, opaquely, to other pointer-accepting foreign functions.

To access native zero-length memory segments, clients have two options, both of which are unsafe. Clients can obtain a new native segment, with new spatial and temporal bounds, as follows:

     SegmentScope scope = ... // obtains a scope
     MemorySegment foreign = someSegment.get(ValueLayout.ADDRESS, 0); // wrap address into segment (size = 0)
     MemorySegment segment = MemorySegment.ofAddress(foreign.address(), 4, scope); // create new segment (size = 4)
     int x = segment.get(ValueLayout.JAVA_INT, 0); //ok

Alternatively, clients can obtain an unboundedPREVIEW address value layout. When an access operation, or a function descriptor that is passed to a downcall method handle, uses an unbounded address value layouts, the runtime will wrap any corresponding raw addresses with native segments with maximal size (i.e. Long.MAX_VALUE). As such, these segments can be accessed directly, as follows:

     MemorySegment foreign = someSegment.get(ValueLayout.ADDRESS.asUnbounded(), 0); // wrap address into segment (size = Long.MAX_VALUE)
     int x = foreign.get(ValueLayout.JAVA_INT, 0); //ok

Both `ofAddress(long, long, SegmentScope)` and `ValueLayout.OfAddress.asUnbounded()`PREVIEW are restricted methods, and should be used with caution: for instance, sizing a segment incorrectly could result in a VM crash when attempting to access the memory segment.

Which approach is taken largely depends on the information that a client has available when obtaining a memory segment wrapping a native pointer. For instance, if such pointer points to a C struct, the client might prefer to resize the segment unsafely, to match the size of the struct (so that out-of-bounds access will be detected by the API). In other instances, however, there will be no, or little information as to what spatial and/or temporal bounds should be associated with a given native pointer. In these cases using an unbounded address layout might be preferable.

Implementation Requirements:
  Implementations of this interface are immutable, thread-safe and value-based.
Since:
  19

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final MemorySegmentPREVIEW`
  `NULL`
  A zero-length native segment modelling the `NULL` address.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `long`
  `address()`
  Returns the address of this memory segment.
  `static MemorySegmentPREVIEW`
  `allocateNative(long byteSize, long byteAlignment, SegmentScopePREVIEW scope)`
  Creates a native segment with the given size (in bytes), alignment (in bytes) and scope.
  `static MemorySegmentPREVIEW`
  `allocateNative(long byteSize, SegmentScopePREVIEW scope)`
  Creates a native segment with the given size (in bytes) and scope.
  `static MemorySegmentPREVIEW`
  `allocateNative(MemoryLayoutPREVIEW layout, SegmentScopePREVIEW scope)`
  Creates a native segment with the given layout and scope.
  `Optional<Object>`
  `array()`
  Returns the Java array associated with this memory segment, if any.
  `ByteBuffer`
  `asByteBuffer()`
  Wraps this segment in a `ByteBuffer`.
  `Optional<MemorySegmentPREVIEW>`
  `asOverlappingSlice(MemorySegmentPREVIEW other)`
  Returns a slice of this segment that is the overlap between this and the provided segment.
  `MemorySegmentPREVIEW`
  `asReadOnly()`
  Returns a read-only view of this segment.
  `default MemorySegmentPREVIEW`
  `asSlice(long offset)`
  Returns a slice of this memory segment, at the given offset.
  `MemorySegmentPREVIEW`
  `asSlice(long offset, long newSize)`
  Returns a slice of this memory segment, at the given offset.
  `long`
  `byteSize()`
  Returns the size (in bytes) of this memory segment.
  `static void`
  `copy(MemorySegmentPREVIEW srcSegment, long srcOffset, MemorySegmentPREVIEW dstSegment, long dstOffset, long bytes)`
  Performs a bulk copy from source segment to destination segment.
  `static void`
  `copy(MemorySegmentPREVIEW srcSegment, ValueLayoutPREVIEW srcElementLayout, long srcOffset, MemorySegmentPREVIEW dstSegment, ValueLayoutPREVIEW dstElementLayout, long dstOffset, long elementCount)`
  Performs a bulk copy from source segment to destination segment.
  `static void`
  `copy(MemorySegmentPREVIEW srcSegment, ValueLayoutPREVIEW srcLayout, long srcOffset, Object dstArray, int dstIndex, int elementCount)`
  Copies a number of elements from a source memory segment to a destination array.
  `static void`
  `copy(Object srcArray, int srcIndex, MemorySegmentPREVIEW dstSegment, ValueLayoutPREVIEW dstLayout, long dstOffset, int elementCount)`
  Copies a number of elements from a source array to a destination memory segment.
  `default MemorySegmentPREVIEW`
  `copyFrom(MemorySegmentPREVIEW src)`
  Performs a bulk copy from given source segment to this segment.
  `Stream<MemorySegmentPREVIEW>`
  `elements(MemoryLayoutPREVIEW elementLayout)`
  Returns a sequential `Stream` over disjoint slices (whose size matches that of the specified layout) in this segment.
  `boolean`
  `equals(Object that)`
  Compares the specified object with this memory segment for equality.
  `MemorySegmentPREVIEW`
  `fill(byte value)`
  Fills a value into this memory segment.
  `void`
  `force()`
  Forces any changes made to the contents of this mapped segment to be written to the storage device described by the mapped segment's file descriptor.
  `default MemorySegmentPREVIEW`
  `get(ValueLayout.OfAddressPREVIEW layout, long offset)`
  Reads an address from this segment at the given offset, with the given layout.
  `default boolean`
  `get(ValueLayout.OfBooleanPREVIEW layout, long offset)`
  Reads a boolean from this segment at the given offset, with the given layout.
  `default byte`
  `get(ValueLayout.OfBytePREVIEW layout, long offset)`
  Reads a byte from this segment at the given offset, with the given layout.
  `default char`
  `get(ValueLayout.OfCharPREVIEW layout, long offset)`
  Reads a char from this segment at the given offset, with the given layout.
  `default double`
  `get(ValueLayout.OfDoublePREVIEW layout, long offset)`
  Reads a double from this segment at the given offset, with the given layout.
  `default float`
  `get(ValueLayout.OfFloatPREVIEW layout, long offset)`
  Reads a float from this segment at the given offset, with the given layout.
  `default int`
  `get(ValueLayout.OfIntPREVIEW layout, long offset)`
  Reads an int from this segment at the given offset, with the given layout.
  `default long`
  `get(ValueLayout.OfLongPREVIEW layout, long offset)`
  Reads a long from this segment at the given offset, with the given layout.
  `default short`
  `get(ValueLayout.OfShortPREVIEW layout, long offset)`
  Reads a short from this segment at the given offset, with the given layout.
  `default MemorySegmentPREVIEW`
  `getAtIndex(ValueLayout.OfAddressPREVIEW layout, long index)`
  Reads an address from this segment at the given at the given index, scaled by the given layout size.
  `default char`
  `getAtIndex(ValueLayout.OfCharPREVIEW layout, long index)`
  Reads a char from this segment at the given index, scaled by the given layout size.
  `default double`
  `getAtIndex(ValueLayout.OfDoublePREVIEW layout, long index)`
  Reads a double from this segment at the given index, scaled by the given layout size.
  `default float`
  `getAtIndex(ValueLayout.OfFloatPREVIEW layout, long index)`
  Reads a float from this segment at the given index, scaled by the given layout size.
  `default int`
  `getAtIndex(ValueLayout.OfIntPREVIEW layout, long index)`
  Reads an int from this segment at the given index, scaled by the given layout size.
  `default long`
  `getAtIndex(ValueLayout.OfLongPREVIEW layout, long index)`
  Reads a long from this segment at the given index, scaled by the given layout size.
  `default short`
  `getAtIndex(ValueLayout.OfShortPREVIEW layout, long index)`
  Reads a short from this segment at the given index, scaled by the given layout size.
  `default String`
  `getUtf8String(long offset)`
  Reads a UTF-8 encoded, null-terminated string from this segment at the given offset.
  `int`
  `hashCode()`
  Returns the hash code value for this memory segment.
  `boolean`
  `isLoaded()`
  Determines whether the contents of this mapped segment is resident in physical memory.
  `boolean`
  `isMapped()`
  Returns `true` if this segment is a mapped segment.
  `boolean`
  `isNative()`
  Returns `true` if this segment is a native segment.
  `boolean`
  `isReadOnly()`
  Returns `true`, if this segment is read-only.
  `void`
  `load()`
  Loads the contents of this mapped segment into physical memory.
  `default long`
  `mismatch(MemorySegmentPREVIEW other)`
  Finds and returns the offset, in bytes, of the first mismatch between this segment and the given other segment.
  `static long`
  `mismatch(MemorySegmentPREVIEW srcSegment, long srcFromOffset, long srcToOffset, MemorySegmentPREVIEW dstSegment, long dstFromOffset, long dstToOffset)`
  Finds and returns the relative offset, in bytes, of the first mismatch between the source and the destination segments.
  `static MemorySegmentPREVIEW`
  `ofAddress(long address)`
  Creates a zero-length native segment from the given address value.
  `static MemorySegmentPREVIEW`
  `ofAddress(long address, long byteSize)`
  Creates a native segment with the given size and address value.
  `static MemorySegmentPREVIEW`
  `ofAddress(long address, long byteSize, SegmentScopePREVIEW scope)`
  Creates a native segment with the given size, address, and scope.
  `static MemorySegmentPREVIEW`
  `ofAddress(long address, long byteSize, SegmentScopePREVIEW scope, Runnable cleanupAction)`
  Creates a native segment with the given size, address, and scope.
  `static MemorySegmentPREVIEW`
  `ofArray(byte[] byteArray)`
  Creates a heap segment backed by the on-heap region of memory that holds the given byte array.
  `static MemorySegmentPREVIEW`
  `ofArray(char[] charArray)`
  Creates a heap segment backed by the on-heap region of memory that holds the given char array.
  `static MemorySegmentPREVIEW`
  `ofArray(double[] doubleArray)`
  Creates a heap segment backed by the on-heap region of memory that holds the given double array.
  `static MemorySegmentPREVIEW`
  `ofArray(float[] floatArray)`
  Creates a heap segment backed by the on-heap region of memory that holds the given float array.
  `static MemorySegmentPREVIEW`
  `ofArray(int[] intArray)`
  Creates a heap segment backed by the on-heap region of memory that holds the given int array.
  `static MemorySegmentPREVIEW`
  `ofArray(long[] longArray)`
  Creates a heap segment backed by the on-heap region of memory that holds the given long array.
  `static MemorySegmentPREVIEW`
  `ofArray(short[] shortArray)`
  Creates a heap segment backed by the on-heap region of memory that holds the given short array.
  `static MemorySegmentPREVIEW`
  `ofBuffer(Buffer buffer)`
  Creates a memory segment that is backed by the same region of memory that backs the given `Buffer` instance.
  `SegmentScopePREVIEW`
  `scope()`
  Returns the scope associated with this memory segment.
  `long`
  `segmentOffset(MemorySegmentPREVIEW other)`
  Returns the offset, in bytes, of the provided segment, relative to this segment.
  `default void`
  `set(ValueLayout.OfAddressPREVIEW layout, long offset, MemorySegmentPREVIEW value)`
  Writes an address into this segment at the given offset, with the given layout.
  `default void`
  `set(ValueLayout.OfBooleanPREVIEW layout, long offset, boolean value)`
  Writes a boolean into this segment at the given offset, with the given layout.
  `default void`
  `set(ValueLayout.OfBytePREVIEW layout, long offset, byte value)`
  Writes a byte into this segment at the given offset, with the given layout.
  `default void`
  `set(ValueLayout.OfCharPREVIEW layout, long offset, char value)`
  Writes a char into this segment at the given offset, with the given layout.
  `default void`
  `set(ValueLayout.OfDoublePREVIEW layout, long offset, double value)`
  Writes a double into this segment at the given offset, with the given layout.
  `default void`
  `set(ValueLayout.OfFloatPREVIEW layout, long offset, float value)`
  Writes a float into this segment at the given offset, with the given layout.
  `default void`
  `set(ValueLayout.OfIntPREVIEW layout, long offset, int value)`
  Writes an int into this segment at the given offset, with the given layout.
  `default void`
  `set(ValueLayout.OfLongPREVIEW layout, long offset, long value)`
  Writes a long into this segment at the given offset, with the given layout.
  `default void`
  `set(ValueLayout.OfShortPREVIEW layout, long offset, short value)`
  Writes a short into this segment at the given offset, with the given layout.
  `default void`
  `setAtIndex(ValueLayout.OfAddressPREVIEW layout, long index, MemorySegmentPREVIEW value)`
  Writes an address into this segment at the given index, scaled by the given layout size.
  `default void`
  `setAtIndex(ValueLayout.OfCharPREVIEW layout, long index, char value)`
  Writes a char into this segment at the given index, scaled by the given layout size.
  `default void`
  `setAtIndex(ValueLayout.OfDoublePREVIEW layout, long index, double value)`
  Writes a double into this segment at the given index, scaled by the given layout size.
  `default void`
  `setAtIndex(ValueLayout.OfFloatPREVIEW layout, long index, float value)`
  Writes a float into this segment at the given index, scaled by the given layout size.
  `default void`
  `setAtIndex(ValueLayout.OfIntPREVIEW layout, long index, int value)`
  Writes an int into this segment at the given index, scaled by the given layout size.
  `default void`
  `setAtIndex(ValueLayout.OfLongPREVIEW layout, long index, long value)`
  Writes a long into this segment at the given index, scaled by the given layout size.
  `default void`
  `setAtIndex(ValueLayout.OfShortPREVIEW layout, long index, short value)`
  Writes a short into this segment at the given index, scaled by the given layout size.
  `default void`
  `setUtf8String(long offset, String str)`
  Writes the given string into this segment at the given offset, converting it to a null-terminated byte sequence using UTF-8 encoding.
  `Spliterator<MemorySegmentPREVIEW>`
  `spliterator(MemoryLayoutPREVIEW elementLayout)`
  Returns a spliterator for this memory segment.
  `byte[]`
  `toArray(ValueLayout.OfBytePREVIEW elementLayout)`
  Copy the contents of this memory segment into a new byte array.
  `char[]`
  `toArray(ValueLayout.OfCharPREVIEW elementLayout)`
  Copy the contents of this memory segment into a new char array.
  `double[]`
  `toArray(ValueLayout.OfDoublePREVIEW elementLayout)`
  Copy the contents of this memory segment into a new double array.
  `float[]`
  `toArray(ValueLayout.OfFloatPREVIEW elementLayout)`
  Copy the contents of this memory segment into a new float array.
  `int[]`
  `toArray(ValueLayout.OfIntPREVIEW elementLayout)`
  Copy the contents of this memory segment into a new int array.
  `long[]`
  `toArray(ValueLayout.OfLongPREVIEW elementLayout)`
  Copy the contents of this memory segment into a new long array.
  `short[]`
  `toArray(ValueLayout.OfShortPREVIEW elementLayout)`
  Copy the contents of this memory segment into a new short array.
  `void`
  `unload()`
  Unloads the contents of this mapped segment from physical memory.

- ## Field Details

  - ### NULL

    static final MemorySegmentPREVIEW NULL
    A zero-length native segment modelling the `NULL` address.

- ## Method Details

  - ### address

    long address()
    Returns the address of this memory segment.
    Returns:
      the address of this memory segment

  - ### array

    Optional<Object> array()
    Returns the Java array associated with this memory segment, if any.
    Returns:
      the Java array associated with this memory segment, if any

  - ### spliterator

    Spliterator<MemorySegmentPREVIEW> spliterator(MemoryLayoutPREVIEW elementLayout)
    Returns a spliterator for this memory segment. The returned spliterator reports `Spliterator.SIZED`, `Spliterator.SUBSIZED`, `Spliterator.IMMUTABLE`, `Spliterator.NONNULL` and `Spliterator.ORDERED` characteristics.

    The returned spliterator splits this segment according to the specified element layout; that is, if the supplied layout has size N, then calling `Spliterator.trySplit()` will result in a spliterator serving approximately `S/N` elements (depending on whether N is even or not), where `S` is the size of this segment. As such, splitting is possible as long as `S/N >= 2`. The spliterator returns segments that are associated with the same scope as that associated with this segment.

    The returned spliterator effectively allows to slice this segment into disjoint slices, which can then be processed in parallel by multiple threads.

    Parameters:
      `elementLayout` - the layout to be used for splitting.
    Returns:
      the element spliterator for this segment
    Throws:
      `IllegalArgumentException` - if the `elementLayout` size is zero, or the segment size modulo the `elementLayout` size is greater than zero, if this segment is incompatible with the alignment constraint in the provided layout, or if the `elementLayout` alignment is greater than its size.

  - ### elements

    Stream<MemorySegmentPREVIEW> elements(MemoryLayoutPREVIEW elementLayout)
    Returns a sequential `Stream` over disjoint slices (whose size matches that of the specified layout) in this segment. Calling this method is equivalent to the following code:

        StreamSupport.stream(segment.spliterator(elementLayout), false);

    Parameters:
      `elementLayout` - the layout to be used for splitting.
    Returns:
      a sequential `Stream` over disjoint slices in this segment.
    Throws:
      `IllegalArgumentException` - if the `elementLayout` size is zero, or the segment size modulo the `elementLayout` size is greater than zero, if this segment is incompatible with the alignment constraint in the provided layout, or if the `elementLayout` alignment is greater than its size.

  - ### scope

    SegmentScopePREVIEW scope()
    Returns the scope associated with this memory segment.
    Returns:
      the scope associated with this memory segment

  - ### byteSize

    long byteSize()
    Returns the size (in bytes) of this memory segment.
    Returns:
      the size (in bytes) of this memory segment

  - ### asSlice

    MemorySegmentPREVIEW asSlice(long offset, long newSize)
    Returns a slice of this memory segment, at the given offset. The returned segment's address is the address of this segment plus the given offset; its size is specified by the given argument.
    Parameters:
      `offset` - The new segment base offset (relative to the address of this segment), specified in bytes.
      `newSize` - The new segment size, specified in bytes.
    Returns:
      a slice of this memory segment.
    Throws:
      `IndexOutOfBoundsException` - if `offset < 0`, `offset > byteSize()`, `newSize < 0`, or `newSize > byteSize() - offset`
    See Also:
      - `asSlice(long)`

  - ### asSlice

    default MemorySegmentPREVIEW asSlice(long offset)
    Returns a slice of this memory segment, at the given offset. The returned segment's address is the address of this segment plus the given offset; its size is computed by subtracting the specified offset from this segment size.

    Equivalent to the following code:

        asSlice(offset, byteSize() - offset);

    Parameters:
      `offset` - The new segment base offset (relative to the address of this segment), specified in bytes.
    Returns:
      a slice of this memory segment.
    Throws:
      `IndexOutOfBoundsException` - if `offset < 0`, or `offset > byteSize()`.
    See Also:
      - `asSlice(long, long)`

  - ### isReadOnly

    boolean isReadOnly()
    Returns `true`, if this segment is read-only.
    Returns:
      `true`, if this segment is read-only
    See Also:
      - `asReadOnly()`

  - ### asReadOnly

    MemorySegmentPREVIEW asReadOnly()
    Returns a read-only view of this segment. The resulting segment will be identical to this one, but attempts to overwrite the contents of the returned segment will cause runtime exceptions.
    Returns:
      a read-only view of this segment
    See Also:
      - `isReadOnly()`

  - ### isNative

    boolean isNative()
    Returns `true` if this segment is a native segment. A native segment is created e.g. using the `allocateNative(long, SegmentScope)` (and related) factory, or by wrapping a direct buffer.
    Returns:
      `true` if this segment is native segment.

  - ### isMapped

    boolean isMapped()
    Returns `true` if this segment is a mapped segment. A mapped memory segment is created e.g. using the `FileChannel.map(FileChannel.MapMode, long, long, SegmentScope)`PREVIEW factory, or by wrapping a mapped byte buffer.
    Returns:
      `true` if this segment is a mapped segment.

  - ### asOverlappingSlice

    Optional<MemorySegmentPREVIEW> asOverlappingSlice(MemorySegmentPREVIEW other)
    Returns a slice of this segment that is the overlap between this and the provided segment.

    Two segments `S1` and `S2` are said to overlap if it is possible to find at least two slices `L1` (from `S1`) and `L2` (from `S2`) that are backed by the same region of memory. As such, it is not possible for a native segment to overlap with a heap segment; in this case, or when no overlap occurs, `null` is returned.

    Parameters:
      `other` - the segment to test for an overlap with this segment.
    Returns:
      a slice of this segment (where overlapping occurs).

  - ### segmentOffset

    long segmentOffset(MemorySegmentPREVIEW other)
    Returns the offset, in bytes, of the provided segment, relative to this segment.

    The offset is relative to the address of this segment and can be a negative or positive value. For instance, if both segments are native segments, or heap segments backed by the same array, the resulting offset can be computed as follows:

        other.address() - segment.address()

    If the segments share the same address, `0` is returned. If `other` is a slice of this segment, the offset is always `0 <= x < this.byteSize()`.
    Parameters:
      `other` - the segment to retrieve an offset to.
    Returns:
      the relative offset, in bytes, of the provided segment.
    Throws:
      `UnsupportedOperationException` - if the two segments cannot be compared, e.g. because they are of a different kind, or because they are backed by different Java arrays.

  - ### fill

    MemorySegmentPREVIEW fill(byte value)
    Fills a value into this memory segment.

    More specifically, the given value is filled into each address of this segment. Equivalent to (but likely more efficient than) the following code:

        byteHandle = MemoryLayout.ofSequence(ValueLayout.JAVA_BYTE)
                .varHandle(byte.class, MemoryLayout.PathElement.sequenceElement());
        for (long l = 0; l < segment.byteSize(); l++) {
            byteHandle.set(segment.address(), l, value);
        }

    without any regard or guarantees on the ordering of particular memory elements being set.

    Fill can be useful to initialize or reset the memory of a segment.

    Parameters:
      `value` - the value to fill into this segment
    Returns:
      this memory segment
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `UnsupportedOperationException` - if this segment is read-only (see `isReadOnly()`).

  - ### copyFrom

    default MemorySegmentPREVIEW copyFrom(MemorySegmentPREVIEW src)
    Performs a bulk copy from given source segment to this segment. More specifically, the bytes at offset `0` through `src.byteSize() - 1` in the source segment are copied into this segment at offset `0` through `src.byteSize() - 1`.

    Calling this method is equivalent to the following code:

        MemorySegment.copy(src, 0, this, 0, src.byteSize);

    Parameters:
      `src` - the source segment.
    Returns:
      this segment.
    Throws:
      `IndexOutOfBoundsException` - if `src.byteSize() > this.byteSize()`.
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalStateException` - if the scope associated with `src` is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `src.scope().isAccessibleBy(T) == false`.
      `UnsupportedOperationException` - if this segment is read-only (see `isReadOnly()`).

  - ### mismatch

    default long mismatch(MemorySegmentPREVIEW other)
    Finds and returns the offset, in bytes, of the first mismatch between this segment and the given other segment. The offset is relative to the address of each segment and will be in the range of 0 (inclusive) up to the size (in bytes) of the smaller memory segment (exclusive).

    If the two segments share a common prefix then the returned offset is the length of the common prefix, and it follows that there is a mismatch between the two segments at that offset within the respective segments. If one segment is a proper prefix of the other, then the returned offset is the smallest of the segment sizes, and it follows that the offset is only valid for the larger segment. Otherwise, there is no mismatch and `-1` is returned.

    Parameters:
      `other` - the segment to be tested for a mismatch with this segment
    Returns:
      the relative offset, in bytes, of the first mismatch between this and the given other segment, otherwise -1 if no mismatch
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalStateException` - if the scope associated with `other` is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `other.scope().isAccessibleBy(T) == false`.

  - ### isLoaded

    boolean isLoaded()
    Determines whether the contents of this mapped segment is resident in physical memory.

    A return value of `true` implies that it is highly likely that all the data in this segment is resident in physical memory and may therefore be accessed without incurring any virtual-memory page faults or I/O operations. A return value of `false` does not necessarily imply that this segment's content is not resident in physical memory.

    The returned value is a hint, rather than a guarantee, because the underlying operating system may have paged out some of this segment's data by the time that an invocation of this method returns.

    Returns:
      `true` if it is likely that the contents of this segment is resident in physical memory
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `UnsupportedOperationException` - if this segment is not a mapped memory segment, e.g. if `isMapped() == false`.

  - ### load

    void load()
    Loads the contents of this mapped segment into physical memory.

    This method makes a best effort to ensure that, when it returns, this contents of this segment is resident in physical memory. Invoking this method may cause some number of page faults and I/O operations to occur.

    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `UnsupportedOperationException` - if this segment is not a mapped memory segment, e.g. if `isMapped() == false`.

  - ### unload

    void unload()
    Unloads the contents of this mapped segment from physical memory.

    This method makes a best effort to ensure that the contents of this segment are are no longer resident in physical memory. Accessing this segment's contents after invoking this method may cause some number of page faults and I/O operations to occur (as this segment's contents might need to be paged back in).

    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `UnsupportedOperationException` - if this segment is not a mapped memory segment, e.g. if `isMapped() == false`.

  - ### force

    void force()
    Forces any changes made to the contents of this mapped segment to be written to the storage device described by the mapped segment's file descriptor.

    If the file descriptor associated with this mapped segment resides on a local storage device then when this method returns it is guaranteed that all changes made to this segment since it was created, or since this method was last invoked, will have been written to that device.

    If the file descriptor associated with this mapped segment does not reside on a local device then no such guarantee is made.

    If this segment was not mapped in read/write mode (`FileChannel.MapMode.READ_WRITE`) then invoking this method may have no effect. In particular, the method has no effect for segments mapped in read-only or private mapping modes. This method may or may not have an effect for implementation-specific mapping modes.

    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `UnsupportedOperationException` - if this segment is not a mapped memory segment, e.g. if `isMapped() == false`.
      `UncheckedIOException` - if there is an I/O error writing the contents of this segment to the associated storage device

  - ### asByteBuffer

    ByteBuffer asByteBuffer()
    Wraps this segment in a `ByteBuffer`. Some properties of the returned buffer are linked to the properties of this segment. For instance, if this segment is immutable (e.g. the segment is a read-only segment, see `isReadOnly()`), then the resulting buffer is read-only (see `Buffer.isReadOnly()`). Additionally, if this is a native segment, the resulting buffer is direct (see `ByteBuffer.isDirect()`).

    The returned buffer's position (see `Buffer.position()`) is initially set to zero, while the returned buffer's capacity and limit (see `Buffer.capacity()` and `Buffer.limit()`, respectively) are set to this segment' size (see `byteSize()`). For this reason, a byte buffer cannot be returned if this segment' size is greater than `Integer.MAX_VALUE`.

    The life-cycle of the returned buffer will be tied to that of this segment. That is, accessing the returned buffer after the scope associated with this segment is no longer alivePREVIEW, will throw an `IllegalStateException`. Similarly, accessing the returned buffer from a thread `T` such that `scope().isAccessible(T) == false` will throw a `WrongThreadException`.

    If this segment is associated with a scope that can only be accessed from a single thread, calling read/write I/O operations on the resulting buffer might result in an unspecified exception being thrown. Examples of such problematic operations are `AsynchronousSocketChannel.read(ByteBuffer)` and `AsynchronousSocketChannel.write(ByteBuffer)`.

    Finally, the resulting buffer's byte order is `ByteOrder.BIG_ENDIAN`; this can be changed using `ByteBuffer.order(java.nio.ByteOrder)`.

    Returns:
      a `ByteBuffer` view of this memory segment.
    Throws:
      `UnsupportedOperationException` - if this segment cannot be mapped onto a `ByteBuffer` instance, e.g. because it models a heap-based segment that is not based on a `byte[]`), or if its size is greater than `Integer.MAX_VALUE`.

  - ### toArray

    byte[] toArray(ValueLayout.OfBytePREVIEW elementLayout)
    Copy the contents of this memory segment into a new byte array.
    Parameters:
      `elementLayout` - the source element layout. If the byte order associated with the layout is different from the native order, a byte swap operation will be performed on each array element.
    Returns:
      a new byte array whose contents are copied from this memory segment.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalStateException` - if this segment's contents cannot be copied into a `byte[]` instance, e.g. its size is greater than `Integer.MAX_VALUE`.

  - ### toArray

    short[] toArray(ValueLayout.OfShortPREVIEW elementLayout)
    Copy the contents of this memory segment into a new short array.
    Parameters:
      `elementLayout` - the source element layout. If the byte order associated with the layout is different from the native order, a byte swap operation will be performed on each array element.
    Returns:
      a new short array whose contents are copied from this memory segment.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalStateException` - if this segment's contents cannot be copied into a `short[]` instance, e.g. because `byteSize() % 2 != 0`, or `byteSize() / 2 > Integer#MAX_VALUE`

  - ### toArray

    char[] toArray(ValueLayout.OfCharPREVIEW elementLayout)
    Copy the contents of this memory segment into a new char array.
    Parameters:
      `elementLayout` - the source element layout. If the byte order associated with the layout is different from the native order, a byte swap operation will be performed on each array element.
    Returns:
      a new char array whose contents are copied from this memory segment.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalStateException` - if this segment's contents cannot be copied into a `char[]` instance, e.g. because `byteSize() % 2 != 0`, or `byteSize() / 2 > Integer#MAX_VALUE`.

  - ### toArray

    int[] toArray(ValueLayout.OfIntPREVIEW elementLayout)
    Copy the contents of this memory segment into a new int array.
    Parameters:
      `elementLayout` - the source element layout. If the byte order associated with the layout is different from the native order, a byte swap operation will be performed on each array element.
    Returns:
      a new int array whose contents are copied from this memory segment.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalStateException` - if this segment's contents cannot be copied into a `int[]` instance, e.g. because `byteSize() % 4 != 0`, or `byteSize() / 4 > Integer#MAX_VALUE`.

  - ### toArray

    float[] toArray(ValueLayout.OfFloatPREVIEW elementLayout)
    Copy the contents of this memory segment into a new float array.
    Parameters:
      `elementLayout` - the source element layout. If the byte order associated with the layout is different from the native order, a byte swap operation will be performed on each array element.
    Returns:
      a new float array whose contents are copied from this memory segment.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalStateException` - if this segment's contents cannot be copied into a `float[]` instance, e.g. because `byteSize() % 4 != 0`, or `byteSize() / 4 > Integer#MAX_VALUE`.

  - ### toArray

    long[] toArray(ValueLayout.OfLongPREVIEW elementLayout)
    Copy the contents of this memory segment into a new long array.
    Parameters:
      `elementLayout` - the source element layout. If the byte order associated with the layout is different from the native order, a byte swap operation will be performed on each array element.
    Returns:
      a new long array whose contents are copied from this memory segment.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalStateException` - if this segment's contents cannot be copied into a `long[]` instance, e.g. because `byteSize() % 8 != 0`, or `byteSize() / 8 > Integer#MAX_VALUE`.

  - ### toArray

    double[] toArray(ValueLayout.OfDoublePREVIEW elementLayout)
    Copy the contents of this memory segment into a new double array.
    Parameters:
      `elementLayout` - the source element layout. If the byte order associated with the layout is different from the native order, a byte swap operation will be performed on each array element.
    Returns:
      a new double array whose contents are copied from this memory segment.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalStateException` - if this segment's contents cannot be copied into a `double[]` instance, e.g. because `byteSize() % 8 != 0`, or `byteSize() / 8 > Integer#MAX_VALUE`.

  - ### getUtf8String

    default String getUtf8String(long offset)
    Reads a UTF-8 encoded, null-terminated string from this segment at the given offset.

    This method always replaces malformed-input and unmappable-character sequences with this charset's default replacement string. The `CharsetDecoder` class should be used when more control over the decoding process is required.

    Parameters:
      `offset` - offset in bytes (relative to this segment address) at which this access operation will occur.
    Returns:
      a Java string constructed from the bytes read from the given starting address up to (but not including) the first `'\0'` terminator character (assuming one is found).
    Throws:
      `IllegalArgumentException` - if the size of the UTF-8 string is greater than the largest string supported by the platform.
      `IndexOutOfBoundsException` - if `offset < 0` or `S + offset > byteSize()`, where `S` is the size of the UTF-8 string (including the terminator character).
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.

  - ### setUtf8String

    default void setUtf8String(long offset, String str)
    Writes the given string into this segment at the given offset, converting it to a null-terminated byte sequence using UTF-8 encoding.

    This method always replaces malformed-input and unmappable-character sequences with this charset's default replacement string. The `CharsetDecoder` class should be used when more control over the decoding process is required.

    If the given string contains any `'\0'` characters, they will be copied as well. This means that, depending on the method used to read the string, such as `getUtf8String(long)`, the string will appear truncated when read again.

    Parameters:
      `offset` - offset in bytes (relative to this segment address) at which this access operation will occur. the final address of this write operation can be expressed as `address() + offset`.
      `str` - the Java string to be written into this segment.
    Throws:
      `IndexOutOfBoundsException` - if `offset < 0` or `str.getBytes().length() + offset >= byteSize()`.
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.

  - ### ofBuffer

    static MemorySegmentPREVIEW ofBuffer(Buffer buffer)
    Creates a memory segment that is backed by the same region of memory that backs the given `Buffer` instance. The segment starts relative to the buffer's position (inclusive) and ends relative to the buffer's limit (exclusive).

    If the buffer is read-only, the resulting segment will also be read-only. Moreover, if the buffer is a direct buffer, the returned segment is a native segment; otherwise the returned memory segment is a heap segment.

    The scope `S` associated with the returned segment is computed as follows:

    - if the buffer has been obtained by calling `asByteBuffer()` on a memory segment whose scope is `S'`, then `S = S'`; or
    - if the buffer is a heap buffer, then `S` is the global scopePREVIEW; or
    - if the buffer is a direct buffer, then `S` is a scope that is always alive and which keeps the buffer reachable. Therefore, the off-heap region of memory backing the buffer instance will remain available as long as the returned segment is reachable.
    Parameters:
      `buffer` - the buffer instance to be turned into a new memory segment.
    Returns:
      a memory segment, derived from the given buffer instance.
    Throws:
      `IllegalArgumentException` - if the provided `buffer` is a heap buffer but is not backed by an array. For example, buffers directly or indirectly obtained via (`CharBuffer.wrap(CharSequence)` or `CharBuffer.wrap(char[], int, int)` are not backed by an array.

  - ### ofArray

    static MemorySegmentPREVIEW ofArray(byte[] byteArray)
    Creates a heap segment backed by the on-heap region of memory that holds the given byte array. The returned segment is associated with the global scopePREVIEW, and its `address()` is set to zero.
    Parameters:
      `byteArray` - the primitive array backing the heap memory segment.
    Returns:
      a heap memory segment backed by a byte array.

  - ### ofArray

    static MemorySegmentPREVIEW ofArray(char[] charArray)
    Creates a heap segment backed by the on-heap region of memory that holds the given char array. The returned segment is associated with the global scopePREVIEW, and its `address()` is set to zero.
    Parameters:
      `charArray` - the primitive array backing the heap segment.
    Returns:
      a heap memory segment backed by a char array.

  - ### ofArray

    static MemorySegmentPREVIEW ofArray(short[] shortArray)
    Creates a heap segment backed by the on-heap region of memory that holds the given short array. The returned segment is associated with the global scopePREVIEW, and its `address()` is set to zero.
    Parameters:
      `shortArray` - the primitive array backing the heap segment.
    Returns:
      a heap memory segment backed by a short array.

  - ### ofArray

    static MemorySegmentPREVIEW ofArray(int[] intArray)
    Creates a heap segment backed by the on-heap region of memory that holds the given int array. The returned segment is associated with the global scopePREVIEW, and its `address()` is set to zero.
    Parameters:
      `intArray` - the primitive array backing the heap segment.
    Returns:
      a heap memory segment backed by an int array.

  - ### ofArray

    static MemorySegmentPREVIEW ofArray(float[] floatArray)
    Creates a heap segment backed by the on-heap region of memory that holds the given float array. The returned segment is associated with the global scopePREVIEW, and its `address()` is set to zero.
    Parameters:
      `floatArray` - the primitive array backing the heap segment.
    Returns:
      a heap memory segment backed by a float array.

  - ### ofArray

    static MemorySegmentPREVIEW ofArray(long[] longArray)
    Creates a heap segment backed by the on-heap region of memory that holds the given long array. The returned segment is associated with the global scopePREVIEW, and its `address()` is set to zero.
    Parameters:
      `longArray` - the primitive array backing the heap segment.
    Returns:
      a heap memory segment backed by a long array.

  - ### ofArray

    static MemorySegmentPREVIEW ofArray(double[] doubleArray)
    Creates a heap segment backed by the on-heap region of memory that holds the given double array. The returned segment is associated with the global scopePREVIEW, and its `address()` is set to zero.
    Parameters:
      `doubleArray` - the primitive array backing the heap segment.
    Returns:
      a heap memory segment backed by a double array.

  - ### ofAddress

    static MemorySegmentPREVIEW ofAddress(long address)
    Creates a zero-length native segment from the given address value. The returned segment is associated with the global scopePREVIEW.

    This is equivalent to the following code:

         ofAddress(address, 0);

    Parameters:
      `address` - the address of the returned native segment.
    Returns:
      a zero-length native segment with the given address.

  - ### ofAddress

    static MemorySegmentPREVIEW ofAddress(long address, long byteSize)
    Creates a native segment with the given size and address value. The returned segment is associated with the global scopePREVIEW.

    This is equivalent to the following code:

         ofAddress(address, byteSize, SegmentScope.global());

    This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.
    Parameters:
      `address` - the address of the returned native segment.
      `byteSize` - the size (in bytes) of the returned native segment.
    Returns:
      a zero-length native segment with the given address and size.
    Throws:
      `IllegalArgumentException` - if `byteSize < 0`.
      `IllegalCallerException` - If the caller is in a module that does not have native access enabled.

  - ### ofAddress

    static MemorySegmentPREVIEW ofAddress(long address, long byteSize, SegmentScopePREVIEW scope)
    Creates a native segment with the given size, address, and scope. This method can be useful when interacting with custom memory sources (e.g. custom allocators), where an address to some underlying region of memory is typically obtained from foreign code (often as a plain `long` value).

    The returned segment is not read-only (see `isReadOnly()`), and is associated with the provided scope.

    This is equivalent to the following code:

         ofAddress(address, byteSize, scope, null);

    This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.
    Parameters:
      `address` - the returned segment's address.
      `byteSize` - the desired size.
      `scope` - the scope associated with the returned native segment.
    Returns:
      a native segment with the given address, size and scope.
    Throws:
      `IllegalArgumentException` - if `byteSize < 0`.
      `IllegalStateException` - if `scope` is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope.isAccessibleBy(T) == false`.
      `IllegalCallerException` - If the caller is in a module that does not have native access enabled.

  - ### ofAddress

    static MemorySegmentPREVIEW ofAddress(long address, long byteSize, SegmentScopePREVIEW scope, Runnable cleanupAction)
    Creates a native segment with the given size, address, and scope. This method can be useful when interacting with custom memory sources (e.g. custom allocators), where an address to some underlying region of memory is typically obtained from foreign code (often as a plain `long` value).

    The returned segment is not read-only (see `isReadOnly()`), and is associated with the provided scope.

    The provided cleanup action (if any) will be invoked when the scope becomes not alivePREVIEW.

    Clients should ensure that the address and bounds refer to a valid region of memory that is accessible for reading and, if appropriate, writing; an attempt to access an invalid address from Java code will either return an arbitrary value, have no visible effect, or cause an unspecified exception to be thrown.

    This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

    Parameters:
      `address` - the returned segment's address.
      `byteSize` - the desired size.
      `scope` - the scope associated with the returned native segment.
      `cleanupAction` - the custom cleanup action to be associated to the returned segment (can be null).
    Returns:
      a native segment with the given address, size and scope.
    Throws:
      `IllegalArgumentException` - if `byteSize < 0`.
      `IllegalStateException` - if `scope` is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope.isAccessibleBy(T) == false`.
      `IllegalCallerException` - If the caller is in a module that does not have native access enabled.

  - ### allocateNative

    static MemorySegmentPREVIEW allocateNative(MemoryLayoutPREVIEW layout, SegmentScopePREVIEW scope)
    Creates a native segment with the given layout and scope.

    The lifetime off-heap region of memory associated with the returned native segment is determined by the provided scope. The off-heap memory region is deallocated when the scope becomes not alivePREVIEW. If the scope has been obtained using an `Arena`PREVIEW, clients are responsible for ensuring that the arena is closed when the returned segment is no longer in use Failure to do so will result in off-heap memory leaks. As an alternative, an automatic scopePREVIEW can be used, allowing the off-heap memory region associated with the returned native segment to be automatically released some unspecified time after the scope is no longer referenced.

    The address of the returned memory segment is the starting address of the newly allocated off-heap region backing the segment. Moreover, the address of the returned segment will be aligned according to the alignment constraint of the provided layout.

    This is equivalent to the following code:

        allocateNative(layout.bytesSize(), layout.bytesAlignment(), scope);

    The region of off-heap region backing the returned native segment is initialized to zero.

    Parameters:
      `layout` - the layout of the off-heap memory region backing the native segment.
      `scope` - the scope associated with the returned native segment.
    Returns:
      a new native segment.
    Throws:
      `IllegalStateException` - if `scope` is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope.isAccessibleBy(T) == false`.

  - ### allocateNative

    static MemorySegmentPREVIEW allocateNative(long byteSize, SegmentScopePREVIEW scope)
    Creates a native segment with the given size (in bytes) and scope.

    The lifetime off-heap region of memory associated with the returned native segment is determined by the provided scope. The off-heap memory region is deallocated when the scope becomes not alivePREVIEW. If the scope has been obtained using an `Arena`PREVIEW, clients are responsible for ensuring that the arena is closed when the returned segment is no longer in use Failure to do so will result in off-heap memory leaks. As an alternative, an automatic scopePREVIEW can be used, allowing the off-heap memory region associated with the returned native segment to be automatically released some unspecified time after the scope is no longer referenced.

    The address of the returned memory segment is the starting address of the newly allocated off-heap region backing the segment. Moreover, the address of the returned segment is guaranteed to be at least 1-byte aligned.

    This is equivalent to the following code:

        allocateNative(bytesSize, 1, scope);

    The region of off-heap region backing the returned native segment is initialized to zero.

    Parameters:
      `byteSize` - the size (in bytes) of the off-heap memory region of memory backing the native memory segment.
      `scope` - the scope associated with the returned native segment.
    Returns:
      a new native memory segment.
    Throws:
      `IllegalArgumentException` - if `byteSize < 0`.
      `IllegalStateException` - if `scope` is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope.isAccessibleBy(T) == false`.

  - ### allocateNative

    static MemorySegmentPREVIEW allocateNative(long byteSize, long byteAlignment, SegmentScopePREVIEW scope)
    Creates a native segment with the given size (in bytes), alignment (in bytes) and scope.

    The lifetime off-heap region of memory associated with the returned native segment is determined by the provided scope. The off-heap memory region is deallocated when the scope becomes not alivePREVIEW. If the scope has been obtained using an `Arena`PREVIEW, clients are responsible for ensuring that the arena is closed when the returned segment is no longer in use Failure to do so will result in off-heap memory leaks. As an alternative, an automatic scopePREVIEW can be used, allowing the off-heap memory region associated with the returned native segment to be automatically released some unspecified time after the scope is no longer referenced.

    The address of the returned memory segment is the starting address of the newly allocated off-heap region backing the segment. Moreover, the address of the returned segment will be aligned according to the provided alignment constraint.

    The region of off-heap region backing the returned native segment is initialized to zero.

    Parameters:
      `byteSize` - the size (in bytes) of the off-heap region of memory backing the native memory segment.
      `byteAlignment` - the alignment constraint (in bytes) of the off-heap region of memory backing the native memory segment.
      `scope` - the scope associated with the returned native segment.
    Returns:
      a new native memory segment.
    Throws:
      `IllegalArgumentException` - if `byteSize < 0`, `byteAlignment <= 0`, or if `byteAlignment` is not a power of 2.
      `IllegalStateException` - if `scope` is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope.isAccessibleBy(T) == false`.

  - ### copy

    static void copy(MemorySegmentPREVIEW srcSegment, long srcOffset, MemorySegmentPREVIEW dstSegment, long dstOffset, long bytes)
    Performs a bulk copy from source segment to destination segment. More specifically, the bytes at offset `srcOffset` through `srcOffset + bytes - 1` in the source segment are copied into the destination segment at offset `dstOffset` through `dstOffset + bytes - 1`.

    If the source segment overlaps with this segment, then the copying is performed as if the bytes at offset `srcOffset` through `srcOffset + bytes - 1` in the source segment were first copied into a temporary segment with size `bytes`, and then the contents of the temporary segment were copied into the destination segment at offset `dstOffset` through `dstOffset + bytes - 1`.

    The result of a bulk copy is unspecified if, in the uncommon case, the source segment and the destination segment do not overlap, but refer to overlapping regions of the same backing storage using different addresses. For example, this may occur if the same file is mapped to two segments.

    Calling this method is equivalent to the following code:

        MemorySegment.copy(srcSegment, ValueLayout.JAVA_BYTE, srcOffset, dstSegment, ValueLayout.JAVA_BYTE, dstOffset, bytes);

    Parameters:
      `srcSegment` - the source segment.
      `srcOffset` - the starting offset, in bytes, of the source segment.
      `dstSegment` - the destination segment.
      `dstOffset` - the starting offset, in bytes, of the destination segment.
      `bytes` - the number of bytes to be copied.
    Throws:
      `IllegalStateException` - if the scope associated with `srcSegment` is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `srcSegment.scope().isAccessibleBy(T) == false`.
      `IllegalStateException` - if the scope associated with `dstSegment` is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `dstSegment.scope().isAccessibleBy(T) == false`.
      `IndexOutOfBoundsException` - if `srcOffset + bytes > srcSegment.byteSize()` or if `dstOffset + bytes > dstSegment.byteSize()`, or if either `srcOffset`, `dstOffset` or `bytes` are `< 0`.
      `UnsupportedOperationException` - if the destination segment is read-only (see `isReadOnly()`).

  - ### copy

    static void copy(MemorySegmentPREVIEW srcSegment, ValueLayoutPREVIEW srcElementLayout, long srcOffset, MemorySegmentPREVIEW dstSegment, ValueLayoutPREVIEW dstElementLayout, long dstOffset, long elementCount)
    Performs a bulk copy from source segment to destination segment. More specifically, if `S` is the byte size of the element layouts, the bytes at offset `srcOffset` through `srcOffset + (elementCount * S) - 1` in the source segment are copied into the destination segment at offset `dstOffset` through `dstOffset + (elementCount * S) - 1`.

    The copy occurs in an element-wise fashion: the bytes in the source segment are interpreted as a sequence of elements whose layout is `srcElementLayout`, whereas the bytes in the destination segment are interpreted as a sequence of elements whose layout is `dstElementLayout`. Both element layouts must have same size `S`. If the byte order of the two element layouts differ, the bytes corresponding to each element to be copied are swapped accordingly during the copy operation.

    If the source segment overlaps with this segment, then the copying is performed as if the bytes at offset `srcOffset` through `srcOffset + (elementCount * S) - 1` in the source segment were first copied into a temporary segment with size `bytes`, and then the contents of the temporary segment were copied into the destination segment at offset `dstOffset` through `dstOffset + (elementCount * S) - 1`.

    The result of a bulk copy is unspecified if, in the uncommon case, the source segment and the destination segment do not overlap, but refer to overlapping regions of the same backing storage using different addresses. For example, this may occur if the same file is mapped to two segments.

    Parameters:
      `srcSegment` - the source segment.
      `srcElementLayout` - the element layout associated with the source segment.
      `srcOffset` - the starting offset, in bytes, of the source segment.
      `dstSegment` - the destination segment.
      `dstElementLayout` - the element layout associated with the destination segment.
      `dstOffset` - the starting offset, in bytes, of the destination segment.
      `elementCount` - the number of elements to be copied.
    Throws:
      `IllegalArgumentException` - if the element layouts have different sizes, if the source (resp. destination) segment/offset are incompatible with the alignment constraint in the source (resp. destination) element layout, or if the source (resp. destination) element layout alignment is greater than its size.
      `IllegalStateException` - if the scope associated with `srcSegment` is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `srcSegment().scope().isAccessibleBy(T) == false`.
      `IllegalStateException` - if the scope associated with `dstSegment` is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `dstSegment().scope().isAccessibleBy(T) == false`.
      `IndexOutOfBoundsException` - if `srcOffset + (elementCount * S) > srcSegment.byteSize()` or if `dstOffset + (elementCount * S) > dstSegment.byteSize()`, where `S` is the byte size of the element layouts, or if either `srcOffset`, `dstOffset` or `elementCount` are `< 0`.
      `UnsupportedOperationException` - if the destination segment is read-only (see `isReadOnly()`).

  - ### get

    default byte get(ValueLayout.OfBytePREVIEW layout, long offset)
    Reads a byte from this segment at the given offset, with the given layout.
    Parameters:
      `layout` - the layout of the region of memory to be read.
      `offset` - offset in bytes (relative to this segment address) at which this access operation will occur.
    Returns:
      a byte value read from this segment.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalArgumentException` - if the access operation is incompatible with the alignment constraint in the provided layout.
      `IndexOutOfBoundsException` - when the access operation falls outside the spatial bounds of the memory segment.

  - ### set

    default void set(ValueLayout.OfBytePREVIEW layout, long offset, byte value)
    Writes a byte into this segment at the given offset, with the given layout.
    Parameters:
      `layout` - the layout of the region of memory to be written.
      `offset` - offset in bytes (relative to this segment address) at which this access operation will occur.
      `value` - the byte value to be written.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalArgumentException` - if the access operation is incompatible with the alignment constraint in the provided layout.
      `IndexOutOfBoundsException` - when the access operation falls outside the spatial bounds of the memory segment.
      `UnsupportedOperationException` - if this segment is read-only.

  - ### get

    default boolean get(ValueLayout.OfBooleanPREVIEW layout, long offset)
    Reads a boolean from this segment at the given offset, with the given layout.
    Parameters:
      `layout` - the layout of the region of memory to be read.
      `offset` - offset in bytes (relative to this segment address) at which this access operation will occur.
    Returns:
      a boolean value read from this segment.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalArgumentException` - if the access operation is incompatible with the alignment constraint in the provided layout.
      `IndexOutOfBoundsException` - when the access operation falls outside the spatial bounds of the memory segment.

  - ### set

    default void set(ValueLayout.OfBooleanPREVIEW layout, long offset, boolean value)
    Writes a boolean into this segment at the given offset, with the given layout.
    Parameters:
      `layout` - the layout of the region of memory to be written.
      `offset` - offset in bytes (relative to this segment address) at which this access operation will occur.
      `value` - the boolean value to be written.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalArgumentException` - if the access operation is incompatible with the alignment constraint in the provided layout.
      `IndexOutOfBoundsException` - when the access operation falls outside the spatial bounds of the memory segment.
      `UnsupportedOperationException` - if this segment is read-only.

  - ### get

    default char get(ValueLayout.OfCharPREVIEW layout, long offset)
    Reads a char from this segment at the given offset, with the given layout.
    Parameters:
      `layout` - the layout of the region of memory to be read.
      `offset` - offset in bytes (relative to this segment address) at which this access operation will occur.
    Returns:
      a char value read from this segment.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalArgumentException` - if the access operation is incompatible with the alignment constraint in the provided layout.
      `IndexOutOfBoundsException` - when the access operation falls outside the spatial bounds of the memory segment.

  - ### set

    default void set(ValueLayout.OfCharPREVIEW layout, long offset, char value)
    Writes a char into this segment at the given offset, with the given layout.
    Parameters:
      `layout` - the layout of the region of memory to be written.
      `offset` - offset in bytes (relative to this segment address) at which this access operation will occur.
      `value` - the char value to be written.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalArgumentException` - if the access operation is incompatible with the alignment constraint in the provided layout.
      `IndexOutOfBoundsException` - when the access operation falls outside the spatial bounds of the memory segment.
      `UnsupportedOperationException` - if this segment is read-only.

  - ### get

    default short get(ValueLayout.OfShortPREVIEW layout, long offset)
    Reads a short from this segment at the given offset, with the given layout.
    Parameters:
      `layout` - the layout of the region of memory to be read.
      `offset` - offset in bytes (relative to this segment address) at which this access operation will occur.
    Returns:
      a short value read from this segment.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalArgumentException` - if the access operation is incompatible with the alignment constraint in the provided layout.
      `IndexOutOfBoundsException` - when the access operation falls outside the spatial bounds of the memory segment.

  - ### set

    default void set(ValueLayout.OfShortPREVIEW layout, long offset, short value)
    Writes a short into this segment at the given offset, with the given layout.
    Parameters:
      `layout` - the layout of the region of memory to be written.
      `offset` - offset in bytes (relative to this segment address) at which this access operation will occur.
      `value` - the short value to be written.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalArgumentException` - if the access operation is incompatible with the alignment constraint in the provided layout.
      `IndexOutOfBoundsException` - when the access operation falls outside the spatial bounds of the memory segment.
      `UnsupportedOperationException` - if this segment is read-only.

  - ### get

    default int get(ValueLayout.OfIntPREVIEW layout, long offset)
    Reads an int from this segment at the given offset, with the given layout.
    Parameters:
      `layout` - the layout of the region of memory to be read.
      `offset` - offset in bytes (relative to this segment address) at which this access operation will occur.
    Returns:
      an int value read from this segment.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalArgumentException` - if the access operation is incompatible with the alignment constraint in the provided layout.
      `IndexOutOfBoundsException` - when the access operation falls outside the spatial bounds of the memory segment.

  - ### set

    default void set(ValueLayout.OfIntPREVIEW layout, long offset, int value)
    Writes an int into this segment at the given offset, with the given layout.
    Parameters:
      `layout` - the layout of the region of memory to be written.
      `offset` - offset in bytes (relative to this segment address) at which this access operation will occur.
      `value` - the int value to be written.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalArgumentException` - if the access operation is incompatible with the alignment constraint in the provided layout.
      `IndexOutOfBoundsException` - when the access operation falls outside the spatial bounds of the memory segment.
      `UnsupportedOperationException` - if this segment is read-only.

  - ### get

    default float get(ValueLayout.OfFloatPREVIEW layout, long offset)
    Reads a float from this segment at the given offset, with the given layout.
    Parameters:
      `layout` - the layout of the region of memory to be read.
      `offset` - offset in bytes (relative to this segment address) at which this access operation will occur.
    Returns:
      a float value read from this segment.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalArgumentException` - if the access operation is incompatible with the alignment constraint in the provided layout.
      `IndexOutOfBoundsException` - when the access operation falls outside the spatial bounds of the memory segment.

  - ### set

    default void set(ValueLayout.OfFloatPREVIEW layout, long offset, float value)
    Writes a float into this segment at the given offset, with the given layout.
    Parameters:
      `layout` - the layout of the region of memory to be written.
      `offset` - offset in bytes (relative to this segment address) at which this access operation will occur.
      `value` - the float value to be written.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalArgumentException` - if the access operation is incompatible with the alignment constraint in the provided layout.
      `IndexOutOfBoundsException` - when the access operation falls outside the spatial bounds of the memory segment.
      `UnsupportedOperationException` - if this segment is read-only.

  - ### get

    default long get(ValueLayout.OfLongPREVIEW layout, long offset)
    Reads a long from this segment at the given offset, with the given layout.
    Parameters:
      `layout` - the layout of the region of memory to be read.
      `offset` - offset in bytes (relative to this segment address) at which this access operation will occur.
    Returns:
      a long value read from this segment.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalArgumentException` - if the access operation is incompatible with the alignment constraint in the provided layout.
      `IndexOutOfBoundsException` - when the access operation falls outside the spatial bounds of the memory segment.

  - ### set

    default void set(ValueLayout.OfLongPREVIEW layout, long offset, long value)
    Writes a long into this segment at the given offset, with the given layout.
    Parameters:
      `layout` - the layout of the region of memory to be written.
      `offset` - offset in bytes (relative to this segment address) at which this access operation will occur.
      `value` - the long value to be written.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalArgumentException` - if the access operation is incompatible with the alignment constraint in the provided layout.
      `IndexOutOfBoundsException` - when the access operation falls outside the spatial bounds of the memory segment.
      `UnsupportedOperationException` - if this segment is read-only.

  - ### get

    default double get(ValueLayout.OfDoublePREVIEW layout, long offset)
    Reads a double from this segment at the given offset, with the given layout.
    Parameters:
      `layout` - the layout of the region of memory to be read.
      `offset` - offset in bytes (relative to this segment address) at which this access operation will occur.
    Returns:
      a double value read from this segment.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalArgumentException` - if the access operation is incompatible with the alignment constraint in the provided layout.
      `IndexOutOfBoundsException` - when the access operation falls outside the spatial bounds of the memory segment.

  - ### set

    default void set(ValueLayout.OfDoublePREVIEW layout, long offset, double value)
    Writes a double into this segment at the given offset, with the given layout.
    Parameters:
      `layout` - the layout of the region of memory to be written.
      `offset` - offset in bytes (relative to this segment address) at which this access operation will occur.
      `value` - the double value to be written.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalArgumentException` - if the access operation is incompatible with the alignment constraint in the provided layout.
      `IndexOutOfBoundsException` - when the access operation falls outside the spatial bounds of the memory segment.
      `UnsupportedOperationException` - if this segment is read-only.

  - ### get

    default MemorySegmentPREVIEW get(ValueLayout.OfAddressPREVIEW layout, long offset)
    Reads an address from this segment at the given offset, with the given layout. The read address is wrapped in a native segment, associated with the global scopePREVIEW. Under normal conditions, the size of the returned segment is `0`. However, if the provided layout is an unboundedPREVIEW address layout, then the size of the returned segment is `Long.MAX_VALUE`.
    Parameters:
      `layout` - the layout of the region of memory to be read.
      `offset` - offset in bytes (relative to this segment address) at which this access operation will occur.
    Returns:
      a native segment wrapping an address read from this segment.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalArgumentException` - if the access operation is incompatible with the alignment constraint in the provided layout.
      `IndexOutOfBoundsException` - when the access operation falls outside the spatial bounds of the memory segment.

  - ### set

    default void set(ValueLayout.OfAddressPREVIEW layout, long offset, MemorySegmentPREVIEW value)
    Writes an address into this segment at the given offset, with the given layout.
    Parameters:
      `layout` - the layout of the region of memory to be written.
      `offset` - offset in bytes (relative to this segment address) at which this access operation will occur.
      `value` - the address value to be written.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalArgumentException` - if the access operation is incompatible with the alignment constraint in the provided layout.
      `IndexOutOfBoundsException` - when the access operation falls outside the spatial bounds of the memory segment.
      `UnsupportedOperationException` - if this segment is read-only.
      `UnsupportedOperationException` - if `value` is not a native segment.

  - ### getAtIndex

    default char getAtIndex(ValueLayout.OfCharPREVIEW layout, long index)
    Reads a char from this segment at the given index, scaled by the given layout size.
    Parameters:
      `layout` - the layout of the region of memory to be read.
      `index` - a logical index. The offset in bytes (relative to this segment address) at which the access operation will occur can be expressed as `(index * layout.byteSize())`.
    Returns:
      a char value read from this segment.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalArgumentException` - if the access operation is incompatible with the alignment constraint in the provided layout, or if the layout alignment is greater than its size.
      `IndexOutOfBoundsException` - when the access operation falls outside the spatial bounds of the memory segment.

  - ### setAtIndex

    default void setAtIndex(ValueLayout.OfCharPREVIEW layout, long index, char value)
    Writes a char into this segment at the given index, scaled by the given layout size.
    Parameters:
      `layout` - the layout of the region of memory to be written.
      `index` - a logical index. The offset in bytes (relative to this segment address) at which the access operation will occur can be expressed as `(index * layout.byteSize())`.
      `value` - the char value to be written.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalArgumentException` - if the access operation is incompatible with the alignment constraint in the provided layout, or if the layout alignment is greater than its size.
      `IndexOutOfBoundsException` - when the access operation falls outside the spatial bounds of the memory segment.
      `UnsupportedOperationException` - if this segment is read-only.

  - ### getAtIndex

    default short getAtIndex(ValueLayout.OfShortPREVIEW layout, long index)
    Reads a short from this segment at the given index, scaled by the given layout size.
    Parameters:
      `layout` - the layout of the region of memory to be read.
      `index` - a logical index. The offset in bytes (relative to this segment address) at which the access operation will occur can be expressed as `(index * layout.byteSize())`.
    Returns:
      a short value read from this segment.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalArgumentException` - if the access operation is incompatible with the alignment constraint in the provided layout, or if the layout alignment is greater than its size.
      `IndexOutOfBoundsException` - when the access operation falls outside the spatial bounds of the memory segment.

  - ### setAtIndex

    default void setAtIndex(ValueLayout.OfShortPREVIEW layout, long index, short value)
    Writes a short into this segment at the given index, scaled by the given layout size.
    Parameters:
      `layout` - the layout of the region of memory to be written.
      `index` - a logical index. The offset in bytes (relative to this segment address) at which the access operation will occur can be expressed as `(index * layout.byteSize())`.
      `value` - the short value to be written.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalArgumentException` - if the access operation is incompatible with the alignment constraint in the provided layout, or if the layout alignment is greater than its size.
      `IndexOutOfBoundsException` - when the access operation falls outside the spatial bounds of the memory segment.
      `UnsupportedOperationException` - if this segment is read-only.

  - ### getAtIndex

    default int getAtIndex(ValueLayout.OfIntPREVIEW layout, long index)
    Reads an int from this segment at the given index, scaled by the given layout size.
    Parameters:
      `layout` - the layout of the region of memory to be read.
      `index` - a logical index. The offset in bytes (relative to this segment address) at which the access operation will occur can be expressed as `(index * layout.byteSize())`.
    Returns:
      an int value read from this segment.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalArgumentException` - if the access operation is incompatible with the alignment constraint in the provided layout, or if the layout alignment is greater than its size.
      `IndexOutOfBoundsException` - when the access operation falls outside the spatial bounds of the memory segment.

  - ### setAtIndex

    default void setAtIndex(ValueLayout.OfIntPREVIEW layout, long index, int value)
    Writes an int into this segment at the given index, scaled by the given layout size.
    Parameters:
      `layout` - the layout of the region of memory to be written.
      `index` - a logical index. The offset in bytes (relative to this segment address) at which the access operation will occur can be expressed as `(index * layout.byteSize())`.
      `value` - the int value to be written.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalArgumentException` - if the access operation is incompatible with the alignment constraint in the provided layout, or if the layout alignment is greater than its size.
      `IndexOutOfBoundsException` - when the access operation falls outside the spatial bounds of the memory segment.
      `UnsupportedOperationException` - if this segment is read-only.

  - ### getAtIndex

    default float getAtIndex(ValueLayout.OfFloatPREVIEW layout, long index)
    Reads a float from this segment at the given index, scaled by the given layout size.
    Parameters:
      `layout` - the layout of the region of memory to be read.
      `index` - a logical index. The offset in bytes (relative to this segment address) at which the access operation will occur can be expressed as `(index * layout.byteSize())`.
    Returns:
      a float value read from this segment.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalArgumentException` - if the access operation is incompatible with the alignment constraint in the provided layout, or if the layout alignment is greater than its size.
      `IndexOutOfBoundsException` - when the access operation falls outside the spatial bounds of the memory segment.

  - ### setAtIndex

    default void setAtIndex(ValueLayout.OfFloatPREVIEW layout, long index, float value)
    Writes a float into this segment at the given index, scaled by the given layout size.
    Parameters:
      `layout` - the layout of the region of memory to be written.
      `index` - a logical index. The offset in bytes (relative to this segment address) at which the access operation will occur can be expressed as `(index * layout.byteSize())`.
      `value` - the float value to be written.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalArgumentException` - if the access operation is incompatible with the alignment constraint in the provided layout, or if the layout alignment is greater than its size.
      `IndexOutOfBoundsException` - when the access operation falls outside the spatial bounds of the memory segment.
      `UnsupportedOperationException` - if this segment is read-only.

  - ### getAtIndex

    default long getAtIndex(ValueLayout.OfLongPREVIEW layout, long index)
    Reads a long from this segment at the given index, scaled by the given layout size.
    Parameters:
      `layout` - the layout of the region of memory to be read.
      `index` - a logical index. The offset in bytes (relative to this segment address) at which the access operation will occur can be expressed as `(index * layout.byteSize())`.
    Returns:
      a long value read from this segment.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalArgumentException` - if the access operation is incompatible with the alignment constraint in the provided layout, or if the layout alignment is greater than its size.
      `IndexOutOfBoundsException` - when the access operation falls outside the spatial bounds of the memory segment.

  - ### setAtIndex

    default void setAtIndex(ValueLayout.OfLongPREVIEW layout, long index, long value)
    Writes a long into this segment at the given index, scaled by the given layout size.
    Parameters:
      `layout` - the layout of the region of memory to be written.
      `index` - a logical index. The offset in bytes (relative to this segment address) at which the access operation will occur can be expressed as `(index * layout.byteSize())`.
      `value` - the long value to be written.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalArgumentException` - if the access operation is incompatible with the alignment constraint in the provided layout, or if the layout alignment is greater than its size.
      `IndexOutOfBoundsException` - when the access operation falls outside the spatial bounds of the memory segment.
      `UnsupportedOperationException` - if this segment is read-only.

  - ### getAtIndex

    default double getAtIndex(ValueLayout.OfDoublePREVIEW layout, long index)
    Reads a double from this segment at the given index, scaled by the given layout size.
    Parameters:
      `layout` - the layout of the region of memory to be read.
      `index` - a logical index. The offset in bytes (relative to this segment address) at which the access operation will occur can be expressed as `(index * layout.byteSize())`.
    Returns:
      a double value read from this segment.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalArgumentException` - if the access operation is incompatible with the alignment constraint in the provided layout, or if the layout alignment is greater than its size.
      `IndexOutOfBoundsException` - when the access operation falls outside the spatial bounds of the memory segment.

  - ### setAtIndex

    default void setAtIndex(ValueLayout.OfDoublePREVIEW layout, long index, double value)
    Writes a double into this segment at the given index, scaled by the given layout size.
    Parameters:
      `layout` - the layout of the region of memory to be written.
      `index` - a logical index. The offset in bytes (relative to this segment address) at which the access operation will occur can be expressed as `(index * layout.byteSize())`.
      `value` - the double value to be written.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalArgumentException` - if the access operation is incompatible with the alignment constraint in the provided layout, or if the layout alignment is greater than its size.
      `IndexOutOfBoundsException` - when the access operation falls outside the spatial bounds of the memory segment.
      `UnsupportedOperationException` - if this segment is read-only.

  - ### getAtIndex

    default MemorySegmentPREVIEW getAtIndex(ValueLayout.OfAddressPREVIEW layout, long index)
    Reads an address from this segment at the given at the given index, scaled by the given layout size. The read address is wrapped in a native segment, associated with the global scopePREVIEW. Under normal conditions, the size of the returned segment is `0`. However, if the provided layout is an unboundedPREVIEW address layout, then the size of the returned segment is `Long.MAX_VALUE`.
    Parameters:
      `layout` - the layout of the region of memory to be read.
      `index` - a logical index. The offset in bytes (relative to this segment address) at which the access operation will occur can be expressed as `(index * layout.byteSize())`.
    Returns:
      a native segment wrapping an address read from this segment.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalArgumentException` - if the access operation is incompatible with the alignment constraint in the provided layout, or if the layout alignment is greater than its size.
      `IndexOutOfBoundsException` - when the access operation falls outside the spatial bounds of the memory segment.

  - ### setAtIndex

    default void setAtIndex(ValueLayout.OfAddressPREVIEW layout, long index, MemorySegmentPREVIEW value)
    Writes an address into this segment at the given index, scaled by the given layout size.
    Parameters:
      `layout` - the layout of the region of memory to be written.
      `index` - a logical index. The offset in bytes (relative to this segment address) at which the access operation will occur can be expressed as `(index * layout.byteSize())`.
      `value` - the address value to be written.
    Throws:
      `IllegalStateException` - if the scope associated with this segment is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `scope().isAccessibleBy(T) == false`.
      `IllegalArgumentException` - if the access operation is incompatible with the alignment constraint in the provided layout, or if the layout alignment is greater than its size.
      `IndexOutOfBoundsException` - when the access operation falls outside the spatial bounds of the memory segment.
      `UnsupportedOperationException` - if this segment is read-only.
      `UnsupportedOperationException` - if `value` is not a native segment.

  - ### equals

    boolean equals(Object that)
    Compares the specified object with this memory segment for equality. Returns `true` if and only if the specified object is also a memory segment, and if the two segments refer to the same location, in some region of memory. More specifically, for two segments `s1` and `s2` to be considered equals, all the following must be true:
    - `s1.array().equals(s2.array())`, that is, the two segments must be of the same kind; either both are native segments, backed by off-heap memory, or both are backed by the same on-heap Java array;
    - `s1.address() == s2.address()`, that is, the address of the two segments should be the same. This means that the two segments either refer to the same location in some off-heap region, or they refer to the same position inside their associated Java array instance.
    Overrides:
      `equals` in class `Object`
    API Note:
      This method does not perform a structural comparison of the contents of the two memory segments. Clients can compare memory segments structurally by using the `mismatch(MemorySegment)` method instead. Note that this method does not compare the temporal and spatial bounds of two segments. As such it is suitable to perform address checks, such as checking if a native segment has the `NULL` address.
    Parameters:
      `that` - the object to be compared for equality with this memory segment.
    Returns:
      `true` if the specified object is equal to this memory segment.
    See Also:
      - `mismatch(MemorySegment)`

  - ### hashCode

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

  - ### copy

    static void copy(MemorySegmentPREVIEW srcSegment, ValueLayoutPREVIEW srcLayout, long srcOffset, Object dstArray, int dstIndex, int elementCount)
    Copies a number of elements from a source memory segment to a destination array. The elements, whose size and alignment constraints are specified by the given layout, are read from the source segment, starting at the given offset (expressed in bytes), and are copied into the destination array, at the given index. Supported array types are `byte[]`, `char[]`, `short[]`, `int[]`, `float[]`, `long[]` and `double[]`.
    Parameters:
      `srcSegment` - the source segment.
      `srcLayout` - the source element layout. If the byte order associated with the layout is different from the native order, a byte swap operation will be performed on each array element.
      `srcOffset` - the starting offset, in bytes, of the source segment.
      `dstArray` - the destination array.
      `dstIndex` - the starting index of the destination array.
      `elementCount` - the number of array elements to be copied.
    Throws:
      `IllegalStateException` - if the scope associated with `srcSegment` is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `srcSegment().isAccessibleBy(T) == false`.
      `IllegalArgumentException` - if `dstArray` is not an array, or if it is an array but whose type is not supported, if the destination array component type does not match the carrier of the source element layout, if the source segment/offset are incompatible with the alignment constraint in the source element layout, or if the destination element layout alignment is greater than its size.

  - ### copy

    static void copy(Object srcArray, int srcIndex, MemorySegmentPREVIEW dstSegment, ValueLayoutPREVIEW dstLayout, long dstOffset, int elementCount)
    Copies a number of elements from a source array to a destination memory segment. The elements, whose size and alignment constraints are specified by the given layout, are read from the source array, starting at the given index, and are copied into the destination segment, at the given offset (expressed in bytes). Supported array types are `byte[]`, `char[]`, `short[]`, `int[]`, `float[]`, `long[]` and `double[]`.
    Parameters:
      `srcArray` - the source array.
      `srcIndex` - the starting index of the source array.
      `dstSegment` - the destination segment.
      `dstLayout` - the destination element layout. If the byte order associated with the layout is different from the native order, a byte swap operation will be performed on each array element.
      `dstOffset` - the starting offset, in bytes, of the destination segment.
      `elementCount` - the number of array elements to be copied.
    Throws:
      `IllegalStateException` - if the scope associated with `dstSegment` is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `dstSegment().isAccessibleBy(T) == false`.
      `IllegalArgumentException` - if `srcArray` is not an array, or if it is an array but whose type is not supported, if the source array component type does not match the carrier of the destination element layout, if the destination segment/offset are incompatible with the alignment constraint in the destination element layout, or if the destination element layout alignment is greater than its size.

  - ### mismatch

    static long mismatch(MemorySegmentPREVIEW srcSegment, long srcFromOffset, long srcToOffset, MemorySegmentPREVIEW dstSegment, long dstFromOffset, long dstToOffset)
    Finds and returns the relative offset, in bytes, of the first mismatch between the source and the destination segments. More specifically, the bytes at offset `srcFromOffset` through `srcToOffset - 1` in the source segment are compared against the bytes at offset `dstFromOffset` through `dstToOffset - 1` in the destination segment.

    If the two segments, over the specified ranges, share a common prefix then the returned offset is the length of the common prefix, and it follows that there is a mismatch between the two segments at that relative offset within the respective segments. If one segment is a proper prefix of the other, over the specified ranges, then the returned offset is the smallest range, and it follows that the relative offset is only valid for the segment with the larger range. Otherwise, there is no mismatch and `-1` is returned.

    Parameters:
      `srcSegment` - the source segment.
      `srcFromOffset` - the offset (inclusive) of the first byte in the source segment to be tested.
      `srcToOffset` - the offset (exclusive) of the last byte in the source segment to be tested.
      `dstSegment` - the destination segment.
      `dstFromOffset` - the offset (inclusive) of the first byte in the destination segment to be tested.
      `dstToOffset` - the offset (exclusive) of the last byte in the destination segment to be tested.
    Returns:
      the relative offset, in bytes, of the first mismatch between the source and destination segments, otherwise -1 if no mismatch.
    Throws:
      `IllegalStateException` - if the scope associated with `srcSegment` is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `srcSegment.scope().isAccessibleBy(T) == false`.
      `IllegalStateException` - if the scope associated with `dstSegment` is not alivePREVIEW.
      `WrongThreadException` - if this method is called from a thread `T`, such that `dstSegment.scope().isAccessibleBy(T) == false`.
      `IndexOutOfBoundsException` - if `srcFromOffset < 0`, `srcToOffset < srcFromOffset` or `srcToOffset > srcSegment.byteSize()`
      `IndexOutOfBoundsException` - if `dstFromOffset < 0`, `dstToOffset < dstFromOffset` or `dstToOffset > dstSegment.byteSize()`
    See Also:
      - `mismatch(MemorySegment)`
      - `Arrays.mismatch(Object[], int, int, Object[], int, int)`