新增 base 和 function 包的 package-info

Reviewed-on: #15

src/main/java/xyz/zhouxy/plusone/commons/base/IWithCode.java

@@ -19,6 +19,7 @@ package xyz.zhouxy.plusone.commons.base;
 import java.util.Objects;
 
 import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
 
 /**
  * 规定实现类带有 {@code getCode} 方法。
@@ -31,19 +32,19 @@ public interface IWithCode<T> {
     @Nonnull
     T getCode();
 
-    default boolean isCodeEquals(T code) {
+    default boolean isCodeEquals(@Nullable T code) {
         return Objects.equals(getCode(), code);
     }
 
-    default boolean isSameCodeAs(IWithCode<?> other) {
+    default boolean isSameCodeAs(@Nullable IWithCode<?> other) {
         return other != null && Objects.equals(getCode(), other.getCode());
     }
 
-    default boolean isSameCodeAs(IWithIntCode other) {
+    default boolean isSameCodeAs(@Nullable IWithIntCode other) {
         return other != null && Objects.equals(getCode(), other.getCode());
     }
 
-    default boolean isSameCodeAs(IWithLongCode other) {
+    default boolean isSameCodeAs(@Nullable IWithLongCode other) {
         return other != null && Objects.equals(getCode(), other.getCode());
     }
 }

src/main/java/xyz/zhouxy/plusone/commons/base/IWithIntCode.java

@@ -18,6 +18,8 @@ package xyz.zhouxy.plusone.commons.base;
 
 import java.util.Objects;
 
+import javax.annotation.Nullable;
+
 /**
  * 规定实现类带有 {@code getCode} 方法。
  * 用于像自定义异常等需要带有 {@code code} 字段的类，
@@ -32,15 +34,15 @@ public interface IWithIntCode {
         return getCode() == code;
     }
 
-    default boolean isSameCodeAs(IWithCode<?> other) {
+    default boolean isSameCodeAs(@Nullable IWithCode<?> other) {
         return other != null && Objects.equals(getCode(), other.getCode());
     }
 
-    default boolean isSameCodeAs(IWithIntCode other) {
+    default boolean isSameCodeAs(@Nullable IWithIntCode other) {
         return other != null && getCode() == other.getCode();
     }
 
-    default boolean isSameCodeAs(IWithLongCode other) {
+    default boolean isSameCodeAs(@Nullable IWithLongCode other) {
         return other != null && getCode() == other.getCode();
     }
 }

src/main/java/xyz/zhouxy/plusone/commons/base/IWithLongCode.java

@@ -18,6 +18,8 @@ package xyz.zhouxy.plusone.commons.base;
 
 import java.util.Objects;
 
+import javax.annotation.Nullable;
+
 /**
  * 规定实现类带有 {@code getCode} 方法。
  * 用于像自定义异常等需要带有 {@code code} 字段的类，
@@ -32,15 +34,15 @@ public interface IWithLongCode {
         return getCode() == code;
     }
 
-    default boolean isSameCodeAs(IWithCode<?> other) {
+    default boolean isSameCodeAs(@Nullable IWithCode<?> other) {
         return other != null && Objects.equals(getCode(), other.getCode());
     }
 
-    default boolean isSameCodeAs(IWithIntCode other) {
+    default boolean isSameCodeAs(@Nullable IWithIntCode other) {
         return other != null && getCode() == other.getCode();
     }
 
-    default boolean isSameCodeAs(IWithLongCode other) {
+    default boolean isSameCodeAs(@Nullable IWithLongCode other) {
         return other != null && getCode() == other.getCode();
     }
 }

src/main/java/xyz/zhouxy/plusone/commons/base/package-info.java

@@ -0,0 +1,75 @@
+/*
+ * Copyright 2025 the original author or authors.
+ *
+ * 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.
+ */
+
+/**
+ * 基础组件
+ *
+ * <h2>Ref</h2>
+ * <p>
+ * {@link Ref} 包装了一个值，表示对该值的应用。
+ * </p>
+ * <p>灵感来自于 C# 的 {@value ref} 参数修饰符。C# 允许通过以下方式，将值返回给调用端：</p>
+ * <pre>
+ * void Method(ref int refArgument)
+ * {
+ *     refArgument = refArgument + 44;
+ * }
+ *
+ * int number = 1;
+ * Method(ref number);
+ * Console.WriteLine(number); // Output: 45
+ * </pre>
+ * {@link Ref} 使 Java 可以达到类似的效果，如：
+ * <pre>
+ * void method(Ref&lt;Integer&gt; refArgument) {
+ *     refArgument.transformValue(i -&gt; i + 44);
+ * }
+ *
+ * Ref&lt;Integer&gt; number = Ref.of(1);
+ * method(number);
+ * System.out.println(number.getValue()); // Output: 45
+ * </pre>
+ * <p>
+ * 当一个方法需要产生多个结果时，无法有多个返回值，可以使用 {@link Ref} 作为参数传入，方法内部修改 {@link Ref} 的值。
+ * 调用方在调用方法之后，使用 {@code getValue()} 获取结果。
+ * </p>
+ * <pre>
+ * String method(Ref&lt;Integer&gt; intRefArgument, Ref&lt;String&gt; strRefArgument) {
+ *     intRefArgument.transformValue(i -&gt; i + 44);
+ *     strRefArgument.setValue("Hello " + strRefArgument.getValue());
+ *     return "Return string";
+ * }
+ *
+ * Ref&lt;Integer&gt; number = Ref.of(1);
+ * Ref&lt;String&gt; str = Ref.of("Java");
+ * String result = method(number, str);
+ * System.out.println(number.getValue()); // Output: 45
+ * System.out.println(str.getValue()); // Output: Hello Java
+ * System.out.println(result); // Output: Return string
+ * </pre>
+ *
+ * <h2>IWithCode</h2>
+ * <p>
+ * 类似于枚举之类的类，通常需要设置固定的码值表示对应的含义。
+ * 可实现 {@link IWithCode}、{@link IWithIntCode}、{@link IWithLongCode}，便于在需要的地方对这些接口的实现进行处理。
+ * </p>
+ */
+@CheckReturnValue
+@ParametersAreNonnullByDefault
+package xyz.zhouxy.plusone.commons.base;
+
+import javax.annotation.ParametersAreNonnullByDefault;
+import javax.annotation.CheckReturnValue;

