# Interface ClassReader

All Superinterfaces:
  `ConstantPool, Iterable<PoolEntry>`

public sealed interface ClassReader extends ConstantPool
Advanced `class` file reading support for `AttributeMapper`s. Supports reading arbitrary offsets within a `class` file and reading data of various numeric types (e.g., `u2`, `u4`) in addition to constant pool access.

All numeric values in the `class` file format are big endian.

Unless otherwise specified, all out-of-bounds access result in an `IllegalArgumentException` to indicate the `class` file data is malformed. Since the `class` file data is arbitrary, users should sanity-check the structural integrity of the data before attempting to interpret the potentially malformed data.

Since:
  24
See Also:
  - `AttributeMapper.readAttribute(AttributedElement, ClassReader, int)`

## Method Summary

Modifier and Type
Method
Description
`int`
`classfileLength()`
Returns the length of the `class` file, in number of bytes.
`void`
`copyBytesTo(BufWriter buf, int offset, int len)`
Copy a range of bytes from the `class` file to a `BufWriter`.
`Function<Utf8Entry, AttributeMapper<?>>`
`customAttributes()`
Returns the table of custom attribute mappers.
`int`
`flags()`
Returns the access flags for the class, as a bit mask.
`byte[]`
`readBytes(int offset, int len)`
Returns a copy of the bytes at the specified range in the `class` file.
`double`
`readDouble(int offset)`
Returns the double value at the specified offset within the `class` file.
`PoolEntry`
`readEntry(int offset)`
Returns the constant pool entry whose index is given at the specified offset within the `class` file.
`<T extends PoolEntry>
T`
`readEntry(int offset, Class<T> cls)`
Returns the constant pool entry of a given type whose index is given at the specified offset within the `class` file.
`PoolEntry`
`readEntryOrNull(int offset)`
Returns the constant pool entry whose index is given at the specified offset within the `class` file, or `null` if the index at the specified offset is zero.
`<T extends PoolEntry>
T`
`readEntryOrNull(int offset, Class<T> cls)`
Returns the constant pool entry of a given type whose index is given at the specified offset within the `class` file, or `null` if the index at the specified offset is zero.
`float`
`readFloat(int offset)`
Returns the float value at the specified offset within the `class` file.
`int`
`readInt(int offset)`
Returns the signed int at the specified offset within the `class` file.
`long`
`readLong(int offset)`
Returns the signed long at the specified offset within the `class` file.
`int`
`readS1(int offset)`
Returns the signed byte at the specified offset within the `class` file.
`int`
`readS2(int offset)`
Returns the signed byte at the specified offset within the `class` file.
`int`
`readU1(int offset)`
Returns the unsigned byte at the specified offset within the `class` file.
`int`
`readU2(int offset)`
Returns the unsigned short at the specified offset within the `class` file.
`Optional<ClassEntry>`
`superclassEntry()`
Returns the constant pool entry describing the name of the superclass, if any.
`ClassEntry`
`thisClassEntry()`
Returns the constant pool entry describing the name of class.

### Methods declared in interface ConstantPool

`bootstrapMethodCount, bootstrapMethodEntry, entryByIndex, entryByIndex, iterator, size`

### Methods declared in interface Iterable

`forEach, spliterator`

## Method Details

### customAttributes

Function<Utf8Entry, AttributeMapper<?>> customAttributes()
Returns the table of custom attribute mappers. This is derived from the processing option `ClassFile.AttributeMapperOption`.

Returns:
  the table of custom attribute mappers

### flags

int flags()
Returns the access flags for the class, as a bit mask.

Returns:
  the access flags for the class, as a bit mask
See Also:
  - `ClassModel.flags()`

### thisClassEntry

ClassEntry thisClassEntry()
Returns the constant pool entry describing the name of class.

Returns:
  the constant pool entry describing the name of class
See Also:
  - `ClassModel.thisClass()`

### superclassEntry

Optional<ClassEntry> superclassEntry()
Returns the constant pool entry describing the name of the superclass, if any.

Returns:
  the constant pool entry describing the name of the superclass, if any
See Also:
  - `ClassModel.superclass()`

### classfileLength

int classfileLength()
Returns the length of the `class` file, in number of bytes.

Returns:
  the length of the `class` file, in number of bytes

### readEntry

PoolEntry readEntry(int offset)
Returns the constant pool entry whose index is given at the specified offset within the `class` file.

API Note:
  If only a particular type of entry is expected, use `readEntry(int, Class)`.
Parameters:
  `offset` - the offset of the index within the `class` file
