io.vertx.core.buffer.package-info Maven / Gradle / Ivy

Go to download
/*
 * Copyright 2014 Red Hat, Inc.
 *
 *  All rights reserved. This program and the accompanying materials
 *  are made available under the terms of the Eclipse Public License v1.0
 *  and Apache License v2.0 which accompanies this distribution.
 *
 *  The Eclipse Public License is available at
 *  http://www.eclipse.org/legal/epl-v10.html
 *
 *  The Apache License v2.0 is available at
 *  http://www.opensource.org/licenses/apache2.0.php
 *
 *  You may elect to redistribute this code under either of these licenses.
 */

/**
 * == Buffers
 * :toc: left
 *
 * Most data is shuffled around inside Vert.x using buffers.
 *
 * A buffer is a sequence of zero or more bytes that can read from or written to and which expands automatically as
 * necessary to accommodate any bytes written to it. You can perhaps think of a buffer as smart byte array.
 *
 * === Creating buffers
 *
 * Buffers can create by using one of the static {@link io.vertx.core.buffer.Buffer#buffer} methods.
 *
 * Buffers can be initialised from strings or byte arrays, or empty buffers can be created.
 *
 * Here are some examples of creating buffers:
 *
 * Create a new empty buffer:
 *
 * [source,$lang]
 * ----
 * {@link examples.BufferExamples#example1}
 * ----
 *
 * Create a buffer from a String. The String will be encoded in the buffer using UTF-8.
 *
 * [source,$lang]
 * ----
 * {@link examples.BufferExamples#example2}
 * ----
 *
 * Create a buffer from a String: The String will be encoded using the specified encoding, e.g:
 *
 * [source,$lang]
 * ----
 * {@link examples.BufferExamples#example3}
 * ----
 *
 * include::override/buffer_from_bytes.adoc[]
 *
 * Create a buffer with an initial size hint. If you know your buffer will have a certain amount of data written to it
 * you can create the buffer and specify this size. This makes the buffer initially allocate that much memory and is
 * more efficient than the buffer automatically resizing multiple times as data is written to it.
 *
 * Note that buffers created this way *are empty*. It does not create a buffer filled with zeros up to the specified size.
 *
 * [source,$lang]
 * ----
 * {@link examples.BufferExamples#example5}
 * ----
 *
 * === Writing to a Buffer
 *
 * There are two ways to write to a buffer: appending, and random access.
 * In either case buffers will always expand automatically to encompass the bytes. It's not possible to get
 * an {@code IndexOutOfBoundsException} with a buffer.
 *
 * ==== Appending to a Buffer
 *
 * To append to a buffer, you use the {@code appendXXX} methods.
 * Append methods exist for appending various different types.
 *
 * The return value of the {@code appendXXX} methods is the buffer itself, so these can be chained:
 *
 * [source,$lang]
 * ----
 * {@link examples.BufferExamples#example6}
 * ----
 *
 * ==== Random access buffer writes
 *
 * You can also write into the buffer at a specific index, by using the {@code setXXX} methods.
 * Set methods exist for various different data types. All the set methods take an index as the first argument - this
 * represents the position in the buffer where to start writing the data.
 *
 * The buffer will always expand as necessary to accommodate the data.
 *
 * [source,$lang]
 * ----
 * {@link examples.BufferExamples#example7}
 * ----
 *
 * === Reading from a Buffer
 *
 * Data is read from a buffer using the {@code getXXX} methods. Get methods exist for various datatypes.
 * The first argument to these methods is an index in the buffer from where to get the data.
 *
 * [source,$lang]
 * ----
 * {@link examples.BufferExamples#example8}
 * ----
 *
 * === Working with unsigned numbers
 *
 * Unsigned numbers can be read from or appended/set to a buffer with the {@code getUnsignedXXX},
 * {@code appendUnsignedXXX} and {@code setUnsignedXXX} methods. This is useful when implementing a codec for a
 * network protocol optimized to minimize bandwidth consumption.
 *
 * In the following example, value 200 is set at specified position with just one byte:
 *
 * [source,$lang]
 * ----
 * {@link examples.BufferExamples#example9}
 * ----
 *
 * The console shows '200'.
 *
 * === Buffer length
 *
 * Use {@link io.vertx.core.buffer.Buffer#length} to obtain the length of the buffer.
 * The length of a buffer is the index of the byte in the buffer with the largest index + 1.
 *
 * === Copying buffers
 *
 * Use {@link io.vertx.core.buffer.Buffer#copy} to make a copy of the buffer
 *
 * === Slicing buffers
 *
 * A sliced buffer is a new buffer which backs onto the original buffer, i.e. it does not copy the underlying data.
 * Use {@link io.vertx.core.buffer.Buffer#slice} to create a sliced buffers
 *
 * === Buffer re-use
 *
 * After writing a buffer to a socket or other similar place, they cannot be re-used.
 *
 */
@Document(fileName = "buffers.adoc")
package io.vertx.core.buffer;

import io.vertx.docgen.Document;