There is no thread-safety guarantee. + *
This class provides an implementation of {@link Bytes} that allows + * converting various sources (e.g., strings, streams, files, readers) + * into byte arrays. This is useful for working with binary data in a unified way.
+ * + *Example usage:
+ * + *{@code
+ * // Convert a string to bytes
+ * byte[] bytes = new BytesOf("example").asBytes();
+ *
+ * // Convert an InputStream to bytes
+ * InputStream input = new ByteArrayInputStream("example".getBytes());
+ * byte[] streamBytes = new BytesOf(input).asBytes();
+ *
+ * // Convert a file to bytes
+ * File file = new File("path/to/file.txt");
+ * byte[] fileBytes = new BytesOf(file).asBytes();
+ *
+ * // Convert a Throwable (exception) stack trace to bytes
+ * Throwable error = new RuntimeException("Something went wrong");
+ * byte[] errorBytes = new BytesOf(error).asBytes();
+ * }
+ *
+ * Thread safety is not guaranteed.
* * @since 0.12 */ @@ -58,16 +81,39 @@ public final class BytesOf implements Bytes { private final Bytes origin; /** - * Ctor. - * @param input The input + * Constructs a {@link BytesOf} instance from an {@link Input}. + * + *This constructor reads bytes from a generic {@link Input} source, + * such as a file, string, or any custom input implementation. + * The resulting bytes can be retrieved using {@link #asBytes()}.
+ * + *Example usage:
+ * + *{@code
+ * Input input = new InputOf("Hello, world!");
+ * byte[] bytes = new BytesOf(input).asBytes();
+ * }
+ *
+ * @param input The input source to read bytes from.
*/
public BytesOf(final Input input) {
this(new InputAsBytes(input));
}
/**
- * Ctor.
- * @param input The input
+ * Constructs a {@link BytesOf} instance from an {@link InputStream}.
+ *
+ * This constructor reads bytes from an {@link InputStream}, + * such as a file or socket stream.
+ * + *Example usage:
+ * + *{@code
+ * InputStream stream = new ByteArrayInputStream("data".getBytes());
+ * byte[] bytes = new BytesOf(stream).asBytes();
+ * }
+ *
+ * @param input The {@link InputStream} to read bytes from.
* @since 0.29.2
*/
public BytesOf(final InputStream input) {
@@ -75,8 +121,18 @@ public BytesOf(final InputStream input) {
}
/**
- * Ctor.
- * @param file The input
+ * Constructs a {@link BytesOf} instance from a {@link File}.
+ *
+ * This constructor reads bytes from the content of a file.
+ * + *Example usage:
+ * + *{@code
+ * File file = new File("example.txt");
+ * byte[] bytes = new BytesOf(file).asBytes();
+ * }
+ *
+ * @param file The {@link File} to read bytes from.
* @since 0.13
*/
public BytesOf(final File file) {
@@ -84,8 +140,19 @@ public BytesOf(final File file) {
}
/**
- * Ctor.
- * @param path The input
+ * Constructs a {@link BytesOf} instance from a {@link Path}.
+ *
+ * This constructor reads bytes from the content of a file represented + * by the {@link Path}.
+ * + *Example usage:
+ * + *{@code
+ * Path path = Paths.get("example.txt");
+ * byte[] bytes = new BytesOf(path).asBytes();
+ * }
+ *
+ * @param path The {@link Path} to read bytes from.
* @since 0.13
*/
public BytesOf(final Path path) {
@@ -93,54 +160,125 @@ public BytesOf(final Path path) {
}
/**
- * Ctor.
- * @param input The input
- * @param max Max length of the buffer for reading
+ * Constructs a {@link BytesOf} instance from an {@link Input} with a buffer limit.
+ *
+ * This constructor reads bytes from an {@link Input} source but + * limits the reading to a specified maximum buffer size.
+ * + *Example usage:
+ * + *{@code
+ * Input input = new InputOf("This is a long string that exceeds the limit.");
+ * byte[] bytes = new BytesOf(input, 10).asBytes();
+ * }
+ *
+ * @param input The input source to read bytes from.
+ * @param max The maximum buffer size for reading bytes.
*/
public BytesOf(final Input input, final int max) {
this(new InputAsBytes(input, max));
}
/**
- * Ctor.
- * @param rdr Reader
+ * Constructs a {@link BytesOf} instance from a {@link Reader}.
+ *
+ * This constructor reads bytes from a {@link Reader}, + * such as a {@link java.io.StringReader} or a {@link java.io.FileReader}. + * The resulting bytes can be retrieved using {@link #asBytes()}.
+ * + *Example usage:
+ * + *{@code
+ * Reader reader = new StringReader("Hello, world!");
+ * byte[] bytes = new BytesOf(reader).asBytes();
+ * }
+ *
+ * @param rdr The {@link Reader} to read bytes from.
*/
public BytesOf(final Reader rdr) {
this(new ReaderAsBytes(rdr));
}
/**
- * Ctor.
- * @param rdr Reader
- * @param charset Charset
+ * Constructs a {@link BytesOf} instance from a {@link Reader} with a specified {@link Charset}.
+ *
+ * This constructor reads bytes from a {@link Reader} and uses the given + * {@link Charset} for encoding. This is useful for handling different + * character encodings like UTF-8 or ISO-8859-1.
+ * + *Example usage:
+ * + *{@code
+ * Reader reader = new StringReader("Привет, мир!");
+ * byte[] bytes = new BytesOf(reader, StandardCharsets.UTF_8).asBytes();
+ * }
+ *
+ * @param rdr The {@link Reader} to read bytes from.
+ * @param charset The {@link Charset} used to encode the characters.
*/
public BytesOf(final Reader rdr, final Charset charset) {
this(new ReaderAsBytes(rdr, charset));
}
/**
- * Ctor.
- * @param rdr Reader
- * @param charset Charset
+ * Constructs a {@link BytesOf} instance from a {@link Reader} with a {@link CharSequence}
+ * representing the charset.
+ *
+ * This constructor reads bytes from a {@link Reader} and uses the charset + * specified as a {@link CharSequence} for encoding.
+ * + *Example usage:
+ * + *{@code
+ * Reader reader = new StringReader("Hola, mundo!");
+ * byte[] bytes = new BytesOf(reader, "UTF-8").asBytes();
+ * }
+ *
+ * @param rdr The {@link Reader} to read bytes from.
+ * @param charset The charset as a {@link CharSequence}.
*/
public BytesOf(final Reader rdr, final CharSequence charset) {
this(new ReaderAsBytes(rdr, charset));
}
/**
- * Ctor.
- * @param rdr Reader
- * @param charset Charset
- * @param max Buffer size
+ * Constructs a {@link BytesOf} instance from a {@link Reader} with a {@link Charset}
+ * and a specified maximum buffer size.
+ *
+ * This constructor reads bytes from a {@link Reader} and uses the given + * {@link Charset} for encoding, but limits the reading to a specified buffer size.
+ * + *Example usage:
+ * + *{@code
+ * Reader reader = new StringReader("This is a long string.");
+ * byte[] bytes = new BytesOf(reader, StandardCharsets.UTF_8, 10).asBytes();
+ * }
+ *
+ * @param rdr The {@link Reader} to read bytes from.
+ * @param charset The {@link Charset} used to encode the characters.
+ * @param max The maximum buffer size for reading bytes.
*/
public BytesOf(final Reader rdr, final Charset charset, final int max) {
this(new ReaderAsBytes(rdr, charset, max));
}
/**
- * Ctor.
- * @param rdr Reader
- * @param max Buffer size
+ * Constructs a {@link BytesOf} instance from a {@link Reader} with a specified maximum
+ * buffer size.
+ *
+ * This constructor reads bytes from a {@link Reader}, such as a + * {@link java.io.StringReader}, + * but limits the reading to the specified buffer size.
+ * + *Example usage:
+ *{@code
+ * Reader reader = new StringReader("Sample text data");
+ * byte[] bytes = new BytesOf(reader, 1024).asBytes();
+ * }
+ *
+ * @param rdr The {@link Reader} to read bytes from.
+ * @param max The maximum buffer size for reading bytes.
* @since 0.13.3
*/
public BytesOf(final Reader rdr, final int max) {
@@ -148,121 +286,261 @@ public BytesOf(final Reader rdr, final int max) {
}
/**
- * Ctor.
- * @param rdr Reader
- * @param charset Charset
- * @param max Buffer size
+ * Constructs a {@link BytesOf} instance from a {@link Reader} with a {@link CharSequence}
+ * representing the charset and a specified maximum buffer size.
+ *
+ * This constructor reads bytes from a {@link Reader} using the provided character encoding + * and limits the reading to the specified buffer size.
+ * + *Example usage:
+ *{@code
+ * Reader reader = new StringReader("Пример данных");
+ * byte[] bytes = new BytesOf(reader, "UTF-8", 512).asBytes();
+ * }
+ *
+ * @param rdr The {@link Reader} to read bytes from.
+ * @param charset The charset as a {@link CharSequence}.
+ * @param max The maximum buffer size for reading bytes.
*/
- public BytesOf(final Reader rdr, final CharSequence charset,
- final int max) {
+ public BytesOf(final Reader rdr, final CharSequence charset, final int max) {
this(new ReaderAsBytes(rdr, charset, max));
}
/**
- * Ctor.
+ * Constructs a {@link BytesOf} instance from a {@link CharSequence}.
+ *
+ * This constructor converts a {@link CharSequence} (e.g., {@link String}) into bytes using + * the default UTF-8 encoding.
* - * @param input The source + *Example usage:
+ *{@code
+ * CharSequence sequence = "Hello, world!";
+ * byte[] bytes = new BytesOf(sequence).asBytes();
+ * }
+ *
+ * @param input The {@link CharSequence} source to convert into bytes.
*/
public BytesOf(final CharSequence input) {
this(input, StandardCharsets.UTF_8);
}
/**
- * Ctor.
+ * Constructs a {@link BytesOf} instance from a {@link CharSequence} with a
+ * specified {@link Charset}.
+ *
+ * This constructor converts a {@link CharSequence} (e.g., {@link String}) into bytes using + * the provided character encoding.
+ * + *Example usage:
+ *{@code
+ * CharSequence sequence = "Привет, мир!";
+ * byte[] bytes = new BytesOf(sequence, StandardCharsets.UTF_8).asBytes();
+ * }
*
- * @param input The source
- * @param charset The charset
+ * @param input The {@link CharSequence} source to convert into bytes.
+ * @param charset The {@link Charset} used to encode the characters into bytes.
*/
public BytesOf(final CharSequence input, final Charset charset) {
this(() -> input.toString().getBytes(charset));
}
/**
- * Ctor.
+ * Constructs a {@link BytesOf} instance from a {@link CharSequence} with
+ * a specified {@link CharSequence} charset.
*
- * @param input The source
- * @param charset The charset
+ * This constructor converts a {@link CharSequence} (e.g., {@link String}) into bytes using + * the charset represented as a {@link CharSequence}.
+ * + *Example usage:
+ *{@code
+ * CharSequence sequence = "Hola, mundo!";
+ * byte[] bytes = new BytesOf(sequence, "ISO-8859-1").asBytes();
+ * }
+ *
+ * @param input The {@link CharSequence} source to convert into bytes.
+ * @param charset The {@link CharSequence} representation of the charset used for encoding.
*/
public BytesOf(final CharSequence input, final CharSequence charset) {
this(() -> input.toString().getBytes(charset.toString()));
}
/**
- * Ctor.
+ * Constructs a {@link BytesOf} instance from a sequence of characters.
+ *
+ * This constructor converts a sequence of characters into bytes using + * the default UTF-8 encoding.
* - * @param chars The chars + *Example usage:
+ *{@code
+ * byte[] bytes = new BytesOf('a', 'b', 'c').asBytes();
+ * }
+ *
+ * @param chars The sequence of characters to be converted into bytes.
*/
public BytesOf(final char... chars) {
this(chars, StandardCharsets.UTF_8);
}
/**
- * Ctor.
+ * Constructs a {@link BytesOf} instance from a sequence of characters
+ * and a specified {@link Charset}.
+ *
+ * This constructor converts a sequence of characters into bytes using + * the provided character encoding.
+ * + *Example usage:
+ *{@code
+ * byte[] bytes = new BytesOf(new char[]{'H', 'e', 'l', 'l', 'o'},
+ * StandardCharsets.UTF_16).asBytes();
+ * }
*
- * @param chars The chars
- * @param charset The charset
+ * @param chars The sequence of characters to be converted into bytes.
+ * @param charset The {@link Charset} used to encode the characters into bytes.
*/
public BytesOf(final char[] chars, final Charset charset) {
this(new String(chars), charset);
}
/**
- * Ctor.
+ * Constructs a {@link BytesOf} instance from a sequence of characters and
+ * a specified charset represented as a {@link CharSequence}.
*
- * @param chars The chars
- * @param charset The charset
+ * This constructor converts a sequence of characters into bytes using the charset + * provided as a {@link CharSequence}.
+ * + *Example usage:
+ *{@code
+ * byte[] bytes = new BytesOf(new char[]{'П', 'р', 'и', 'в', 'е', 'т'}, "UTF-8").asBytes();
+ * }
+ *
+ * @param chars The sequence of characters to be converted into bytes.
+ * @param charset The charset represented as a {@link CharSequence}.
*/
public BytesOf(final char[] chars, final CharSequence charset) {
this(new String(chars), charset);
}
/**
- * Ctor.
- * @param text The source
+ * Constructs a {@link BytesOf} instance from a {@link Text} object.
+ *
+ * This constructor converts the text into bytes using the default UTF-8 encoding.
+ * + *Example usage:
+ *{@code
+ * Text text = new TextOf("Hello, world!");
+ * byte[] bytes = new BytesOf(text).asBytes();
+ * }
+ *
+ * @param text The {@link Text} source to be converted into bytes.
*/
public BytesOf(final Text text) {
this(text, StandardCharsets.UTF_8);
}
/**
- * Ctor.
- * @param text The source
- * @param charset The charset
+ * Constructs a {@link BytesOf} instance from a {@link Text} object and
+ * a specified {@link Charset}.
+ *
+ * This constructor converts the text into bytes using the provided character encoding.
+ * + *Example usage:
+ *{@code
+ * Text text = new TextOf("Привет, мир!");
+ * byte[] bytes = new BytesOf(text, StandardCharsets.UTF_8).asBytes();
+ * }
+ *
+ * @param text The {@link Text} source to be converted into bytes.
+ * @param charset The {@link Charset} used to encode the text into bytes.
*/
public BytesOf(final Text text, final Charset charset) {
this(() -> text.asString().getBytes(charset));
}
/**
- * Ctor.
- * @param text The source
- * @param charset The charset
+ * Constructs a {@link BytesOf} instance from a {@link Text} object and
+ * a charset represented as a {@link CharSequence}.
+ *
+ * This constructor converts the text into bytes using the charset provided as + * a {@link CharSequence}.
+ * + *Example usage:
+ *{@code
+ * Text text = new TextOf("Hola, mundo!");
+ * byte[] bytes = new BytesOf(text, "ISO-8859-1").asBytes();
+ * }
+ *
+ * @param text The {@link Text} source to be converted into bytes.
+ * @param charset The charset represented as a {@link CharSequence}.
*/
public BytesOf(final Text text, final CharSequence charset) {
this(() -> text.asString().getBytes(charset.toString()));
}
/**
- * Ctor.
- * @param error The exception to serialize
+ * Constructs a {@link BytesOf} instance from a {@link Throwable} (exception or error).
+ *
+ * This constructor serializes the stack trace of the exception using + * the default UTF-8 encoding.
+ * + *Example usage:
+ *{@code
+ * try {
+ * throw new RuntimeException("Example exception");
+ * } catch (Exception ex) {
+ * byte[] bytes = new BytesOf(ex).asBytes();
+ * System.out.println(new String(bytes, StandardCharsets.UTF_8));
+ * }
+ * }
+ *
+ * @param error The exception or error to serialize into bytes.
*/
public BytesOf(final Throwable error) {
this(error, StandardCharsets.UTF_8);
}
/**
- * Ctor.
- * @param error The exception to serialize
- * @param charset Charset
+ * Constructs a {@link BytesOf} instance from a {@link Throwable} (exception or error) and
+ * a specified {@link Charset}.
+ *
+ * This constructor serializes the stack trace of the exception using + * the provided character encoding.
+ * + *Example usage:
+ *{@code
+ * try {
+ * throw new IllegalStateException("Another exception");
+ * } catch (Exception ex) {
+ * byte[] bytes = new BytesOf(ex, StandardCharsets.ISO_8859_1).asBytes();
+ * System.out.println(new String(bytes, StandardCharsets.ISO_8859_1));
+ * }
+ * }
+ *
+ * @param error The exception or error to serialize into bytes.
+ * @param charset The {@link Charset} used to encode the stack trace into bytes.
*/
public BytesOf(final Throwable error, final Charset charset) {
this(error, charset.name());
}
/**
- * Ctor.
- * @param error The exception to serialize
- * @param charset Charset
+ * Constructs a {@link BytesOf} instance from a {@link Throwable} (exception or error) and
+ * a charset represented as a {@link CharSequence}.
+ *
+ * This constructor serializes the stack trace of the exception using the charset + * provided as a {@link CharSequence}.
+ * + *Example usage:
+ *{@code
+ * try {
+ * throw new NullPointerException("Null pointer exception");
+ * } catch (Exception ex) {
+ * byte[] bytes = new BytesOf(ex, "UTF-16").asBytes();
+ * System.out.println(new String(bytes, "UTF-16"));
+ * }
+ * }
+ *
+ * @param error The exception or error to serialize into bytes.
+ * @param charset The charset represented as a {@link CharSequence}.
*/
@SuppressWarnings("PMD.ConstructorOnlyInitializesOrCallOtherConstructors")
public BytesOf(final Throwable error, final CharSequence charset) {
@@ -282,8 +560,19 @@ public BytesOf(final Throwable error, final CharSequence charset) {
}
/**
- * Ctor.
- * @param strace The stack trace
+ * Constructs a {@link BytesOf} instance from a series of {@link StackTraceElement}.
+ *
+ * This constructor serializes the stack trace elements into bytes using + * the default UTF-8 encoding.
+ * + *Example usage:
+ *{@code
+ * StackTraceElement[] stack = Thread.currentThread().getStackTrace();
+ * byte[] bytes = new BytesOf(stack).asBytes();
+ * System.out.println(new String(bytes, StandardCharsets.UTF_8));
+ * }
+ *
+ * @param strace The array of stack trace elements to serialize.
* @since 0.29
*/
public BytesOf(final StackTraceElement... strace) {
@@ -291,9 +580,21 @@ public BytesOf(final StackTraceElement... strace) {
}
/**
- * Ctor.
- * @param strace The stack trace
- * @param charset Charset
+ * Constructs a {@link BytesOf} instance from a stack trace represented
+ * as an array of {@link StackTraceElement}.
+ *
+ * This constructor serializes the stack trace elements into bytes using + * the provided {@link Charset}.
+ * + *Example usage:
+ *{@code
+ * StackTraceElement[] stack = Thread.currentThread().getStackTrace();
+ * byte[] bytes = new BytesOf(stack, StandardCharsets.UTF_8).asBytes();
+ * System.out.println(new String(bytes, StandardCharsets.UTF_8));
+ * }
+ *
+ * @param strace The stack trace elements to serialize.
+ * @param charset The {@link Charset} used to encode the stack trace into bytes.
* @since 0.29
*/
public BytesOf(final StackTraceElement[] strace, final Charset charset) {
@@ -301,9 +602,21 @@ public BytesOf(final StackTraceElement[] strace, final Charset charset) {
}
/**
- * Ctor.
- * @param strace The stack trace
- * @param charset Charset
+ * Constructs a {@link BytesOf} instance from a stack trace represented as
+ * an array of {@link StackTraceElement}.
+ *
+ * This constructor serializes the stack trace elements into bytes using + * the provided charset represented as a {@link CharSequence}.
+ * + *Example usage:
+ *{@code
+ * StackTraceElement[] stack = Thread.currentThread().getStackTrace();
+ * byte[] bytes = new BytesOf(stack, "UTF-16").asBytes();
+ * System.out.println(new String(bytes, "UTF-16"));
+ * }
+ *
+ * @param strace The stack trace elements to serialize.
+ * @param charset The charset represented as a {@link CharSequence}.
* @since 0.29
*/
@SuppressWarnings("PMD.ConstructorOnlyInitializesOrCallOtherConstructors")
@@ -329,27 +642,55 @@ public BytesOf(final StackTraceElement[] strace,
}
/**
- * Ctor.
+ * Constructs a {@link BytesOf} instance from a sequence of bytes.
+ *
+ * This constructor encapsulates the provided byte array.
* - * @param bytes Bytes to encapsulate + *Example usage:
+ *{@code
+ * byte[] data = new BytesOf((byte) 1, (byte) 2, (byte) 3).asBytes();
+ * System.out.println(Arrays.toString(data));
+ * }
+ *
+ * @param bytes The bytes to encapsulate.
*/
public BytesOf(final byte... bytes) {
this(() -> bytes);
}
/**
- * Ctor.
+ * Constructs a {@link BytesOf} instance from an {@link Iterator} of bytes.
+ *
+ * This constructor collects the bytes from the iterator and encapsulates + * them as an array.
+ * + *Example usage:
+ *{@code
+ * List byteList = Arrays.asList((byte) 10, (byte) 20, (byte) 30);
+ * byte[] data = new BytesOf(byteList.iterator()).asBytes();
+ * System.out.println(Arrays.toString(data));
+ * }
*
- * @param iterator Iterator of bytes
+ * @param iterator The iterator of bytes to encapsulate.
*/
public BytesOf(final IteratorThis constructor collects the bytes from the iterable and encapsulates + * them as an array.
+ * + *Example usage:
+ *{@code
+ * Iterable bytes = Arrays.asList((byte) 100, (byte) 101);
+ * byte[] data = new BytesOf(bytes).asBytes();
+ * System.out.println(Arrays.toString(data));
+ * }
+ *
+ * @param bytes The iterable collection of bytes to encapsulate.
*/
public BytesOf(final IterableThis constructor collects the bytes from the collection and encapsulates + * them as an array.
* - * @param bytes Collection of bytes + *Example usage:
+ *{@code
+ * Collection bytes = List.of((byte) 65, (byte) 66);
+ * byte[] data = new BytesOf(bytes).asBytes();
+ * System.out.println(new String(data, StandardCharsets.UTF_8));
+ * }
+ *
+ * @param bytes The collection of bytes to encapsulate.
*/
public BytesOf(final CollectionThis constructor is private and is intended for internal usage only, allowing + * composition of {@link Bytes} implementations.
+ * + *Example usage (indirectly via other constructors):
+ *{@code
+ * byte[] data = new BytesOf(new InputOf("example")).asBytes();
+ * System.out.println(Arrays.toString(data));
+ * }
*
- * @param bytes Bytes to encapsulate
+ * @param bytes The {@link Bytes} instance to encapsulate.
*/
private BytesOf(final Bytes bytes) {
this.origin = bytes;