(causeway) branch master updated: CAUSEWAY-3404: Can: adds accessors relative to last

[ahuber]

This is an automated email from the ASF dual-hosted git repository.

ahuber pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/causeway.git


The following commit(s) were added to refs/heads/master by this push:
     new 5d30332fd4 CAUSEWAY-3404: Can: adds accessors relative to last
5d30332fd4 is described below

commit 5d30332fd46a08d8d8d0d5aff8d9cecaf719a464
Author: Andi Huber <ahu...@apache.org>
AuthorDate: Wed Feb 7 11:02:06 2024 +0100

    CAUSEWAY-3404: Can: adds accessors relative to last
---
 .../apache/causeway/commons/collections/Can.java   | 25 ++++++++++++++++++----
 1 file changed, 21 insertions(+), 4 deletions(-)

diff --git 
a/commons/src/main/java/org/apache/causeway/commons/collections/Can.java 
b/commons/src/main/java/org/apache/causeway/commons/collections/Can.java
index 22c25d83ea..fc4e9fc011 100644
--- a/commons/src/main/java/org/apache/causeway/commons/collections/Can.java
+++ b/commons/src/main/java/org/apache/causeway/commons/collections/Can.java
@@ -72,13 +72,22 @@ public interface Can<T>
 extends ImmutableCollection<T>, Comparable<Can<T>>, Serializable {
 
     /**
-     * Will only ever return an empty Optional, if the elementIndex is out of 
bounds.
+     * Will (only ever) return an empty {@link Optional}, if the elementIndex 
is out of bounds.
      * @param elementIndex
      * @return optionally this Can's element with index {@code elementIndex},
      * based on whether this index is within bounds
      */
     Optional<T> get(int elementIndex);
 
+    /**
+     * Shortcut for {@code get(this.size() - 1 - (-offset))} 
+     * @param offset - expected zero or negative (zero returning the last 
element)
+     * @see #get(int)
+     */
+    default Optional<T> getRelativeToLast(int offset) {
+        return get(size() - 1 + offset);
+    }
+    
     /**
      * Shortcut to {@code get(elementIndex).orElseThrow(...)}
      * <p>
@@ -93,6 +102,15 @@ extends ImmutableCollection<T>, Comparable<Can<T>>, 
Serializable {
                 .orElseThrow(()->new NoSuchElementException(
                         "no element with elementIndex = " + elementIndex));
     }
+    
+    /**
+     * Shortcut for {@code getElseFail(this.size() - 1 - (-offset))} 
+     * @param offset - expected zero or negative (zero returning the last 
element)
+     * @see #getElseFail(int)
+     */
+    default T getRelativeToLastElseFail(final int offset) {
+        return getElseFail(size() - 1 + offset);
+    }
 
     /**
      * For convenience allows the argument to be {@code null} treating {@code 
null}
@@ -589,14 +607,13 @@ extends ImmutableCollection<T>, Comparable<Can<T>>, 
Serializable {
 
     /**
      * Returns a sub-{@link Can} that is made of elements from this {@link 
Can},
-     * when selected by those indices,
-     * that result from given range {@code [startInclusive, endExclusive]}.
+     * when selected by indices from given range {@code [startInclusive, 
endExclusive)}.
      * <p>
      * Out of bounds picking is simply ignored.
      *
      * @param startInclusive the (inclusive) initial index
      * @param endExclusive the exclusive upper bound index
-     *      - if negative is interpreted as {@code this.size - 
abs(endExclusive)}
+     *      - if negative is interpreted as {@code this.size() - 
abs(endExclusive)}
      */
     Can<T> subCan(int startInclusive, int endExclusive);