src/main/java/xyz/zhouxy/plusone/commons/function/package-info.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2025 the original author or authors.
+ *
+ * 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.
+ */
+
+/**
+ * 函数式编程
+ *
+ * <h2>PredicateTools</h2>
+ * <p>
+ * {@link PredicateTools} 用于 {@link java.util.function.Predicate} 的相关操作。
+ * </p>
+ *
+ * <h2>Functional interfaces</h2>
+ * <p>
+ * 补充一些 JDK 没有，而项目中可能用得上的函数式接口：
+ * <pre>
+ * | Group         | FunctionalInterface  | method                           |
+ * | ------------- | -------------------- | -------------------------------- |
+ * | UnaryOperator | BoolUnaryOperator    | boolean applyAsBool (boolean)    |
+ * | UnaryOperator | CharUnaryOperator    | char applyAsChar(char)           |
+ * | Throwing      | Executable           | void execute() throws E          |
+ * | Throwing      | ThrowingConsumer     | void accept(T) throws E          |
+ * | Throwing      | ThrowingPredicate    | boolean test(T) throws E         |
+ * | Throwing      | ThrowingSupplier     | T get() throws E                 |
+ * | Optional      | OptionalSupplier     | Optional&lt;T&gt; get() throws E       |
+ * | Optional      | ToOptionalBiFunction | Optional&lt;R&gt; apply(T,U)           |
+ * | Optional      | ToOptionalFunction   | Optional&lt;R&gt; apply(T)             |
+ * </pre>
+ * </p>
+ */
+package xyz.zhouxy.plusone.commons.function;