Merge pull request #5 from mercyblitz/main

Feature 0.1.5

Author: mercyblitz

microsphere-java-core/src/main/java/io/microsphere/collection/ArrayStack.java

@@ -0,0 +1,141 @@
+/*
+ * 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
+ *
+ *     http://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 io.microsphere.collection;
+
+import java.util.ArrayList;
+import java.util.EmptyStackException;
+import java.util.Stack;
+
+/**
+ * The {@code Stack} class represents a last-in-first-out
+ * (LIFO) stack of objects. It extends class {@code Vector} with five
+ * operations that allow a vector to be treated as a stack. The usual
+ * {@code push} and {@code pop} operations are provided, as well as a
+ * method to {@code peek} at the top item on the stack, a method to test
+ * for whether the stack is {@code empty}, and a method to {@code search}
+ * the stack for an item and discover how far it is from the top.
+ * <p>
+ * The non thread-safe version of {@link Stack}.
+ *
+ * @param <E> Type of component elements
+ * @author <a href="mailto:mercyblitz@gmail.com">Mercy</a>
+ * @see ArrayList
+ * @see Stack
+ * @since 1.0.0
+ */
+public class ArrayStack<E> extends ArrayList<E> {
+
+    private static final long serialVersionUID = -1417040223081465932L;
+
+    /**
+     * Creates an empty Stack.
+     */
+    public ArrayStack() {
+        this(0);
+    }
+
+    /**
+     * Constructs a new, empty stack with the specified initial
+     * capacity.
+     *
+     * @param initialCapacity the initial capacity of the stack.
+     * @throws IllegalArgumentException if the specified initial capacity
+     *                                  is negative
+     */
+    public ArrayStack(int initialCapacity) {
+        super(initialCapacity);
+    }
+
+    /**
+     * Pushes an item onto the top of this stack. This has exactly
+     * the same effect as: {@link #add(Object)}
+     *
+     * @param item the item to be pushed onto this stack.
+     * @return the {@code item} argument.
+     * @see ArrayList#add(Object)
+     */
+    public E push(E item) {
+        super.add(item);
+        return item;
+    }
+
+    /**
+     * Removes the object at the top of this stack and returns that
+     * object as the value of this function.
+     *
+     * @return The object at the top of this stack (the last item
+     * of the {@code ArrayList} object).
+     * @throws EmptyStackException if this stack is empty.
+     */
+    public E pop() {
+        E obj;
+        int len = super.size();
+
+        obj = this.peek();
+        super.remove(len - 1);
+        return obj;
+    }
+
+    /**
+     * Looks at the object at the top of this stack without removing it
+     * from the stack.
+     *
+     * @return the object at the top of this stack (the last item
+     * of the {@code ArrayList} object).
+     * @throws EmptyStackException if this stack is empty.
+     */
+    public E peek() throws EmptyStackException {
+        int len = super.size();
+        if (len == 0)
+            throw new EmptyStackException();
+        return super.get(len - 1);
+    }
+
+    /**
+     * Tests if this stack is empty.
+     *
+     * @return {@code true} if and only if this stack contains
+     * no items; {@code false} otherwise.
+     */
+    public boolean empty() {
+        return super.isEmpty();
+    }
+
+    /**
+     * Returns the 1-based position where an object is on this stack.
+     * If the object {@code o} occurs as an item in this stack, this
+     * method returns the distance from the top of the stack of the
+     * occurrence nearest the top of the stack; the topmost item on the
+     * stack is considered to be at distance {@code 1}. The {@code equals}
+     * method is used to compare {@code o} to the
+     * items in this stack.
+     *
+     * @param o the desired object.
+     * @return the 1-based position from the top of the stack where
+     * the object is located; the return value {@code -1}
+     * indicates that the object is not on the stack.
+     */
+    public int search(Object o) {
+        int i = super.lastIndexOf(o);
+
+        if (i >= 0) {
+            return super.size() - i;
+        }
+        return -1;
+    }
+}

microsphere-java-core/src/main/java/io/microsphere/collection/CollectionUtils.java

