1 /* 2 * Copyright (c) 2005, 2020, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 /* 27 ******************************************************************************* 28 * (C) Copyright IBM Corp. 1996-2005 - All Rights Reserved * 29 * * 30 * The original version of this source code and documentation is copyrighted * 31 * and owned by IBM, These materials are provided under terms of a License * 32 * Agreement between IBM and Sun. This technology is protected by multiple * 33 * US and International patents. This notice and attribution to IBM may not * 34 * to removed. * 35 ******************************************************************************* 36 */ 37 38 package jdk.internal.icu.text; 39 40 /** 41 * <code>Replaceable</code> is an interface representing a 42 * string of characters that supports the replacement of a range of 43 * itself with a new string of characters. It is used by APIs that 44 * change a piece of text while retaining metadata. Metadata is data 45 * other than the Unicode characters returned by char32At(). One 46 * example of metadata is style attributes; another is an edit 47 * history, marking each character with an author and revision number. 48 * 49 * <p>An implicit aspect of the <code>Replaceable</code> API is that 50 * during a replace operation, new characters take on the metadata of 51 * the old characters. For example, if the string "the <b>bold</b> 52 * font" has range (4, 8) replaced with "strong", then it becomes "the 53 * <b>strong</b> font". 54 * 55 * <p><code>Replaceable</code> specifies ranges using a start 56 * offset and a limit offset. The range of characters thus specified 57 * includes the characters at offset start..limit-1. That is, the 58 * start offset is inclusive, and the limit offset is exclusive. 59 * 60 * <p><code>Replaceable</code> also includes API to access characters 61 * in the string: <code>length()</code>, <code>charAt()</code>, 62 * <code>char32At()</code>, and <code>extractBetween()</code>. 63 * 64 * <p>For a subclass to support metadata, typical behavior of 65 * <code>replace()</code> is the following: 66 * <ul> 67 * <li>Set the metadata of the new text to the metadata of the first 68 * character replaced</li> 69 * <li>If no characters are replaced, use the metadata of the 70 * previous character</li> 71 * <li>If there is no previous character (i.e. start == 0), use the 72 * following character</li> 73 * <li>If there is no following character (i.e. the replaceable was 74 * empty), use default metadata</li> 75 * <li>If the code point U+FFFF is seen, it should be interpreted as 76 * a special marker having no metadata</li> 77 * </ul> 78 * If this is not the behavior, the subclass should document any differences. 79 * 80 * <p>Copyright © IBM Corporation 1999. All rights reserved. 81 * 82 * @author Alan Liu 83 * @stable ICU 2.0 84 */ 85 public interface Replaceable { 86 /** 87 * Returns the number of 16-bit code units in the text. 88 * @return number of 16-bit code units in text 89 * @stable ICU 2.0 90 */ 91 int length(); 92 93 /** 94 * Returns the 16-bit code unit at the given offset into the text. 95 * @param offset an integer between 0 and <code>length()</code>-1 96 * inclusive 97 * @return 16-bit code unit of text at given offset 98 * @stable ICU 2.0 99 */ 100 char charAt(int offset); 101 102 /** 103 * Copies characters from this object into the destination 104 * character array. The first character to be copied is at index 105 * <code>srcStart</code>; the last character to be copied is at 106 * index <code>srcLimit-1</code> (thus the total number of 107 * characters to be copied is <code>srcLimit-srcStart</code>). The 108 * characters are copied into the subarray of <code>dst</code> 109 * starting at index <code>dstStart</code> and ending at index 110 * <code>dstStart + (srcLimit-srcStart) - 1</code>. 111 * 112 * @param srcStart the beginning index to copy, inclusive; 113 * {@code 0 <= start <= limit}. 114 * @param srcLimit the ending index to copy, exclusive; 115 * {@code start <= limit <= length()}. 116 * @param dst the destination array. 117 * @param dstStart the start offset in the destination array. 118 * @stable ICU 2.0 119 */ 120 void getChars(int srcStart, int srcLimit, char dst[], int dstStart); 121 }