+ * More complex layouts can be derived from simpler ones: a sequence layout denotes a repetition of one or more + * element layout (see {@link SequenceLayout}); a group layout denotes an aggregation of (typically) heterogeneous + * member layouts (see {@link GroupLayout}). + *
+ * All implementations of this interface must be value-based; + * use of identity-sensitive operations (including reference equality ({@code ==}), identity hash code, or synchronization) on + * instances of {@code MemoryLayout} may have unpredictable results and should be avoided. The {@code equals} method should + * be used for comparisons. + *
+ * Non-platform classes should not implement {@linkplain MemoryLayout} directly. + * + *
+ * Furthermore, all layouts feature a natural alignment which can be inferred as follows: + *
+ * All value layouts have an explicit byte order (see {@link java.nio.ByteOrder}) which is set when the layout is created. + * + *
+ * Layout paths are useful in order to e.g. to obtain offset of leaf elements inside arbitrarily nested layouts + * (see {@link MemoryLayout#offset(PathElement...)}), or to quickly obtain a memory access handle corresponding to the selected + * layout (see {@link MemoryLayout#varHandle(Class, PathElement...)}). + *
+ * Such layout paths can be constructed programmatically using the methods in this class. + * For instance, given a layout constructed as follows: + *
{@code
+SequenceLayout seq = MemoryLayout.ofSequence(5,
+ MemoryLayout.ofStruct(
+ MemoryLayout.ofPaddingBits(32),
+ MemoryLayout.ofValueBits(32, ByteOrder.BIG_ENDIAN).withName("value")
+));
+ * }value from seq, as follows:
+ * {@code
+long valueOffset = seq.offset(PathElement.sequenceElement(), PathElement.groupElement("value"));
+ * }+ * Non-platform classes should not implement {@linkplain PathElement} directly. + * + * @apiNote In the future, if the Java language permits, {@link PathElement} + * may become a {@code sealed} interface, which would prohibit subclassing except by + * explicitly permitted types. + * + * @implSpec + * Implementations of this interface are immutable and thread-safe. + */ + interface PathElement { + + /** + * Returns a path element which selects a member layout with given name from a given group layout. + * The path element returned by this method does not alter the number of free dimensions of any path + * that is combined with such element. + * + * @implSpec in case multiple group elements with a matching name exist, the path element returned by this + * method will select the first one; that is, the group element with lowest offset from current path is selected. + * + * @param name the name of the group element to be selected. + * @return a path element which selects the group element with given name. + * @throws NullPointerException if the specified group element name is {@code null}. + */ + static PathElement groupElement(String name) { + Objects.requireNonNull(name); + return new LayoutPath.PathElementImpl(path -> path.groupElement(name)); + } + + /** + * Returns a path element which selects the element layout at the specified position in a given the sequence layout. + * The path element returned by this method does not alter the number of free dimensions of any path + * that is combined with such element. + * + * @param index the index of the sequence element to be selected. + * @return a path element which selects the sequence element layout with given index. + * @throws IllegalArgumentException if {@code index < 0}. + */ + static PathElement sequenceElement(long index) { + if (index < 0) { + throw new IllegalArgumentException("Index must be positive: " + index); + } + return new LayoutPath.PathElementImpl(path -> path.sequenceElement(index)); + } + + /** + * Returns a path element which selects the element layout in a range of positions in a given the sequence layout, + * where the range is expressed as a pair of starting index (inclusive) {@code S} and step factor (which can also be negative) + * {@code F}. + * If a path with free dimensions {@code n} is combined with the path element returned by this method, + * the number of free dimensions of the resulting path will be {@code 1 + n}. If the free dimension associated + * with this path is bound by an index {@code I}, the resulting accessed offset can be obtained with the following + * formula: + *
{@code
+E * (S + I * F)
+ * }