1 /* 2 * reserved comment block 3 * DO NOT REMOVE OR ALTER! 4 */ 5 /* 6 * Licensed to the Apache Software Foundation (ASF) under one or more 7 * contributor license agreements. See the NOTICE file distributed with 8 * this work for additional information regarding copyright ownership. 9 * The ASF licenses this file to You under the Apache License, Version 2.0 10 * (the "License"); you may not use this file except in compliance with 11 * the License. You may obtain a copy of the License at 12 * 13 * http://www.apache.org/licenses/LICENSE-2.0 14 * 15 * Unless required by applicable law or agreed to in writing, software 16 * distributed under the License is distributed on an "AS IS" BASIS, 17 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 18 * See the License for the specific language governing permissions and 19 * limitations under the License. 20 */ 21 22 package com.sun.org.apache.xml.internal.utils; 23 24 import java.util.Locale; 25 26 /** 27 * This class is meant to be an interface to character strings, whether they 28 * be java Strings or <code>com.sun.org.apache.xml.internal.utils.FastStringBuffer</code>s, or 29 * other character data. By using XMLString, character copies can be reduced 30 * in the XML pipeline. 31 */ 32 public interface XMLString 33 { 34 35 /** 36 * Directly call the 37 * characters method on the passed ContentHandler for the 38 * string-value. Multiple calls to the 39 * ContentHandler's characters methods may well occur for a single call to 40 * this method. 41 * 42 * @param ch A non-null reference to a ContentHandler. 43 * 44 * @throws org.xml.sax.SAXException 45 */ dispatchCharactersEvents(org.xml.sax.ContentHandler ch)46 public abstract void dispatchCharactersEvents(org.xml.sax.ContentHandler ch) 47 throws org.xml.sax.SAXException; 48 49 /** 50 * Directly call the 51 * comment method on the passed LexicalHandler for the 52 * string-value. 53 * 54 * @param lh A non-null reference to a LexicalHandler. 55 * 56 * @throws org.xml.sax.SAXException 57 */ dispatchAsComment(org.xml.sax.ext.LexicalHandler lh)58 public abstract void dispatchAsComment(org.xml.sax.ext.LexicalHandler lh) 59 throws org.xml.sax.SAXException; 60 61 /** 62 * Conditionally trim all leading and trailing whitespace in the specified String. 63 * All strings of white space are 64 * replaced by a single space character (#x20), except spaces after punctuation which 65 * receive double spaces if doublePunctuationSpaces is true. 66 * This function may be useful to a formatter, but to get first class 67 * results, the formatter should probably do it's own white space handling 68 * based on the semantics of the formatting object. 69 * 70 * @param trimHead Trim leading whitespace? 71 * @param trimTail Trim trailing whitespace? 72 * @param doublePunctuationSpaces Use double spaces for punctuation? 73 * @return The trimmed string. 74 */ fixWhiteSpace(boolean trimHead, boolean trimTail, boolean doublePunctuationSpaces)75 public XMLString fixWhiteSpace(boolean trimHead, 76 boolean trimTail, 77 boolean doublePunctuationSpaces); 78 79 /** 80 * Returns the length of this string. 81 * 82 * @return the length of the sequence of characters represented by this 83 * object. 84 */ length()85 public abstract int length(); 86 87 /** 88 * Returns the character at the specified index. An index ranges 89 * from <code>0</code> to <code>length() - 1</code>. The first character 90 * of the sequence is at index <code>0</code>, the next at index 91 * <code>1</code>, and so on, as for array indexing. 92 * 93 * @param index the index of the character. 94 * @return the character at the specified index of this string. 95 * The first character is at index <code>0</code>. 96 * @exception IndexOutOfBoundsException if the <code>index</code> 97 * argument is negative or not less than the length of this 98 * string. 99 */ charAt(int index)100 public abstract char charAt(int index); 101 102 /** 103 * Copies characters from this string into the destination character 104 * array. 105 * 106 * @param srcBegin index of the first character in the string 107 * to copy. 108 * @param srcEnd index after the last character in the string 109 * to copy. 110 * @param dst the destination array. 111 * @param dstBegin the start offset in the destination array. 112 * @exception IndexOutOfBoundsException If any of the following 113 * is true: 114 * <ul><li><code>srcBegin</code> is negative. 115 * <li><code>srcBegin</code> is greater than <code>srcEnd</code> 116 * <li><code>srcEnd</code> is greater than the length of this 117 * string 118 * <li><code>dstBegin</code> is negative 119 * <li><code>dstBegin+(srcEnd-srcBegin)</code> is larger than 120 * <code>dst.length</code></ul> 121 * @exception NullPointerException if <code>dst</code> is <code>null</code> 122 */ getChars(int srcBegin, int srcEnd, char dst[], int dstBegin)123 public abstract void getChars(int srcBegin, int srcEnd, char dst[], 124 int dstBegin); 125 126 /** 127 * Compares this string to the specified object. 128 * The result is <code>true</code> if and only if the argument is not 129 * <code>null</code> and is an <code>XMLString</code> object that represents 130 * the same sequence of characters as this object. 131 * 132 * @param anObject the object to compare this <code>String</code> 133 * against. 134 * @return <code>true</code> if the <code>String </code>are equal; 135 * <code>false</code> otherwise. 136 * @see java.lang.String#compareTo(java.lang.String) 137 * @see java.lang.String#equalsIgnoreCase(java.lang.String) 138 */ equals(XMLString anObject)139 public abstract boolean equals(XMLString anObject); 140 141 /** 142 * Compares this string to the specified <code>String</code>. 143 * The result is <code>true</code> if and only if the argument is not 144 * <code>null</code> and is a <code>String</code> object that represents 145 * the same sequence of characters as this object. 146 * 147 * @param anotherString the object to compare this <code>String</code> 148 * against. 149 * @return <code>true</code> if the <code>String</code>s are equal; 150 * <code>false</code> otherwise. 151 * @see java.lang.String#compareTo(java.lang.String) 152 * @see java.lang.String#equalsIgnoreCase(java.lang.String) 153 */ equals(String anotherString)154 public abstract boolean equals(String anotherString); 155 156 /** 157 * Compares this string to the specified object. 158 * The result is <code>true</code> if and only if the argument is not 159 * <code>null</code> and is a <code>String</code> object that represents 160 * the same sequence of characters as this object. 161 * 162 * @param anObject the object to compare this <code>String</code> 163 * against. 164 * @return <code>true</code> if the <code>String </code>are equal; 165 * <code>false</code> otherwise. 166 * @see java.lang.String#compareTo(java.lang.String) 167 * @see java.lang.String#equalsIgnoreCase(java.lang.String) 168 */ equals(Object anObject)169 public abstract boolean equals(Object anObject); 170 171 /** 172 * Compares this <code>String</code> to another <code>String</code>, 173 * ignoring case considerations. Two strings are considered equal 174 * ignoring case if they are of the same length, and corresponding 175 * characters in the two strings are equal ignoring case. 176 * 177 * @param anotherString the <code>String</code> to compare this 178 * <code>String</code> against. 179 * @return <code>true</code> if the argument is not <code>null</code> 180 * and the <code>String</code>s are equal, 181 * ignoring case; <code>false</code> otherwise. 182 * @see #equals(Object) 183 * @see java.lang.Character#toLowerCase(char) 184 * @see java.lang.Character#toUpperCase(char) 185 */ equalsIgnoreCase(String anotherString)186 public abstract boolean equalsIgnoreCase(String anotherString); 187 188 /** 189 * Compares two strings lexicographically. 190 * 191 * @param anotherString the <code>String</code> to be compared. 192 * @return the value <code>0</code> if the argument string is equal to 193 * this string; a value less than <code>0</code> if this string 194 * is lexicographically less than the string argument; and a 195 * value greater than <code>0</code> if this string is 196 * lexicographically greater than the string argument. 197 * @exception java.lang.NullPointerException if <code>anotherString</code> 198 * is <code>null</code>. 199 */ compareTo(XMLString anotherString)200 public abstract int compareTo(XMLString anotherString); 201 202 /** 203 * Compares two strings lexicographically, ignoring case considerations. 204 * This method returns an integer whose sign is that of 205 * <code>this.toUpperCase().toLowerCase().compareTo( 206 * str.toUpperCase().toLowerCase())</code>. 207 * <p> 208 * Note that this method does <em>not</em> take locale into account, 209 * and will result in an unsatisfactory ordering for certain locales. 210 * The java.text package provides <em>collators</em> to allow 211 * locale-sensitive ordering. 212 * 213 * @param str the <code>String</code> to be compared. 214 * @return a negative integer, zero, or a positive integer as the 215 * the specified String is greater than, equal to, or less 216 * than this String, ignoring case considerations. 217 * @see java.text.Collator#compare(String, String) 218 * @since 1.2 219 */ compareToIgnoreCase(XMLString str)220 public abstract int compareToIgnoreCase(XMLString str); 221 222 /** 223 * Tests if this string starts with the specified prefix beginning 224 * a specified index. 225 * 226 * @param prefix the prefix. 227 * @param toffset where to begin looking in the string. 228 * @return <code>true</code> if the character sequence represented by the 229 * argument is a prefix of the substring of this object starting 230 * at index <code>toffset</code>; <code>false</code> otherwise. 231 * The result is <code>false</code> if <code>toffset</code> is 232 * negative or greater than the length of this 233 * <code>String</code> object; otherwise the result is the same 234 * as the result of the expression 235 * <pre> 236 * this.subString(toffset).startsWith(prefix) 237 * </pre> 238 * @exception java.lang.NullPointerException if <code>prefix</code> is 239 * <code>null</code>. 240 */ startsWith(String prefix, int toffset)241 public abstract boolean startsWith(String prefix, int toffset); 242 243 /** 244 * Tests if this string starts with the specified prefix beginning 245 * a specified index. 246 * 247 * @param prefix the prefix. 248 * @param toffset where to begin looking in the string. 249 * @return <code>true</code> if the character sequence represented by the 250 * argument is a prefix of the substring of this object starting 251 * at index <code>toffset</code>; <code>false</code> otherwise. 252 * The result is <code>false</code> if <code>toffset</code> is 253 * negative or greater than the length of this 254 * <code>String</code> object; otherwise the result is the same 255 * as the result of the expression 256 * <pre> 257 * this.subString(toffset).startsWith(prefix) 258 * </pre> 259 * @exception java.lang.NullPointerException if <code>prefix</code> is 260 * <code>null</code>. 261 */ startsWith(XMLString prefix, int toffset)262 public abstract boolean startsWith(XMLString prefix, int toffset); 263 264 /** 265 * Tests if this string starts with the specified prefix. 266 * 267 * @param prefix the prefix. 268 * @return <code>true</code> if the character sequence represented by the 269 * argument is a prefix of the character sequence represented by 270 * this string; <code>false</code> otherwise. 271 * Note also that <code>true</code> will be returned if the 272 * argument is an empty string or is equal to this 273 * <code>String</code> object as determined by the 274 * {@link #equals(Object)} method. 275 * @exception java.lang.NullPointerException if <code>prefix</code> is 276 * <code>null</code>. 277 * @since JDK1. 0 278 */ startsWith(String prefix)279 public abstract boolean startsWith(String prefix); 280 281 /** 282 * Tests if this string starts with the specified prefix. 283 * 284 * @param prefix the prefix. 285 * @return <code>true</code> if the character sequence represented by the 286 * argument is a prefix of the character sequence represented by 287 * this string; <code>false</code> otherwise. 288 * Note also that <code>true</code> will be returned if the 289 * argument is an empty string or is equal to this 290 * <code>String</code> object as determined by the 291 * {@link #equals(Object)} method. 292 * @exception java.lang.NullPointerException if <code>prefix</code> is 293 * <code>null</code>. 294 * @since JDK1. 0 295 */ startsWith(XMLString prefix)296 public abstract boolean startsWith(XMLString prefix); 297 298 /** 299 * Tests if this string ends with the specified suffix. 300 * 301 * @param suffix the suffix. 302 * @return <code>true</code> if the character sequence represented by the 303 * argument is a suffix of the character sequence represented by 304 * this object; <code>false</code> otherwise. Note that the 305 * result will be <code>true</code> if the argument is the 306 * empty string or is equal to this <code>String</code> object 307 * as determined by the {@link #equals(Object)} method. 308 * @exception java.lang.NullPointerException if <code>suffix</code> is 309 * <code>null</code>. 310 */ endsWith(String suffix)311 public abstract boolean endsWith(String suffix); 312 313 /** 314 * Returns a hashcode for this string. The hashcode for a 315 * <code>String</code> object is computed as 316 * <blockquote><pre> 317 * s[0]*31^(n-1) + s[1]*31^(n-2) + ... + s[n-1] 318 * </pre></blockquote> 319 * using <code>int</code> arithmetic, where <code>s[i]</code> is the 320 * <i>i</i>th character of the string, <code>n</code> is the length of 321 * the string, and <code>^</code> indicates exponentiation. 322 * (The hash value of the empty string is zero.) 323 * 324 * @return a hash code value for this object. 325 */ hashCode()326 public abstract int hashCode(); 327 328 /** 329 * Returns the index within this string of the first occurrence of the 330 * specified character. If a character with value <code>ch</code> occurs 331 * in the character sequence represented by this <code>String</code> 332 * object, then the index of the first such occurrence is returned -- 333 * that is, the smallest value <i>k</i> such that: 334 * <blockquote><pre> 335 * this.charAt(<i>k</i>) == ch 336 * </pre></blockquote> 337 * is <code>true</code>. If no such character occurs in this string, 338 * then <code>-1</code> is returned. 339 * 340 * @param ch a character. 341 * @return the index of the first occurrence of the character in the 342 * character sequence represented by this object, or 343 * <code>-1</code> if the character does not occur. 344 */ indexOf(int ch)345 public abstract int indexOf(int ch); 346 347 /** 348 * Returns the index within this string of the first occurrence of the 349 * specified character, starting the search at the specified index. 350 * <p> 351 * If a character with value <code>ch</code> occurs in the character 352 * sequence represented by this <code>String</code> object at an index 353 * no smaller than <code>fromIndex</code>, then the index of the first 354 * such occurrence is returned--that is, the smallest value <i>k</i> 355 * such that: 356 * <blockquote><pre> 357 * (this.charAt(<i>k</i>) == ch) && (<i>k</i> >= fromIndex) 358 * </pre></blockquote> 359 * is true. If no such character occurs in this string at or after 360 * position <code>fromIndex</code>, then <code>-1</code> is returned. 361 * <p> 362 * There is no restriction on the value of <code>fromIndex</code>. If it 363 * is negative, it has the same effect as if it were zero: this entire 364 * string may be searched. If it is greater than the length of this 365 * string, it has the same effect as if it were equal to the length of 366 * this string: <code>-1</code> is returned. 367 * 368 * @param ch a character. 369 * @param fromIndex the index to start the search from. 370 * @return the index of the first occurrence of the character in the 371 * character sequence represented by this object that is greater 372 * than or equal to <code>fromIndex</code>, or <code>-1</code> 373 * if the character does not occur. 374 */ indexOf(int ch, int fromIndex)375 public abstract int indexOf(int ch, int fromIndex); 376 377 /** 378 * Returns the index within this string of the last occurrence of the 379 * specified character. That is, the index returned is the largest 380 * value <i>k</i> such that: 381 * <blockquote><pre> 382 * this.charAt(<i>k</i>) == ch 383 * </pre></blockquote> 384 * is true. 385 * The String is searched backwards starting at the last character. 386 * 387 * @param ch a character. 388 * @return the index of the last occurrence of the character in the 389 * character sequence represented by this object, or 390 * <code>-1</code> if the character does not occur. 391 */ lastIndexOf(int ch)392 public abstract int lastIndexOf(int ch); 393 394 /** 395 * Returns the index within this string of the last occurrence of the 396 * specified character, searching backward starting at the specified 397 * index. That is, the index returned is the largest value <i>k</i> 398 * such that: 399 * <blockquote><pre> 400 * this.charAt(k) == ch) && (k <= fromIndex) 401 * </pre></blockquote> 402 * is true. 403 * 404 * @param ch a character. 405 * @param fromIndex the index to start the search from. There is no 406 * restriction on the value of <code>fromIndex</code>. If it is 407 * greater than or equal to the length of this string, it has 408 * the same effect as if it were equal to one less than the 409 * length of this string: this entire string may be searched. 410 * If it is negative, it has the same effect as if it were -1: 411 * -1 is returned. 412 * @return the index of the last occurrence of the character in the 413 * character sequence represented by this object that is less 414 * than or equal to <code>fromIndex</code>, or <code>-1</code> 415 * if the character does not occur before that point. 416 */ lastIndexOf(int ch, int fromIndex)417 public abstract int lastIndexOf(int ch, int fromIndex); 418 419 /** 420 * Returns the index within this string of the first occurrence of the 421 * specified substring. The integer returned is the smallest value 422 * <i>k</i> such that: 423 * <blockquote><pre> 424 * this.startsWith(str, <i>k</i>) 425 * </pre></blockquote> 426 * is <code>true</code>. 427 * 428 * @param str any string. 429 * @return if the string argument occurs as a substring within this 430 * object, then the index of the first character of the first 431 * such substring is returned; if it does not occur as a 432 * substring, <code>-1</code> is returned. 433 * @exception java.lang.NullPointerException if <code>str</code> is 434 * <code>null</code>. 435 */ indexOf(String str)436 public abstract int indexOf(String str); 437 438 /** 439 * Returns the index within this string of the first occurrence of the 440 * specified substring. The integer returned is the smallest value 441 * <i>k</i> such that: 442 * <blockquote><pre> 443 * this.startsWith(str, <i>k</i>) 444 * </pre></blockquote> 445 * is <code>true</code>. 446 * 447 * @param str any string. 448 * @return if the string argument occurs as a substring within this 449 * object, then the index of the first character of the first 450 * such substring is returned; if it does not occur as a 451 * substring, <code>-1</code> is returned. 452 * @exception java.lang.NullPointerException if <code>str</code> is 453 * <code>null</code>. 454 */ indexOf(XMLString str)455 public abstract int indexOf(XMLString str); 456 457 /** 458 * Returns the index within this string of the first occurrence of the 459 * specified substring, starting at the specified index. The integer 460 * returned is the smallest value <i>k</i> such that: 461 * <blockquote><pre> 462 * this.startsWith(str, <i>k</i>) && (<i>k</i> >= fromIndex) 463 * </pre></blockquote> 464 * is <code>true</code>. 465 * <p> 466 * There is no restriction on the value of <code>fromIndex</code>. If 467 * it is negative, it has the same effect as if it were zero: this entire 468 * string may be searched. If it is greater than the length of this 469 * string, it has the same effect as if it were equal to the length of 470 * this string: <code>-1</code> is returned. 471 * 472 * @param str the substring to search for. 473 * @param fromIndex the index to start the search from. 474 * @return If the string argument occurs as a substring within this 475 * object at a starting index no smaller than 476 * <code>fromIndex</code>, then the index of the first character 477 * of the first such substring is returned. If it does not occur 478 * as a substring starting at <code>fromIndex</code> or beyond, 479 * <code>-1</code> is returned. 480 * @exception java.lang.NullPointerException if <code>str</code> is 481 * <code>null</code> 482 */ indexOf(String str, int fromIndex)483 public abstract int indexOf(String str, int fromIndex); 484 485 /** 486 * Returns the index within this string of the rightmost occurrence 487 * of the specified substring. The rightmost empty string "" is 488 * considered to occur at the index value <code>this.length()</code>. 489 * The returned index is the largest value <i>k</i> such that 490 * <blockquote><pre> 491 * this.startsWith(str, k) 492 * </pre></blockquote> 493 * is true. 494 * 495 * @param str the substring to search for. 496 * @return if the string argument occurs one or more times as a substring 497 * within this object, then the index of the first character of 498 * the last such substring is returned. If it does not occur as 499 * a substring, <code>-1</code> is returned. 500 * @exception java.lang.NullPointerException if <code>str</code> is 501 * <code>null</code>. 502 */ lastIndexOf(String str)503 public abstract int lastIndexOf(String str); 504 505 /** 506 * Returns the index within this string of the last occurrence of 507 * the specified substring. 508 * 509 * @param str the substring to search for. 510 * @param fromIndex the index to start the search from. There is no 511 * restriction on the value of fromIndex. If it is greater than 512 * the length of this string, it has the same effect as if it 513 * were equal to the length of this string: this entire string 514 * may be searched. If it is negative, it has the same effect 515 * as if it were -1: -1 is returned. 516 * @return If the string argument occurs one or more times as a substring 517 * within this object at a starting index no greater than 518 * <code>fromIndex</code>, then the index of the first character of 519 * the last such substring is returned. If it does not occur as a 520 * substring starting at <code>fromIndex</code> or earlier, 521 * <code>-1</code> is returned. 522 * @exception java.lang.NullPointerException if <code>str</code> is 523 * <code>null</code>. 524 */ lastIndexOf(String str, int fromIndex)525 public abstract int lastIndexOf(String str, int fromIndex); 526 527 /** 528 * Returns a new string that is a substring of this string. The 529 * substring begins with the character at the specified index and 530 * extends to the end of this string. <p> 531 * Examples: 532 * <blockquote><pre> 533 * "unhappy".substring(2) returns "happy" 534 * "Harbison".substring(3) returns "bison" 535 * "emptiness".substring(9) returns "" (an empty string) 536 * </pre></blockquote> 537 * 538 * @param beginIndex the beginning index, inclusive. 539 * @return the specified substring. 540 * @exception IndexOutOfBoundsException if 541 * <code>beginIndex</code> is negative or larger than the 542 * length of this <code>String</code> object. 543 */ substring(int beginIndex)544 public abstract XMLString substring(int beginIndex); 545 546 /** 547 * Returns a new string that is a substring of this string. The 548 * substring begins at the specified <code>beginIndex</code> and 549 * extends to the character at index <code>endIndex - 1</code>. 550 * Thus the length of the substring is <code>endIndex-beginIndex</code>. 551 * 552 * @param beginIndex the beginning index, inclusive. 553 * @param endIndex the ending index, exclusive. 554 * @return the specified substring. 555 * @exception IndexOutOfBoundsException if the 556 * <code>beginIndex</code> is negative, or 557 * <code>endIndex</code> is larger than the length of 558 * this <code>String</code> object, or 559 * <code>beginIndex</code> is larger than 560 * <code>endIndex</code>. 561 */ substring(int beginIndex, int endIndex)562 public abstract XMLString substring(int beginIndex, int endIndex); 563 564 /** 565 * Concatenates the specified string to the end of this string. 566 * 567 * @param str the <code>String</code> that is concatenated to the end 568 * of this <code>String</code>. 569 * @return a string that represents the concatenation of this object's 570 * characters followed by the string argument's characters. 571 * @exception java.lang.NullPointerException if <code>str</code> is 572 * <code>null</code>. 573 */ concat(String str)574 public abstract XMLString concat(String str); 575 576 /** 577 * Converts all of the characters in this <code>String</code> to lower 578 * case using the rules of the given <code>Locale</code>. 579 * 580 * @param locale use the case transformation rules for this locale 581 * @return the String, converted to lowercase. 582 * @see java.lang.Character#toLowerCase(char) 583 * @see java.lang.String#toUpperCase(Locale) 584 */ toLowerCase(Locale locale)585 public abstract XMLString toLowerCase(Locale locale); 586 587 /** 588 * Converts all of the characters in this <code>String</code> to lower 589 * case using the rules of the default locale, which is returned 590 * by <code>Locale.getDefault</code>. 591 * <p> 592 * 593 * @return the string, converted to lowercase. 594 * @see java.lang.Character#toLowerCase(char) 595 * @see java.lang.String#toLowerCase(Locale) 596 */ toLowerCase()597 public abstract XMLString toLowerCase(); 598 599 /** 600 * Converts all of the characters in this <code>String</code> to upper 601 * case using the rules of the given locale. 602 * @param locale use the case transformation rules for this locale 603 * @return the String, converted to uppercase. 604 * @see java.lang.Character#toUpperCase(char) 605 * @see java.lang.String#toLowerCase(Locale) 606 */ toUpperCase(Locale locale)607 public abstract XMLString toUpperCase(Locale locale); 608 609 /** 610 * Converts all of the characters in this <code>String</code> to upper 611 * case using the rules of the default locale, which is returned 612 * by <code>Locale.getDefault</code>. 613 * 614 * <p> 615 * If no character in this string has a different uppercase version, 616 * based on calling the <code>toUpperCase</code> method defined by 617 * <code>Character</code>, then the original string is returned. 618 * <p> 619 * Otherwise, this method creates a new <code>String</code> object 620 * representing a character sequence identical in length to the 621 * character sequence represented by this <code>String</code> object and 622 * with every character equal to the result of applying the method 623 * <code>Character.toUpperCase</code> to the corresponding character of 624 * this <code>String</code> object. <p> 625 * Examples: 626 * <blockquote><pre> 627 * "Fahrvergnügen".toUpperCase() returns "FAHRVERGNÜGEN" 628 * "Visit Ljubinje!".toUpperCase() returns "VISIT LJUBINJE!" 629 * </pre></blockquote> 630 * 631 * @return the string, converted to uppercase. 632 * @see java.lang.Character#toUpperCase(char) 633 * @see java.lang.String#toUpperCase(Locale) 634 */ toUpperCase()635 public abstract XMLString toUpperCase(); 636 637 /** 638 * Removes white space from both ends of this string. 639 * <p> 640 * If this <code>String</code> object represents an empty character 641 * sequence, or the first and last characters of character sequence 642 * represented by this <code>String</code> object both have codes 643 * greater than <code>'\u0020'</code> (the space character), then a 644 * reference to this <code>String</code> object is returned. 645 * <p> 646 * Otherwise, if there is no character with a code greater than 647 * <code>'\u0020'</code> in the string, then a new 648 * <code>String</code> object representing an empty string is created 649 * and returned. 650 * <p> 651 * Otherwise, let <i>k</i> be the index of the first character in the 652 * string whose code is greater than <code>'\u0020'</code>, and let 653 * <i>m</i> be the index of the last character in the string whose code 654 * is greater than <code>'\u0020'</code>. A new <code>String</code> 655 * object is created, representing the substring of this string that 656 * begins with the character at index <i>k</i> and ends with the 657 * character at index <i>m</i>-that is, the result of 658 * <code>this.substring(<i>k</i>, <i>m</i>+1)</code>. 659 * <p> 660 * This method may be used to trim 661 * {@link Character#isSpace(char) whitespace} from the beginning and end 662 * of a string; in fact, it trims all ASCII control characters as well. 663 * 664 * @return this string, with white space removed from the front and end. 665 */ trim()666 public abstract XMLString trim(); 667 668 /** 669 * This object (which is already a string!) is itself returned. 670 * 671 * @return the string itself. 672 */ toString()673 public abstract String toString(); 674 675 /** 676 * Tell if this object contains a java String object. 677 * 678 * @return true if this XMLString can return a string without creating one. 679 */ hasString()680 public abstract boolean hasString(); 681 682 /** 683 * Convert a string to a double -- Allowed input is in fixed 684 * notation ddd.fff. 685 * 686 * @return A double value representation of the string, or return Double.NaN 687 * if the string can not be converted. 688 */ toDouble()689 public double toDouble(); 690 } 691