001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the "License");
007 * you may not use this file except in compliance with the License.
008 * You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018 /*
019 * $Id: XMLString.java 570109 2007-08-27 13:31:35Z zongaro $
020 */
021 package org.apache.xml.utils;
022
023 import java.util.Locale;
024
025 /**
026 * This class is meant to be an interface to character strings, whether they
027 * be java Strings or <code>org.apache.xml.utils.FastStringBuffer</code>s, or
028 * other character data. By using XMLString, character copies can be reduced
029 * in the XML pipeline.
030 */
031 public interface XMLString
032 {
033
034 /**
035 * Directly call the
036 * characters method on the passed ContentHandler for the
037 * string-value. Multiple calls to the
038 * ContentHandler's characters methods may well occur for a single call to
039 * this method.
040 *
041 * @param ch A non-null reference to a ContentHandler.
042 *
043 * @throws org.xml.sax.SAXException
044 */
045 public abstract void dispatchCharactersEvents(org.xml.sax.ContentHandler ch)
046 throws org.xml.sax.SAXException;
047
048 /**
049 * Directly call the
050 * comment method on the passed LexicalHandler for the
051 * string-value.
052 *
053 * @param lh A non-null reference to a LexicalHandler.
054 *
055 * @throws org.xml.sax.SAXException
056 */
057 public abstract void dispatchAsComment(org.xml.sax.ext.LexicalHandler lh)
058 throws org.xml.sax.SAXException;
059
060 /**
061 * Conditionally trim all leading and trailing whitespace in the specified String.
062 * All strings of white space are
063 * replaced by a single space character (#x20), except spaces after punctuation which
064 * receive double spaces if doublePunctuationSpaces is true.
065 * This function may be useful to a formatter, but to get first class
066 * results, the formatter should probably do it's own white space handling
067 * based on the semantics of the formatting object.
068 *
069 * @param trimHead Trim leading whitespace?
070 * @param trimTail Trim trailing whitespace?
071 * @param doublePunctuationSpaces Use double spaces for punctuation?
072 * @return The trimmed string.
073 */
074 public XMLString fixWhiteSpace(boolean trimHead,
075 boolean trimTail,
076 boolean doublePunctuationSpaces);
077
078 /**
079 * Returns the length of this string.
080 *
081 * @return the length of the sequence of characters represented by this
082 * object.
083 */
084 public abstract int length();
085
086 /**
087 * Returns the character at the specified index. An index ranges
088 * from <code>0</code> to <code>length() - 1</code>. The first character
089 * of the sequence is at index <code>0</code>, the next at index
090 * <code>1</code>, and so on, as for array indexing.
091 *
092 * @param index the index of the character.
093 * @return the character at the specified index of this string.
094 * The first character is at index <code>0</code>.
095 * @exception IndexOutOfBoundsException if the <code>index</code>
096 * argument is negative or not less than the length of this
097 * string.
098 */
099 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 }