001    /*
002     * Created on Jul 25, 2010
003     * 
004     * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
005     * the License. You may obtain a copy of the License at
006     * 
007     * http://www.apache.org/licenses/LICENSE-2.0
008     * 
009     * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
010     * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
011     * specific language governing permissions and limitations under the License.
012     * 
013     * Copyright @2010-2011 the original author or authors.
014     */
015    package org.fest.assertions.core;
016    
017    import java.util.Comparator;
018    
019    /**
020     * Assertions applicable to primitive arrays or arrays of elements either naturally {@link Comparable} or according to a
021     * given {@link Comparator}.
022     * <p>
023     * Note that the contract defined here is can't be totally applied to List (that's why its name is not SortedAssert),
024     * the differences being that we can't check that - for empty List - the list parameter is comparable or compatible with given comparator
025     * due to type erasure.
026     * 
027     * @param <S> the "self" type of this assertion class that must be a array type (e.g. arrays, collections).<br>
028     *          Please read &quot;<a href="http://bit.ly/anMa4g" target="_blank">Emulating 'self types' using Java Generics
029     *          to simplify fluent API implementation</a>&quot; for more details.
030     * @param <E> the array element type.
031     * 
032     * @author Joel Costigliola
033     * @author Mikhail Mazursky
034     */
035    public interface ArraySortedAssert<S, E> {
036    
037      /**
038       * Verifies that the actual array is sorted into ascending order according to the natural ordering of its elements.
039       * <p>
040       * All array elements must be primitive or implement the {@link Comparable} interface and must be mutually comparable
041       * (that is, e1.compareTo(e2) must not throw a ClassCastException for any elements e1 and e2 in the array), examples :
042       * <ul>
043       * <li>a array composed of {2, 4, 6} is ok because the element type is a primitive type.</li>
044       * <li>a array composed of {"a1", "a2", "a3"} is ok because the element type (String) is Comparable</li>
045       * <li>a array composed of Rectangle {r1, r2, r3} is <b>NOT ok</b> because Rectangle is not Comparable</li>
046       * <li>a array composed of {True, "abc", False} is <b>NOT ok</b> because elements are not mutually comparable (even
047       * though each element type implements Comparable)</li>
048       * </ul>
049       * Empty or one element arrays are considered sorted (unless the array element type is not Comparable).</br></br>
050       * 
051       * @return {@code this} assertion object.
052       * 
053       * @throws AssertionError if the actual array is not sorted into ascending order according to the natural ordering of
054       *           its elements.
055       * @throws AssertionError if the actual array is <code>null</code>.
056       * @throws AssertionError if the actual array element type does not implement {@link Comparable}.
057       * @throws AssertionError if the actual array elements are not mutually {@link Comparable}.
058       */
059      S isSorted();
060    
061      /**
062       * Verifies that the actual array is sorted according to the given comparator.</br> Empty arrays are considered sorted
063       * whatever the comparator is.</br> One element arrays are considered sorted if element is compatible with comparator,
064       * otherwise an AssertionError is thrown.
065       * 
066       * @param comparator the {@link Comparator} used to compare array elements
067       * 
068       * @return {@code this} assertion object.
069       * 
070       * @throws AssertionError if the actual array is not sorted according to the given comparator.
071       * @throws AssertionError if the actual array is <code>null</code>.
072       * @throws NullPointerException if the given comparator is <code>null</code>.
073       * @throws AssertionError if the actual array elements are not mutually comparable according to given Comparator.
074       */
075      S isSortedAccordingTo(Comparator<? super E> comparator);
076    
077    }