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