/*

* Copyright 2012 The Netty Project

*

* The Netty Project licenses this file to you under the Apache License,

* version 2.0 (the "License"); you may not use this file except in compliance

* with the License. You may obtain a copy of the License at:

*

* http://www.apache.org/licenses/LICENSE-2.0

*

* Unless required by applicable law or agreed to in writing, software

* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT

* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the

* License for the specific language governing permissions and limitations

* under the License.

*/

package io.netty.buffer;

import java.io.IOException;

import java.io.InputStream;

import java.io.OutputStream;

import java.nio.ByteBuffer;

import java.nio.ByteOrder;

import java.nio.channels.GatheringByteChannel;

import java.nio.channels.ScatteringByteChannel;

import java.nio.charset.Charset;

import java.nio.charset.UnsupportedCharsetException;

/**

* A random and sequential accessible sequence of zero or more bytes (octets).

* This interface provides an abstract view for one or more primitive byte

* arrays ({@code byte[]}) and {@linkplain ByteBuffer NIO buffers}.

*

* <h3>Creation of a buffer</h3>

*

* It is recommended to create a new buffer using the helper methods in

* {@link Unpooled} rather than calling an individual implementation's

* constructor.

*

* <h3>Random Access Indexing</h3>

*

* Just like an ordinary primitive byte array, {@link ByteBuf} uses

* <a href="http://en.wikipedia.org/wiki/Zero-based_numbering">zero-based indexing</a>.

* It means the index of the first byte is always {@code 0} and the index of the last byte is

* always {@link #capacity() capacity - 1}. For example, to iterate all bytes of a buffer, you

* can do the following, regardless of its internal implementation:

*

* <pre>

* {@link ByteBuf} buffer = ...;

* for (int i = 0; i &lt; buffer.capacity(); i ++) {

* byte b = buffer.getByte(i);

* System.out.println((char) b);

* }

* </pre>

*

* <h3>Sequential Access Indexing</h3>

*

* {@link ByteBuf} provides two pointer variables to support sequential

* read and write operations - {@link #readerIndex() readerIndex} for a read

* operation and {@link #writerIndex() writerIndex} for a write operation

* respectively. The following diagram shows how a buffer is segmented into

* three areas by the two pointers:

*

* <pre>

* +-------------------+------------------+------------------+

* | discardable bytes | readable bytes | writable bytes |

* | | (CONTENT) | |

* +-------------------+------------------+------------------+

* | | | |

* 0 <= readerIndex <= writerIndex <= capacity

* </pre>

*

* <h4>Readable bytes (the actual content)</h4>

*

* This segment is where the actual data is stored. Any operation whose name

* starts with {@code read} or {@code skip} will get or skip the data at the

* current {@link #readerIndex() readerIndex} and increase it by the number of

* read bytes. If the argument of the read operation is also a

* {@link ByteBuf} and no destination index is specified, the specified

* buffer's {@link #readerIndex() readerIndex} is increased together.

* <p>

* If there's not enough content left, {@link IndexOutOfBoundsException} is

* raised. The default value of newly allocated, wrapped or copied buffer's

* {@link #readerIndex() readerIndex} is {@code 0}.

*

* <pre>

* // Iterates the readable bytes of a buffer.

* {@link ByteBuf} buffer = ...;

* while (buffer.readable()) {

* System.out.println(buffer.readByte());

* }

* </pre>

*

* <h4>Writable bytes</h4>

*

* This segment is a undefined space which needs to be filled. Any operation

* whose name ends with {@code write} will write the data at the current

* {@link #writerIndex() writerIndex} and increase it by the number of written

* bytes. If the argument of the write operation is also a {@link ByteBuf},

* and no source index is specified, the specified buffer's

* {@link #readerIndex() readerIndex} is increased together.

* <p>

* If there's not enough writable bytes left, {@link IndexOutOfBoundsException}

* is raised. The default value of newly allocated buffer's

* {@link #writerIndex() writerIndex} is {@code 0}. The default value of

* wrapped or copied buffer's {@link #writerIndex() writerIndex} is the

* {@link #capacity() capacity} of the buffer.

*

* <pre>

* // Fills the writable bytes of a buffer with random integers.

* {@link ByteBuf} buffer = ...;

* while (buffer.writableBytes() >= 4) {

* buffer.writeInt(random.nextInt());

* }

* </pre>

*

* <h4>Discardable bytes</h4>

*

* This segment contains the bytes which were read already by a read operation.

* Initially, the size of this segment is {@code 0}, but its size increases up

* to the {@link #writerIndex() writerIndex} as read operations are executed.

* The read bytes can be discarded by calling {@link #discardReadBytes()} to

* reclaim unused area as depicted by the following diagram:

*

* <pre>

* BEFORE discardReadBytes()

*

* +-------------------+------------------+------------------+

* | discardable bytes | readable bytes | writable bytes |

* +-------------------+------------------+------------------+

* | | | |

* 0 <= readerIndex <= writerIndex <= capacity

*

*

* AFTER discardReadBytes()

*

* +------------------+--------------------------------------+

* | readable bytes | writable bytes (got more space) |

* +------------------+--------------------------------------+

* | | |

* readerIndex (0) <= writerIndex (decreased) <= capacity

* </pre>

*

* Please note that there is no guarantee about the content of writable bytes

* after calling {@link #discardReadBytes()}. The writable bytes will not be

* moved in most cases and could even be filled with completely different data

* depending on the underlying buffer implementation.

*

* <h4>Clearing the buffer indexes</h4>

*

* You can set both {@link #readerIndex() readerIndex} and

* {@link #writerIndex() writerIndex} to {@code 0} by calling {@link #clear()}.

* It does not clear the buffer content (e.g. filling with {@code 0}) but just

* clears the two pointers. Please also note that the semantic of this

* operation is different from {@link ByteBuffer#clear()}.

*

* <pre>

* BEFORE clear()

*

* +-------------------+------------------+------------------+

* | discardable bytes | readable bytes | writable bytes |

* +-------------------+------------------+------------------+

* | | | |

* 0 <= readerIndex <= writerIndex <= capacity

*

*

* AFTER clear()

*

* +---------------------------------------------------------+

* | writable bytes (got more space) |

* +---------------------------------------------------------+

* | |

* 0 = readerIndex = writerIndex <= capacity

* </pre>

*

* <h3>Search operations</h3>

*

* Various {@link #indexOf(int, int, byte)} methods help you locate an index of

* a value which meets a certain criteria. Complicated dynamic sequential

* search can be done with {@link ByteBufIndexFinder} as well as simple

* static single byte search.

* <p>

* If you are decoding variable length data such as NUL-terminated string, you

* will find {@link #bytesBefore(byte)} also useful.

*

* <h3>Mark and reset</h3>

*

* There are two marker indexes in every buffer. One is for storing

* {@link #readerIndex() readerIndex} and the other is for storing

* {@link #writerIndex() writerIndex}. You can always reposition one of the

* two indexes by calling a reset method. It works in a similar fashion to

* the mark and reset methods in {@link InputStream} except that there's no

* {@code readlimit}.

*

* <h3>Derived buffers</h3>

*

* You can create a view of an existing buffer by calling either

* {@link #duplicate()}, {@link #slice()} or {@link #slice(int, int)}.

* A derived buffer will have an independent {@link #readerIndex() readerIndex},

* {@link #writerIndex() writerIndex} and marker indexes, while it shares

* other internal data representation, just like a NIO buffer does.

* <p>

* In case a completely fresh copy of an existing buffer is required, please

* call {@link #copy()} method instead.

*

* <h3>Conversion to existing JDK types</h3>

*

* <h4>Byte array</h4>

*

* If a {@link ByteBuf} is backed by a byte array (i.e. {@code byte[]}),

* you can access it directly via the {@link #array()} method. To determine

* if a buffer is backed by a byte array, {@link #hasArray()} should be used.

*

* <h4>NIO Buffers</h4>

*

* If a {@link ByteBuf} can be converted into an NIO {@link ByteBuffer} which shares its

* content (i.e. view buffer), you can get it via the {@link #nioBuffer()} method. To determine

* if a buffer can be converted into an NIO buffer, use {@link #nioBuffer()}.

*

* <h4>Strings</h4>

*

* Various {@link #toString(Charset)} methods convert a {@link ByteBuf}

* into a {@link String}. Please note that {@link #toString()} is not a

* conversion method.

*

* <h4>I/O Streams</h4>

*

* Please refer to {@link ByteBufInputStream} and

* {@link ByteBufOutputStream}.

* @apiviz.landmark

*/

