Commits

Bogdan Mart committed 76916eb

JavaDoc

Comments (0)

Files changed (3)

 }
 
 tasks.getByName("javadoc") {
-    options.links ("http://docs.oracle.com/javase/6/docs/api/")
+    options.links (
+            "http://docs.oracle.com/javase/6/docs/api/",
+            "http://mart_bogdan.bitbucket.org/Generic-Arithmetic/api/"
+    )
 }
 
 task javadocJar(type: Jar, dependsOn: javadoc) {

src/main/java/com/innahema/collections/query/queriables/Queryable.java

     }
 
     /**
-     * converts array to Queriable.
+     * converts array to Queryable.
      * <br>
      * <i>Note -- all operations will be performed  around original <b>array</b>.</i>
      * @param <T> generic type
 
     //--------------------------------- min/max
 
+    /**
+     * Finds maximum value between elements in sequence, elements must be {@link Comparable},
+     * {@link IllegalStateException} will be thrown otherwise
+     * @return maximum value
+     * @throws IllegalStateException if elements of collection aren't {@link Comparable}
+     */
     @Nullable
     @SuppressWarnings("unchecked")
     public T max() {
         }
     }
 
+    /**
+     * Finds minimum value between elements in sequence, elements must be {@link Comparable},
+     * {@link IllegalStateException} will be thrown otherwise
+     * @return minimum value
+     * @throws IllegalStateException if elements of collection aren't {@link Comparable}
+     */
     @Nullable
     @SuppressWarnings("unchecked")
     public T min() {
         }
     }
 
+    /**
+     * Finds minimum value between elements in sequence, using specified {@link Comparator}
+     * @param comparator comparator to be used during search
+     * @return minimum value
+     */
     @Nullable
     public T min(@NotNull Comparator<T> comparator) {
         T acc=null;
         return acc;
     }
 
+    /**
+     * Finds maximum value between elements in sequence, using specified {@link Comparator}
+     * @param comparator comparator to be used during search
+     * @return maximum value
+     */
     @Nullable
     public T max(@NotNull Comparator<T> comparator) {
         T acc=null;
         return acc;
     }
 
+    /**
+     * Finds <b>minimum</b> value between elements in sequence, comparation is made only between special fields,
+     * selected by {@code keySelector}, which must be {@link Comparable}, {@link IllegalStateException} will be thrown otherwise.
+     * <br>Example:<br> {@code  Queryable.from("sdsd","sfsffff").min(s->s.length());
+     * // will retutn "sdsd"}
+     * @throws IllegalStateException if keys aren't {@link Comparable}
+     * @param keySelector function to select key, which will be compared to find <b>minimum</b> object
+     * @param <TKey> type of key. <b>TKey</b> extends <b>Comparable&lt;TKey&gt;</b>
+     * @return minimum value
+     */
     @Nullable
     public <TKey extends Comparable<TKey>> T min(@NotNull Function1<T,TKey> keySelector) {
         try {
         }
     }
 
+    /**
+     * Finds <b>maximum</b> value between elements in sequence, comparation is made only between special fields,
+     * selected by {@code keySelector}, which must be {@link Comparable}, {@link IllegalStateException} will be thrown otherwise.
+     * <br>Example:<br> {@code  Queryable.from("sdsd","sfsffff").max(s->s.length());
+     * // will retutn "sfsffff"}
+     * @throws IllegalStateException if keys aren't {@link Comparable}
+     * @param keySelector function to select key, which will be compared to find <b>maximum</b> object
+     * @param <TKey> type of key. <b>TKey</b> extends <b>Comparable&lt;TKey&gt;</b>
+     * @return maximum value
+     */
     @Nullable
     public <TKey extends Comparable<TKey>> T max(@NotNull Function1<T,TKey> keySelector) {
         try {
         }
     }
 
+    /**
+     * Finds <b>minimum</b> value between elements in sequence, comparation is made only between special fields,
+     * selected by {@code keySelector}, using specified {@link Comparator} .<br>
+     * Actually {@link Queryable#min(Function1)} was designed especially,
+     * to get rid of custom {@link Comparable Comparables}, but there are some perverted case when you can actually want
+     * to use this method.
+     * <br>For example:<br>
+     *     {@code Queryable.from(getAllPersons()).min(p->p.getCar(), new CarComparator());}
+     * <br>or<br>
+     * <pre>{@code
+     * Comparator<?> comparator =
+     *      (Comparator<>)Class.forName("javax.swing.table.TableRowSorter.ComparableComparator")
+     *                         .newInstance();
+     * Queryable.from(getAllPersons()).min(
+     *                                     p      -> p.getCar(),
+     *                                    (c1,c2) -> comparator.compare(c1.getAge(),c2.getAge()) 
+     *                                 );} </pre>
+     * Please notice, that both <b>c1</b>and <b>c2</b> can't be null, so second action won't be called, this can be used for null safety
+     * @throws IllegalStateException if keys aren't {@link Comparable}
+     * @param keySelector function to select key, which will be compared to find <b>minimum</b> object
+     * @param comparator comparator to be used during search
+     * @param <TKey> type of key. <b>TKey</b> extends <b>Comparable&lt;TKey&gt;</b>
+     * @return minimum value
+     */
+
     @Nullable
     public <TKey> T min(@NotNull Function1<T,TKey> keySelector, @NotNull Comparator<TKey> comparator) {
         T acc=null;
                 accKey = valKey;
                 continue;
             }
