001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied.  See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019
020package org.apache.commons.io;
021
022import java.nio.ByteBuffer;
023import java.nio.ByteOrder;
024
025/**
026 * Manufactures {@link ByteBuffer} instances.
027 *
028 * @since 2.19.0
029 */
030public final class ByteBuffers {
031
032    /**
033     * Allocates a new byte buffer with little-endian byte order. The bytes of a multibyte value are ordered from least significant to most significant.
034     * <p>
035     * The new buffer's position is zero, the limit is its capacity, the mark is undefined, and each of element is initialized to zero. The new buffer has the
036     * given backing {@code array}, and its {@link ByteBuffer#arrayOffset() array offset} is zero.
037     * </p>
038     *
039     * @param array The array that will back the new byte buffer.
040     * @return The new byte buffer.
041     */
042    public static ByteBuffer littleEndian(final byte[] array) {
043        return littleEndian(ByteBuffer.wrap(array));
044    }
045
046    /**
047     * Sets the give buffer to little-endian.
048     *
049     * @param allocate The buffer to set to little-endian.
050     * @return the given buffer.
051     */
052    public static ByteBuffer littleEndian(final ByteBuffer allocate) {
053        return allocate.order(ByteOrder.LITTLE_ENDIAN);
054    }
055
056    /**
057     * Allocates a new byte buffer with little-endian byte order. The bytes of a multibyte value are ordered from least significant to most significant.
058     * <p>
059     * The new buffer's position is zero, the limit is its capacity, the mark is undefined, and each of element is initialized to zero. The new buffer has a
060     * {@link ByteBuffer#array() backing array}, and its {@link ByteBuffer#arrayOffset() array offset} is zero.
061     * </p>
062     *
063     * @param capacity The new buffer's capacity, in bytes.
064     * @return The new byte buffer.
065     * @throws IllegalArgumentException If the <code>capacity</code> is negative.
066     */
067    public static ByteBuffer littleEndian(final int capacity) {
068        return littleEndian(ByteBuffer.allocate(capacity));
069    }
070
071    private ByteBuffers() {
072        // empty, no instance.
073    }
074
075}