org.pkl.thirdparty.graalvm.polyglot.io.ByteSequence Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of pkl-config-java-all Show documentation
Shaded fat Jar for pkl-config-java, a Java config library based on the Pkl config language.
There is a newer version: 0.27.1
/*
 * Copyright (c) 2018, 2019, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * The Universal Permissive License (UPL), Version 1.0
 *
 * Subject to the condition set forth below, permission is hereby granted to any
 * person obtaining a copy of this software, associated documentation and/or
 * data (collectively the "Software"), free of charge and under any and all
 * copyright rights in the Software, and any and all patent rights owned or
 * freely licensable by each licensor hereunder covering either (i) the
 * unmodified Software as contributed to or provided by such licensor, or (ii)
 * the Larger Works (as defined below), to deal in both
 *
 * (a) the Software, and
 *
 * (b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
 * one is included with the Software each a "Larger Work" to which the Software
 * is contributed by such licensors),
 *
 * without restriction, including without limitation the rights to copy, create
 * derivative works of, display, perform, and distribute the Software and make,
 * use, sell, offer for sale, import, export, have made, and have sold the
 * Software and the Larger Work(s), and to sublicense the foregoing rights on
 * either these or other terms.
 *
 * This license is subject to the following condition:
 *
 * The above copyright notice and either this complete permission notice or at a
 * minimum a reference to the UPL must be included in all copies or substantial
 * portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */
package org.pkl.thirdparty.graalvm.polyglot.io;

import java.util.NoSuchElementException;
import java.util.PrimitiveIterator;
import java.util.Spliterator;
import java.util.Spliterators;
import java.util.function.IntConsumer;
import java.util.stream.IntStream;
import java.util.stream.StreamSupport;

/**
 * A ByteSequence is a readable sequence of byte values. This interface
 * provides uniform, read-only access to many different kinds of byte sequences.
 * 
 * This interface does not refine the general contracts of the
 * {@link java.lang.Object#equals(java.lang.Object) equals} and {@link java.lang.Object#hashCode()
 * hashCode} methods. The result of comparing two objects that implement ByteSequence is
 * therefore, in general, undefined. Each object may be implemented by a different class, and there
 * is no guarantee that each class will be capable of testing its instances for equality with those
 * of the other. It is therefore inappropriate to use arbitrary ByteSequence instances as
 * elements in a set or as keys in a map.
 * 
 *
 * @since 19.0
 */
public interface ByteSequence {

    /**
     * Returns the length of this byte sequence.
     *
     * @return the number of bytes in this sequence
     * @since 19.0
     */
    int length();

    /**
     * Returns the byte value at the specified index. An index ranges from zero to
     * length() - 1. The first char value of the sequence is at index zero,
     * the next at index one, and so on, as for array indexing.
     *
     * @param index the index of the byte value to be returned
     * @return the specified byte value
     * @throws IndexOutOfBoundsException if the index argument is negative or not less than
     *             length()
     * @since 19.0
     */
    byte byteAt(int index);

    /**
     * Returns a ByteSequence that is a subsequence of this sequence. The subsequence
     * starts with the byte value at the specified index and ends with the
     * byte value at index end - 1. The length (in bytes) of the
     * returned sequence is end - start, so if start == end then an empty sequence
     * is returned.
     *
     * @param startIndex the start index, inclusive
     * @param endIndex the end index, exclusive
     * @return the specified subsequence
     * @throws IndexOutOfBoundsException if start or end are negative, if
     *             end is greater than length(), or if start is greater
     *             than end
     * @since 19.0
     */
    default ByteSequence subSequence(int startIndex, int endIndex) {
        int l = endIndex - startIndex;
        if (l < 0) {
            throw new IndexOutOfBoundsException(String.valueOf(l));
        }
        if (startIndex < 0) {
            throw new IndexOutOfBoundsException(String.valueOf(startIndex));
        }
        if (startIndex + l > length()) {
            throw new IndexOutOfBoundsException(String.valueOf(startIndex + l));
        }
        return new ByteSequence() {
            public int length() {
                return l;
            }

            public byte byteAt(int index) {
                return ByteSequence.this.byteAt(startIndex + index);
            }
        };
    }

    /**
     * Returns a byte[] containing the bytes in this sequence in the same order as this
     * sequence. The length of the byte array will be the length of this sequence. Creates a new
     * byte array with every invocation.
     *
     * @since 19.0
     */
    default byte[] toByteArray() {
        byte[] b = new byte[length()];
        for (int i = 0; i < b.length; i++) {
            b[i] = byteAt(i);
        }
        return b;
    }

    /**
     * Returns a stream of {@code int} zero-extending the {@code byte} values from this sequence.
     *
     * @return an IntStream of byte values from this sequence
     * @since 19.0
     */
    default IntStream bytes() {
        class ByteIterator implements PrimitiveIterator.OfInt {
            int cur = 0;

            public boolean hasNext() {
                return cur < length();
            }

            public int nextInt() {
                if (hasNext()) {
                    return byteAt(cur++) & 0xFF;
                } else {
                    throw new NoSuchElementException();
                }
            }

            @Override
            public void forEachRemaining(IntConsumer block) {
                for (; cur < length(); cur++) {
                    block.accept(byteAt(cur) & 0xFF);
                }
            }
        }
        return StreamSupport.intStream(() -> Spliterators.spliterator(
                        new ByteIterator(),
                        length(),
                        Spliterator.ORDERED),
                        Spliterator.SUBSIZED | Spliterator.SIZED | Spliterator.ORDERED,
                        false);
    }

    /**
     * Creates a ByteSequence from an existing byte[]. The byte array is
     * not defensively copied, therefore the given bytes must not mutate to ensure the contract of
     * an immutable ByteSequence.
     *
     * @since 19.0
     */
    static ByteSequence create(byte[] buffer) {
        return new ByteArraySequence(buffer, 0, buffer.length);
    }

}