1 /*
2 * Copyright 2021 The Netty Project
3 *
4 * The Netty Project licenses this file to you under the Apache License, version 2.0 (the
5 * "License"); you may not use this file except in compliance with the License. You may obtain a
6 * copy of the License at:
7 *
8 * https://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software distributed under the License
11 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
12 * or implied. See the License for the specific language governing permissions and limitations under
13 * the License.
14 */
15 package io.netty5.buffer.api;
16
17 import io.netty5.util.ByteProcessor;
18
19 /**
20 * The ByteCursor scans through a sequence of bytes.
21 * This is similar to {@link ByteProcessor}, but for external iteration rather than internal iteration.
22 * The external iteration allows the callers to control the pace of the iteration.
23 */
24 public interface ByteCursor {
25 /**
26 * Check if the iterator has at least one byte left, and if so, read that byte and move the cursor forward.
27 * The byte will then be available through the {@link #getByte()}.
28 *
29 * @return {@code true} if the cursor read a byte and moved forward, otherwise {@code false}.
30 */
31 boolean readByte();
32
33 /**
34 * Return the last byte that was read by {@link #readByte()}.
35 * If {@link #readByte()} has not been called on this cursor before, then {@code -1} is returned.
36 *
37 * @return The next byte that was read by the most recent successful call to {@link #readByte()}.
38 */
39 byte getByte();
40
41 /**
42 * The current position of this iterator into the underlying sequence of bytes.
43 * For instance, if we are iterating a buffer, this would be the iterators current offset into the buffer.
44 *
45 * @return The current iterator offset into the underlying sequence of bytes.
46 */
47 int currentOffset();
48
49 /**
50 * Get the current number of bytes left in the iterator.
51 *
52 * @return The number of bytes left in the iterator.
53 */
54 int bytesLeft();
55
56 /**
57 * Process the remaining bytes in this iterator with the given {@link ByteProcessor}.
58 * This method consumes the iterator.
59 *
60 * @param processor The processor to use for processing the bytes in the iterator.
61 * @return The number of bytes processed, if the {@link ByteProcessor#process(byte) process} method returned
62 * {@code false}, or {@code -1} if the whole iterator was processed.
63 */
64 default int process(ByteProcessor processor) {
65 boolean requestMore = true;
66 int count = 0;
67 while (readByte() && (requestMore = processor.process(getByte()))) {
68 count++;
69 }
70 return requestMore? -1 : count;
71 }
72 }