Returns:
  the constant pool entry whose index is given at the specified offset within the `class` file
Throws:
  `ConstantPoolException` - if the index is out of range of the constant pool size, or zero

### readEntry

<T extends PoolEntry> T readEntry(int offset, Class<T> cls)
Returns the constant pool entry of a given type whose index is given at the specified offset within the `class` file.

Type Parameters:
  `T` - the entry type
Parameters:
  `offset` - the offset of the index within the `class` file
  `cls` - the entry type
Returns:
  the constant pool entry of a given type whose index is given at the specified offset within the `class` file
Throws:
  `ConstantPoolException` - if the index is out of range of the constant pool size, or zero, or the entry is not of the given type

### readEntryOrNull

PoolEntry readEntryOrNull(int offset)
Returns the constant pool entry whose index is given at the specified offset within the `class` file, or `null` if the index at the specified offset is zero.

API Note:
  If only a particular type of entry is expected, use `readEntryOrNull(int, Class)`.
Parameters:
  `offset` - the offset of the index within the `class` file
Returns:
  the constant pool entry whose index is given at the specified offset within the `class` file, or `null` if the index at the specified offset is zero
Throws:
  `ConstantPoolException` - if the index is out of range of the constant pool size

### readEntryOrNull

<T extends PoolEntry> T readEntryOrNull(int offset, Class<T> cls)
Returns the constant pool entry of a given type whose index is given at the specified offset within the `class` file, or `null` if the index at the specified offset is zero.

Type Parameters:
  `T` - the entry type
Parameters:
  `offset` - the offset of the index within the `class` file
  `cls` - the entry type
Returns:
  the constant pool entry of a given type whose index is given at the specified offset within the `class` file, or `null` if the index at the specified offset is zero
Throws:
  `ConstantPoolException` - if the index is out of range of the constant pool size, or zero, or the entry is not of the given type

### readU1

int readU1(int offset)
Returns the unsigned byte at the specified offset within the `class` file. Reads a byte and zero-extends it to an `int`.

Parameters:
  `offset` - the offset within the `class` file
Returns:
  the unsigned byte at the specified offset within the `class` file

### readU2

int readU2(int offset)
Returns the unsigned short at the specified offset within the `class` file. Reads a 2-byte value and zero-extends it to an `int`.

Parameters:
  `offset` - the offset within the `class` file
Returns:
  the unsigned short at the specified offset within the `class` file

### readS1

int readS1(int offset)
Returns the signed byte at the specified offset within the `class` file. Reads a byte and sign-extends it to an `int`.

Parameters:
  `offset` - the offset within the `class` file
Returns:
  the signed byte at the specified offset within the `class` file

### readS2

int readS2(int offset)
Returns the signed byte at the specified offset within the `class` file. Reads a 2-byte value and sign-extends it to an `int`.

Parameters:
  `offset` - the offset within the `class` file
Returns:
  the signed byte at the specified offset within the `class` file

### readInt

int readInt(int offset)
Returns the signed int at the specified offset within the `class` file. Reads 4 bytes of value.

Parameters:
  `offset` - the offset within the `class` file
Returns:
  the signed int at the specified offset within the `class` file

### readLong

long readLong(int offset)
Returns the signed long at the specified offset within the `class` file. Reads 8 bytes of value.

Parameters:
  `offset` - the offset within the `class` file
Returns:
  the signed long at the specified offset within the `class` file

### readFloat

float readFloat(int offset)
Returns the float value at the specified offset within the `class` file. Reads 4 bytes of value.

In the conversions, all NaN values of the `float` may or may not be collapsed into a single "canonical" NaN value.

Parameters:
  `offset` - the offset within the `class` file
Returns:
  the float value at the specified offset within the `class` file

### readDouble

double readDouble(int offset)
Returns the double value at the specified offset within the `class` file. Reads 8 bytes of value.

In the conversions, all NaN values of the `double` may or may not be collapsed into a single "canonical" NaN value.

Parameters:
  `offset` - the offset within the `class` file
Returns:
  the double value at the specified offset within the `class` file

### readBytes

byte[] readBytes(int offset, int len)
Returns a copy of the bytes at the specified range in the `class` file.

Parameters:
  `offset` - the offset within the `class` file
  `len` - the length of the range
Returns:
  a copy of the bytes at the specified range in the `class` file

### copyBytesTo

void copyBytesTo(BufWriter buf, int offset, int len)
Copy a range of bytes from the `class` file to a `BufWriter`.

Parameters:
  `buf` - the BufWriter
  `offset` - the offset within the `class` file
  `len` - the length of the range