001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.text.similarity;
018
019/**
020 * The hamming distance between two strings of equal length is the number of
021 * positions at which the corresponding symbols are different.
022 *
023 * <p>
024 * For further explanation about the Hamming Distance, take a look at its
025 * Wikipedia page at https://en.wikipedia.org/wiki/Hamming_distance.
026 * </p>
027 *
028 * @since 1.0
029 */
030public class HammingDistance implements EditDistance<Integer> {
031
032    /**
033     * Find the Hamming Distance between two strings with the same
034     * length.
035     *
036     * <p>The distance starts with zero, and for each occurrence of a
037     * different character in either String, it increments the distance
038     * by 1, and finally return its value.</p>
039     *
040     * <p>Since the Hamming Distance can only be calculated between strings of equal length, input of different lengths
041     * will throw IllegalArgumentException</p>
042     *
043     * <pre>
044     * distance.apply("", "")               = 0
045     * distance.apply("pappa", "pappa")     = 0
046     * distance.apply("1011101", "1011111") = 1
047     * distance.apply("ATCG", "ACCC")       = 2
048     * distance.apply("karolin", "kerstin"  = 3
049     * </pre>
050     *
051     * @param left the first CharSequence, must not be null
052     * @param right the second CharSequence, must not be null
053     * @return distance
054     * @throws IllegalArgumentException if either input is {@code null} or
055     *             if they do not have the same length
056     */
057    @Override
058    public Integer apply(final CharSequence left, final CharSequence right) {
059        if (left == null || right == null) {
060            throw new IllegalArgumentException("CharSequences must not be null");
061        }
062
063        if (left.length() != right.length()) {
064            throw new IllegalArgumentException("CharSequences must have the same length");
065        }
066
067        int distance = 0;
068
069        for (int i = 0; i < left.length(); i++) {
070            if (left.charAt(i) != right.charAt(i)) {
071                distance++;
072            }
073        }
074
075        return distance;
076    }
077
078}