libjava/java/nio/CharBuffer.java

   1 /* CharBuffer.java --
   2    Copyright (C) 2002, 2003 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.nio;
  40
  41 /**
  42  * @since 1.4
  43  */
  44 public abstract class CharBuffer extends Buffer
  45   implements Comparable, CharSequence
  46 {
  47   int array_offset;
  48   char[] backing_buffer;
  49
  50   CharBuffer (int capacity, int limit, int position, int mark)
  51   {
  52     super (capacity, limit, position, mark);
  53     array_offset = 0;
  54   }
  55
  56   CharBuffer (char[] buffer, int offset, int capacity, int limit, int position, int mark)
  57   {
  58     super (capacity, limit, position, mark);
  59     this.backing_buffer = buffer;
  60     this.array_offset = offset;
  61   }
  62
  63   /**
  64    * Allocates a new <code>CharBuffer</code> object with a given capacity.
  65    */
  66   public static CharBuffer allocate (int capacity)
  67   {
  68     return new CharBufferImpl (capacity);
  69   }
  70
  71   /**
  72    * Wraps a <code>char</code> array into a <code>CharBuffer</code>
  73    * object.
  74    *
  75    * @exception IndexOutOfBoundsException If the preconditions on the offset
  76    * and length parameters do not hold
  77    */
  78   final public static CharBuffer wrap (char[] array, int offset, int length)
  79   {
  80     return new CharBufferImpl (array, 0, array.length, offset + length, offset, -1, false);
  81   }
  82
  83   /**
  84    * Wraps a character sequence into a <code>CharBuffer</code> object.
  85    */
  86   final public static CharBuffer wrap (CharSequence a)
  87   {
  88     return wrap (a, 0, a.length ());
  89   }
  90
  91   /**
  92    * Wraps a character sequence into a <code>CharBuffer</code> object.
  93    *
  94    * @exception IndexOutOfBoundsException If the preconditions on the offset
  95    * and length parameters do not hold
  96    */
  97   final public static CharBuffer wrap (CharSequence a, int offset, int length)
  98   {
  99     // FIXME: implement better handling of java.lang.String.
 100     // Probably share data with String via reflection.
 101
 102     if ((offset < 0)
 103         || (offset > a.length ())
 104         || (length < 0)
 105         || (length > (a.length () - offset)))
 106       throw new IndexOutOfBoundsException ();
 107
 108     char [] buffer = new char [a.length ()];
 109
 110     for (int i = offset; i < length; i++)
 111       {
 112         buffer [i] = a.charAt (i);
 113       }
 114
 115     return wrap (buffer, offset, length).asReadOnlyBuffer ();
 116   }
 117
 118   /**
 119    * Wraps a <code>char</code> array into a <code>CharBuffer</code>
 120    * object.
 121    */
 122   final public static CharBuffer wrap (char[] array)
 123   {
 124     return wrap (array, 0, array.length);
 125   }
 126
 127   /**
 128    * This method transfers <code>chars<code> from this buffer into the given
 129    * destination array.
 130    *
 131    * @param dst The destination array
 132    * @param offset The offset within the array of the first <code>char</code>
 133    * to be written; must be non-negative and no larger than dst.length.
 134    * @param length The maximum number of bytes to be written to the given array;
 135    * must be non-negative and no larger than dst.length - offset.
 136    *
 137    * @exception BufferUnderflowException If there are fewer than length
 138    * <code>chars</code> remaining in this buffer.
 139    * @exception IndexOutOfBoundsException If the preconditions on the offset
 140    * and length parameters do not hold.
 141    */
 142   public CharBuffer get (char[] dst, int offset, int length)
 143   {
 144     for (int i = offset; i < offset + length; i++)
 145       {
 146         dst [i] = get ();
 147       }
 148
 149     return this;
 150   }
 151
 152   /**
 153    * This method transfers <code>chars<code> from this buffer into the given
 154    * destination array.
 155    *
 156    * @param dst The byte array to write into.
 157    *
 158    * @exception BufferUnderflowException If there are fewer than dst.length
 159    * <code>chars</code> remaining in this buffer.
 160    */
 161   public CharBuffer get (char[] dst)
 162   {
 163     return get (dst, 0, dst.length);
 164   }
 165
 166   /**
 167    * Writes the content of the the <code>CharBUFFER</code> src
 168    * into the buffer.
 169    *
 170    * @param src The source data.
 171    *
 172    * @exception BufferOverflowException If there is insufficient space in this
 173    * buffer for the remaining <code>chars<code> in the source buffer.
 174    * @exception IllegalArgumentException If the source buffer is this buffer.
 175    * @exception ReadOnlyBufferException If this buffer is read-only.
 176    */
 177   public CharBuffer put (CharBuffer src)
 178   {
 179     if (src == this)
 180       throw new IllegalArgumentException ();
 181
 182     if (src.remaining () > remaining ())
 183       throw new BufferOverflowException ();
 184
 185     if (src.remaining () > 0)
 186       {
 187         char[] toPut = new char [src.remaining ()];
 188         src.get (toPut);
 189         src.put (toPut);
 190       }
 191
 192     return this;
 193   }
 194
 195   /**
 196    * Writes the content of the the <code>char array</code> src
 197    * into the buffer.
 198    *
 199    * @param src The array to copy into the buffer.
 200    * @param offset The offset within the array of the first byte to be read;
 201    * must be non-negative and no larger than src.length.
 202    * @param length The number of bytes to be read from the given array;
 203    * must be non-negative and no larger than src.length - offset.
 204    *
 205    * @exception BufferOverflowException If there is insufficient space in this
 206    * buffer for the remaining <code>chars<code> in the source array.
 207    * @exception IndexOutOfBoundsException If the preconditions on the offset
 208    * and length parameters do not hold
 209    * @exception ReadOnlyBufferException If this buffer is read-only.
 210    */
 211   public CharBuffer put (char[] src, int offset, int length)
 212   {
 213     if (offset < 0
 214         || offset >= src.length
 215         || length < 0
 216         || length > (src.length - offset))
 217       throw new IndexOutOfBoundsException ();
 218
 219     // Put nothing into this buffer when not enough space left.
 220     if (length > remaining ())
 221       throw new BufferOverflowException ();
 222
 223     for (int i = offset; i < offset + length; i++)
 224       put (src [i]);
 225
 226     return this;
 227   }
 228
 229   /**
 230    * Writes the content of the the <code>char array</code> src
 231    * into the buffer.
 232    *
 233    * @param src The array to copy into the buffer.
 234    *
 235    * @exception BufferOverflowException If there is insufficient space in this
 236    * buffer for the remaining <code>chars<code> in the source array.
 237    * @exception ReadOnlyBufferException If this buffer is read-only.
 238    */
 239   public final CharBuffer put (char[] src)
 240   {
 241     return put (src, 0, src.length);
 242   }
 243
 244   /**
 245    * Tells whether ot not this buffer is backed by an accessible
 246    * <code>char</code> array.
 247    */
 248   public final boolean hasArray ()
 249   {
 250     return (backing_buffer != null
 251             && !isReadOnly ());
 252   }
 253
 254   /**
 255    * Returns the <code>char</code> array that backs this buffer.
 256    *
 257    * @exception ReadOnlyBufferException If this buffer is read-only.
 258    * @exception UnsupportedOperationException If this buffer is not backed
 259    * by an accessible array.
 260    */
 261   public final char[] array ()
 262   {
 263     if (backing_buffer == null)
 264       throw new UnsupportedOperationException ();
 265
 266     if (isReadOnly ())
 267       throw new ReadOnlyBufferException ();
 268
 269     return backing_buffer;
 270   }
 271
 272   /**
 273    * Returns the offset within this buffer's backing array of the first element.
 274    *
 275    * @exception ReadOnlyBufferException If this buffer is read-only.
 276    * @exception UnsupportedOperationException If this buffer is not backed
 277    * by an accessible array.
 278    */
 279   public final int arrayOffset ()
 280   {
 281     if (backing_buffer == null)
 282       throw new UnsupportedOperationException ();
 283
 284     if (isReadOnly ())
 285       throw new ReadOnlyBufferException ();
 286
 287     return array_offset;
 288   }
 289
 290   /**
 291    * Calculates a hash code for this buffer.
 292    */
 293   public int hashCode ()
 294   {
 295     // FIXME: Check what SUN calculates here.
 296     return super.hashCode ();
 297   }
 298
 299   /**
 300    * Checks if this buffer is equal to obj.
 301    */
 302   public boolean equals (Object obj)
 303   {
 304     if (obj instanceof CharBuffer)
 305       {
 306         return compareTo (obj) == 0;
 307       }
 308
 309     return false;
 310   }
 311
 312   /**
 313    * Compares two <code>CharBuffer</code> objects.
 314    *
 315    * @exception ClassCastException If obj is not an object derived from
 316    * <code>CharBuffer</code>.
 317    */
 318   public int compareTo (Object obj)
 319   {
 320     CharBuffer a = (CharBuffer) obj;
 321
 322     if (a.remaining () != remaining ())
 323       return 1;
 324
 325     if (! hasArray () ||
 326         ! a.hasArray ())
 327       {
 328         return 1;
 329       }
 330
 331     int r = remaining ();
 332     int i1 = position ();
 333     int i2 = a.position ();
 334
 335     for (int i = 0; i < r; i++)
 336       {
 337         int t = (int) (get (i1) - a.get (i2));
 338
 339         if (t != 0)
 340           {
 341             return (int) t;
 342           }
 343       }
 344
 345     return 0;
 346   }
 347
 348   /**
 349    * Returns the byte order of this buffer.
 350    */
 351   public abstract ByteOrder order ();
 352
 353   /**
 354    * Reads the <code>char</code> at this buffer's current position,
 355    * and then increments the position.
 356    *
 357    * @exception BufferUnderflowException If there are no remaining
 358    * <code>chars</code> in this buffer.
 359    */
 360   public abstract char get ();
 361
 362   /**
 363    * Writes the <code>char</code> at this buffer's current position,
 364    * and then increments the position.
 365    *
 366    * @exception BufferOverflowException If there no remaining
 367    * <code>chars</code> in this buffer.
 368    * @exception ReadOnlyBufferException If this buffer is read-only.
 369    */
 370   public abstract CharBuffer put (char b);
 371
 372   /**
 373    * Absolute get method.
 374    *
 375    * @exception IndexOutOfBoundsException If index is negative or not smaller
 376    * than the buffer's limit.
 377    */
 378   public abstract char get (int index);
 379
 380   /**
 381    * Absolute put method.
 382    *
 383    * @exception IndexOutOfBoundsException If index is negative or not smaller
 384    * than the buffer's limit.
 385    * @exception ReadOnlyBufferException If this buffer is read-only.
 386    */
 387   public abstract CharBuffer put (int index, char b);
 388
 389   /**
 390    * Compacts this buffer.
 391    *
 392    * @exception ReadOnlyBufferException If this buffer is read-only.
 393    */
 394   public abstract CharBuffer compact ();
 395
 396   /**
 397    * Tells wether or not this buffer is direct.
 398    */
 399   public abstract boolean isDirect ();
 400
 401   /**
 402    * Creates a new <code>CharBuffer</code> whose content is a shared
 403    * subsequence of this buffer's content.
 404    */
 405   public abstract CharBuffer slice ();
 406
 407   /**
 408    * Creates a new <code>CharBuffer</code> that shares this buffer's
 409    * content.
 410    */
 411   public abstract CharBuffer duplicate ();
 412
 413   /**
 414    * Creates a new read-only <code>CharBuffer</code> that shares this
 415    * buffer's content.
 416    */
 417   public abstract CharBuffer asReadOnlyBuffer ();
 418
 419   /**
 420    * Returns the remaining content of the buffer as a string.
 421    */
 422   public String toString ()
 423   {
 424     if (hasArray ())
 425       return new String (array (), position (), length ());
 426
 427     char[] buf = new char [length ()];
 428     int pos = position ();
 429     get (buf, 0, buf.length);
 430     position (pos);
 431     return new String (buf);
 432   }
 433
 434   /**
 435    * Returns the length of the remaining chars in this buffer.
 436    */
 437   public final int length ()
 438   {
 439     return remaining ();
 440   }
 441
 442   /**
 443    * Creates a new character buffer that represents the specified subsequence
 444    * of this buffer, relative to the current position.
 445    *
 446    * @exception IndexOutOfBoundsException If the preconditions on start and
 447    * end do not hold.
 448    */
 449   public abstract CharSequence subSequence (int start, int length);
 450
 451   /**
 452    * Relative put method.
 453    *
 454    * @exception BufferOverflowException If there is insufficient space in this
 455    * buffer.
 456    * @exception IndexOutOfBoundsException If the preconditions on the start
 457    * and end parameters do not hold.
 458    * @exception ReadOnlyBufferException If this buffer is read-only.
 459    */
 460   public CharBuffer put (String str, int start, int length)
 461   {
 462     return put (str.toCharArray (), start, length);
 463   }
 464
 465   /**
 466    * Relative put method.
 467    *
 468    * @exception BufferOverflowException If there is insufficient space in this
 469    * buffer.
 470    * @exception ReadOnlyBufferException If this buffer is read-only.
 471    */
 472   public final CharBuffer put (String str)
 473   {
 474     return put (str.toCharArray (), 0, str.length ());
 475   }
 476
 477   /**
 478    * Returns the character at <code>position() + index</code>.
 479    *
 480    * @exception IndexOutOfBoundsException If index is negative not smaller than
 481    * <code>remaining()</code>.
 482    */
 483   public final char charAt (int index)
 484   {
 485     if (index < 0
 486         || index >= remaining ())
 487       throw new IndexOutOfBoundsException ();
 488
 489     return get (position () + index);
 490   }
 491 }