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