From ef504bbe06971458669c22bcc84f6175066d6ef5 Mon Sep 17 00:00:00 2001 From: zihluwang Date: Sun, 19 Jan 2025 00:06:18 +0800 Subject: [PATCH] feat: added RangeUtil RangeUtil is a utility class providing methods for generating streams of integers that emulate the behaviour of Python's range function. --- .../com/onixbyte/devkit/utils/RangeUtil.java | 171 ++++++++++++++++++ 1 file changed, 171 insertions(+) create mode 100644 devkit-utils/src/main/java/com/onixbyte/devkit/utils/RangeUtil.java diff --git a/devkit-utils/src/main/java/com/onixbyte/devkit/utils/RangeUtil.java b/devkit-utils/src/main/java/com/onixbyte/devkit/utils/RangeUtil.java new file mode 100644 index 0000000..7a7dd6a --- /dev/null +++ b/devkit-utils/src/main/java/com/onixbyte/devkit/utils/RangeUtil.java @@ -0,0 +1,171 @@ +/* + * Copyright (C) 2024-2025 OnixByte. + * + * 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 + * + * 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 com.onixbyte.devkit.utils; + +import java.util.stream.IntStream; + +/** + * {@code RangeUtil} is a utility class providing methods for generating streams of integers that + * emulate the behaviour of Python's {@code range} function. + *

+ * This class offers static methods to create ranges with various configurations. These methods + * leverage the {@link IntStream} to provide efficient and versatile integer sequences. + * + * @author zihluwang + * @see IntStream + */ +public final class RangeUtil { + + /** + * Private constructor prevent class being instantiated. + */ + private RangeUtil() { + } + + /** + * Generates a stream of integers starting from {@code 0} up to the specified {@code end} value. + *

+ * It creates a sequential, ordered {@code IntStream} that can be used for iteration or + * further processing. + *

+ * Example Usage: + * 

{@code
+     * RangeUtil.range(5).forEach(System.out::println);
+     *
+     * // Output:
+     * // 0
+     * // 1
+     * // 2
+     * // 3
+     * // 4
+     * }
+ * + * @param end upper-bound of the range (exclusive) + * @return an {@code IntStream} of integers from {@code 0} (inclusive) to + * {@code end} (exclusive) + * @throws IllegalArgumentException if the given {@code end} value is less equal to 0 + * @see IntStream + */ + public static IntStream range(int end) { + if (end <= 0) { + throw new IllegalArgumentException("Parameter [end] should not less than 0, provided is " + + end); + } + return IntStream.range(0, end); + } + + /** + * Generates a stream of integers starting from the specified {@code start} value up to the + * specified {@code end} value. + *

+ * It creates a sequential, ordered {@code IntStream} that can be used for iteration or + * further processing. + *

+ * Example Usage: + * 

{@code
+     * RangeUtil.range(3, 8).forEach(System.out::println);
+     *
+     * // Output:
+     * // 3
+     * // 4
+     * // 5
+     * // 6
+     * // 7
+     * }
+ * + * @param start the starting value of the range (inclusive) + * @param end upper-bound of the range (exclusive) + * @return an {@code IntStream} of integers from {@code 0} (inclusive) to + * {@code end} (exclusive) + * @throws IllegalArgumentException if the given {@code end} value is less equal to 0 + * @see IntStream + */ + public static IntStream range(int start, int end) { + if (end >= start) { + throw new IllegalStateException("Parameter [start] should less than parameter [end]."); + } + return IntStream.range(start, end); + } + + /** + * Generates a stream of integers starting from the specified {@code start} value up to the + * specified {@code end} value. + *

+ * It creates a sequential, ordered {@code IntStream} that can be used for iteration or + * further processing. + *

+ * Example Usage: + * 

{@code
+     * RangeUtil.rangeClosed(3, 8).forEach(System.out::println);
+     *
+     * // Output:
+     * // 3
+     * // 4
+     * // 5
+     * // 6
+     * // 7
+     * // 8
+     * }
+ * + * @param start the starting value of the range (inclusive) + * @param end upper-bound of the range (inclusive) + * @return an {@code IntStream} of integers from {@code 0} (inclusive) to + * {@code end} (inclusive) + * @throws IllegalArgumentException if the given {@code end} value is less equal to 0 + * @see IntStream + */ + public static IntStream rangeClosed(int start, int end) { + return IntStream.rangeClosed(start, end); + } + + /** + * Generates a stream of integers starting from the specified {@code start} value, increment by + * the specified {@code step}, up to the specified {@code end} value. + *

+ * It creates a sequential, ordered {@code IntStream} that can be used for iteration or + * further processing. + *

+ * Example Usage: + * 

{@code
+     * RangeUtil.range(3, 8, 2).forEach(System.out::println);
+     *
+     * // Output:
+     * // 3
+     * // 5
+     * // 7
+     * }
+ * + * @param start the starting value of the range (inclusive) + * @param end upper-bound of the range (exclusive) + * @param step the increment (or decrement) between each value + * @return an {@code IntStream} of integers from {@code 0} (inclusive) to + * {@code end} (exclusive) + * @throws IllegalArgumentException if the given {@code end} value is less equal to 0 + * @see IntStream + */ + public static IntStream range(int start, int end, int step) { + if (step == 0) { + throw new IllegalArgumentException("Step value must not be zero."); + } + if ((step > 0 && start >= end) || (step < 0 && start <= end)) { + throw new IllegalArgumentException("Range parameters are inconsistent with the step value."); + } + return IntStream.iterate(start, (n) -> n < end, (n) -> n + step); + } + +}