1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 package org.apache.commons.text.similarity; 19 20 import java.util.Objects; 21 22 /** 23 * An ordered input of elements used to compute a similarity score. 24 * <p> 25 * You can implement a SimilarityInput on a domain object instead of CharSequence where implementing CharSequence does not make sense. 26 * </p> 27 * 28 * @param <E> the type of elements in this input. 29 * @since 1.13.0 30 */ 31 public interface SimilarityInput<E> { 32 33 /** 34 * Creates a new input for a {@link CharSequence}. 35 * 36 * @param cs input character sequence. 37 * @return a new input. 38 */ 39 static SimilarityInput<Character> input(final CharSequence cs) { 40 return new SimilarityCharacterInput(cs); 41 } 42 43 /** 44 * Creates a new input for a {@link CharSequence} or {@link SimilarityInput}. 45 * 46 * @param <T> The type of similarity score unit. 47 * @param input character sequence or similarity input. 48 * @return a new input. 49 * @throws IllegalArgumentException when the input type is neither {@link CharSequence} or {@link SimilarityInput}. 50 */ 51 @SuppressWarnings("unchecked") 52 static <T> SimilarityInput<T> input(final Object input) { 53 if (input instanceof SimilarityInput) { 54 return (SimilarityInput<T>) input; 55 } 56 if (input instanceof CharSequence) { 57 return (SimilarityInput<T>) input((CharSequence) input); 58 } 59 throw new IllegalArgumentException(Objects.requireNonNull(input, "input").getClass().getName()); 60 } 61 62 /** 63 * Gets the element in the input at the given 0-based index. 64 * 65 * @param index a 0-based index. 66 * @return the element in the input at the given 0-based index. 67 */ 68 E at(int index); 69 70 /** 71 * Gets the length of the input. 72 * 73 * @return the length of the input. 74 */ 75 int length(); 76 77 }