# Interface BufWriter

public sealed interface BufWriter
Advanced `class` file writing support for `AttributeMapper`s. Supports writing portions of a `class` file to a growable buffer, such as writing various numerical types (e.g., `u2`, `u4`), to the end of the buffer, as well as to create constant pool entries.

All numeric values in the `class` file format are big endian. Writing larger numeric values to smaller numeric values are always done with truncation, that the least significant bytes are kept and the other bytes are silently dropped. As a result, numeric value writing methods can write both signed and unsigned values, and users should validate their values before writing if silent dropping of most significant bytes is not the intended behavior.

Since:
  24
See Also:
  - `AttributeMapper.writeAttribute(BufWriter, Attribute)`

## Method Summary

Modifier and Type
Method
Description
`boolean`
`canWriteDirect(ConstantPool other)`
Returns whether the provided constant pool is index-compatible with the constant pool of this buffer.
`ConstantPoolBuilder`
`constantPool()`
Returns the constant pool builder associated with this buffer.
`void`
`patchInt(int offset, int size, int value)`
Patches a previously written integer value.
`void`
`reserveSpace(int freeBytes)`
Ensures that the buffer has at least `freeBytes` bytes of free space in the end of the buffer.
`int`
`size()`
Returns the number of bytes that have been written to the buffer.
`void`
`writeBytes(byte[] arr)`
Writes the contents of a byte array to the buffer.
`void`
`writeBytes(byte[] arr, int start, int length)`
Writes a range of a byte array to the buffer.
`void`
`writeDouble(double x)`
Writes a double value, of 8 bytes, to the buffer.
`void`
`writeFloat(float x)`
Writes a float value, of 4 bytes, to the buffer.
`void`
`writeIndex(PoolEntry entry)`
Writes the index of the specified constant pool entry as a `u2`.
`void`
`writeIndexOrZero(PoolEntry entry)`
Writes the index of the specified constant pool entry, or the value `0` if the specified entry is `null`, as a `u2`.
`void`
`writeInt(int x)`
Writes 4 bytes, or an int, to the buffer.
`void`
`writeIntBytes(int intSize, long intValue)`
Writes a multibyte value to the buffer.
`void`
`writeLong(long x)`
Writes 8 bytes, or a long, to the buffer.
`void`
`writeU1(int x)`
Writes a byte to the buffer.
`void`
`writeU2(int x)`
Writes 2 bytes, or a short, to the buffer.

## Method Details

### constantPool

ConstantPoolBuilder constantPool()
Returns the constant pool builder associated with this buffer.

Returns:
  the constant pool builder associated with this buffer
See Also:
  - `ClassFileBuilder.constantPool()`

### canWriteDirect

boolean canWriteDirect(ConstantPool other)
Returns whether the provided constant pool is index-compatible with the constant pool of this buffer.

This is a shortcut for `constantPool().canWriteDirect(other)`.

Parameters:
  `other` - the other constant pool
Returns:
  whether the provided constant pool is index-compatible with the constant pool of this buffer
See Also:
  - `ConstantPoolBuilder.canWriteDirect(ConstantPool)`

### reserveSpace

void reserveSpace(int freeBytes)
Ensures that the buffer has at least `freeBytes` bytes of free space in the end of the buffer.

The writing result is the same without calls to this method, but the writing process may be slower.

API Note:
  This is a hint that changes no visible state of the buffer; it helps to reduce reallocation of the underlying storage by allocating sufficient space at once.
Parameters:
  `freeBytes` - the number of bytes to reserve

### writeU1

void writeU1(int x)
Writes a byte to the buffer. `x` is truncated to a byte and written.

Parameters:
  `x` - the value to truncate to a byte

### writeU2

void writeU2(int x)
Writes 2 bytes, or a short, to the buffer. `x` is truncated to two bytes and written.

Parameters:
  `x` - the value to truncate to a short

### writeInt

void writeInt(int x)
Writes 4 bytes, or an int, to the buffer.

Parameters:
  `x` - the int value

### writeFloat

void writeFloat(float x)
Writes a float value, of 4 bytes, to the buffer.

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

Parameters:
  `x` - the float value

### writeLong

void writeLong(long x)
Writes 8 bytes, or a long, to the buffer.

Parameters:
  `x` - the long value

### writeDouble

void writeDouble(double x)
Writes a double value, of 8 bytes, to the buffer.

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

Parameters:
  `x` - the double value

### writeBytes

void writeBytes(byte[] arr)
Writes the contents of a byte array to the buffer.

Parameters:
  `arr` - the byte array

### writeBytes

void writeBytes(byte[] arr, int start, int length)
Writes a range of a byte array to the buffer.

Parameters:
  `arr` - the byte array
  `start` - the start offset of the range within the byte array
  `length` - the length of the range
Throws:
  `IndexOutOfBoundsException` - if range is outside the array bounds

### patchInt

void patchInt(int offset, int size, int value)
Patches a previously written integer value. `value` is truncated to the given `size` number of bytes and written at the given `offset`. The end of this buffer stays unchanged.

API Note:
  The `offset` can be obtained by calling `size()` before writing the previous integer value.
Parameters:
  `offset` - the offset in this buffer at which to patch
  `size` - the size of the integer value being written, in bytes
  `value` - the integer value to be truncated
Throws:
  `IndexOutOfBoundsException` - if patched int is outside of bounds
See Also:
  - `size()`

### writeIntBytes

void writeIntBytes(int intSize, long intValue)
Writes a multibyte value to the buffer. `intValue` is truncated to the given `intSize` number of bytes and written.

Parameters:
  `intSize` - the size of the integer value being written, in bytes
  `intValue` - the value to be truncated

### writeIndex

void writeIndex(PoolEntry entry)
Writes the index of the specified constant pool entry as a `u2`. If the `entry` does not belong to the constant pool of this buffer, it will be converted, and the index of the converted pool entry is written instead.

Parameters:
  `entry` - the constant pool entry
Throws:
  `IllegalArgumentException` - if the entry has invalid index

### writeIndexOrZero

void writeIndexOrZero(PoolEntry entry)
Writes the index of the specified constant pool entry, or the value `0` if the specified entry is `null`, as a `u2`. If the `entry` does not belong to the constant pool of this buffer, it will be converted, and the index of the converted pool entry is written instead.

Parameters:
  `entry` - the constant pool entry, may be `null`
Throws:
  `IllegalArgumentException` - if the entry is not `null` and has invalid index

### size

int size()
Returns the number of bytes that have been written to the buffer.

Returns:
  the number of bytes that have been written to the buffer
See Also:
  - `patchInt(int, int, int)`