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 }