/*
 * Copyright 2017-2020 original authors
 *
 * Licensed 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
 *
 * https://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.micronaut.core.io.buffer;

import java.io.InputStream;
import java.io.OutputStream;
import java.nio.charset.Charset;

Interface to allow interfacing with different byte buffer implementations, primarily as an abstraction over Netty.
Author:
Graeme Rocher
Type parameters:
<T> – buffer type
Since:
1.0/**
 * Interface to allow interfacing with different byte buffer implementations, primarily as an abstraction over Netty.
 *
 * @param <T> buffer type
 * @author Graeme Rocher
 * @since 1.0
 */
public interface ByteBuffer<T> {

    
Returns:
The native buffer type/**
     * @return The native buffer type
     */
    T asNativeBuffer();

    
Returns the number of readable bytes which is equal to (this.writerIndex - this.readerIndex). 
Returns:
bytes/**
     * Returns the number of readable bytes which is equal to
     * {@code (this.writerIndex - this.readerIndex)}.
     * @return bytes
     */
    int readableBytes();

    
Returns the number of writable bytes which is equal to (this.capacity - this.writerIndex). 
Returns:
The bytes/**
     * Returns the number of writable bytes which is equal to
     * {@code (this.capacity - this.writerIndex)}.
     * @return The bytes
     */
    int writableBytes();

    
Returns the maximum allowed capacity of this buffer. If a user attempts to increase the capacity of this buffer beyond the maximum capacity using capacity(int) or IllegalArgumentException. 
Returns:
The max capacity/**
     * Returns the maximum allowed capacity of this buffer.  If a user attempts to increase the
     * capacity of this buffer beyond the maximum capacity using {@link #capacity(int)} or
     * {@link IllegalArgumentException}.
     * @return The max capacity
     */
    int maxCapacity();

    
Adjusts the capacity of this buffer. If the newCapacity is less than the current capacity, the content of this buffer is truncated. If the newCapacity is greater than the current capacity, the buffer is appended with unspecified data whose length is (newCapacity - currentCapacity). 
Params:
capacity – capacity
Returns:
The bytebuffer/**
     * Adjusts the capacity of this buffer.  If the {@code newCapacity} is less than the current
     * capacity, the content of this buffer is truncated.  If the {@code newCapacity} is greater
     * than the current capacity, the buffer is appended with unspecified data whose length is
     * {@code (newCapacity - currentCapacity)}.
     * @param capacity capacity
     * @return The bytebuffer
     */
    ByteBuffer capacity(int capacity);

    
Returns the readerIndex of this buffer. 
Returns:
The index/**
     * Returns the {@code readerIndex} of this buffer.
     * @return The index
     */
    int readerIndex();

    
Sets the readerIndex of this buffer. 
Params:
readPosition – readPosition
Throws:
IndexOutOfBoundsException – if the specified readerIndex is less than 0 or greater than this.writerIndex
Returns:
The buffer/**
     * Sets the {@code readerIndex} of this buffer.
     * @param readPosition readPosition
     * @return The buffer
     * @throws IndexOutOfBoundsException if the specified {@code readerIndex} is
     *                                   less than {@code 0} or
     *                                   greater than {@code this.writerIndex}
     */
    ByteBuffer readerIndex(int readPosition);

    
Returns the writerIndex of this buffer. 
Returns:
The index/**
     * Returns the {@code writerIndex} of this buffer.
     * @return The index
     */
    int writerIndex();

    
Sets the writerIndex of this buffer. 
Params:
position – The position
Throws:
IndexOutOfBoundsException – if the specified writerIndex is less than this.readerIndex or greater than this.capacity
Returns:
The index as buffer/**
     * Sets the {@code writerIndex} of this buffer.
     *
     * @param position The position
     * @throws IndexOutOfBoundsException if the specified {@code writerIndex} is
     *                                   less than {@code this.readerIndex} or
     *                                   greater than {@code this.capacity}
     * @return The index as buffer
     */
    ByteBuffer writerIndex(int position);

    
Gets a byte at the current readerIndex and increases the readerIndex by 1 in this buffer. 
Throws:
IndexOutOfBoundsException – if this.readableBytes is less than 1
Returns:
bytes/**
     * Gets a byte at the current {@code readerIndex} and increases
     * the {@code readerIndex} by {@code 1} in this buffer.
     * @return bytes
     * @throws IndexOutOfBoundsException if {@code this.readableBytes} is less than {@code 1}
     */
    byte read();

    
Gets a CharSequence with the given length at the current readerIndex and increases the readerIndex by the given length. 
Params:
length –  the length to read
charset – that should be used
Throws:
IndexOutOfBoundsException – if length is greater than this.readableBytes
Returns:
the sequence/**
     * Gets a {@link CharSequence} with the given length at the current {@code readerIndex}
     * and increases the {@code readerIndex} by the given length.
     *
     * @param length  the length to read
     * @param charset that should be used
     * @return the sequence
     * @throws IndexOutOfBoundsException if {@code length} is greater than {@code this.readableBytes}
     */
    CharSequence readCharSequence(int length, Charset charset);

    
Transfers this buffer's data to the specified destination starting at the current readerIndex and increases the readerIndex by the number of the transferred bytes (= dst.length). 
Params:
destination – destination
Throws:
IndexOutOfBoundsException – if dst.length is greater than this.readableBytes
Returns:
bytesBuffer/**
     * Transfers this buffer's data to the specified destination starting at
     * the current {@code readerIndex} and increases the {@code readerIndex}
     * by the number of the transferred bytes (= {@code dst.length}).
     * @param destination destination
     * @return bytesBuffer
     * @throws IndexOutOfBoundsException if {@code dst.length} is greater than {@code this.readableBytes}
     */
    ByteBuffer read(byte[] destination);

    
Transfers this buffer's data to the specified destination starting at the current readerIndex and increases the readerIndex by the number of the transferred bytes (= length). 
Params:
destination – The destination byte array
offset –      the first index of the destination
length –      the number of bytes to transfer
Throws:
IndexOutOfBoundsException – if the specified dstIndex is less than 0, if length is greater than this.readableBytes, or if dstIndex + length is greater than dst.length
Returns:
bytesBuffer/**
     * Transfers this buffer's data to the specified destination starting at
     * the current {@code readerIndex} and increases the {@code readerIndex}
     * by the number of the transferred bytes (= {@code length}).
     *
     * @param destination The destination byte array
     * @param offset      the first index of the destination
     * @param length      the number of bytes to transfer
     * @return bytesBuffer
     * @throws IndexOutOfBoundsException if the specified {@code dstIndex} is less than {@code 0},
     *                                   if {@code length} is greater than {@code this.readableBytes}, or
     *                                   if {@code dstIndex + length} is greater than {@code dst.length}
     */
    ByteBuffer read(byte[] destination, int offset, int length);

    
Sets the specified byte at the current writerIndex and increases the writerIndex by 1 in this buffer. The 24 high-order bits of the specified value are ignored. 
Params:
b – The byte to write
Throws:
IndexOutOfBoundsException – if this.writableBytes is less than 1
Returns:
bytesBuffer/**
     * Sets the specified byte at the current {@code writerIndex}
     * and increases the {@code writerIndex} by {@code 1} in this buffer.
     * The 24 high-order bits of the specified value are ignored.
     * @return bytesBuffer
     * @param b The byte to write
     * @throws IndexOutOfBoundsException if {@code this.writableBytes} is less than {@code 1}
     */
    ByteBuffer write(byte b);

    
Transfers the specified source array's data to this buffer starting at the current writerIndex and increases the writerIndex by the number of the transferred bytes (= src.length). 
Params:
source – The source bytes
Throws:
IndexOutOfBoundsException – if src.length is greater than this.writableBytes
Returns:
bytesBuffer/**
     * Transfers the specified source array's data to this buffer starting at
     * the current {@code writerIndex} and increases the {@code writerIndex}
     * by the number of the transferred bytes (= {@code src.length}).
     *
     * @param source The source bytes
     * @return bytesBuffer
     * @throws IndexOutOfBoundsException if {@code src.length} is greater than {@code this.writableBytes}
     */
    ByteBuffer write(byte[] source);

    
Transfers the specified source CharSequence's data to this buffer starting at the current writerIndex and increases the writerIndex by the number of the transferred bytes (= src.length). 
Params:
source –  The char sequence
charset – The charset
Returns:
This buffer/**
     * Transfers the specified source CharSequence's data to this buffer starting at
     * the current {@code writerIndex} and increases the {@code writerIndex}
     * by the number of the transferred bytes (= {@code src.length}).
     *
     * @param source  The char sequence
     * @param charset The charset
     * @return This buffer
     */
    ByteBuffer write(CharSequence source, Charset charset);

    
Transfers the specified source array's data to this buffer starting at the current writerIndex and increases the writerIndex by the number of the transferred bytes (= length). 
Params:
source – The source byte array
offset – the first index of the source
length – the number of bytes to transfer
Throws:
IndexOutOfBoundsException – if the specified srcIndex is less than 0, if srcIndex + length is greater than src.length, or if length is greater than this.writableBytes
Returns:
bytesBuffer/**
     * Transfers the specified source array's data to this buffer starting at
     * the current {@code writerIndex} and increases the {@code writerIndex}
     * by the number of the transferred bytes (= {@code length}).
     *
     * @param source The source byte array
     * @param offset the first index of the source
     * @param length the number of bytes to transfer
     * @return bytesBuffer
     * @throws IndexOutOfBoundsException if the specified {@code srcIndex} is less than {@code 0},
     *                                   if {@code srcIndex + length} is greater than
     *                                   {@code src.length}, or
     *                                   if {@code length} is greater than {@code this.writableBytes}
     */
    ByteBuffer write(byte[] source, int offset, int length);

    
Write the given ByteBuffer instances to this buffer. 
Params:
buffers – The buffers to write
Returns:
this buffer/**
     * Write the given {@link ByteBuffer} instances to this buffer.
     *
     * @param buffers The buffers to write
     * @return this buffer
     */
    ByteBuffer write(ByteBuffer... buffers);

    
Write the given ByteBuffer instances to this buffer. 
Params:
buffers – The buffers to write
Returns:
this buffer/**
     * Write the given {@link java.nio.ByteBuffer} instances to this buffer.
     *
     * @param buffers The buffers to write
     * @return this buffer
     */
    ByteBuffer write(java.nio.ByteBuffer... buffers);

    
Create a new ByteBuffer whose contents is a shared subsequence of this data buffer's content. Data between this byte buffer and the returned buffer is shared; though changes in the returned buffer's position will not be reflected in the reading nor writing position of this data buffer. 
Params:
index –  the index at which to start the slice
length – the length of the slice
Returns:
the specified slice of this data buffer/**
     * Create a new {@code ByteBuffer} whose contents is a shared subsequence of this
     * data buffer's content.  Data between this byte buffer and the returned buffer is
     * shared; though changes in the returned buffer's position will not be reflected
     * in the reading nor writing position of this data buffer.
     *
     * @param index  the index at which to start the slice
     * @param length the length of the slice
     * @return the specified slice of this data buffer
     */
    ByteBuffer slice(int index, int length);

    
Exposes this buffer's readable bytes as an NIO ByteBuffer. The returned buffer shares the content with this buffer, while changing the position and limit of the returned NIO buffer does not affect the indexes and marks of this buffer. This method is identical to buf.nioBuffer(buf.readerIndex(), buf.readableBytes()). This method does not modify readerIndex or writerIndex of this buffer. Please note that the returned NIO buffer will not see the changes of this buffer if this buffer is a dynamic buffer and it adjusted its capacity. 
Throws:
UnsupportedOperationException – if this buffer cannot create a ByteBuffer that shares the content with itself
Returns:
byteBuffer/**
     * Exposes this buffer's readable bytes as an NIO {@link java.nio.ByteBuffer}.  The returned buffer
     * shares the content with this buffer, while changing the position and limit of the returned
     * NIO buffer does not affect the indexes and marks of this buffer.  This method is identical
     * to {@code buf.nioBuffer(buf.readerIndex(), buf.readableBytes())}.  This method does not
     * modify {@code readerIndex} or {@code writerIndex} of this buffer.  Please note that the
     * returned NIO buffer will not see the changes of this buffer if this buffer is a dynamic
     * buffer and it adjusted its capacity.
     *
     * @return byteBuffer
     * @throws UnsupportedOperationException if this buffer cannot create a {@link java.nio.ByteBuffer}
     *                                       that shares the content with itself
     */
    java.nio.ByteBuffer asNioBuffer();

    
Exposes this buffer's sub-region as an NIO ByteBuffer. The returned buffer shares the content with this buffer, while changing the position and limit of the returned NIO buffer does not affect the indexes and marks of this buffer. This method does not modify readerIndex or writerIndex of this buffer. Please note that the returned NIO buffer will not see the changes of this buffer if this buffer is a dynamic buffer and it adjusted its capacity. 
Params:
index –  The index
length – The length
Throws:
UnsupportedOperationException – if this buffer cannot create a ByteBuffer that shares the content with itself
Returns:
byteBuffer/**
     * Exposes this buffer's sub-region as an NIO {@link java.nio.ByteBuffer}.  The returned buffer
     * shares the content with this buffer, while changing the position and limit of the returned
     * NIO buffer does not affect the indexes and marks of this buffer.  This method does not
     * modify {@code readerIndex} or {@code writerIndex} of this buffer.  Please note that the
     * returned NIO buffer will not see the changes of this buffer if this buffer is a dynamic
     * buffer and it adjusted its capacity.
     * @return byteBuffer
     * @param index  The index
     * @param length The length
     * @throws UnsupportedOperationException if this buffer cannot create a {@link java.nio.ByteBuffer}
     *                                       that shares the content with itself
     */
    java.nio.ByteBuffer asNioBuffer(int index, int length);

    
Convert the ByteBuffer into an input stream. 
Returns:
this buffer as an input stream/**
     * Convert the {@link ByteBuffer} into an input stream.
     *
     * @return this buffer as an input stream
     */
    InputStream toInputStream();

    
Convert the ByteBuffer into an output stream. 
Returns:
this buffer as an input stream/**
     * Convert the {@link ByteBuffer} into an output stream.
     *
     * @return this buffer as an input stream
     */
    OutputStream toOutputStream();

    
Create a copy of the underlying storage from buf into a byte array. The copy will start at readerIndex() and copy readableBytes() bytes. 
Returns:
byte array/**
     * Create a copy of the underlying storage from {@code buf} into a byte array.
     * The copy will start at {@link ByteBuffer#readerIndex()} and copy {@link ByteBuffer#readableBytes()} bytes.
     * @return byte array
     */
    byte[] toByteArray();

    
To string.
Params:
charset – converted charset
Returns:
string/**
     * To string.
     * @param charset converted charset
     * @return string
     */
    String toString(Charset charset);

    
Find the index of the first occurrence of the given byte.
Params:
b – The byte to find
Returns:
The index of the byte/**
     * Find the index of the first occurrence of the given byte.
     *
     * @param b The byte to find
     * @return The index of the byte
     */
    int indexOf(byte b);

    
Get the byte at the specified index.
Params:
index – The index
Returns:
The byte/**
     * Get the byte at the specified index.
     *
     * @param index The index
     * @return The byte
     */
    byte getByte(int index);
}