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 "<a href="http://bit.ly/anMa4g" target="_blank">Emulating 'self types' using Java Generics
029 * to simplify fluent API implementation</a>" 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 }