新增 base 和 function 的包说明

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

@@ -0,0 +1,76 @@
+/*
+ * Copyright 2024 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} 及相关的 {@link BoolRef}、{@link ByteRef}、{@link CharRef}、
+ * {@link DoubleRef}、{@link IntRef}、{@link LongRef} 包装了一个值，表示对该值的应用。
+ * </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} 及各个 {@code XxxRef} 使 Java 可以达到类似的效果，如：
+ * <pre>
+ * void method(IntRef refArgument) {
+ *     refArgument.apply(i -> i + 44);
+ * }
+ *
+ * IntRef number = IntRef.of(1);
+ * method(number);
+ * System.out.println(number.getValue()); // Output: 45
+ * </pre>
+ * <p>
+ * 当一个方法需要产生多个结果时，无法有多个返回值，可以使用 {@link Ref} 作为参数传入，方法内部修改 {@link Ref} 的值。
+ * 调用方在调用方法之后，使用 {@code getValue()} 获取结果。
+ * </p>
+ * <pre>
+ * String method(IntRef intRefArgument, Ref<String> strRefArgument) {
+ *     intRefArgument.apply(i -> i + 44);
+ *     strRefArgument.setValue("Hello " + strRefArgument.getValue());
+ *     return "Return string";
+ * }
+ *
+ * IntRef number = IntRef.of(1);
+ * Ref<String> 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>
+ *
+ * <h2>JRE</h2>
+ * <p>
+ * {@link JRE} 可获取当前 Java 版本号
+ * </p>
+ */
+package xyz.zhouxy.plusone.commons.base;

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

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2024 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 | ByteUnaryOperator    | byte applyAsByte(byte)           |
+ * | UnaryOperator | CharUnaryOperator    | char applyAsChar(char)           |
+ * | Throwing      | Executable           | void execute() throws E          |
+ * | Throwing      | ThrowingConsumer     | void accept(T) throws E          |
+ * | Throwing      | ThrowingFunction     | R apply(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;