@@ -432,7 +432,7 @@ public static boolean equals(@Nullable Collection<?> one, @Nullable Collection<?
      * </p>
      *
      * @param collection the collection to which elements are to be added, may be null or empty
-     * @param values     the array of elements to add, may be null
+     * @param newValues  the array of elements to add, may be null
      * @param <T>        the type of elements in the collection and array
      * @return the number of elements successfully added to the collection
      *
@@ -449,21 +449,61 @@ public static boolean equals(@Nullable Collection<?> one, @Nullable Collection<?
      * int count4 = CollectionUtils.addAll(emptyCollection, "x"); // returns 0
      * }</pre>
      */
-    public static <T> int addAll(@Nullable Collection<T> collection, T... values) {
-
+    public static <T> int addAll(@Nullable Collection<T> collection, T... newValues) {
         if (collection == null) {
             return 0;
         }
 
-        int size = length(values);
-
+        int size = length(newValues);
         if (size < 1) {
             return 0;
         }
 
         int effectedCount = 0;
         for (int i = 0; i < size; i++) {
-            if (collection.add(values[i])) {
+            if (collection.add(newValues[i])) {
+                effectedCount++;
+            }
+        }
+
+        return effectedCount;
+    }
+
+    /**
+     * Adds all the elements in the specified {@link Iterable} to the given collection.
+     *
+     * <p>
+     * If the provided collection is null or empty, no elements are added, and 0 is returned.
+     * If the iterable is null or has no elements, 0 is also returned.
+     * </p>
+     *
+     * @param collection the collection to which elements are to be added, may be null or empty
+     * @param newValues  the {@link Iterable} of elements to add, may be null
+     * @param <T>        the type of elements in the collection and iterable
+     * @return the number of elements successfully added to the collection
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     * Collection<String> collection = new ArrayList<>();
+     * Iterable<String> values = Arrays.asList("a", "b", "c");
+     * int count1 = CollectionUtils.addAll(collection, values); // returns 3
+     *
+     * int count2 = CollectionUtils.addAll(null, values); // returns 0
+     *
+     * int count3 = CollectionUtils.addAll(collection, (Iterable<String>) null); // returns 0
+     *
+     * Collection<String> emptyCollection = Collections.emptyList();
+     * int count4 = CollectionUtils.addAll(emptyCollection, values); // returns 0
+     * }</pre>
+     */
+    public static <T> int addAll(@Nullable Collection<T> collection, @Nullable Iterable<T> newValues) {
+        if (collection == null || newValues == null) {
+            return 0;
+        }
+
+        int effectedCount = 0;
+        for (T newValue : newValues) {
+            if (collection.add(newValue)) {
                 effectedCount++;
             }
         }

microsphere-java-core/src/main/java/io/microsphere/util/IterableUtils.java

@@ -17,8 +17,11 @@
 
 package io.microsphere.util;
 
+import io.microsphere.annotation.Nonnull;
 import io.microsphere.annotation.Nullable;
 
+import java.util.function.Consumer;
+
 import static io.microsphere.util.ClassUtils.isAssignableFrom;
 
 /**
@@ -66,6 +69,56 @@ public static boolean isIterable(@Nullable Class<?> clazz) {
         return isAssignableFrom(Iterable.class, clazz);
     }
 
+    /**
+     * Iterates over the given {@link Iterable} and applies the provided {@link Consumer} to each element.
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     * List<String> list = Arrays.asList("a", "b", "c");
+     * IterableUtils.iterate(list, System.out::println);
+     * // Output:
+     * // a
+     * // b
+     * // c
+     * }</pre>
+     *
+     * @param elements        the {@link Iterable} to iterate over
+     * @param elementConsumer the {@link Consumer} to apply to each element
+     * @param <E>             the type of elements in the {@link Iterable}
+     */
+    public static <E> void iterate(@Nullable Iterable<E> elements, @Nonnull Consumer<E> elementConsumer) {
+        if (elements != null) {
+            for (E element : elements) {
+                elementConsumer.accept(element);
+            }
+        }
+    }
+
+    /**
+     * Iterates over the given {@link Iterable} and applies the provided {@link Consumer} to each element.
+     * <p>
+     * This method is equivalent to {@link #iterate(Iterable, Consumer)}.
+     * </p>
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     * List<String> list = Arrays.asList("a", "b", "c");
+     * IterableUtils.forEach(list, System.out::println);
+     * // Output:
+     * // a
+     * // b
+     * // c
+     * }</pre>
+     *
+     * @param elements        the {@link Iterable} to iterate over
+     * @param elementConsumer the {@link Consumer} to apply to each element
+     * @param <E>             the type of elements in the {@link Iterable}
+     * @see #iterate(Iterable, Consumer)
+     */
+    public static <E> void forEach(@Nullable Iterable<E> elements, @Nonnull Consumer<E> elementConsumer) {
+        iterate(elements, elementConsumer);
+    }
+
     private IterableUtils() {
     }
 }

microsphere-java-core/src/test/java/io/microsphere/collection/ArrayStackTest.java

@@ -0,0 +1,93 @@
+/*
+ * 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
+ *
+ *     http://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 io.microsphere.collection;
+
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.util.EmptyStackException;
+
+import static io.microsphere.collection.ListUtils.ofArrayList;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * {@link ArrayStack} Test
+ *
+ * @author <a href="mailto:mercyblitz@gmail.com">Mercy</a>
+ * @see ArrayStack
+ * @since 1.0.0
+ */
+class ArrayStackTest {
+
+    private ArrayStack<String> stack;
+
+    @BeforeEach
+    void setUp() {
+        this.stack = new ArrayStack<>();
+    }
+
+    @Test
+    void testPush() {
+        this.stack.push("A");
+        assertEquals(ofArrayList("A"), this.stack);
+    }
+
+    @Test
+    void testPop() {
+        this.stack.push("A");
+        assertEquals("A", this.stack.pop());
+        assertEquals(0, this.stack.size());
+    }
+
+    @Test
+    void testPopWithoutElement() {
+        assertThrows(EmptyStackException.class, this.stack::pop);
+    }
+
+    @Test
+    void testPeek() {
+        this.stack.push("A");
+        assertEquals("A", this.stack.peek());
+        assertEquals(1, this.stack.size());
+    }
+
+    @Test
+    void testPeekWithoutElement() {
+        assertThrows(EmptyStackException.class, this.stack::peek);
+    }
+
+    @Test
+    void testEmpty() {
+        assertTrue(this.stack.empty());
+
+        this.stack.push("A");
+        assertFalse(this.stack.empty());
+    }
+
+    @Test
+    void testSearch() {
+        this.stack.push("A");
+
+        assertEquals(1, this.stack.search("A"));
+        assertEquals(-1, this.stack.search("B"));
+    }
+}