Add ByteConsumer

Author: garydgregory

src/changes/changes.xml

@@ -84,6 +84,7 @@ The <action> type attribute can be add,update,fix,remove.
     <action                   type="add" dev="ggregory" due-to="Finger, Gary Gregory, Piotr P. Karwasz">Add org.apache.commons.lang3.time.DateUtils.toLocalDateTime(Date[, TimeZone]) #1385.</action>
     <action                   type="add" dev="ggregory" due-to="Gary Gregory">Add org.apache.commons.lang3.time.DateUtils.toOffsetDateTime(Date[, TimeZone]).</action>
     <action                   type="add" dev="ggregory" due-to="Gary Gregory">Add org.apache.commons.lang3.time.DateUtils.toZonedDateTime(Date[, TimeZone]).</action>
+    <action                   type="add" dev="ggregory" due-to="Gary Gregory">Add ByteConsumer.</action>
     <!-- UPDATE -->
     <action type="update" dev="ggregory" due-to="Gary Gregory">[test] Bump org.apache.commons:commons-text from 1.13.1 to 1.14.0.</action>
     <action type="update" dev="ggregory" due-to="Gary Gregory">Bump org.apache.commons:commons-parent from 85 to 87.</action>

src/main/java/org/apache/commons/lang3/function/ByteConsumer.java

@@ -0,0 +1,68 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.commons.lang3.function;
+
+import java.util.Objects;
+import java.util.function.IntConsumer;
+
+/**
+ * A functional interface like {@link IntConsumer} but for {@code byte}.
+ *
+ * @see IntConsumer
+ * @since 3.19.0
+ */
+@FunctionalInterface
+public interface ByteConsumer {
+
+    /** NOP singleton */
+    ByteConsumer NOP = t -> {
+        /* NOP */ };
+
+    /**
+     * Gets the NOP singleton.
+     *
+     * @return The NOP singleton.
+     */
+    static ByteConsumer nop() {
+        return NOP;
+    }
+
+    /**
+     * Accepts the given arguments.
+     *
+     * @param value the input argument
+     */
+    void accept(byte value);
+
+    /**
+     * Returns a composed {@link ByteConsumer} that performs, in sequence, this operation followed by the {@code after} operation. If performing either
+     * operation throws an exception, it is relayed to the caller of the composed operation. If performing this operation throws an exception, the {@code after}
+     * operation will not be performed.
+     *
+     * @param after the operation to perform after this operation
+     * @return a composed {@link ByteConsumer} that performs in sequence this operation followed by the {@code after} operation
+     * @throws NullPointerException if {@code after} is null
+     */
+    default ByteConsumer andThen(final ByteConsumer after) {
+        Objects.requireNonNull(after);
+        return (final byte t) -> {
+            accept(t);
+            after.accept(t);
+        };
+    }
+}

src/test/java/org/apache/commons/lang3/function/ByteConsumerTest.java

@@ -0,0 +1,82 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.commons.lang3.function;
+
+import static org.apache.commons.lang3.LangAssertions.assertNullPointerException;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import java.util.concurrent.atomic.AtomicInteger;
+
+import org.apache.commons.lang3.AbstractLangTest;
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+
+/**
+ * Tests {@link ByteConsumer}.
+ */
+class ByteConsumerTest extends AbstractLangTest {
+
+    private static final byte B0 = (byte) 0;
+    private static final byte B1 = (byte) 1;
+
+    private ByteConsumer accept(final ByteConsumer consumer, final byte expected) {
+        consumer.accept(expected);
+        return consumer;
+    }
+
+    @Test
+    void testAccept() {
+        final AtomicInteger ref = new AtomicInteger();
+        accept(v -> ref.lazySet(v), B1);
+        assertEquals(1, ref.get());
+        accept(v -> ref.lazySet(v), B0);
+        assertEquals(0, ref.get());
+    }
+
+    @Test
+    void testAndThen() throws Throwable {
+        final ByteConsumer nop = ByteConsumer.nop();
+        nop.andThen(nop);
+        // Documented in Javadoc edge-case.
+        assertNullPointerException(() -> nop.andThen(null));
+
+        final AtomicInteger ref1 = new AtomicInteger();
+        final AtomicInteger ref2 = new AtomicInteger();
+
+        final ByteConsumer bc = ref1::lazySet;
+        final ByteConsumer composite = bc.andThen(ref2::lazySet);
+
+        composite.accept(B1);
+        assertEquals(1, ref1.get());
+        assertEquals(1, ref2.get());
+
+        composite.accept(B0);
+        assertEquals(0, ref1.get());
+        assertEquals(0, ref2.get());
+
+        // Check order
+        final ByteConsumer bad = value -> {
+            throw new IllegalStateException();
+        };
+        final ByteConsumer badComposite = bad.andThen(ref2::lazySet);
+
+        Assertions.assertThrows(IllegalStateException.class, () -> badComposite.accept(B1));
+        assertEquals(0, ref2.get(), "Second consumer should not be invoked");
+    }
+
+}