-            if(comparator.compare(accKey,valKey)>0) {
+            if(valKey != null && comparator.compare(accKey,valKey)>0) {
                 acc = val;
                 accKey = valKey;
             }
         return acc;
     }
 
+    /**
+     * Finds <b>maximum</b> value between elements in sequence, comparation is made only between special fields,
+     * selected by {@code keySelector}, using specified {@link Comparator} .<br>
+     * Actually {@link Queryable#max(Function1)} was designed especially,
+     * to get rid of custom {@link Comparable Comparables}, but there are some perverted case when you can actually want
+     * to use this method.
+     * <br>For example:<br>
+     *     {@code  Queryable.from(getAllPersons()).max(p->p.getCar(), new CarComparator());}
+     * <br>or<br>
+     * <pre>{@code
+     * Comparator<?> comparator =
+     *      (Comparator<>)Class.forName("javax.swing.table.TableRowSorter.ComparableComparator")
+     *                         .newInstance();
+     * Queryable.from(getAllPersons()).max(
+     *                                     p      -> p.getCar(),
+     *                                    (c1,c2) -> comparator.compare(c1.getAge(),c2.getAge()) 
+     *                                 );} </pre>
+     * Please notice, that both <b>c1</b>and <b>c2</b> can't be null, so second action won't be called, this can be used for null safety
+     * @throws IllegalStateException if keys aren't {@link Comparable}
+     * @param keySelector function to select key, which will be compared to find <b>maximum</b> object
+     * @param comparator comparator to be used during search
+     * @param <TKey> type of key. <b>TKey</b> extends <b>Comparable&lt;TKey&gt;</b>
+     * @return maximum value
+     */
     @Nullable
     public <TKey> T max(@NotNull Function1<T,TKey> keySelector, @NotNull Comparator<TKey> comparator) {
         T acc=null;
                 accKey = valKey;
                 continue;
             }
-            if(comparator.compare(accKey,valKey)<0) {
+            if(valKey != null && comparator.compare(accKey,valKey)<0) {
                 acc = val;
                 accKey = valKey;
             }
     }
     //-------------------------------- sum
 
+    /**
+     * Calculates sum of all elements of collection
+     * @return sum of all elements of collection
+     * @throws ArithmeticException in case if underlying type isn't processable by {@link Arithmetic GenericArithmetic}
+     */
     @Nullable
     public T sum() throws ArithmeticException
     {
         return (acc != null ? uncheckedCast(acc.value()) : null);
     }
 
+    /**
+     * Calculates production of all elements of collection
+     * @return production of all elements of collection
+     * @throws ArithmeticException in case if underlying type isn't processable by {@link Arithmetic GenericArithmetic}
+     */
     @Nullable
     public T product()  throws ArithmeticException
     {
         return (acc != null ? uncheckedCast(acc.value()) : null);
     }
 
+    /**
+     * Just for semantic compatibility (if you want to calculate sum for non numeric type).
+     * It just redirects to {@link Queryable#fold(Function2)}
+     * @param operator function to be applied to each element, example:
+     * <pre>{@code
+     * s=f(e1,e2);
+     * s=f(s,e3);
+     * s=f(s,e4);
+     * return s; }</pre>
+     * @return result of operation
+     */
     @Nullable
-    public T sum(Function2<T,T,T> operator) throws ArithmeticException
+    public T sum(Function2<T,T,T> operator)
     {
         return fold(operator);
     }
 
+    /**
+     * Just for semantic compatibility (if you want to calculate product for non numeric type).
+     * It just redirects to {@link Queryable#fold(Function2)}
+     * @param operator function to be applied to each element, example:
+     * <pre>{@code
+     * s=f(e1,e2);
+     * s=f(s,e3);
+     * s=f(s,e4);
+     * return s; }</pre>
+     * @return result of operation
+     */
     @Nullable
-    public T product(Function2<T,T,T> operator) throws ArithmeticException
+    public T product(Function2<T,T,T> operator)
     {
         return fold(operator);
     }

src/test/java/com/innahema/collections/query/queriables/QueryableTest.java

 
         assertEquals(0, (int) ints.max((x,y) -> -x.compareTo(y)));
         assertEquals(6, (int) ints.min((x,y) -> -x.compareTo(y)));
+
+        Queryable.from("sdsd","sfsffff").min(s->s.length());
     }
 
     @Test(expected = IllegalStateException.class)