public interface ByteBuf extends ChannelBuf, Comparable<ByteBuf> {

/**

* Returns the factory which creates a {@link ByteBuf} whose

* type and default {@link ByteOrder} are same with this buffer.

*/

ByteBufFactory factory();

/**

* Returns the number of bytes (octets) this buffer can contain.

*/

int capacity();

/**

* Returns the <a href="http://en.wikipedia.org/wiki/Endianness">endianness</a>

* of this buffer.

*/

ByteOrder order();

/**

* Returns a buffer with the specified {@code endianness} which shares the whole region,

* indexes, and marks of this buffer. Modifying the content, the indexes, or the marks of the

* returned buffer or this buffer affects each other's content, indexes, and marks. If the

* specified {@code endianness} is identical to this buffer's byte order, this method can

* return {@code this}. This method does not modify {@code readerIndex} or {@code writerIndex}

* of this buffer.

*/

ByteBuf order(ByteOrder endianness);

/**

* Returns {@code true} if and only if this buffer is backed by an

* NIO direct buffer.

*/

boolean isDirect();

/**

* Returns the {@code readerIndex} of this buffer.

*/

int readerIndex();

/**

* Sets the {@code readerIndex} of this buffer.

*

* @throws IndexOutOfBoundsException

* if the specified {@code readerIndex} is

* less than {@code 0} or

* greater than {@code this.writerIndex}

*/

void readerIndex(int readerIndex);

/**

* Returns the {@code writerIndex} of this buffer.

*/

int writerIndex();

/**

* Sets the {@code writerIndex} of this buffer.

*

* @throws IndexOutOfBoundsException

* if the specified {@code writerIndex} is

* less than {@code this.readerIndex} or

* greater than {@code this.capacity}

*/

void writerIndex(int writerIndex);

/**

* Sets the {@code readerIndex} and {@code writerIndex} of this buffer

* in one shot. This method is useful when you have to worry about the

* invocation order of {@link #readerIndex(int)} and {@link #writerIndex(int)}

* methods. For example, the following code will fail:

*

* <pre>

* // Create a buffer whose readerIndex, writerIndex and capacity are

* // 0, 0 and 8 respectively.

* {@link ByteBuf} buf = {@link Unpooled}.buffer(8);

*

* // IndexOutOfBoundsException is thrown because the specified

* // readerIndex (2) cannot be greater than the current writerIndex (0).

* buf.readerIndex(2);

* buf.writerIndex(4);

* </pre>

*

* The following code will also fail:

*

* <pre>

* // Create a buffer whose readerIndex, writerIndex and capacity are

* // 0, 8 and 8 respectively.

* {@link ByteBuf} buf = {@link Unpooled}.wrappedBuffer(new byte[8]);

*

* // readerIndex becomes 8.

* buf.readLong();

*

* // IndexOutOfBoundsException is thrown because the specified

* // writerIndex (4) cannot be less than the current readerIndex (8).

* buf.writerIndex(4);

* buf.readerIndex(2);

* </pre>

*

* By contrast, {@link #setIndex(int, int)} guarantees that it never

* throws an {@link IndexOutOfBoundsException} as long as the specified

* indexes meet basic constraints, regardless what the current index

* values of the buffer are:

*

* <pre>

* // No matter what the current state of the buffer is, the following

* // call always succeeds as long as the capacity of the buffer is not

* // less than 4.

* buf.setIndex(2, 4);

* </pre>

*

* @throws IndexOutOfBoundsException

* if the specified {@code readerIndex} is less than 0,

* if the specified {@code writerIndex} is less than the specified

* {@code readerIndex} or if the specified {@code writerIndex} is

* greater than {@code this.capacity}

*/

void setIndex(int readerIndex, int writerIndex);

/**

* Returns the number of readable bytes which is equal to

* {@code (this.writerIndex - this.readerIndex)}.

*/

int readableBytes();

/**

* Returns the number of writable bytes which is equal to

* {@code (this.capacity - this.writerIndex)}.

*/

int writableBytes();

/**

* Returns {@code true}

* if and only if {@code (this.writerIndex - this.readerIndex)} is greater

* than {@code 0}.

*/

boolean readable();

/**

* Returns {@code true}

* if and only if {@code (this.capacity - this.writerIndex)} is greater

* than {@code 0}.

*/

boolean writable();

/**

* Sets the {@code readerIndex} and {@code writerIndex} of this buffer to

* {@code 0}.

* This method is identical to {@link #setIndex(int, int) setIndex(0, 0)}.

* <p>

* Please note that the behavior of this method is different

* from that of NIO buffer, which sets the {@code limit} to

* the {@code capacity} of the buffer.

*/

void clear();

/**

* Marks the current {@code readerIndex} in this buffer. You can

* reposition the current {@code readerIndex} to the marked

* {@code readerIndex} by calling {@link #resetReaderIndex()}.

* The initial value of the marked {@code readerIndex} is {@code 0}.

*/

void markReaderIndex();

/**

* Repositions the current {@code readerIndex} to the marked

* {@code readerIndex} in this buffer.

*

* @throws IndexOutOfBoundsException

* if the current {@code writerIndex} is less than the marked

* {@code readerIndex}

*/

void resetReaderIndex();

/**

* Marks the current {@code writerIndex} in this buffer. You can

* reposition the current {@code writerIndex} to the marked

* {@code writerIndex} by calling {@link #resetWriterIndex()}.

* The initial value of the marked {@code writerIndex} is {@code 0}.

*/

void markWriterIndex();

/**

* Repositions the current {@code writerIndex} to the marked

* {@code writerIndex} in this buffer.

*

* @throws IndexOutOfBoundsException

* if the current {@code readerIndex} is greater than the marked

* {@code writerIndex}

*/

void resetWriterIndex();

/**

* Discards the bytes between the 0th index and {@code readerIndex}.

* It moves the bytes between {@code readerIndex} and {@code writerIndex}

* to the 0th index, and sets {@code readerIndex} and {@code writerIndex}

* to {@code 0} and {@code oldWriterIndex - oldReaderIndex} respectively.

* <p>

* Please refer to the class documentation for more detailed explanation.

*/

void discardReadBytes();

/**

* Makes sure the number of {@linkplain #writableBytes() the writable bytes}

* is equal to or greater than the specified value. If there is enough

* writable bytes in this buffer, this method returns with no side effect.

* Otherwise:

* <ul>

* <li>a non-dynamic buffer will throw an {@link IndexOutOfBoundsException}.</li>

* <li>a dynamic buffer will expand its capacity so that the number of the

* {@link #writableBytes() writable bytes} becomes equal to or greater

* than the specified value. The expansion involves the reallocation of

* the internal buffer and consequently memory copy.</li>

* </ul>

*

* @param writableBytes

* the expected minimum number of writable bytes

* @throws IndexOutOfBoundsException

* if {@linkplain #writableBytes() the writable bytes} of this

* buffer is less than the specified value and if this buffer is

* not a dynamic buffer

*/

void ensureWritableBytes(int writableBytes);

/**

* Gets a boolean at the specified absolute (@code index) in this buffer.

* This method does not modify the {@code readerIndex} or {@code writerIndex}

* of this buffer.

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0} or

* {@code index + 1} is greater than {@code this.capacity}

*/

boolean getBoolean(int index);

/**

* Gets a byte at the specified absolute {@code index} in this buffer.

* This method does not modify {@code readerIndex} or {@code writerIndex} of

* this buffer.

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0} or

* {@code index + 1} is greater than {@code this.capacity}

*/

byte getByte(int index);

/**

* Gets an unsigned byte at the specified absolute {@code index} in this

* buffer. This method does not modify {@code readerIndex} or

* {@code writerIndex} of this buffer.

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0} or

* {@code index + 1} is greater than {@code this.capacity}

*/

short getUnsignedByte(int index);

/**

* Gets a 16-bit short integer at the specified absolute {@code index} in

* this buffer. This method does not modify {@code readerIndex} or

* {@code writerIndex} of this buffer.

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0} or

* {@code index + 2} is greater than {@code this.capacity}

*/

short getShort(int index);

/**

* Gets an unsigned 16-bit short integer at the specified absolute

* {@code index} in this buffer. This method does not modify

* {@code readerIndex} or {@code writerIndex} of this buffer.

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0} or

* {@code index + 2} is greater than {@code this.capacity}

*/

int getUnsignedShort(int index);

/**

* Gets a 24-bit medium integer at the specified absolute {@code index} in

* this buffer. This method does not modify {@code readerIndex} or

* {@code writerIndex} of this buffer.

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0} or

* {@code index + 3} is greater than {@code this.capacity}

*/

int getMedium(int index);

/**

* Gets an unsigned 24-bit medium integer at the specified absolute

* {@code index} in this buffer. This method does not modify

* {@code readerIndex} or {@code writerIndex} of this buffer.

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0} or

* {@code index + 3} is greater than {@code this.capacity}

*/

int getUnsignedMedium(int index);

/**

* Gets a 32-bit integer at the specified absolute {@code index} in

* this buffer. This method does not modify {@code readerIndex} or

* {@code writerIndex} of this buffer.

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0} or

* {@code index + 4} is greater than {@code this.capacity}

*/

int getInt(int index);

/**

* Gets an unsigned 32-bit integer at the specified absolute {@code index}

* in this buffer. This method does not modify {@code readerIndex} or

* {@code writerIndex} of this buffer.

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0} or

* {@code index + 4} is greater than {@code this.capacity}

*/

long getUnsignedInt(int index);

/**

* Gets a 64-bit long integer at the specified absolute {@code index} in

* this buffer. This method does not modify {@code readerIndex} or

* {@code writerIndex} of this buffer.

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0} or

* {@code index + 8} is greater than {@code this.capacity}

*/

long getLong(int index);

/**

* Gets a 2-byte UTF-16 character at the specified absolute

* {@code index} in this buffer. This method does not modify

* {@code readerIndex} or {@code writerIndex} of this buffer.

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0} or

* {@code index + 2} is greater than {@code this.capacity}

*/

char getChar(int index);

/**

* Gets a 32-bit floating point number at the specified absolute

* {@code index} in this buffer. This method does not modify

* {@code readerIndex} or {@code writerIndex} of this buffer.

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0} or

* {@code index + 4} is greater than {@code this.capacity}

*/

float getFloat(int index);

/**

* Gets a 64-bit floating point number at the specified absolute

* {@code index} in this buffer. This method does not modify

* {@code readerIndex} or {@code writerIndex} of this buffer.

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0} or

* {@code index + 8} is greater than {@code this.capacity}

*/

double getDouble(int index);

/**

* Transfers this buffer's data to the specified destination starting at

* the specified absolute {@code index} until the destination becomes

* non-writable. This method is basically same with

* {@link #getBytes(int, ByteBuf, int, int)}, except that this

* method increases the {@code writerIndex} of the destination by the

* number of the transferred bytes while

* {@link #getBytes(int, ByteBuf, int, int)} does not.

* This method does not modify {@code readerIndex} or {@code writerIndex} of

* the source buffer (i.e. {@code this}).

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0} or

* if {@code index + dst.writableBytes} is greater than

* {@code this.capacity}

*/

void getBytes(int index, ByteBuf dst);

/**

* Transfers this buffer's data to the specified destination starting at

* the specified absolute {@code index}. This method is basically same

* with {@link #getBytes(int, ByteBuf, int, int)}, except that this

* method increases the {@code writerIndex} of the destination by the

* number of the transferred bytes while

* {@link #getBytes(int, ByteBuf, int, int)} does not.

* This method does not modify {@code readerIndex} or {@code writerIndex} of

* the source buffer (i.e. {@code this}).

*

* @param length the number of bytes to transfer

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0},

* if {@code index + length} is greater than

* {@code this.capacity}, or

* if {@code length} is greater than {@code dst.writableBytes}

*/

void getBytes(int index, ByteBuf dst, int length);

/**

* Transfers this buffer's data to the specified destination starting at

* the specified absolute {@code index}.

* This method does not modify {@code readerIndex} or {@code writerIndex}

* of both the source (i.e. {@code this}) and the destination.

*

* @param dstIndex the first index of the destination

* @param length the number of bytes to transfer

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0},

* if the specified {@code dstIndex} is less than {@code 0},

* if {@code index + length} is greater than

* {@code this.capacity}, or

* if {@code dstIndex + length} is greater than

* {@code dst.capacity}

*/

void getBytes(int index, ByteBuf dst, int dstIndex, int length);

/**

* Transfers this buffer's data to the specified destination starting at

* the specified absolute {@code index}.

* This method does not modify {@code readerIndex} or {@code writerIndex} of

* this buffer

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0} or

* if {@code index + dst.length} is greater than

* {@code this.capacity}

*/

void getBytes(int index, byte[] dst);

/**

* Transfers this buffer's data to the specified destination starting at

* the specified absolute {@code index}.

* This method does not modify {@code readerIndex} or {@code writerIndex}

* of this buffer.

*

* @param dstIndex the first index of the destination

* @param length the number of bytes to transfer

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0},

* if the specified {@code dstIndex} is less than {@code 0},

* if {@code index + length} is greater than

* {@code this.capacity}, or

* if {@code dstIndex + length} is greater than

* {@code dst.length}

*/

void getBytes(int index, byte[] dst, int dstIndex, int length);

/**

* Transfers this buffer's data to the specified destination starting at

* the specified absolute {@code index} until the destination's position

* reaches its limit.

* This method does not modify {@code readerIndex} or {@code writerIndex} of

* this buffer while the destination's {@code position} will be increased.

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0} or

* if {@code index + dst.remaining()} is greater than

* {@code this.capacity}

*/

void getBytes(int index, ByteBuffer dst);

/**

* Transfers this buffer's data to the specified stream starting at the

* specified absolute {@code index}.

* This method does not modify {@code readerIndex} or {@code writerIndex} of

* this buffer.

*

* @param length the number of bytes to transfer

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0} or

* if {@code index + length} is greater than

* {@code this.capacity}

* @throws IOException

* if the specified stream threw an exception during I/O

*/

void getBytes(int index, OutputStream out, int length) throws IOException;

/**

* Transfers this buffer's data to the specified channel starting at the

* specified absolute {@code index}.

* This method does not modify {@code readerIndex} or {@code writerIndex} of

* this buffer.

*

* @param length the maximum number of bytes to transfer

*

* @return the actual number of bytes written out to the specified channel

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0} or

* if {@code index + length} is greater than

* {@code this.capacity}

* @throws IOException

* if the specified channel threw an exception during I/O

*/

int getBytes(int index, GatheringByteChannel out, int length) throws IOException;

/**

* Sets the specified boolean at the specified absolute {@code index} in this

* buffer.

* This method does not modify {@code readerIndex} or {@code writerIndex} of

* this buffer.

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0} or

* {@code index + 1} is greater than {@code this.capacity}

*/

void setBoolean(int index, boolean value);

/**

* Sets the specified byte at the specified absolute {@code index} in this

* buffer. The 24 high-order bits of the specified value are ignored.

* This method does not modify {@code readerIndex} or {@code writerIndex} of

* this buffer.

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0} or

* {@code index + 1} is greater than {@code this.capacity}

*/

void setByte(int index, int value);

/**

* Sets the specified 16-bit short integer at the specified absolute

* {@code index} in this buffer. The 16 high-order bits of the specified

* value are ignored.

* This method does not modify {@code readerIndex} or {@code writerIndex} of

* this buffer.

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0} or

* {@code index + 2} is greater than {@code this.capacity}

*/

void setShort(int index, int value);

/**

* Sets the specified 24-bit medium integer at the specified absolute

* {@code index} in this buffer. Please note that the most significant

* byte is ignored in the specified value.

* This method does not modify {@code readerIndex} or {@code writerIndex} of

* this buffer.

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0} or

* {@code index + 3} is greater than {@code this.capacity}

*/

void setMedium(int index, int value);

/**

* Sets the specified 32-bit integer at the specified absolute

* {@code index} in this buffer.

* This method does not modify {@code readerIndex} or {@code writerIndex} of

* this buffer.

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0} or

* {@code index + 4} is greater than {@code this.capacity}

*/

void setInt(int index, int value);

/**

* Sets the specified 64-bit long integer at the specified absolute

* {@code index} in this buffer.

* This method does not modify {@code readerIndex} or {@code writerIndex} of

* this buffer.

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0} or

* {@code index + 8} is greater than {@code this.capacity}

*/

void setLong(int index, long value);

/**

* Sets the specified 2-byte UTF-16 character at the specified absolute

* {@code index} in this buffer.

* The 16 high-order bits of the specified value are ignored.

* This method does not modify {@code readerIndex} or {@code writerIndex} of

* this buffer.

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0} or

* {@code index + 2} is greater than {@code this.capacity}

*/

void setChar(int index, int value);

/**

* Sets the specified 32-bit floating-point number at the specified

* absolute {@code index} in this buffer.

* This method does not modify {@code readerIndex} or {@code writerIndex} of

* this buffer.

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0} or

* {@code index + 4} is greater than {@code this.capacity}

*/

void setFloat(int index, float value);

/**

* Sets the specified 64-bit floating-point number at the specified

* absolute {@code index} in this buffer.

* This method does not modify {@code readerIndex} or {@code writerIndex} of

* this buffer.

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0} or

* {@code index + 8} is greater than {@code this.capacity}

*/

void setDouble(int index, double value);

/**

* Transfers the specified source buffer's data to this buffer starting at

* the specified absolute {@code index} until the source buffer becomes

* unreadable. This method is basically same with

* {@link #setBytes(int, ByteBuf, int, int)}, except that this

* method increases the {@code readerIndex} of the source buffer by

* the number of the transferred bytes while

* {@link #setBytes(int, ByteBuf, int, int)} does not.

* This method does not modify {@code readerIndex} or {@code writerIndex} of

* the source buffer (i.e. {@code this}).

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0} or

* if {@code index + src.readableBytes} is greater than

* {@code this.capacity}

*/

void setBytes(int index, ByteBuf src);

/**

* Transfers the specified source buffer's data to this buffer starting at

* the specified absolute {@code index}. This method is basically same

* with {@link #setBytes(int, ByteBuf, int, int)}, except that this

* method increases the {@code readerIndex} of the source buffer by

* the number of the transferred bytes while

* {@link #setBytes(int, ByteBuf, int, int)} does not.

* This method does not modify {@code readerIndex} or {@code writerIndex} of

* the source buffer (i.e. {@code this}).

*

* @param length the number of bytes to transfer

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0},

* if {@code index + length} is greater than

* {@code this.capacity}, or

* if {@code length} is greater than {@code src.readableBytes}

*/

void setBytes(int index, ByteBuf src, int length);

/**

* Transfers the specified source buffer's data to this buffer starting at

* the specified absolute {@code index}.

* This method does not modify {@code readerIndex} or {@code writerIndex}

* of both the source (i.e. {@code this}) and the destination.

*

* @param srcIndex the first index of the source

* @param length the number of bytes to transfer

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0},

* if the specified {@code srcIndex} is less than {@code 0},

* if {@code index + length} is greater than

* {@code this.capacity}, or

* if {@code srcIndex + length} is greater than

* {@code src.capacity}

*/

void setBytes(int index, ByteBuf src, int srcIndex, int length);

/**

* Transfers the specified source array's data to this buffer starting at

* the specified absolute {@code index}.

* This method does not modify {@code readerIndex} or {@code writerIndex} of

* this buffer.

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0} or

* if {@code index + src.length} is greater than

* {@code this.capacity}

*/

void setBytes(int index, byte[] src);

/**

* Transfers the specified source array's data to this buffer starting at

* the specified absolute {@code index}.

* This method does not modify {@code readerIndex} or {@code writerIndex} of

* this buffer.

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0},

* if the specified {@code srcIndex} is less than {@code 0},

* if {@code index + length} is greater than

* {@code this.capacity}, or

* if {@code srcIndex + length} is greater than {@code src.length}

*/

void setBytes(int index, byte[] src, int srcIndex, int length);

/**

* Transfers the specified source buffer's data to this buffer starting at

* the specified absolute {@code index} until the source buffer's position

* reaches its limit.

* This method does not modify {@code readerIndex} or {@code writerIndex} of

* this buffer.

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0} or

* if {@code index + src.remaining()} is greater than

* {@code this.capacity}

*/

void setBytes(int index, ByteBuffer src);

/**

* Transfers the content of the specified source stream to this buffer

* starting at the specified absolute {@code index}.

* This method does not modify {@code readerIndex} or {@code writerIndex} of

* this buffer.

*

* @param length the number of bytes to transfer

*

* @return the actual number of bytes read in from the specified channel.

* {@code -1} if the specified channel is closed.

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0} or

* if {@code index + length} is greater than {@code this.capacity}

* @throws IOException

* if the specified stream threw an exception during I/O

*/

int setBytes(int index, InputStream in, int length) throws IOException;

/**

* Transfers the content of the specified source channel to this buffer

* starting at the specified absolute {@code index}.

* This method does not modify {@code readerIndex} or {@code writerIndex} of

* this buffer.

*

* @param length the maximum number of bytes to transfer

*

* @return the actual number of bytes read in from the specified channel.

* {@code -1} if the specified channel is closed.

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0} or

* if {@code index + length} is greater than {@code this.capacity}

* @throws IOException

* if the specified channel threw an exception during I/O

*/

int setBytes(int index, ScatteringByteChannel in, int length) throws IOException;

/**

* Fills this buffer with <tt>NUL (0x00)</tt> starting at the specified

* absolute {@code index}.

* This method does not modify {@code readerIndex} or {@code writerIndex} of

* this buffer.

*

* @param length the number of <tt>NUL</tt>s to write to the buffer

*

* @throws IndexOutOfBoundsException

* if the specified {@code index} is less than {@code 0} or

* if {@code index + length} is greater than {@code this.capacity}

*/

void setZero(int index, int length);

/**

* Gets a boolean at the current {@code readerIndex} and increases

* the {@code readerIndex} by {@code 1} in this buffer.