jetbrains.exodus.ByteIterable Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of sonarlint-core Show documentation
Common library used by some SonarLint flavors
There is a newer version: 10.5.0.78949
/**
 * Copyright 2010 - 2022 JetBrains s.r.o.
 *
 * 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 jetbrains.exodus;

import org.jetbrains.annotations.NotNull;

/**
 * If working with {@link jetbrains.exodus.env.Environment}, any key and value should be a ByteIterable.
 * ByteIterable is a mix of iterable and array. It allows to lazily enumerate bytes without boxing.
 * On the other hand, you can get its length using method getLength(). Generally, iterating over bytes
 * of ByteIterable is performed by means of getting {@link ByteIterator}.
 *
 * @see jetbrains.exodus.ArrayByteIterable
 * @see jetbrains.exodus.ByteBufferByteIterable
 * @see jetbrains.exodus.FileByteIterable
 * @see jetbrains.exodus.FixedLengthByteIterable
 * @see jetbrains.exodus.CompoundByteIterable
 */
public interface ByteIterable extends Comparable {

    byte[] EMPTY_BYTES = {};

    ByteIterator iterator();

    /**
     * @return raw content of the {@code ByteIterable}. May return array with length greater than {@link #getLength()}.
     */
    byte[] getBytesUnsafe();

    /**
     * @return length of the {@code ByteIterable}.
     */
    int getLength();

    /**
     * @param offset start offset, inclusive
     * @param length length of the sub-iterable
     * @return a fixed-length sub-iterable of the {@code ByteIterable} starting from {@code offset}.
     */
    @NotNull
    ByteIterable subIterable(final int offset, final int length);

    ByteIterator EMPTY_ITERATOR = new ByteIterator() {

        @Override
        public boolean hasNext() {
            return false;
        }

        @Override
        public byte next() {
            return (byte) 0;
        }

        @Override
        public long skip(long bytes) {
            return 0;
        }
    };

    ByteIterable EMPTY = new ByteIterable() {

        @Override
        public ByteIterator iterator() {
            return EMPTY_ITERATOR;
        }

        @Override
        public int compareTo(@NotNull ByteIterable right) {
            return right.iterator().hasNext() ? -1 : 0;
        }

        @Override
        public byte[] getBytesUnsafe() {
            return EMPTY_BYTES;
        }

        @Override
        public int getLength() {
            return 0;
        }

        @NotNull
        @Override
        public ByteIterable subIterable(int offset, int length) {
            return this;
        }

        @Override
        public String toString() {
            return "[ByteIterable.EMPTY]";
        }
    };
}