Coverage Report

 /*
  * Licensed to the Apache Software Foundation (ASF) under one or more
  * contributor license agreements.  See the NOTICE file distributed with
  * this work for additional information regarding copyright ownership.
  * The ASF licenses this file to You under the Apache License, Version 2.0
  * (the "License"); you may not use this file except in compliance with
  * the License.  You may obtain a copy of the License at
  *
  *      http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 
 package org.apache.commons.codec.language.bm;
 
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Collections;
 import java.util.EnumMap;
 import java.util.HashSet;
 import java.util.Iterator;
 import java.util.LinkedHashSet;
 import java.util.List;
 import java.util.Locale;
 import java.util.Map;
 import java.util.Set;
 import java.util.TreeSet;
 
 /**
  * Converts words into potential phonetic representations.
  * <p>
  * This is a two-stage process. Firstly, the word is converted into a phonetic representation that takes
  * into account the likely source language. Next, this phonetic representation is converted into a
  * pan-european 'average' representation, allowing comparison between different versions of essentially
  * the same word from different languages.
  * <p>
  * This class is intentionally immutable. If you wish to alter the settings for a PhoneticEngine, you
  * must make a new one with the updated settings. This makes the class thread-safe.
  * <p>
  * Ported from phoneticengine.php
  *
  * @since 1.6
  * @version $Id$
  */
 public class PhoneticEngine {
 
     /**
      * Utility for manipulating a set of phonemes as they are being built up. Not intended for use outside
      * this package, and probably not outside the {@link PhoneticEngine} class.
      *
      * @since 1.6
      */
     static final class PhonemeBuilder {
 
         /**
          * An empty builder where all phonemes must come from some set of languages. This will contain a single
          * phoneme of zero characters. This can then be appended to. This should be the only way to create a new
          * phoneme from scratch.
          *
          * @param languages the set of languages
          * @return  a new, empty phoneme builder
          */
         public static PhonemeBuilder empty(Languages.LanguageSet languages) {
             return new PhonemeBuilder(Collections.singleton(new Rule.Phoneme("", languages)));
         }
 
         private final Set<Rule.Phoneme> phonemes;
 
         private PhonemeBuilder(Set<Rule.Phoneme> phonemes) {
             this.phonemes = phonemes;
         }
 
         /**
          * Creates a new phoneme builder containing all phonemes in this one extended by <code>str</code>.
          *
          * @param str   the characters to append to the phonemes
          * @return  a new phoneme builder lenghtened by <code>str</code>
          */
         public PhonemeBuilder append(CharSequence str) {
             Set<Rule.Phoneme> newPhonemes = new LinkedHashSet<Rule.Phoneme>();
 
             for (Rule.Phoneme ph : this.phonemes) {
                 newPhonemes.add(ph.append(str));
             }
 
             return new PhonemeBuilder(newPhonemes);
         }
 
         /**
          * Creates a new phoneme builder containing the application of the expression to all phonemes in this builder.
          * <p>
          * This will lengthen phonemes that have compatible language sets to the expression, and drop those that are
          * incompatible.
          *
          * @param phonemeExpr   the expression to apply
          * @param maxPhonemes   the maximum number of phonemes to build up
          * @return  a new phoneme builder containing the results of <code>phonemeExpr</code> applied to each phoneme
          *      in turn
          */
         public PhonemeBuilder apply(Rule.PhonemeExpr phonemeExpr, int maxPhonemes) {
             Set<Rule.Phoneme> newPhonemes = new LinkedHashSet<Rule.Phoneme>();
 
             EXPR: for (Rule.Phoneme left : this.phonemes) {
                 for (Rule.Phoneme right : phonemeExpr.getPhonemes()) {
                     Rule.Phoneme join = left.join(right);
                     if (!join.getLanguages().isEmpty()) {
                         if (newPhonemes.size() < maxPhonemes) {
                             newPhonemes.add(join);
                         } else {
                             break EXPR;
                         }
                     }
                 }
             }
 
             return new PhonemeBuilder(newPhonemes);
         }
 
         /**
          * Gets underlying phoneme set. Please don't mutate.
          *
          * @return  the phoneme set
          */
         public Set<Rule.Phoneme> getPhonemes() {
             return this.phonemes;
         }
 
         /**
          * Stringifies the phoneme set. This produces a single string of the strings of each phoneme,
          * joined with a pipe. This is explicitly provided in place of toString as it is a potentially
          * expensive operation, which should be avoided when debugging.
          *
          * @return  the stringified phoneme set
          */
         public String makeString() {
             final StringBuilder sb = new StringBuilder();
 
             for (Rule.Phoneme ph : this.phonemes) {
                 if (sb.length() > 0) {
                     sb.append("|");
                 }
                 sb.append(ph.getPhonemeText());
             }
 
             return sb.toString();
         }
     }
 
     /**
      * A function closure capturing the application of a list of rules to an input sequence at a particular offset.
      * After invocation, the values <code>i</code> and <code>found</code> are updated. <code>i</code> points to the
      * index of the next char in <code>input</code> that must be processed next (the input up to that index having been
      * processed already), and <code>found</code> indicates if a matching rule was found or not. In the case where a
      * matching rule was found, <code>phonemeBuilder</code> is replaced with a new builder containing the phonemes
      * updated by the matching rule.
      *
      * Although this class is not thread-safe (it has mutable unprotected fields), it is not shared between threads
      * as it is constructed as needed by the calling methods.
      * @since 1.6
      */
     private static final class RulesApplication {
         private final List<Rule> finalRules;
         private final CharSequence input;
 
         private PhonemeBuilder phonemeBuilder;
         private int i;
         private int maxPhonemes;
         private boolean found;
 
         public RulesApplication(List<Rule> finalRules, CharSequence input,
                                 PhonemeBuilder phonemeBuilder, int i, int maxPhonemes) {
             if (finalRules == null) {
                 throw new NullPointerException("The finalRules argument must not be null");
             }
             this.finalRules = finalRules;
             this.phonemeBuilder = phonemeBuilder;
             this.input = input;
             this.i = i;
             this.maxPhonemes = maxPhonemes;
         }
 
         public int getI() {
             return this.i;
         }
 
         public PhonemeBuilder getPhonemeBuilder() {
             return this.phonemeBuilder;
         }
 
         /**
          * Invokes the rules. Loops over the rules list, stopping at the first one that has a matching context
          * and pattern. Then applies this rule to the phoneme builder to produce updated phonemes. If there was no
          * match, <code>i</code> is advanced one and the character is silently dropped from the phonetic spelling.
          *
          * @return <code>this</code>
          */
         public RulesApplication invoke() {
             this.found = false;
             int patternLength = 0;
             for (Rule rule : this.finalRules) {
                 String pattern = rule.getPattern();
                 patternLength = pattern.length();
 
                 if (!rule.patternAndContextMatches(this.input, this.i)) {
                     continue;
                 }
 
                 this.phonemeBuilder = this.phonemeBuilder.apply(rule.getPhoneme(), maxPhonemes);
                 this.found = true;
                 break;
             }
 
             if (!this.found) {
                 patternLength = 1;
             }
 
             this.i += patternLength;
             return this;
         }
 
         public boolean isFound() {
             return this.found;
         }
     }
 
     private static final Map<NameType, Set<String>> NAME_PREFIXES = new EnumMap<NameType, Set<String>>(NameType.class);
 
     static {
         NAME_PREFIXES.put(NameType.ASHKENAZI,
                 Collections.unmodifiableSet(
                         new HashSet<String>(Arrays.asList("bar", "ben", "da", "de", "van", "von"))));
         NAME_PREFIXES.put(NameType.SEPHARDIC,
                 Collections.unmodifiableSet(
                         new HashSet<String>(Arrays.asList("al", "el", "da", "dal", "de", "del", "dela", "de la",
                                                           "della", "des", "di", "do", "dos", "du", "van", "von"))));
         NAME_PREFIXES.put(NameType.GENERIC,
                 Collections.unmodifiableSet(
                         new HashSet<String>(Arrays.asList("da", "dal", "de", "del", "dela", "de la", "della",
                                                           "des", "di", "do", "dos", "du", "van", "von"))));
     }
 
     /**
      * This is a performance hack to avoid overhead associated with very frequent CharSequence.subSequence calls.
      *
      * @param cached the character sequence to cache
      * @return a <code>CharSequence</code> that internally caches subSequence values
      */
     private static CharSequence cacheSubSequence(final CharSequence cached) {
         // return cached;
         final CharSequence[][] cache = new CharSequence[cached.length()][cached.length()];
         return new CharSequence() {
             @Override
             public char charAt(int index) {
                 return cached.charAt(index);
             }
 
             @Override
             public int length() {
                 return cached.length();
             }
 
             @Override
             public CharSequence subSequence(int start, int end) {
                 if (start == end) {
                     return "";
                 }
 
                 CharSequence res = cache[start][end - 1];
                 if (res == null) {
                     res = cached.subSequence(start, end);
                     cache[start][end - 1] = res;
                 }
                 return res;
             }
         };
     }
 
     /**
      * Joins some strings with an internal separator.
      * @param strings   Strings to join
      * @param sep       String to separate them with
      * @return a single String consisting of each element of <code>strings</code> interleaved by <code>sep</code>
      */
     private static String join(Iterable<String> strings, String sep) {
         StringBuilder sb = new StringBuilder();
         Iterator<String> si = strings.iterator();
         if (si.hasNext()) {
             sb.append(si.next());
         }
         while (si.hasNext()) {
             sb.append(sep).append(si.next());
         }
 
         return sb.toString();
     }
 
     private static final int DEFAULT_MAX_PHONEMES = 20;
 
     private final Lang lang;
 
     private final NameType nameType;
 
     private final RuleType ruleType;
 
     private final boolean concat;
 
     private final int maxPhonemes;
 
     /**
      * Generates a new, fully-configured phonetic engine.
      *
      * @param nameType
      *            the type of names it will use
      * @param ruleType
      *            the type of rules it will apply
      * @param concat
      *            if it will concatenate multiple encodings
      */
     public PhoneticEngine(NameType nameType, RuleType ruleType, boolean concat) {
         this(nameType, ruleType, concat, DEFAULT_MAX_PHONEMES);
     }
 
     /**
      * Generates a new, fully-configured phonetic engine.
      *
      * @param nameType
      *            the type of names it will use
      * @param ruleType
      *            the type of rules it will apply
      * @param concat
      *            if it will concatenate multiple encodings
      * @param maxPhonemes
      *            the maximum number of phonemes that will be handled
      * @since 1.7
      */
     public PhoneticEngine(NameType nameType, RuleType ruleType, boolean concat, int maxPhonemes) {
         if (ruleType == RuleType.RULES) {
             throw new IllegalArgumentException("ruleType must not be " + RuleType.RULES);
         }
         this.nameType = nameType;
         this.ruleType = ruleType;
         this.concat = concat;
         this.lang = Lang.instance(nameType);
         this.maxPhonemes = maxPhonemes;
     }
 
     /**
      * Applies the final rules to convert from a language-specific phonetic representation to a
      * language-independent representation.
      *
      * @param phonemeBuilder the current phonemes
      * @param finalRules the final rules to apply
      * @return the resulting phonemes
      */
     private PhonemeBuilder applyFinalRules(PhonemeBuilder phonemeBuilder, List<Rule> finalRules) {
         if (finalRules == null) {
             throw new NullPointerException("finalRules can not be null");
         }
         if (finalRules.isEmpty()) {
             return phonemeBuilder;
         }
 
         Set<Rule.Phoneme> phonemes = new TreeSet<Rule.Phoneme>(Rule.Phoneme.COMPARATOR);
 
         for (Rule.Phoneme phoneme : phonemeBuilder.getPhonemes()) {
             PhonemeBuilder subBuilder = PhonemeBuilder.empty(phoneme.getLanguages());
             CharSequence phonemeText = cacheSubSequence(phoneme.getPhonemeText());
 
             for (int i = 0; i < phonemeText.length();) {
                 RulesApplication rulesApplication =
                         new RulesApplication(finalRules, phonemeText, subBuilder, i, maxPhonemes).invoke();
                 boolean found = rulesApplication.isFound();
                 subBuilder = rulesApplication.getPhonemeBuilder();
 
                 if (!found) {
                     // not found, appending as-is
                     subBuilder = subBuilder.append(phonemeText.subSequence(i, i + 1));
                 }
 
                 i = rulesApplication.getI();
             }
 
             phonemes.addAll(subBuilder.getPhonemes());
         }
 
         return new PhonemeBuilder(phonemes);
     }
 
     /**
      * Encodes a string to its phonetic representation.
      *
      * @param input
      *            the String to encode
      * @return the encoding of the input
      */
     public String encode(String input) {
         Languages.LanguageSet languageSet = this.lang.guessLanguages(input);
         return encode(input, languageSet);
     }
 
     /**
      * Encodes an input string into an output phonetic representation, given a set of possible origin languages.
      *
      * @param input
      *            String to phoneticise; a String with dashes or spaces separating each word
      * @param languageSet
      * @return a phonetic representation of the input; a String containing '-'-separated phonetic representations
      *   of the input
      */
     public String encode(String input, final Languages.LanguageSet languageSet) {
         final List<Rule> rules = Rule.getInstance(this.nameType, RuleType.RULES, languageSet);
         // rules common across many (all) languages
         final List<Rule> finalRules1 = Rule.getInstance(this.nameType, this.ruleType, "common");
         // rules that apply to a specific language that may be ambiguous or wrong if applied to other languages
         final List<Rule> finalRules2 = Rule.getInstance(this.nameType, this.ruleType, languageSet);
 
         // tidy the input
         // lower case is a locale-dependent operation
         input = input.toLowerCase(Locale.ENGLISH).replace('-', ' ').trim();
 
         if (this.nameType == NameType.GENERIC) {
             if (input.length() >= 2 && input.substring(0, 2).equals("d'")) { // check for d'
                 String remainder = input.substring(2);
                 String combined = "d" + remainder;
                 return "(" + encode(remainder) + ")-(" + encode(combined) + ")";
             }
             for (String l : NAME_PREFIXES.get(this.nameType)) {
                 // handle generic prefixes
                 if (input.startsWith(l + " ")) {
                     // check for any prefix in the words list
                     String remainder = input.substring(l.length() + 1); // input without the prefix
                     String combined = l + remainder; // input with prefix without space
                     return "(" + encode(remainder) + ")-(" + encode(combined) + ")";
                 }
             }
         }
 
         final List<String> words = Arrays.asList(input.split("\\s+"));
         final List<String> words2 = new ArrayList<String>();
 
         // special-case handling of word prefixes based upon the name type
         switch (this.nameType) {
         case SEPHARDIC:
             for (String aWord : words) {
                 String[] parts = aWord.split("'");
                 String lastPart = parts[parts.length - 1];
                 words2.add(lastPart);
             }
             words2.removeAll(NAME_PREFIXES.get(this.nameType));
             break;
         case ASHKENAZI:
             words2.addAll(words);
             words2.removeAll(NAME_PREFIXES.get(this.nameType));
             break;
         case GENERIC:
             words2.addAll(words);
             break;
         default:
             throw new IllegalStateException("Unreachable case: " + this.nameType);
         }
 
         if (this.concat) {
             // concat mode enabled
             input = join(words2, " ");
         } else if (words2.size() == 1) {
             // not a multi-word name
             input = words.iterator().next();
         } else {
             // encode each word in a multi-word name separately (normally used for approx matches)
             StringBuilder result = new StringBuilder();
             for (String word : words2) {
                 result.append("-").append(encode(word));
             }
             // return the result without the leading "-"
             return result.substring(1);
         }
 
         PhonemeBuilder phonemeBuilder = PhonemeBuilder.empty(languageSet);
 
         // loop over each char in the input - we will handle the increment manually
         CharSequence inputCache = cacheSubSequence(input);
         for (int i = 0; i < inputCache.length();) {
             RulesApplication rulesApplication =
                     new RulesApplication(rules, inputCache, phonemeBuilder, i, maxPhonemes).invoke();
             i = rulesApplication.getI();
             phonemeBuilder = rulesApplication.getPhonemeBuilder();
         }
 
         // Apply the general rules
         phonemeBuilder = applyFinalRules(phonemeBuilder, finalRules1);
         // Apply the language-specific rules
         phonemeBuilder = applyFinalRules(phonemeBuilder, finalRules2);
 
         return phonemeBuilder.makeString();
     }
 
     /**
      * Gets the Lang language guessing rules being used.
      *
      * @return the Lang in use
      */
     public Lang getLang() {
         return this.lang;
     }
 
     /**
      * Gets the NameType being used.
      *
      * @return the NameType in use
      */
     public NameType getNameType() {
         return this.nameType;
     }
 
     /**
      * Gets the RuleType being used.
      *
      * @return the RuleType in use
      */
     public RuleType getRuleType() {
         return this.ruleType;
     }
 
     /**
      * Gets if multiple phonetic encodings are concatenated or if just the first one is kept.
      *
      * @return true if multiple phonetic encodings are returned, false if just the first is
      */
     public boolean isConcat() {
         return this.concat;
     }
 
     /**
      * Gets the maximum number of phonemes the engine will calculate for a given input.
      *
      * @return the maximum number of phonemes
      * @since 1.7
      */
     public int getMaxPhonemes() {
         return this.maxPhonemes;
     }
 }

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.codec.language.bm;
19
20		import java.util.ArrayList;
21		import java.util.Arrays;
22		import java.util.Collections;
23		import java.util.EnumMap;
24		import java.util.HashSet;
25		import java.util.Iterator;
26		import java.util.LinkedHashSet;
27		import java.util.List;
28		import java.util.Locale;
29		import java.util.Map;
30		import java.util.Set;
31		import java.util.TreeSet;
32
33		/**
34		* Converts words into potential phonetic representations.
35		* <p>
36		* This is a two-stage process. Firstly, the word is converted into a phonetic representation that takes
37		* into account the likely source language. Next, this phonetic representation is converted into a
38		* pan-european 'average' representation, allowing comparison between different versions of essentially
39		* the same word from different languages.
40		* <p>
41		* This class is intentionally immutable. If you wish to alter the settings for a PhoneticEngine, you
42		* must make a new one with the updated settings. This makes the class thread-safe.
43		* <p>
44		* Ported from phoneticengine.php
45		*
46		* @since 1.6
47		* @version $Id$
48		*/
49		public class PhoneticEngine {
50
51		/**
52		* Utility for manipulating a set of phonemes as they are being built up. Not intended for use outside
53		* this package, and probably not outside the {@link PhoneticEngine} class.
54		*
55		* @since 1.6
56		*/
57	134301	static final class PhonemeBuilder {
58
59		/**
60		* An empty builder where all phonemes must come from some set of languages. This will contain a single
61		* phoneme of zero characters. This can then be appended to. This should be the only way to create a new
62		* phoneme from scratch.
63		*
64		* @param languages the set of languages
65		* @return a new, empty phoneme builder
66		*/
67		public static PhonemeBuilder empty(Languages.LanguageSet languages) {
68	208023	return new PhonemeBuilder(Collections.singleton(new Rule.Phoneme("", languages)));
69		}
70
71		private final Set<Rule.Phoneme> phonemes;
72
73	449897	private PhonemeBuilder(Set<Rule.Phoneme> phonemes) {
74	449897	this.phonemes = phonemes;
75	449897	}
76
77		/**
78		* Creates a new phoneme builder containing all phonemes in this one extended by <code>str</code>.
79		*
80		* @param str the characters to append to the phonemes
81		* @return a new phoneme builder lenghtened by <code>str</code>
82		*/
83		public PhonemeBuilder append(CharSequence str) {
84	75837	Set<Rule.Phoneme> newPhonemes = new LinkedHashSet<Rule.Phoneme>();
85
86	75837	for (Rule.Phoneme ph : this.phonemes) {
87	152223	newPhonemes.add(ph.append(str));
88		}
89
90	75837	return new PhonemeBuilder(newPhonemes);
91		}
92
93		/**
94		* Creates a new phoneme builder containing the application of the expression to all phonemes in this builder.
95		* <p>
96		* This will lengthen phonemes that have compatible language sets to the expression, and drop those that are
97		* incompatible.
98		*
99		* @param phonemeExpr the expression to apply
100		* @param maxPhonemes the maximum number of phonemes to build up
101		* @return a new phoneme builder containing the results of <code>phonemeExpr</code> applied to each phoneme
102		* in turn
103		*/
104		public PhonemeBuilder apply(Rule.PhonemeExpr phonemeExpr, int maxPhonemes) {
105	31736	Set<Rule.Phoneme> newPhonemes = new LinkedHashSet<Rule.Phoneme>();
106
107	31736	EXPR: for (Rule.Phoneme left : this.phonemes) {
108	101477	for (Rule.Phoneme right : phonemeExpr.getPhonemes()) {
109	175837	Rule.Phoneme join = left.join(right);
110	175837	if (!join.getLanguages().isEmpty()) {
111	127487	if (newPhonemes.size() < maxPhonemes) {
112	126216	newPhonemes.add(join);
113		} else {
114		break EXPR;
115		}
116		}
117	174566	}
118		}
119
120	31736	return new PhonemeBuilder(newPhonemes);
121		}
122
123		/**
124		* Gets underlying phoneme set. Please don't mutate.
125		*
126		* @return the phoneme set
127		*/
128		public Set<Rule.Phoneme> getPhonemes() {
129	275162	return this.phonemes;
130		}
131
132		/**
133		* Stringifies the phoneme set. This produces a single string of the strings of each phoneme,
134		* joined with a pipe. This is explicitly provided in place of toString as it is a potentially
135		* expensive operation, which should be avoided when debugging.
136		*
137		* @return the stringified phoneme set
138		*/
139		public String makeString() {
140	67162	final StringBuilder sb = new StringBuilder();
141
142	67162	for (Rule.Phoneme ph : this.phonemes) {
143	79365	if (sb.length() > 0) {
144	12135	sb.append("\|");
145		}
146	79365	sb.append(ph.getPhonemeText());
147		}
148
149	67162	return sb.toString();
150		}
151		}
152
153		/**
154		* A function closure capturing the application of a list of rules to an input sequence at a particular offset.
155		* After invocation, the values <code>i</code> and <code>found</code> are updated. <code>i</code> points to the
156		* index of the next char in <code>input</code> that must be processed next (the input up to that index having been
157		* processed already), and <code>found</code> indicates if a matching rule was found or not. In the case where a
158		* matching rule was found, <code>phonemeBuilder</code> is replaced with a new builder containing the phonemes
159		* updated by the matching rule.
160		*
161		* Although this class is not thread-safe (it has mutable unprotected fields), it is not shared between threads
162		* as it is constructed as needed by the calling methods.
163		* @since 1.6
164		*/
165		private static final class RulesApplication {
166		private final List<Rule> finalRules;
167		private final CharSequence input;
168
169		private PhonemeBuilder phonemeBuilder;
170		private int i;
171		private int maxPhonemes;
172		private boolean found;
173
174		public RulesApplication(List<Rule> finalRules, CharSequence input,
175	172993	PhonemeBuilder phonemeBuilder, int i, int maxPhonemes) {
176	172993	if (finalRules == null) {
177	0	throw new NullPointerException("The finalRules argument must not be null");
178		}
179	172993	this.finalRules = finalRules;
180	172993	this.phonemeBuilder = phonemeBuilder;
181	172993	this.input = input;
182	172993	this.i = i;
183	172993	this.maxPhonemes = maxPhonemes;
184	172993	}
185
186		public int getI() {
187	172993	return this.i;
188		}
189
190		public PhonemeBuilder getPhonemeBuilder() {
191	172993	return this.phonemeBuilder;
192		}
193
194		/**
195		* Invokes the rules. Loops over the rules list, stopping at the first one that has a matching context
196		* and pattern. Then applies this rule to the phoneme builder to produce updated phonemes. If there was no
197		* match, <code>i</code> is advanced one and the character is silently dropped from the phonetic spelling.
198		*
199		* @return <code>this</code>
200		*/
201		public RulesApplication invoke() {
202	172993	this.found = false;
203	172993	int patternLength = 0;
204	172993	for (Rule rule : this.finalRules) {
205	32427496	String pattern = rule.getPattern();
206	32427496	patternLength = pattern.length();
207
208	32427496	if (!rule.patternAndContextMatches(this.input, this.i)) {
209	32395760	continue;
210		}
211
212	31736	this.phonemeBuilder = this.phonemeBuilder.apply(rule.getPhoneme(), maxPhonemes);
213	31736	this.found = true;
214	31736	break;
215		}
216
217	172993	if (!this.found) {
218	141257	patternLength = 1;
219		}
220
221	172993	this.i += patternLength;
222	172993	return this;
223		}
224
225		public boolean isFound() {
226	101508	return this.found;
227		}
228		}
229
230	1	private static final Map<NameType, Set<String>> NAME_PREFIXES = new EnumMap<NameType, Set<String>>(NameType.class);
231
232		static {
233	1	NAME_PREFIXES.put(NameType.ASHKENAZI,
234		Collections.unmodifiableSet(
235		new HashSet<String>(Arrays.asList("bar", "ben", "da", "de", "van", "von"))));
236	1	NAME_PREFIXES.put(NameType.SEPHARDIC,
237		Collections.unmodifiableSet(
238		new HashSet<String>(Arrays.asList("al", "el", "da", "dal", "de", "del", "dela", "de la",
239		"della", "des", "di", "do", "dos", "du", "van", "von"))));
240	1	NAME_PREFIXES.put(NameType.GENERIC,
241		Collections.unmodifiableSet(
242		new HashSet<String>(Arrays.asList("da", "dal", "de", "del", "dela", "de la", "della",
243		"des", "di", "do", "dos", "du", "van", "von"))));
244	1	}
245
246		/**
247		* This is a performance hack to avoid overhead associated with very frequent CharSequence.subSequence calls.
248		*
249		* @param cached the character sequence to cache
250		* @return a <code>CharSequence</code> that internally caches subSequence values
251		*/
252		private static CharSequence cacheSubSequence(final CharSequence cached) {
253		// return cached;
254	208023	final CharSequence[][] cache = new CharSequence[cached.length()][cached.length()];
255	208023	return new CharSequence() {
256		@Override
257		public char charAt(int index) {
258	0	return cached.charAt(index);
259		}
260
261		@Override
262		public int length() {
263	33010001	return cached.length();
264		}
265
266		@Override
267		public CharSequence subSequence(int start, int end) {
268	19584741	if (start == end) {
269	25935	return "";
270		}
271
272	19558806	CharSequence res = cache[start][end - 1];
273	19558806	if (res == null) {
274	480035	res = cached.subSequence(start, end);
275	480035	cache[start][end - 1] = res;
276		}
277	19558806	return res;
278		}
279		};
280		}
281
282		/**
283		* Joins some strings with an internal separator.
284		* @param strings Strings to join
285		* @param sep String to separate them with
286		* @return a single String consisting of each element of <code>strings</code> interleaved by <code>sep</code>
287		*/
288		private static String join(Iterable<String> strings, String sep) {
289	67128	StringBuilder sb = new StringBuilder();
290	67128	Iterator<String> si = strings.iterator();
291	67128	if (si.hasNext()) {
292	67128	sb.append(si.next());
293		}
294	67149	while (si.hasNext()) {
295	21	sb.append(sep).append(si.next());
296		}
297
298	67128	return sb.toString();
299		}
300
301		private static final int DEFAULT_MAX_PHONEMES = 20;
302
303		private final Lang lang;
304
305		private final NameType nameType;
306
307		private final RuleType ruleType;
308
309		private final boolean concat;
310
311		private final int maxPhonemes;
312
313		/**
314		* Generates a new, fully-configured phonetic engine.
315		*
316		* @param nameType
317		* the type of names it will use
318		* @param ruleType
319		* the type of rules it will apply
320		* @param concat
321		* if it will concatenate multiple encodings
322		*/
323		public PhoneticEngine(NameType nameType, RuleType ruleType, boolean concat) {
324	96	this(nameType, ruleType, concat, DEFAULT_MAX_PHONEMES);
325	96	}
326
327		/**
328		* Generates a new, fully-configured phonetic engine.
329		*
330		* @param nameType
331		* the type of names it will use
332		* @param ruleType
333		* the type of rules it will apply
334		* @param concat
335		* if it will concatenate multiple encodings
336		* @param maxPhonemes
337		* the maximum number of phonemes that will be handled
338		* @since 1.7
339		*/
340	128	public PhoneticEngine(NameType nameType, RuleType ruleType, boolean concat, int maxPhonemes) {
341	128	if (ruleType == RuleType.RULES) {
342	1	throw new IllegalArgumentException("ruleType must not be " + RuleType.RULES);
343		}
344	127	this.nameType = nameType;
345	127	this.ruleType = ruleType;
346	127	this.concat = concat;
347	127	this.lang = Lang.instance(nameType);
348	127	this.maxPhonemes = maxPhonemes;
349	127	}
350
351		/**
352		* Applies the final rules to convert from a language-specific phonetic representation to a
353		* language-independent representation.
354		*
355		* @param phonemeBuilder the current phonemes
356		* @param finalRules the final rules to apply
357		* @return the resulting phonemes
358		*/
359		private PhonemeBuilder applyFinalRules(PhonemeBuilder phonemeBuilder, List<Rule> finalRules) {
360	134324	if (finalRules == null) {
361	0	throw new NullPointerException("finalRules can not be null");
362		}
363	134324	if (finalRules.isEmpty()) {
364	23	return phonemeBuilder;
365		}
366
367	134301	Set<Rule.Phoneme> phonemes = new TreeSet<Rule.Phoneme>(Rule.Phoneme.COMPARATOR);
368
369	134301	for (Rule.Phoneme phoneme : phonemeBuilder.getPhonemes()) {
370	140861	PhonemeBuilder subBuilder = PhonemeBuilder.empty(phoneme.getLanguages());
371	140861	CharSequence phonemeText = cacheSubSequence(phoneme.getPhonemeText());
372
373	140861	for (int i = 0; i < phonemeText.length();) {
374	101508	RulesApplication rulesApplication =
375		new RulesApplication(finalRules, phonemeText, subBuilder, i, maxPhonemes).invoke();
376	101508	boolean found = rulesApplication.isFound();
377	101508	subBuilder = rulesApplication.getPhonemeBuilder();
378
379	101508	if (!found) {
380		// not found, appending as-is
381	75837	subBuilder = subBuilder.append(phonemeText.subSequence(i, i + 1));
382		}
383
384	101508	i = rulesApplication.getI();
385	101508	}
386
387	140861	phonemes.addAll(subBuilder.getPhonemes());
388	140861	}
389
390	134301	return new PhonemeBuilder(phonemes);
391		}
392
393		/**
394		* Encodes a string to its phonetic representation.
395		*
396		* @param input
397		* the String to encode
398		* @return the encoding of the input
399		*/
400		public String encode(String input) {
401	67144	Languages.LanguageSet languageSet = this.lang.guessLanguages(input);
402	67144	return encode(input, languageSet);
403		}
404
405		/**
406		* Encodes an input string into an output phonetic representation, given a set of possible origin languages.
407		*
408		* @param input
409		* String to phoneticise; a String with dashes or spaces separating each word
410		* @param languageSet
411		* @return a phonetic representation of the input; a String containing '-'-separated phonetic representations
412		* of the input
413		*/
414		public String encode(String input, final Languages.LanguageSet languageSet) {
415	67168	final List<Rule> rules = Rule.getInstance(this.nameType, RuleType.RULES, languageSet);
416		// rules common across many (all) languages
417	67168	final List<Rule> finalRules1 = Rule.getInstance(this.nameType, this.ruleType, "common");
418		// rules that apply to a specific language that may be ambiguous or wrong if applied to other languages
419	67168	final List<Rule> finalRules2 = Rule.getInstance(this.nameType, this.ruleType, languageSet);
420
421		// tidy the input
422		// lower case is a locale-dependent operation
423	67168	input = input.toLowerCase(Locale.ENGLISH).replace('-', ' ').trim();
424
425	67168	if (this.nameType == NameType.GENERIC) {
426	67125	if (input.length() >= 2 && input.substring(0, 2).equals("d'")) { // check for d'
427	5	String remainder = input.substring(2);
428	5	String combined = "d" + remainder;
429	5	return "(" + encode(remainder) + ")-(" + encode(combined) + ")";
430		}
431	67120	for (String l : NAME_PREFIXES.get(this.nameType)) {
432		// handle generic prefixes
433	939668	if (input.startsWith(l + " ")) {
434		// check for any prefix in the words list
435	1	String remainder = input.substring(l.length() + 1); // input without the prefix
436	1	String combined = l + remainder; // input with prefix without space
437	1	return "(" + encode(remainder) + ")-(" + encode(combined) + ")";
438		}
439		}
440		}
441
442	67162	final List<String> words = Arrays.asList(input.split("\\s+"));
443	67162	final List<String> words2 = new ArrayList<String>();
444
445		// special-case handling of word prefixes based upon the name type
446	67162	switch (this.nameType) {
447		case SEPHARDIC:
448	21	for (String aWord : words) {
449	21	String[] parts = aWord.split("'");
450	21	String lastPart = parts[parts.length - 1];
451	21	words2.add(lastPart);
452	21	}
453	21	words2.removeAll(NAME_PREFIXES.get(this.nameType));
454	21	break;
455		case ASHKENAZI:
456	22	words2.addAll(words);
457	22	words2.removeAll(NAME_PREFIXES.get(this.nameType));
458	22	break;
459		case GENERIC:
460	67119	words2.addAll(words);
461	67119	break;
462		default:
463	0	throw new IllegalStateException("Unreachable case: " + this.nameType);
464		}
465
466	67162	if (this.concat) {
467		// concat mode enabled
468	67128	input = join(words2, " ");
469	34	} else if (words2.size() == 1) {
470		// not a multi-word name
471	34	input = words.iterator().next();
472		} else {
473		// encode each word in a multi-word name separately (normally used for approx matches)
474	0	StringBuilder result = new StringBuilder();
475	0	for (String word : words2) {
476	0	result.append("-").append(encode(word));
477		}
478		// return the result without the leading "-"
479	0	return result.substring(1);
480		}
481
482	67162	PhonemeBuilder phonemeBuilder = PhonemeBuilder.empty(languageSet);
483
484		// loop over each char in the input - we will handle the increment manually
485	67162	CharSequence inputCache = cacheSubSequence(input);
486	67162	for (int i = 0; i < inputCache.length();) {
487	71485	RulesApplication rulesApplication =
488		new RulesApplication(rules, inputCache, phonemeBuilder, i, maxPhonemes).invoke();
489	71485	i = rulesApplication.getI();
490	71485	phonemeBuilder = rulesApplication.getPhonemeBuilder();
491	71485	}
492
493		// Apply the general rules
494	67162	phonemeBuilder = applyFinalRules(phonemeBuilder, finalRules1);
495		// Apply the language-specific rules
496	67162	phonemeBuilder = applyFinalRules(phonemeBuilder, finalRules2);
497
498	67162	return phonemeBuilder.makeString();
499		}
500
501		/**
502		* Gets the Lang language guessing rules being used.
503		*
504		* @return the Lang in use
505		*/
506		public Lang getLang() {
507	0	return this.lang;
508		}
509
510		/**
511		* Gets the NameType being used.
512		*
513		* @return the NameType in use
514		*/
515		public NameType getNameType() {
516	15	return this.nameType;
517		}
518
519		/**
520		* Gets the RuleType being used.
521		*
522		* @return the RuleType in use
523		*/
524		public RuleType getRuleType() {
525	14	return this.ruleType;
526		}
527
528		/**
529		* Gets if multiple phonetic encodings are concatenated or if just the first one is kept.
530		*
531		* @return true if multiple phonetic encodings are returned, false if just the first is
532		*/
533		public boolean isConcat() {
534	25	return this.concat;
535		}
536
537		/**
538		* Gets the maximum number of phonemes the engine will calculate for a given input.
539		*
540		* @return the maximum number of phonemes
541		* @since 1.7
542		*/
543		public int getMaxPhonemes() {
544	24	return this.maxPhonemes;
545		}
546		}