Extend library API part 9 (#55)

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: JavaSaBr

README.md

@@ -14,7 +14,7 @@ repositories {
 }
 
 ext {
-   rlibVersion = "10.0.alpha9"
+   rlibVersion = "10.0.alpha10"
 }
 
 dependencies {

build.gradle

@@ -1,4 +1,4 @@
-rootProject.version = "10.0.alpha9"
+rootProject.version = "10.0.alpha10"
 group = 'javasabr.rlib'
 
 allprojects {

rlib-collections/src/main/java/javasabr/rlib/collections/array/MutableArray.java

@@ -1,6 +1,7 @@
 package javasabr.rlib.collections.array;
 
 import java.util.Collection;
+import java.util.Comparator;
 import java.util.Iterator;
 import java.util.function.Consumer;
 import java.util.function.IntFunction;
@@ -48,4 +49,8 @@ default void forEach(Consumer<? super E> action) {
 
   @Override
   UnsafeMutableArray<E> asUnsafe();
+  
+  void sort();
+  
+  void sort(Comparator<E> comparator);
 }

rlib-collections/src/main/java/javasabr/rlib/collections/array/impl/AbstractMutableArray.java

@@ -2,6 +2,7 @@
 
 import java.util.Arrays;
 import java.util.Collection;
+import java.util.Comparator;
 import java.util.Iterator;
 import java.util.Objects;
 import java.util.Spliterator;
@@ -10,6 +11,7 @@
 import java.util.stream.StreamSupport;
 import javasabr.rlib.collections.array.Array;
 import javasabr.rlib.collections.array.UnsafeMutableArray;
+import javasabr.rlib.common.util.ObjectUtils;
 import lombok.AccessLevel;
 import lombok.experimental.FieldDefaults;
 import org.jspecify.annotations.Nullable;
@@ -226,6 +228,31 @@ public UnsafeMutableArray<E> asUnsafe() {
     return this;
   }
 
+  @Override
+
+  public void sort() {
+    sortInternalArray(wrapped(), size());
+  }
+
+  @SuppressWarnings({
+      "rawtypes",
+      "unchecked"
+  })
+  protected void sortInternalArray(@Nullable E[] array, int size) {
+    if (Comparable.class.isAssignableFrom(type())) {
+      Comparable[] wrapped = (Comparable[]) array;
+      Arrays.sort(wrapped, 0, size, Comparator.naturalOrder());
+    } else {
+      throw new IllegalStateException(
+          "Cannot sort array of non-Comparable elements without an explicit comparator");
+    }
+  }
+  
+  @Override
+  public void sort(Comparator<E> comparator) {
+    Arrays.sort(wrapped(), 0, size(), comparator);
+  }
+
   protected static void validateCapacity(int capacity) {
     if (capacity < 0) {
       throw new IllegalArgumentException("Capacity cannot be negative");

rlib-collections/src/main/java/javasabr/rlib/collections/array/impl/CopyOnWriteMutableArray.java

@@ -2,6 +2,7 @@
 
 import java.util.Arrays;
 import java.util.Collection;
+import java.util.Comparator;
 import java.util.ConcurrentModificationException;
 import java.util.concurrent.atomic.AtomicReference;
 import javasabr.rlib.collections.array.Array;
@@ -208,4 +209,30 @@ protected int getAndIncrementSize() {
   protected int decrementAnGetSize() {
     return 0;
   }
+
+  @Override
+  public void sort() {
+    for (int i = 0; i < LIMIT_ATTEMPTS; i++) {
+      @Nullable E[] original = wrapped.get();
+      @Nullable E[] copy = Arrays.copyOf(original, original.length);
+      sortInternalArray(copy, copy.length);
+      if (wrapped.compareAndSet(original, copy)) {
+        return;
+      }
+    }
+    throw new ConcurrentModificationException("Cannot successfully sort this array");
+  }
+
+  @Override
+  public void sort(Comparator<E> comparator) {
+    for (int i = 0; i < LIMIT_ATTEMPTS; i++) {
+      @Nullable E[] original = wrapped.get();
+      @Nullable E[] copy = Arrays.copyOf(original, original.length);
+      Arrays.sort(copy, comparator);
+      if (wrapped.compareAndSet(original, copy)) {
+        return;
+      }
+    }
+    throw new ConcurrentModificationException("Cannot successfully sort this array");
+  }
 }

rlib-collections/src/test/java/javasabr/rlib/collections/array/MutableArrayTest.java

@@ -1,5 +1,6 @@
 package javasabr.rlib.collections.array;
 
+import java.util.Comparator;
 import java.util.List;
 import java.util.stream.Stream;
 import org.junit.jupiter.api.Assertions;
@@ -253,6 +254,36 @@ void shouldRenderToStringCorrectly(MutableArray<String> mutableArray) {
         mutableArray.toString());
   }
 
+  @ParameterizedTest
+  @MethodSource("generateMutableArrays")
+  @DisplayName("should sort array correctly")
+  void shouldSortArrayCorrectly(MutableArray<String> mutableArray) {
+    // given:
+    mutableArray.addAll(Array.of("10", "99", "5", "3", "77", "45", "25", "56"));
+    
+    // when:
+    mutableArray.sort();
+    
+    // then:
+    var expected = Array.of("10", "25", "3", "45", "5", "56", "77", "99");
+    Assertions.assertEquals(expected, mutableArray);
+  }
+
+  @ParameterizedTest
+  @MethodSource("generateMutableArrays")
+  @DisplayName("should sort array using comparator correctly")
+  void shouldSortArrayUsingComparatorCorrectly(MutableArray<String> mutableArray) {
+    // given:
+    mutableArray.addAll(Array.of("10", "99", "5", "3", "77", "45", "25", "56"));
+
+    // when:
+    mutableArray.sort(Comparator.comparingInt(Integer::parseInt));
+
+    // then:
+    var expected = Array.of("3", "5", "10", "25", "45", "56", "77", "99");
+    Assertions.assertEquals(expected, mutableArray);
+  }
+
   private static Stream<Arguments> generateMutableArrays() {
     return Stream.of(
         Arguments.of(ArrayFactory.mutableArray(String.class)),

rlib-common/src/main/java/javasabr/rlib/common/AliasedEnum.java

@@ -0,0 +1,31 @@
+package javasabr.rlib.common;
+
+import java.util.Collection;
+
+/**
+ * Marks an {@link Enum} whose constants expose one or more string aliases.
+ * <p>
+ * Implementing enums can provide alternative string representations for each constant,
+ * which can be used, for example, for parsing user input, configuration values,
+ * or external identifiers that do not necessarily match the constant {@code name()}.
+ *
+ * @param <T> the concrete enum type implementing this interface
+ */
+public interface AliasedEnum<T extends Enum<T>> {
+
+  /**
+   * Returns the string aliases associated with this enum constant.
+   * <p>
+   * An alias is an alternative textual identifier for the constant, such as a
+   * short name, legacy name, or external code, that can be used for lookup
+   * or serialization instead of the enum's {@link Enum#name()}.
+   * <p>
+   * Implementations should never return {@code null}; an empty collection
+   * indicates that the constant has no aliases. Callers should not modify
+   * the returned collection unless the implementation explicitly documents
+   * that it is mutable.
+   *
+   * @return a non-{@code null} collection of aliases for this constant
+   */
+  Collection<String> aliases();
+}

rlib-common/src/main/java/javasabr/rlib/common/util/AliasedEnumMap.java

@@ -0,0 +1,52 @@
+package javasabr.rlib.common.util;
+
+import java.util.HashMap;
+import java.util.Map;
+import javasabr.rlib.common.AliasedEnum;
+import lombok.AccessLevel;
+import lombok.CustomLog;
+import lombok.experimental.FieldDefaults;
+import org.jspecify.annotations.Nullable;
+
+@CustomLog
+@FieldDefaults(level = AccessLevel.PRIVATE, makeFinal = true)
+public class AliasedEnumMap<T extends Enum<T> & AliasedEnum<T>> {
+
+  Map<String, T> aliasToValue;
+
+  public AliasedEnumMap(Class<T> enumClass) {
+    var enumConstants = enumClass.getEnumConstants();
+    var aliasToValue = new HashMap<String, T>();
+
+    for (T enumConstant : enumConstants) {
+      for (String alias : enumConstant.aliases()) {
+        T previous = aliasToValue.put(alias, enumConstant);
+        if (previous != null) {
+          throw new IllegalArgumentException("Detected duplicated alias:[%s] for [%s] and [%s]".formatted(
+              alias,
+              previous.name(),
+              enumConstant.name()));
+        }
+      }
+    }
+    this.aliasToValue = Map.copyOf(aliasToValue);
+  }
+
+  @Nullable
+  public T resolve(String alias) {
+    return aliasToValue.get(alias);
+  }
+
+  public T resolve(String alias, T def) {
+    T resolved = resolve(alias);
+    return resolved == null ? def : resolved;
+  }
+
+  public T require(String alias) {
+    T constant = resolve(alias);
+    if (constant == null) {
+      throw new IllegalArgumentException("Unknown enum constant for alias:[%s]".formatted(alias));
+    }
+    return constant;
+  }
+}

rlib-common/src/main/java/javasabr/rlib/common/util/StringUtils.java

@@ -37,16 +37,27 @@ public static String emptyIfNull(@Nullable String string) {
   }
 
   /**
-   * Return the another string if the received string is empty.
+   * Return the another string if the received string is empty or null.
    *
    * @param string the string.
    * @param another the another string.
-   * @return the another string if the received string is empty.
+   * @return the another string if the received string is empty or null.
    */
   public static String ifEmpty(@Nullable String string, String another) {
     return isEmpty(string) ? another : string;
   }
 
+  /**
+   * Return the another string if the received string is blank or null.
+   *
+   * @param string the string.
+   * @param another the another string.
+   * @return the another string if the received string is blank or null.
+   */
+  public static String ifBlank(@Nullable String string, String another) {
+    return isBlank(string) ? another : string;
+  }
+  
   /**
    * Check a string email.
    *
@@ -212,7 +223,7 @@ private static MessageDigest getHashMD5() {
   }
 
   /**
-   * Returns true if the string empty or null.
+   * Returns true if the string is empty or null.
    *
    * @param string the string.
    * @return true if the string is null or empty.
@@ -221,6 +232,16 @@ public static boolean isEmpty(@Nullable String string) {
     return string == null || string.isEmpty();
   }
 
+  /**
+   * Returns true if the string is blank or null.
+   *
+   * @param string the string.
+   * @return true if the string is null or blank.
+   */
+  public static boolean isBlank(@Nullable String string) {
+    return string == null || string.isBlank();
+  }
+
   /**
    * Returns true if the string isn't empty.
    *
@@ -231,6 +252,16 @@ public static boolean isNotEmpty(@Nullable String string) {
     return !isEmpty(string);
   }
 
+  /**
+   * Returns true if the string isn't blank.
+   *
+   * @param string the string.
+   * @return true if the string isn't blank.
+   */
+  public static boolean isNotBlank(@Nullable String string) {
+    return !isBlank(string);
+  }
+
   /**
    * Gets the length of the string.
    *

rlib-common/src/test/java/javasabr/rlib/common/util/AliasedEnumMapTest.java

@@ -0,0 +1,63 @@
+package javasabr.rlib.common.util;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import java.util.Collection;
+import java.util.List;
+import java.util.Set;
+import javasabr.rlib.common.AliasedEnum;
+import org.jspecify.annotations.NonNull;
+import org.junit.jupiter.api.Test;
+
+class AliasedEnumMapTest {
+
+  public enum TestEnum implements AliasedEnum<@NonNull TestEnum> {
+    CONSTANT1(Set.of("cnst1", "constant1", "CONSTANT1")),
+    CONSTANT2(Set.of("cnst2", "constant2", "CONSTANT2")),
+    CONSTANT3(Set.of("cnst3", "constant3", "CONSTANT3")),
+    CONSTANT4(Set.of("cnst4", "constant4", "CONSTANT4")),
+    CONSTANT5(Set.of("cnst5", "constant5", "CONSTANT5"));
+
+    private static final AliasedEnumMap<TestEnum> MAP = new AliasedEnumMap<>(TestEnum.class);
+
+    private final Collection<String> aliases;
+
+    TestEnum(Collection<String> aliases) {
+      this.aliases = aliases;
+    }
+
+    @Override
+    public Collection<String> aliases() {
+      return aliases;
+    }
+  }
+
+  @Test
+  void shouldResolveEnumByAlias() {
+    // when\then:
+    assertThat(TestEnum.MAP.resolve("cnst1")).isEqualTo(TestEnum.CONSTANT1);
+    assertThat(TestEnum.MAP.resolve("constant1")).isEqualTo(TestEnum.CONSTANT1);
+    assertThat(TestEnum.MAP.resolve("CONSTANT1")).isEqualTo(TestEnum.CONSTANT1);
+    assertThat(TestEnum.MAP.resolve("cnst2")).isEqualTo(TestEnum.CONSTANT2);
+    assertThat(TestEnum.MAP.resolve("CONSTANT2")).isEqualTo(TestEnum.CONSTANT2);
+    assertThat(TestEnum.MAP.resolve("constant3")).isEqualTo(TestEnum.CONSTANT3);
+    assertThat(TestEnum.MAP.resolve("CONSTANT4")).isEqualTo(TestEnum.CONSTANT4);
+    assertThat(TestEnum.MAP.resolve("unknown")).isNull();
+    assertThat(TestEnum.MAP.resolve("")).isNull();
+    assertThat(TestEnum.MAP.resolve("unknown", TestEnum.CONSTANT4)).isEqualTo(TestEnum.CONSTANT4);
+  }
+
+  @Test
+  void shouldRequireEnumByAlias() {
+    // when\then:
+    assertThat(TestEnum.MAP.require("cnst1")).isEqualTo(TestEnum.CONSTANT1);
+    assertThat(TestEnum.MAP.require("CONSTANT2")).isEqualTo(TestEnum.CONSTANT2);
+    assertThat(TestEnum.MAP.require("cnst3")).isEqualTo(TestEnum.CONSTANT3);
+    assertThat(TestEnum.MAP.require("constant4")).isEqualTo(TestEnum.CONSTANT4);
+    assertThatThrownBy(() -> TestEnum.MAP.require("unknown"))
+        .isInstanceOf(IllegalArgumentException.class);
+    assertThatThrownBy(() -> TestEnum.MAP.require(""))
+        .isInstanceOf(IllegalArgumentException.class);
+  }
+}