Source for java.nio.IntBuffer

   1: /* IntBuffer.java -- 
   2:    Copyright (C) 2002, 2003, 2004  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., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 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 IntBuffer extends Buffer
  45:   implements Comparable
  46: {
  47:   int array_offset;
  48:   int[] backing_buffer;
  49: 
  50:   IntBuffer (int capacity, int limit, int position, int mark)
  51:   {
  52:     super (capacity, limit, position, mark);
  53:     array_offset = 0;
  54:   }
  55: 
  56:   /**
  57:    * Allocates a new <code>IntBuffer</code> object with a given capacity.
  58:    */
  59:   public static IntBuffer allocate (int capacity)
  60:   {
  61:     return new IntBufferImpl (capacity);
  62:   }
  63: 
  64:   /**
  65:    * Wraps a <code>int</code> array into a <code>IntBuffer</code>
  66:    * object.
  67:    *
  68:    * @exception IndexOutOfBoundsException If the preconditions on the offset
  69:    * and length parameters do not hold
  70:    */
  71:   public static final IntBuffer wrap (int[] array, int offset, int length)
  72:   {
  73:     return new IntBufferImpl (array, 0, array.length, offset + length, offset, -1, false);
  74:   }
  75: 
  76:   /**
  77:    * Wraps a <code>int</code> array into a <code>IntBuffer</code>
  78:    * object.
  79:    */
  80:   public static final IntBuffer wrap (int[] array)
  81:   {
  82:     return wrap (array, 0, array.length);
  83:   }
  84:   
  85:   /**
  86:    * This method transfers <code>int</code>s from this buffer into the given
  87:    * destination array. Before the transfer, it checks if there are fewer than
  88:    * length <code>int</code>s remaining in this buffer. 
  89:    *
  90:    * @param dst The destination array
  91:    * @param offset The offset within the array of the first <code>int</code>
  92:    * to be written; must be non-negative and no larger than dst.length.
  93:    * @param length The maximum number of bytes to be written to the given array;
  94:    * must be non-negative and no larger than dst.length - offset.
  95:    *
  96:    * @exception BufferUnderflowException If there are fewer than length
  97:    * <code>int</code>s remaining in this buffer.
  98:    * @exception IndexOutOfBoundsException If the preconditions on the offset
  99:    * and length parameters do not hold.
 100:    */
 101:   public IntBuffer get (int[] dst, int offset, int length)
 102:   {
 103:     checkArraySize(dst.length, offset, length);
 104:     checkForUnderflow(length);
 105: 
 106:     for (int i = offset; i < offset + length; i++)
 107:       {
 108:         dst [i] = get ();
 109:       }
 110: 
 111:     return this;
 112:   }
 113: 
 114:   /**
 115:    * This method transfers <code>int</code>s from this buffer into the given
 116:    * destination array.
 117:    *
 118:    * @param dst The byte array to write into.
 119:    *
 120:    * @exception BufferUnderflowException If there are fewer than dst.length
 121:    * <code>int</code>s remaining in this buffer.
 122:    */
 123:   public IntBuffer get (int[] dst)
 124:   {
 125:     return get (dst, 0, dst.length);
 126:   }
 127: 
 128:   /**
 129:    * Writes the content of the the <code>IntBUFFER</code> src
 130:    * into the buffer. Before the transfer, it checks if there is fewer than
 131:    * <code>src.remaining()</code> space remaining in this buffer.
 132:    *
 133:    * @param src The source data.
 134:    *
 135:    * @exception BufferOverflowException If there is insufficient space in this
 136:    * buffer for the remaining <code>int</code>s in the source buffer.
 137:    * @exception IllegalArgumentException If the source buffer is this buffer.
 138:    * @exception ReadOnlyBufferException If this buffer is read-only.
 139:    */
 140:   public IntBuffer put (IntBuffer src)
 141:   {
 142:     if (src == this)
 143:       throw new IllegalArgumentException ();
 144: 
 145:     checkForOverflow(src.remaining ());
 146: 
 147:     if (src.remaining () > 0)
 148:       {
 149:         int[] toPut = new int [src.remaining ()];
 150:         src.get (toPut);
 151:         put (toPut);
 152:       }
 153: 
 154:     return this;
 155:   }
 156: 
 157:   /**
 158:    * Writes the content of the the <code>int array</code> src
 159:    * into the buffer. Before the transfer, it checks if there is fewer than
 160:    * length space remaining in this buffer.
 161:    *
 162:    * @param src The array to copy into the buffer.
 163:    * @param offset The offset within the array of the first byte to be read;
 164:    * must be non-negative and no larger than src.length.
 165:    * @param length The number of bytes to be read from the given array;
 166:    * must be non-negative and no larger than src.length - offset.
 167:    * 
 168:    * @exception BufferOverflowException If there is insufficient space in this
 169:    * buffer for the remaining <code>int</code>s in the source array.
 170:    * @exception IndexOutOfBoundsException If the preconditions on the offset
 171:    * and length parameters do not hold
 172:    * @exception ReadOnlyBufferException If this buffer is read-only.
 173:    */
 174:   public IntBuffer put (int[] src, int offset, int length)
 175:   {
 176:     checkArraySize(src.length, offset, length);
 177:     checkForOverflow(length);
 178: 
 179:     for (int i = offset; i < offset + length; i++)
 180:       put (src [i]);
 181: 
 182:     return this;
 183:   }
 184: 
 185:   /**
 186:    * Writes the content of the the <code>int array</code> src
 187:    * into the buffer.
 188:    *
 189:    * @param src The array to copy into the buffer.
 190:    * 
 191:    * @exception BufferOverflowException If there is insufficient space in this
 192:    * buffer for the remaining <code>int</code>s in the source array.
 193:    * @exception ReadOnlyBufferException If this buffer is read-only.
 194:    */
 195:   public final IntBuffer put (int[] src)
 196:   {
 197:     return put (src, 0, src.length);
 198:   }
 199: 
 200:   /**
 201:    * Tells whether ot not this buffer is backed by an accessible
 202:    * <code>int</code> array.
 203:    */
 204:   public final boolean hasArray ()
 205:   {
 206:     return (backing_buffer != null
 207:             && !isReadOnly ());
 208:   }
 209: 
 210:   /**
 211:    * Returns the <code>int</code> array that backs this buffer.
 212:    *
 213:    * @exception ReadOnlyBufferException If this buffer is read-only.
 214:    * @exception UnsupportedOperationException If this buffer is not backed
 215:    * by an accessible array.
 216:    */
 217:   public final int[] array ()
 218:   {
 219:     if (backing_buffer == null)
 220:       throw new UnsupportedOperationException ();
 221: 
 222:     checkIfReadOnly();
 223:     
 224:     return backing_buffer;
 225:   }
 226: 
 227:   /**
 228:    * Returns the offset within this buffer's backing array of the first element.
 229:    *
 230:    * @exception ReadOnlyBufferException If this buffer is read-only.
 231:    * @exception UnsupportedOperationException If this buffer is not backed
 232:    * by an accessible array.
 233:    */
 234:   public final int arrayOffset ()
 235:   {
 236:     if (backing_buffer == null)
 237:       throw new UnsupportedOperationException ();
 238: 
 239:     checkIfReadOnly();
 240:     
 241:     return array_offset;
 242:   }
 243: 
 244:   /**
 245:    * Calculates a hash code for this buffer.
 246:    *
 247:    * This is done with <code>int</code> arithmetic,
 248:    * where ** represents exponentiation, by this formula:<br>
 249:    * <code>s[position()] + 31 + (s[position()+1] + 30)*31**1 + ... +
 250:    * (s[limit()-1]+30)*31**(limit()-1)</code>.
 251:    * Where s is the buffer data. Note that the hashcode is dependent
 252:    * on buffer content, and therefore is not useful if the buffer
 253:    * content may change.
 254:    *
 255:    * @return the hash code
 256:    */
 257:   public int hashCode ()
 258:   {
 259:     int hashCode = get(position()) + 31;
 260:     int multiplier = 1;
 261:     for (int i = position() + 1; i < limit(); ++i)
 262:       {
 263:       multiplier *= 31;
 264:       hashCode += (get(i) + 30)*multiplier;
 265:       }
 266:     return hashCode;
 267:   }
 268: 
 269:   /**
 270:    * Checks if this buffer is equal to obj.
 271:    */
 272:   public boolean equals (Object obj)
 273:   {
 274:     if (obj instanceof IntBuffer)
 275:       {
 276:         return compareTo (obj) == 0;
 277:       }
 278: 
 279:     return false;
 280:   }
 281: 
 282:   /**
 283:    * Compares two <code>IntBuffer</code> objects.
 284:    *
 285:    * @exception ClassCastException If obj is not an object derived from
 286:    * <code>IntBuffer</code>.
 287:    */
 288:   public int compareTo (Object obj)
 289:   {
 290:     IntBuffer other = (IntBuffer) obj;
 291: 
 292:     int num = Math.min(remaining(), other.remaining());
 293:     int pos_this = position();
 294:     int pos_other = other.position();
 295:     
 296:     for (int count = 0; count < num; count++)
 297:       {
 298:            int a = get(pos_this++);
 299:            int b = other.get(pos_other++);
 300:            
 301:            if (a == b)
 302:              continue;
 303:              
 304:            if (a < b)
 305:              return -1;
 306:              
 307:            return 1;
 308:       }
 309:       
 310:      return remaining() - other.remaining();
 311:   }
 312: 
 313:   /**
 314:    * Returns the byte order of this buffer.
 315:    */
 316:   public abstract ByteOrder order ();
 317: 
 318:   /**
 319:    * Reads the <code>int</code> at this buffer's current position,
 320:    * and then increments the position.
 321:    *
 322:    * @exception BufferUnderflowException If there are no remaining
 323:    * <code>int</code>s in this buffer.
 324:    */
 325:   public abstract int get ();
 326: 
 327:   /**
 328:    * Writes the <code>int</code> at this buffer's current position,
 329:    * and then increments the position.
 330:    *
 331:    * @exception BufferOverflowException If there no remaining 
 332:    * <code>int</code>s in this buffer.
 333:    * @exception ReadOnlyBufferException If this buffer is read-only.
 334:    */
 335:   public abstract IntBuffer put (int b);
 336: 
 337:   /**
 338:    * Absolute get method.
 339:    *
 340:    * @exception IndexOutOfBoundsException If index is negative or not smaller
 341:    * than the buffer's limit.
 342:    */
 343:   public abstract int get (int index);
 344:   
 345:   /**
 346:    * Absolute put method.
 347:    *
 348:    * @exception IndexOutOfBoundsException If index is negative or not smaller
 349:    * than the buffer's limit.
 350:    * @exception ReadOnlyBufferException If this buffer is read-only.
 351:    */
 352:   public abstract IntBuffer put (int index, int b);
 353: 
 354:   /**
 355:    * Compacts this buffer.
 356:    * 
 357:    * @exception ReadOnlyBufferException If this buffer is read-only.
 358:    */
 359:   public abstract IntBuffer compact ();
 360: 
 361:   /**
 362:    * Tells wether or not this buffer is direct.
 363:    */
 364:   public abstract boolean isDirect ();
 365: 
 366:   /**
 367:    * Creates a new <code>IntBuffer</code> whose content is a shared
 368:    * subsequence of this buffer's content.
 369:    */
 370:   public abstract IntBuffer slice ();
 371: 
 372:   /**
 373:    * Creates a new <code>IntBuffer</code> that shares this buffer's
 374:    * content.
 375:    */
 376:   public abstract IntBuffer duplicate ();
 377: 
 378:   /**
 379:    * Creates a new read-only <code>IntBuffer</code> that shares this
 380:    * buffer's content.
 381:    */
 382:   public abstract IntBuffer asReadOnlyBuffer ();
 383: }