1 /* 2 * Copyright (C) 2014 The Android Open Source Project 3 * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved. 4 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 5 * 6 * This code is free software; you can redistribute it and/or modify it 7 * under the terms of the GNU General Public License version 2 only, as 8 * published by the Free Software Foundation. Oracle designates this 9 * particular file as subject to the "Classpath" exception as provided 10 * by Oracle in the LICENSE file that accompanied this code. 11 * 12 * This code is distributed in the hope that it will be useful, but WITHOUT 13 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 14 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 15 * version 2 for more details (a copy is included in the LICENSE file that 16 * accompanied this code). 17 * 18 * You should have received a copy of the GNU General Public License version 19 * 2 along with this work; if not, write to the Free Software Foundation, 20 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 21 * 22 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 23 * or visit www.oracle.com if you need additional information or have any 24 * questions. 25 */ 26 27 /* 28 ******************************************************************************* 29 * (C) Copyright IBM Corp. 1996-2005 - All Rights Reserved * 30 * * 31 * The original version of this source code and documentation is copyrighted * 32 * and owned by IBM, These materials are provided under terms of a License * 33 * Agreement between IBM and Sun. This technology is protected by multiple * 34 * US and International patents. This notice and attribution to IBM may not * 35 * to removed. * 36 ******************************************************************************* 37 */ 38 39 package java.text; 40 41 import android.icu.text.Normalizer2; 42 43 import java.util.function.Supplier; 44 45 /** 46 * This class provides the method <code>normalize</code> which transforms Unicode 47 * text into an equivalent composed or decomposed form, allowing for easier 48 * sorting and searching of text. 49 * The <code>normalize</code> method supports the standard normalization forms 50 * described in 51 * <a href="http://www.unicode.org/unicode/reports/tr15/tr15-23.html"> 52 * Unicode Standard Annex #15 — Unicode Normalization Forms</a>. 53 * <p> 54 * Characters with accents or other adornments can be encoded in 55 * several different ways in Unicode. For example, take the character A-acute. 56 * In Unicode, this can be encoded as a single character (the "composed" form): 57 * 58 * <pre> 59 * U+00C1 LATIN CAPITAL LETTER A WITH ACUTE</pre> 60 * 61 * or as two separate characters (the "decomposed" form): 62 * 63 * <pre> 64 * U+0041 LATIN CAPITAL LETTER A 65 * U+0301 COMBINING ACUTE ACCENT</pre> 66 * 67 * To a user of your program, however, both of these sequences should be 68 * treated as the same "user-level" character "A with acute accent". When you 69 * are searching or comparing text, you must ensure that these two sequences are 70 * treated as equivalent. In addition, you must handle characters with more than 71 * one accent. Sometimes the order of a character's combining accents is 72 * significant, while in other cases accent sequences in different orders are 73 * really equivalent. 74 * <p> 75 * Similarly, the string "ffi" can be encoded as three separate letters: 76 * 77 * <pre> 78 * U+0066 LATIN SMALL LETTER F 79 * U+0066 LATIN SMALL LETTER F 80 * U+0069 LATIN SMALL LETTER I</pre> 81 * 82 * or as the single character 83 * 84 * <pre> 85 * U+FB03 LATIN SMALL LIGATURE FFI</pre> 86 * 87 * The ffi ligature is not a distinct semantic character, and strictly speaking 88 * it shouldn't be in Unicode at all, but it was included for compatibility 89 * with existing character sets that already provided it. The Unicode standard 90 * identifies such characters by giving them "compatibility" decompositions 91 * into the corresponding semantic characters. When sorting and searching, you 92 * will often want to use these mappings. 93 * <p> 94 * The <code>normalize</code> method helps solve these problems by transforming 95 * text into the canonical composed and decomposed forms as shown in the first 96 * example above. In addition, you can have it perform compatibility 97 * decompositions so that you can treat compatibility characters the same as 98 * their equivalents. 99 * Finally, the <code>normalize</code> method rearranges accents into the 100 * proper canonical order, so that you do not have to worry about accent 101 * rearrangement on your own. 102 * <p> 103 * The W3C generally recommends to exchange texts in NFC. 104 * Note also that most legacy character encodings use only precomposed forms and 105 * often do not encode any combining marks by themselves. For conversion to such 106 * character encodings the Unicode text needs to be normalized to NFC. 107 * For more usage examples, see the Unicode Standard Annex. 108 * 109 * @since 1.6 110 */ 111 public final class Normalizer { 112 Normalizer()113 private Normalizer() {}; 114 115 /** 116 * This enum provides constants of the four Unicode normalization forms 117 * that are described in 118 * <a href="http://www.unicode.org/unicode/reports/tr15/tr15-23.html"> 119 * Unicode Standard Annex #15 — Unicode Normalization Forms</a> 120 * and two methods to access them. 121 * 122 * @since 1.6 123 */ 124 // BEGIN Android-changed: remove static modifier and add mapping to equivalent ICU values. 125 public enum Form { 126 127 /** 128 * Canonical decomposition. 129 */ 130 NFD(Normalizer2::getNFDInstance), 131 132 /** 133 * Canonical decomposition, followed by canonical composition. 134 */ 135 NFC(Normalizer2::getNFCInstance), 136 137 /** 138 * Compatibility decomposition. 139 */ 140 NFKD(Normalizer2::getNFKDInstance), 141 142 /** 143 * Compatibility decomposition, followed by canonical composition. 144 */ 145 NFKC(Normalizer2::getNFKCInstance); 146 147 private final Supplier<Normalizer2> icuNormalizer; 148 Form(Supplier<Normalizer2> icuNormalizer)149 Form(Supplier<Normalizer2> icuNormalizer) { 150 this.icuNormalizer = icuNormalizer; 151 } 152 } 153 // END Android-changed: remove static modifier and add mapping to equivalent ICU values. 154 155 /** 156 * Normalize a sequence of char values. 157 * The sequence will be normalized according to the specified normalization 158 * from. 159 * @param src The sequence of char values to normalize. 160 * @param form The normalization form; one of 161 * {@link java.text.Normalizer.Form#NFC}, 162 * {@link java.text.Normalizer.Form#NFD}, 163 * {@link java.text.Normalizer.Form#NFKC}, 164 * {@link java.text.Normalizer.Form#NFKD} 165 * @return The normalized String 166 * @throws NullPointerException If <code>src</code> or <code>form</code> 167 * is null. 168 */ normalize(CharSequence src, Form form)169 public static String normalize(CharSequence src, Form form) { 170 // Android-changed: Switched to ICU. 171 return form.icuNormalizer.get().normalize(src); 172 } 173 174 /** 175 * Determines if the given sequence of char values is normalized. 176 * @param src The sequence of char values to be checked. 177 * @param form The normalization form; one of 178 * {@link java.text.Normalizer.Form#NFC}, 179 * {@link java.text.Normalizer.Form#NFD}, 180 * {@link java.text.Normalizer.Form#NFKC}, 181 * {@link java.text.Normalizer.Form#NFKD} 182 * @return true if the sequence of char values is normalized; 183 * false otherwise. 184 * @throws NullPointerException If <code>src</code> or <code>form</code> 185 * is null. 186 */ isNormalized(CharSequence src, Form form)187 public static boolean isNormalized(CharSequence src, Form form) { 188 // Android-changed: Switched to ICU. 189 return form.icuNormalizer.get().isNormalized(src); 190 } 191 } 192