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 wether 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     */
034    public interface ArraySortedAssert<S, E> {
035    
036      /**
037       * Verifies that the actual array is sorted into ascending order according to the natural ordering of its elements.
038       * <p>
039       * All array elements must be primitive or implement the {@link Comparable} interface and must be mutually comparable
040       * (that is, e1.compareTo(e2) must not throw a ClassCastException for any elements e1 and e2 in the array), examples :
041       * <ul>
042       * <li>a array composed of {2, 4, 6} is ok because the element type is a primitive type.</li>
043       * <li>a array composed of {"a1", "a2", "a3"} is ok because the element type (String) is Comparable</li>
044       * <li>a array composed of Rectangle {r1, r2, r3} is <b>NOT ok</b> because Rectangle is not Comparable</li>
045       * <li>a array composed of {True, "abc", False} is <b>NOT ok</b> because elements are not mutually comparable (even
046       * though each element type implements Comparable)</li>
047       * </ul>
048       * Empty or one element arrays are considered sorted (unless the array element type is not Comparable).</br></br>
049       * 
050       * @return {@code this} assertion object.
051       * 
052       * @throws AssertionError if the actual array is not sorted into ascending order according to the natural ordering of
053       *           its elements.
054       * @throws AssertionError if the actual array is <code>null</code>.
055       * @throws AssertionError if the actual array element type does not implement {@link Comparable}.
056       * @throws AssertionError if the actual array elements are not mutually {@link Comparable}.
057       */
058      S isSorted();
059    
060      /**
061       * Verifies that the actual array is sorted according to the given comparator.</br> Empty arrays are considered sorted
062       * whatever the comparator is.</br> One element arrays are considered sorted if element is compatible with comparator,
063       * otherwise an AssertionError is thrown.
064       * 
065       * @param comparator the {@link Comparator} used to compare array elements
066       * 
067       * @return {@code this} assertion object.
068       * 
069       * @throws AssertionError if the actual array is not sorted according to the given comparator.
070       * @throws AssertionError if the actual array is <code>null</code>.
071       * @throws NullPointerException if the given comparator is <code>null</code>.
072       * @throws AssertionError if the actual array elements are not mutually comparabe according to given Comparator.
073       */
074      S isSortedAccordingTo(Comparator<? extends E> comparator);
075    
076    }